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.
Authorizations
Token from POST /auth/token
Headers
Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.
Body
Create a Deposit Address: the expected inbound asset/network pair plus the bank destination that receives the converted funds.
Owning customer ID (cst_ prefix).
Asset of the inbound crypto the DA expects. "usdc" | "usdt" (lowercase).
Network senders will use for the inbound deposit. Availability is per-provider rather than one global list: a network outside the CryptoNetwork vocabulary, or one the provider that issues your Deposit Address does not serve, is rejected with 422 ExpectedSourceNetworkUnsupported. GET /networks reports the networks your project can currently receive on.
ethereum, polygon, base, solana, tron, bnb Where the Deposit Address delivers converted funds. Pick a type: a bank account (bankUs, on ach / achSameDay / wire / rtp; bankIban; bankCanada) or a fiat balance wallet (walletFiat) for crypto-to-fiat, or a registered external crypto wallet (walletExternal) for crypto-to-crypto. A walletExternal network must be one the Deposit Address's own provider serves — per provider, not one global list — or it is rejected with 422 DestinationNetworkUnsupported. walletFiat credits the customer's own fiat wallet by internal book transfer, so the resolved destination instrument reads network: bookTransfer. walletCrypto is rejected with 422 DestinationWalletCryptoNotSupported. The side details (asset and network) are validated against the resolved External Account or wallet.
- US bank account
- IBAN bank account
- Canadian bank account
- OMS wallet
- External wallet (registered)
- Fiat wallet
Registered crypto return destination, for operations-triggered returns of stranded inbound deposits.
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).
Partner display label.
Free-form key-value pairs stored on the resource and echoed back on reads.
Response
The request has succeeded and a new resource has been created as a result.
A reusable crypto deposit configuration. Senders deposit the expected asset/network to the assigned on-chain address; OMS converts and delivers the funds to the configured bank destination automatically, creating a transaction per inbound deposit.
A Deposit Address is permanent: there is no delete operation for a Deposit Address. The on-chain address is published to senders and can receive a deposit at any time, so removing the record would strand any funds that arrive afterwards with nothing to route them to. The terminal closed status is not a partner call either: it is reached through the provider's own lifecycle or an operator action, and a closed Deposit Address is still not deleted — it stays retrievable by id. To stop using one, stop handing its address to senders. PATCH destination changes where deposits that arrive afterwards are delivered; a deposit that has already arrived keeps the destination that was in effect when it arrived. Contrast a Virtual Account, which does support DELETE because its close is a real provider-side account closure.
The customer that owns this record.
Deposit Address ID (da_ prefix).
^[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})$Current lifecycle status of the deposit address.
pending, active, frozen, closed, failed, inactiveActionRequired What a sender deposits and where. The asset and network are there from creation; the on-chain address is left out until the provider issues it. A provider that issues it during the create call returns it in the create response; otherwise the deposit address turns active once it is issued, and reading it returns the address from then on.
The account deposits are paid out to. A bank account carries no rail and no ACH options; they are on payout.
- OMS wallet
- External wallet
- Fiat wallet
- US bank account
- IBAN bank account
- Canadian bank account
How a deposit is paid out to a bank or walletFiat destination: the rail and, on ach and achSameDay, the ACH options. Left out for a crypto destination.
Whose name a payout from this Deposit Address goes out under: the holder stored when it was created, or its provider's for an address created before holders were stored. Left out for a walletFiat destination or none.
Where inbound crypto is sent back when its payout cannot be completed. Present only when you set one.
- OMS wallet
- External wallet
The return destination types this Deposit Address accepts, derived by OMS from its issuing provider and its depositInstructions.network with the same rules a returnDestination is validated against on create and PATCH. walletExternal is listed when the provider serves this network for the network's External Account family; walletCrypto is listed when the provider can return to an OMS wallet. Read-only. Left out when no return destination can be configured on this Deposit Address and when OMS could not determine it; the create and PATCH validation stays authoritative.
The type of a crypto return destination: an OMS wallet (walletCrypto) or a registered external wallet (walletExternal).
walletCrypto, walletExternal Why the deposit address failed. Present only when status is failed.
What you must do for a deposit address in inactiveActionRequired: set a new destination. Present only in that status.
Whether OMS absorbs the on-chain gas cost for the destination delivery. Present only when true, the only value a create or update request accepts.
The institution that issues and custodies this Deposit Address — currently "Erebor Bank, N.A." or "Coinme Inc.". Assigned by OMS from your project's configuration. It determines which asset and network pairs you can create a deposit address for: an unsupported pair is rejected at create time with 422 depositAddressAssetNetworkNotSupported, which names the same provider in details.provider. Read it when you need to tell an end user or a support ticket which institution is holding the funds. It is not the name a payout is sent under, which is the payout transfer's originatorName and can name a different company. New providers may be added, so treat the string as free-form rather than a fixed set. Read-only; omitted when the issuing institution is not recognised.
Present, and true, when a sender's wallet must be registered as a walletExternal External Account under this Deposit Address's customer before it deposits. Derived from the issuing provider, never supplied by you: Deposit Addresses issued by Erebor Bank, N.A. accept a deposit only from a registered counterparty wallet, while those issued by Coinme Inc. accept a deposit from any crypto address and leave the field out. When true, a deposit from an unregistered address still arrives, but its transaction parks on a senderAttribution hold until you register a matching External Account (the hold's matchableExternalAccountCriteria says what will match) and fails at the hold's deadline if you never do — so capture the sender's address up front. Read it per Deposit Address rather than caching it per project. Read-only. Also left out when OMS cannot identify the issuing provider.
Partner display label.
Free-form key-value pairs supplied at creation or update.
When the deposit address was created.
When the deposit address was last updated.