Sign in
External Wallets

Create an external wallet

Create an external wallet for a customer. This is an asynchronous flow.

post/v1/external-wallets

Headers

X-API-Keystring

API key

Request body

customerIdstring required

Customer ID

counterpartyIdstring

Existing counterparty ID for third-party recipient wallets. If not provided, we'll upsert a new counterparty.

walletAddressstring required

Wallet address

chainsstring[]

Supported chains

currenciesstring[]

Supported currencies

externalReferencestring

Client-provided external reference for mapping to your system (UUID v4 or CUID recommended)

isThirdPartyboolean

Whether this account belongs to a third party (not the customer). Defaults to false.

custodyType'SELF_HOSTED' | 'ANCHORAGE' | 'BINANCE' | 'BITGO' | 'CIRCLE' | 'COINBASE' | 'FIREBLOCKS' | 'GEMINI' | 'KRAKEN' | 'ROBINHOOD' | 'OTHER_EXCHANGE'

Wallet custody type used for provider custodian mapping. Defaults to SELF_HOSTED.

beneficiaryType'INDIVIDUAL' | 'BUSINESS'

Beneficiary type for third-party recipients. Required when creating a new third-party counterparty.

beneficiaryNamestring

Beneficiary legal name for third-party recipients. Required when creating a new third-party counterparty.

Example request

{
  "customerId": "cust_abc123",
  "counterpartyId": "cp_abc123",
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "chains": [
    "ETHEREUM",
    "BASE"
  ],
  "currencies": [
    "USDC",
    "USDT"
  ],
  "externalReference": "550e8400-e29b-41d4-a716-446655440000",
  "custodyType": "SELF_HOSTED",
  "metadata": {
    "nickname": "Main Checking Account",
    "purpose": "Business operations",
    "tags": [
      "primary",
      "operations"
    ]
  },
  "beneficiaryType": "INDIVIDUAL",
  "beneficiaryName": "Jane Doe",
  "beneficiaryAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US",
    "transliterated": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "city": "Beijing",
      "state": "Hebei"
    }
  }
}

Response

External wallet created and submitted for async review

idstring required

Account ID

customerIdstring required

Customer ID

counterpartyIdstring nullable

Counterparty ID when this is a third-party recipient wallet

type'EXTERNAL_WALLET' required

Account type

status'IN_REVIEW' | 'ACTIVE' | 'CLOSED' required

Account status

walletAddressstring required

Wallet address

addressType'EVM' | 'TRON' | 'BITCOIN' | 'SOLANA' required

Wallet address type

chainsstring[]

Supported blockchain chains

custodyType'SELF_HOSTED' | 'ANCHORAGE' | 'BINANCE' | 'BITGO' | 'CIRCLE' | 'COINBASE' | 'FIREBLOCKS' | 'GEMINI' | 'KRAKEN' | 'ROBINHOOD' | 'OTHER_EXCHANGE'

Wallet custody type used for provider custodian mapping.

createdAtstring date-time required

Account creation date

updatedAtstring date-time required

Account last update date

createdboolean

Whether this account was newly created in this request or returned from an existing match

Example response

{
  "id": "ewa_1234567890abcdef",
  "customerId": "cust_abc123",
  "counterpartyId": "cp_abc123",
  "type": "EXTERNAL_WALLET",
  "status": "IN_REVIEW",
  "metadata": {
    "nickname": "Main Checking Account",
    "purpose": "Business operations",
    "tags": [
      "primary",
      "operations"
    ]
  },
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "addressType": "EVM",
  "chains": [
    "ETHEREUM",
    "BASE"
  ],
  "currencies": [
    [
      "USDC",
      "USDT"
    ]
  ],
  "custodyType": "SELF_HOSTED",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-15T10:00:00Z",
  "created": true
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.