curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.13/external-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "label": "Acme deposits",
  "owner": {
    "kind": "counterparty",
    "counterpartyId": "ctp_1x0yvbj459mtzq609n8p33twd1"
  },
  "type": "walletExternal",
  "walletExternal": {
    "blockchainAddress": "0xbEeF4A2C891d56e72B67a3f21d0cF94f1D7c5911",
    "networkFamily": "evm",
    "custodian": "COINBASE_US"
  }
}
'

{
  "id": "ext_95863ktcdhw27ze8hxgybb24n9",
  "object": "externalAccount",
  "type": "walletExternal",
  "category": "crypto",
  "owner": {
    "kind": "counterparty",
    "counterpartyId": "ctp_yp5z8m7n22svc0vh6edqgcfdat"
  },
  "status": "active",
  "resolvedTransactions": [
    "txn_x9waqqeg1ng6v32c5142zfp89d"
  ],
  "label": "Acme deposits inbound",
  "createdAt": "2026-05-15T18:01:12Z",
  "updatedAt": "2026-05-15T18:01:12Z",
  "walletExternal": {
    "blockchainAddress": "0xeB3eCfb244E94a407bfb1EEcFEDe27D920cc00F5",
    "custodian": "COINBASE_US",
    "networkFamily": "evm"
  }
}

External Accounts

Create an External Account

Create an External Account (saved payment destination). Provisions synchronously against the configured payment provider; the account starts pending and flips to active or failed. Exactly one per-type detail object must match type. The owner discriminator determines whether this account belongs to a customer directly or to one of the customer’s counterparties.

Uniqueness (walletExternal). A wallet is registered at most once per owner: the key is (owner, normalized blockchain address, network family). Consequences:

Re-registering an address the same owner already holds active, pending or invalid returns 409 externalAccountAlreadyRegistered, with details.existingAccountId naming that account and details.existingAccountStatus telling you what to do next: - "pending" means a registration is still in flight and this is TRANSIENT — the account resolves to active or failed on its own (typically within ~30 minutes; see the stale-pending sweep), after which re-registering a failed account re-drives it. Retrying the create immediately will not help; poll GET on existingAccountId, or simply wait and re-submit later. - "active" (or "invalid") is TERMINAL: use the account named by existingAccountId instead of retrying the create. - Two different owners under the same customer (the customer itself and one of its counterparties, or two counterparties) may each register the same address — each gets its own account, 201. - The same address under two different customers is likewise allowed. - An account in failed or rejected state does not block re-registration: submitting it again re-drives provisioning on that same account (same id) and adopts the newly submitted label and metadata, returning 201. Deleted accounts free their key entirely.

Send an Idempotency-Key and retry with the SAME key after a network failure: the original response is replayed, so a 409 always means a genuinely different request collided with an existing account.

POST

external-accounts

curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.13/external-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "label": "Acme deposits",
  "owner": {
    "kind": "counterparty",
    "counterpartyId": "ctp_1x0yvbj459mtzq609n8p33twd1"
  },
  "type": "walletExternal",
  "walletExternal": {
    "blockchainAddress": "0xbEeF4A2C891d56e72B67a3f21d0cF94f1D7c5911",
    "networkFamily": "evm",
    "custodian": "COINBASE_US"
  }
}
'

{
  "id": "ext_95863ktcdhw27ze8hxgybb24n9",
  "object": "externalAccount",
  "type": "walletExternal",
  "category": "crypto",
  "owner": {
    "kind": "counterparty",
    "counterpartyId": "ctp_yp5z8m7n22svc0vh6edqgcfdat"
  },
  "status": "active",
  "resolvedTransactions": [
    "txn_x9waqqeg1ng6v32c5142zfp89d"
  ],
  "label": "Acme deposits inbound",
  "createdAt": "2026-05-15T18:01:12Z",
  "updatedAt": "2026-05-15T18:01:12Z",
  "walletExternal": {
    "blockchainAddress": "0xeB3eCfb244E94a407bfb1EEcFEDe27D920cc00F5",
    "custodian": "COINBASE_US",
    "networkFamily": "evm"
  }
}

Authorizations

Authorization

string

header

required

Token from POST /auth/token

Headers

Idempotency-Key

string

required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Body

application/json

Create an External Account. Exactly one per-type detail object must be supplied, matching type; the service validates the correct subset and rejects mismatches with 422.

owner

Customer-owned · object

required

Who owns this account - { kind: customer, customerId } or { kind: counterparty, counterpartyId }. Cards must be customer-owned.

Customer-owned
Counterparty-owned

Hide child attributes

owner.kind

enum<string>

required

Owner kind discriminator.

Available options:

