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

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

Response

{
  "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

{
  "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.

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.