Sign in

v1

latestOpenAPI 3.0.32026-07-2650226215.9 KB
DepositAddress

Create a Deposit Address

Create a Deposit Address. Requires deposit addresses to be enabled for your project and the customer to be provisioned with the banking provider. The address starts pending and becomes active once the inbound on-chain address is assigned.

post/deposit-addresses

Headers

Idempotency-Keystring required

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

Request body

customerIdstring required

Owning customer (cus_… or legacy public id).

expectedSourceAssetstring required

Asset of the inbound crypto the deposit address expects. "usdc" | "usdt" (lowercase).

expectedSourceNetworkstring required

Network of the inbound crypto the deposit address expects. Drawn from the served-network enum; excludes polygon/ink/sui.

sponsorGasboolean

When true, OMS absorbs the on-chain gas cost for the destination delivery. Only true is currently supported. Ignored for non-crypto destinations (no on-chain leg).

labelstring

Partner display label.

metadataobject

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

Example request

{
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "expectedSourceAsset": "usdc",
  "expectedSourceNetwork": "ethereum",
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "ext_fky491gakzj0dd46qb6whsr2vq",
      "asset": "usd",
      "network": "ach",
      "accountHolder": "customer"
    }
  },
  "sponsorGas": true,
  "label": "Alice deposit address"
}

Response

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

idstring

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

object'depositAddress'

Resource type discriminator. Always "depositAddress".

customerIdstring

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

status'pending' | 'active' | 'frozen' | 'closed' | 'failed' | 'inactiveActionRequired'

Lifecycle of a Deposit Address. pending: awaiting on-chain address assignment. active: accepting deposits. frozen: deposits held by compliance. inactiveActionRequired: destination unusable, re-point destination to recover. closed: permanently disabled. failed: provisioning failed.

statusReasonstring

Human-readable explanation of the current status.

expectedSourceAssetstring

Asset of the inbound crypto the deposit address expects.

expectedSourceNetworkstring

Network of the inbound crypto the deposit address expects.

failureReason'provisioningTimeout' | 'systemError' | 'ereborRejected' | 'intlBankAccountCreateRejected' | 'noMatchingNetwork' | 'blockchainAddressInUse' | 'bankAccountInUse'

Closed enum carried on DA when status = "failed". camelCase per partner channel naming convention.

sourceToDestination'cryptoToCrypto' | 'cryptoToCash' | 'cryptoToFiatAccount' | 'cashToCrypto' | 'fiatAccountToCrypto' | 'fiatAccountToFiatAccount'

Composite of source and destination instrument categories, inferred from each side. The cash corridors (cryptoToCash, cashToCrypto) are derived from a cash-pickup destination / cash-in source respectively; the rest map straight from the internal corridor type.

sponsorGasboolean

Whether OMS absorbs the on-chain gas cost for the destination delivery. Persisted from the create/update request (currently only true is accepted).

labelstring

Partner display label.

metadataobject

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

createdAtstring date-time

When the deposit address was created.

updatedAtstring date-time

When the deposit address was last updated.