customer

owner.customerId

string

required

Owning customer (cus_… or legacy public id).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

type

enum<string>

required

The instrument type. Exactly one matching per-type detail object must be supplied.

Available options:

bankUs,

bankIban,

bankCanada,

card,

walletExternal

label

string

Optional display label.

metadata

object

Free-form key-value pairs stored on the resource and echoed back on reads.

Hide child attributes

metadata.{key}

string

bankUs

object

Required when type = bankUs.

Hide child attributes

bankUs.accountNumber

string

required

US bank account number. Write-only; never returned (reads expose accountNumberLast4).

bankUs.routingNumber

string

required

Nine-digit ABA routing number.

bankUs.accountType

enum<string>

Optional; defaults to checking. Send the account's actual type — an ACH entry with the wrong account type can be returned by the receiving bank (NACHA return codes R03 / R04), which fails the transaction. If you do not know the type, ask the account holder rather than relying on the default.

Available options:

checking,

savings

bankUs.bankName

string

Bank display name.

bankIban

object

Required when type = bankIban.

Hide child attributes

bankIban.iban

string

required

IBAN value. Write-only; never returned (reads expose ibanLast4). Shape ^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$.

bankIban.BIC

string

required

SWIFT BIC (8 or 11 chars).

bankIban.bankAddress

object

Structured bank postal address (canonical Address).

Hide child attributes

bankIban.bankAddress.line1

string

Street address, line 1.

bankIban.bankAddress.line2

string

Street address, line 2.

bankIban.bankAddress.city

string

City.

bankIban.bankAddress.state

string

State / province / region.

bankIban.bankAddress.country

string

ISO 3166-1 alpha-2

bankIban.bankAddress.zipCode

string

ZIP / postal code.

bankIban.countryCode

string

ISO 3166-1 alpha-2. Optional - derived from the IBAN's first two letters when omitted; validated against any supplied value.

bankCanada

object

Required when type = bankCanada.

Hide child attributes

bankCanada.institutionNumber

string

required

Three-digit institution number.

bankCanada.transitNumber

string

required

Five-digit transit number.

bankCanada.accountNumber

string

required

Canadian bank account number (7-12 digits). Write-only; never returned (reads expose accountNumberLast4).

bankCanada.bankName

string

Bank display name.

walletExternal

object

Required when type = walletExternal.

Hide child attributes

walletExternal.blockchainAddress

string

required

Blockchain wallet address. For networkFamily = evm the address must be all-lowercase, all-uppercase, or a valid EIP-55 checksummed form; an inconsistent mixed-case address is rejected as a likely casing typo, and the zero address is rejected. Solana is validated structurally.

walletExternal.networkFamily

enum<string>

required

Crypto network family for a registered external wallet. A walletExternal is registered per family (an EVM address is valid across every EVM chain), and the registration covers every served network in that family.

Available options:

evm,

solana

walletExternal.custodian

enum<string>

required

DestinationCustodian enum value (reused from VA).

Available options:

ANCHORAGE_SG,

ANCHORAGE_US,

AQUANOW_CA,

B2C2_UK,

B2C2_US,

BITGO_SG,

BITGO_US,

BITSTAMP_US,

BVNK_US,

CIRCLE_FR,

CIRCLE_US,

CITIBANK_US,

COINBASE_US,

COINSMART_CA,

COPPER_CH,

COPPER_UK,

CUMBERLAND_DRW_LLC_US,

CUMBERLAND_SG,

EREBOR_BANK_US,

FALCONX_US,

FIDELITY_UK,

FIDELITY_US,

FIREBLOCKS_APAC,

FIREBLOCKS_US,

GALAXY_KY,

GEMINI_US,

KRAKEN_BVI,

KRAKEN_EU_IE,

KRAKEN_UK,

KRAKEN_US,

NUBANK_BR,

PAXOS_US,

RAMP_NETWORK_US,

ROBINHOOD_US,

WINTERMUTE_GB,

SELF_HOSTED,

OTHER

walletExternal.otherCustodian

string

Required iff custodian = OTHER; max 100 chars.

Response

The request has succeeded and a new resource has been created as a result.

A saved payment destination registered for a customer or one of their counterparties. Exactly one of the per-type response detail objects is populated, selected by type. Write-only secrets (full account number, full IBAN) are never present on reads - only their last-4 renderings.

string

