# Wallets API

Register and manage crypto wallets for your business. Wallets are the core account primitive in Chain — they hold USDC balances, enable transfers, and power card spending. All wallet addresses are automatically screened for compliance.

## Create a Wallet

Register a new wallet by providing an Ethereum address. The address is automatically screened against risk databases for compliance.

**POST/v1/wallets**

| Parameter          | Type     | Description                                               |
|-------------------|----------|-----------------------------------------------------------|
| `label`required    | `string` | Friendly name for the wallet (1–100 characters).         |
| `address`required  | `string` | Ethereum wallet address (0x...).                          |
| `blockchain`       | `string` | Blockchain network (default: "ethereum").               |
| `is_primary`       | `boolean`| Set as the primary wallet (default: false).               |
| `metadata`         | `object` | Key-value metadata to attach.                             |

**Scope required**  
This endpoint requires the `wallets:write` scope and a verified business.

### Example request

```bash
curl -X POST https://api.chain.com/v1/wallets \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{\n    "label": "Treasury",\n    "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",\n    "blockchain": "ethereum",\n    "is_primary": true,\n    "metadata": { "department": "finance" }\n  }'
```

### Response

```json
{
  "id": "wal_xyz789",
  "label": "Treasury",
  "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
  "blockchain": "ethereum",
  "is_primary": true,
  "status": "active",
  "risk_score": 12,
  "risk_category": "low",
  "metadata": { "department": "finance" },
  "created_at": "2026-01-15T10:00:00Z"
}
```

## List Wallets

Retrieve all wallets for the current business.

### GET/v1/wallets

| Parameter          | Type    | Description                                        |
|-------------------|---------|----------------------------------------------------|
| `limit`           | `number`| Results per page (default 20, max 100).           |
| `starting_after`  | `string`| Cursor for pagination — wallet ID to start after. |
| `status`          | `string`| Filter by status: "active", "frozen", "flagged". |

### Response

```json
{
  "data": [
    {
      "id": "wal_xyz789",
      "label": "Treasury",
      "address": "0x1a2b3c4d5e6f...",
      "blockchain": "ethereum",
      "is_primary": true,
      "status": "active",
      "risk_score": 12,
      "risk_category": "low",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "wal_abc456",
      "label": "Operations",
      "address": "0x9876543210ab...",
      "blockchain": "ethereum",
      "is_primary": false,
      "status": "active",
      "risk_score": 5,
      "risk_category": "low",
      "created_at": "2026-01-05T00:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Compliance Screening

Automatic screening

All wallet addresses are automatically screened against sanctions lists and risk databases when created. Wallets flagged during screening will be marked with a higher risk score and may require review.

| Risk Category | Score Range | Action                                                    |
|---------------|-------------|----------------------------------------------------------|
| `low`         | 0–30       | Wallet is active and fully operational.                  |
| `medium`      | 31–60      | Wallet is active but may be subject to additional monitoring. |
| `high`        | 61–100     | Wallet may be frozen pending manual review.             |

## Wallet Management

You can manage wallet settings — such as updating the label or setting a wallet as primary — from the [Chain Dashboard](https://app.chain.com/).

### Set as primary

The primary wallet is used by default for funding and payouts when no wallet ID is specified.

### Update label

Rename a wallet for better organization in your dashboard and reports.

Pax Dollar

USDP

Ripple USD

RLUSD

Dollar

USD

Tether

USDT

Pounds

GBP

Euro

Eur