balance-accounts

Create a balance account

Creates a USD account that holds a balance. Use product STANDARD (default) for a fiat hold funded by bank transfer, or YIELD for a reserve-backed hold that can earn configurable yield. Pay out by creating a transfer sourced from this account. Requires the matching customer capability (USD_BALANCE or USD_YIELD). Use the Idempotency-Key header to safely retry on network failure.

post/v1/balance-accounts

Headers

X-API-Keystring

API key

Idempotency-Keystring

Optional idempotency key. When supplied, a retry with the same key replays the original response (24h TTL) instead of being rejected as a duplicate.

Request body

customerIdstring required

Customer ID

product'STANDARD' | 'YIELD'

Balance product. STANDARD holds fiat USD. YIELD holds a reserve-backed token that can earn configurable yield. Defaults to STANDARD.

externalReferencestring

Client-provided external reference

Example request

{
  "customerId": "cus_abc123",
  "product": "STANDARD",
  "externalReference": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "nickname": "Main Checking Account",
    "purpose": "Business operations",
    "tags": [
      "primary",
      "operations"
    ]
  }
}

Response

Balance account created successfully

idstring required

Account ID (vba_xxx for virtual bank, vwa_xxx for virtual wallet, inb_xxx for infinite bank, inw_xxx for infinite wallet, eba_xxx for external bank, ewa_xxx for external wallet, pba_xxx for provider balance)

customerIdstring required

Customer ID

Account type

externalReferencestring

Client-provided external reference for mapping to your system

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

Account status

currencyCodesstring[]

Currency codes supported by this account

isThirdPartyboolean

Is this account owned by a third party?

counterpartyIdstring nullable

Counterparty ID when this is a third-party recipient account

referenceIdstring

Client-provided reference ID

originCapableboolean nullable

Whether this account can be used as the canonical transfer origin.

originAccountIdstring nullable

Canonical origin account ID when this account is a virtual alias.

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. Returns false if an existing account was returned (idempotent behavior).

holdsBalanceboolean

Present and true when this is a balance account (USD or stablecoin). Deposits credit the account instead of being swept, and the balance can fund transfers. See GET /v1/accounts/{id}/balance.

paymentRailstring

Payment rail for provider balance accounts (e.g. ETHEREUM). Omitted for other account types.

lastSentAtstring date-time nullable

Timestamp of the last transfer sent from this account

lastReceivedAtstring date-time nullable

Timestamp of the last transfer received to this account

screeningStatusstring nullable

Changes

Changed in 8 of the 19 revisions of this API.147

Sep 24, 2026c5a90949ca591See the full diff
- ○
  added the required property ////////////// to the response with the status
  response-required-property-added
Sep 24, 2026bb2702829ce01See the full diff
- ●
  added the new ROBINHOOD enum value to the /////////////// response property for the response status
  response-property-enum-value-added
Sep 22, 2026916d2367a8f812See the full diff
- ▲
  the response property // became nullable for the status
  response-property-became-nullable
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Sep 20, 20267788dddbcb212See the full diff
- ○
  added the optional property //////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
Sep 19, 202616bbb87acca91See the full diff
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
Sep 18, 2026f0ba578043a91See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Sep 5, 202670223aefae8c1See the full diff
- ●
  added the new LIVENESS_CHECK enum value to the /////// response property for the response status
  response-property-enum-value-added
Sep 4, 20267d6487f295d72See the full diff
- ●
  added the new MESTA enum value to the ////////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new MESTA enum value to the //////////// response property for the response status
  response-property-enum-value-added

Full history