External Account ID (ext_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

object

enum<string>

Resource type discriminator. Always "externalAccount".

Available options:

externalAccount

owner

Customer-owned · object

Who owns this account: the customer or one of their counterparties.

Customer-owned
Counterparty-owned

Hide child attributes

owner.kind

enum<string>

required

Owner kind discriminator.

Available options:

customer

owner.customerId

string

required

Owning customer (cus_… or legacy public id).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

ownerDisplayName

string

Server-rendered display name of the owning Customer — lets a list row render "who owns this account" without a second request. Additive next to the owner reference. Present only when owner.kind is customer; absent for counterparty-owned accounts.

customer

object

Resolved id + display name of the owning customer. Present only when owner.kind = customer; absent for counterparty-owned accounts.

Hide child attributes

customer.id

string

required

The OMS customer id (cst_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

customer.name

string

required

Customer display name.

type

enum<string>

The instrument type; determines which detail object is populated.

Available options:

bankUs,

bankIban,

bankCanada,

card,

walletExternal

category

enum<string>

High-level grouping: fiatAccount for bank or card accounts, crypto for wallets. The same value as the instrument category when this account is referenced in a transaction.

Available options:

fiatAccount,

crypto

status

enum<string>

Current lifecycle status. A transition to invalid always fires the externalAccount.statusChanged webhook.

Available options:

active,

pending,

rejected,

invalid,

deleted,

failed

failureReason

enum<string>

Set when status = failed.

Available options:

ereborRejected,

cardProviderRejected,

providerAccountMissing,

cardLimitReached,

cardInUse,

provisioningTimeout,

systemError

failureDetail

object

Structured provider rejection detail. Set when status = failed and the failure was a provider terminal rejection; absent for provisioning timeouts and internal failures.

Hide child attributes

failureDetail.provider

string

The institution that rejected the request — erebor for Erebor Bank, N.A. New providers may be added, so treat the string as free-form rather than a fixed set.

failureDetail.code

string

Vendor machine-readable error code (e.g. INVALID_REQUEST).

failureDetail.message

string

Vendor human-readable message.

failureDetail.details

string[]

Per-field validation messages, each in field: message form.

failureDetail.providerRequestId

string

Vendor request id, for support escalation.

rejectionReason

enum<string>

Why registration was rejected. Present when status is rejected; the key is absent otherwise.

Available options:

countryProhibited,

cardVerificationDeclined,

bankVerificationDeclined,

countryNotSupported

invalidReason

enum<string>

Why the account became unusable after activation, derived from a returned payout. Present when status is invalid; the key is absent otherwise.

Available options:

accountClosed,

accountFrozenByBank,

routingOrAccountNumberInvalid,

accountHolderDeceased,

accountDoesNotSupportTransfers,

payeeNameMismatch,

walletUnreachableOnNetwork,

billingAddressMismatch,

cardExpired,

cardClosedOrLostStolen,

pushToCardUnsupported,

cardDeclinedByIssuer

invalidReasonCode

string

The provider's own code for the failure behind invalidReason, verbatim — for US bank accounts the NACHA return code from the failed payout, e.g. R15. Absent when the provider gave no code, or when the account was invalidated by something other than a returned payment.

Read invalidReason to decide what to do; read this when you need the precise cause for support or reconciliation. invalidReason is a deliberately small set, so several codes map to one member — treat this field as an open vocabulary and do not switch on it. A return code that maps to no invalidReason leaves the account active and sets neither field; the returned payout still fails the transaction, but the unmapped code is not surfaced on the External Account.

label

string

Optional display label.

metadata

object

Free-form key-value pairs supplied at creation or update.

Hide child attributes

metadata.{key}

string

bankUs

object

Populated when type = bankUs.

Hide child attributes

bankUs.accountNumberLast4

string

required

Last four digits of the US bank account number.

bankUs.routingNumber

string

required

Nine-digit ABA routing number (not a secret).

bankUs.accountType

enum<string>

required

The account type on file. Always present.

Available options:

checking,

savings

bankUs.bankName

string

Bank display name.

bankUs.supportedDestinations

object[]

The (asset, rail) pairs this account can be paid over — a per-account answer, not a platform-wide one. For an account provisioned through Coinme Inc. it is the participation list this specific bank reported at registration, narrowed by the rails your project and the platform enable, so it never advertises a rail a payout or Deposit Address create would then refuse. Erebor Bank, N.A. publishes no per-bank participation check, so accounts it provisions report the conservative ach / achSameDay / wire set and rtp stays absent — there, a missing rtp means unverified, not refused. Look for an {asset: usd, network: rtp} pair before choosing rtp as a payout rail.

Hide child attributes

bankUs.supportedDestinations.asset

string

required

Fiat currency, e.g. usd.

bankUs.supportedDestinations.network

enum<string>

required

Rail this account can receive on.

Available options:

ach,

achSameDay,

wire,

rtp

bankUs.supportedDestinations.minimumAmount

string

Minimum transfer amount enforced for this (asset, rail) pair. Absent when no limit is published for the rail — absence is not a claim that the provider enforces none.

bankUs.supportedDestinations.maximumAmount

string

Maximum transfer amount enforced for this (asset, rail) pair. Absent on the same terms as minimumAmount.

bankIban

object

Populated when type = bankIban.

Hide child attributes

bankIban.ibanLast4

string

required

Last four characters of the IBAN.

bankIban.BIC

string

required

SWIFT BIC (8 or 11 chars).

bankIban.countryCode

string

required

ISO 3166-1 alpha-2; derived from the IBAN prefix when not supplied.

bankIban.bankAddress

object

Structured bank postal address (canonical Address).

Hide child attributes

bankIban.bankAddress.line1

string

Street address, line 1.

bankIban.bankAddress.line2

string

Street address, line 2.

bankIban.bankAddress.city

string

City.

bankIban.bankAddress.state

string

State / province / region.

bankIban.bankAddress.country

string

ISO 3166-1 alpha-2

bankIban.bankAddress.zipCode

string

ZIP / postal code.

bankCanada

object

Populated when type = bankCanada.

Hide child attributes

bankCanada.institutionNumber

string

required

Three-digit institution number.

bankCanada.transitNumber

string

required

Five-digit transit number.

bankCanada.accountNumberLast4

string

required

Last four digits of the Canadian bank account number.

bankCanada.bankName

string

Bank display name.

walletExternal

object

Populated when type = walletExternal.

Hide child attributes

walletExternal.blockchainAddress

string

required

The registered blockchain address, as submitted.

walletExternal.networkFamily

enum<string>

required

Available options:

evm,

solana

walletExternal.custodian

enum<string>

required

DestinationCustodian enum value (reused from VA).

Available options:

ANCHORAGE_SG,

ANCHORAGE_US,

AQUANOW_CA,

B2C2_UK,

B2C2_US,

BITGO_SG,

BITGO_US,

BITSTAMP_US,

BVNK_US,

CIRCLE_FR,

CIRCLE_US,

CITIBANK_US,

COINBASE_US,

COINSMART_CA,

COPPER_CH,

COPPER_UK,

CUMBERLAND_DRW_LLC_US,

CUMBERLAND_SG,

EREBOR_BANK_US,

FALCONX_US,

FIDELITY_UK,

FIDELITY_US,

FIREBLOCKS_APAC,

FIREBLOCKS_US,

GALAXY_KY,

GEMINI_US,

KRAKEN_BVI,

KRAKEN_EU_IE,

KRAKEN_UK,

KRAKEN_US,

NUBANK_BR,

PAXOS_US,

RAMP_NETWORK_US,

ROBINHOOD_US,

WINTERMUTE_GB,

SELF_HOSTED,

OTHER

walletExternal.otherCustodian

string

Set when custodian = OTHER.

walletExternal.supportedDestinations

object[]

The (asset, network) pairs this wallet can receive, derived from networkFamily ({usdc, usdt} across the family's served networks).

Hide child attributes

walletExternal.supportedDestinations.asset

string

required

Stablecoin symbol, e.g. usdc / usdt.

walletExternal.supportedDestinations.network

enum<string>

required

Network the asset can be delivered on, e.g. ethereum / base / solana.

Available options:

ethereum,

polygon,

base,

solana,

tron

card

object

Populated when type = card.

Hide child attributes

card.cardNumberLast4

string

Last four digits of the card PAN.

card.cardProvider

enum<string>

Card brand, derived server-side from the PAN.

Available options:

visa,

mastercard,

amex,

discover

card.cardType

enum<string>

Card funding type, derived server-side. Only debit today.

Available options:

debit,

credit,

prepaid

card.expiryMonth

integer<int32>

Card expiry month (MM).

card.expiryYear

integer<int32>

Card expiry year (YYYY).

card.billingAddressSource

enum<string>

Whether the stored billing address was supplied on the request or filled from the owning customer's address.

Available options:

provided,

customerDefault

resolvedTransactions

string[]

Transaction ids that this registration submitted for sender-attribution release. Returned ONLY on the POST create response, and only when registering this walletExternal matched held inbounds. Attribution is async: each entry is submitted to the provider from awaitingAction.awaitingSenderAttribution and moves to processing.fundsPulled once settlement confirms — so an immediate GET of an id may still show awaitingAction. Omitted on GETs (the create path is the only writer).

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

createdAt

string<date-time>

When the external account was registered.

updatedAt

string<date-time>

When the external account was last updated.

Overview

Move money

Routes

External Payment Methods

Platform

Create an External Account

Authorizations

Headers

Body

Response