Deposit addresses - Polygon Developer Docs

A deposit address is a reusable onchain address assigned to a customer. When crypto arrives at the address, OMS automatically creates and executes a transaction that delivers it to the configured destination: converted and paid out to a bank account or fiat wallet (cryptoToFiatAccount), or forwarded as crypto to a registered external wallet (cryptoToCrypto). No developer action is required after the address is provisioned, unless the address only accepts deposits from registered sender wallets (see Sender wallet registration). Deposit addresses are persistent. OMS keeps them active until they are frozen or closed.

How it works

Once a deposit address is provisioned, you display its onchain address to the customer. When a supported stablecoin arrives at that address, OMS:

Detects the inbound transfer on the source chain.
Creates a transaction whose precursor is { "type": "depositAddress", "id": "da_..." }. Dereference the deposit address by that id for its inlet address and instructions.
Moves the transaction directly to processing (there is no quote step, because pricing cannot be locked before the funds arrive).
Delivers the funds to the configured destination, converting them to fiat first when the destination is a bank account or fiat wallet.

The resulting transaction follows the standard transaction lifecycle, including webhook events.

Creating a deposit address

Create a deposit address with POST /deposit-addresses:

{
  "customerId": "cst_...",
  "expectedSourceAsset": "usdc",
  "expectedSourceNetwork": "ethereum",
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "ext_...",
      "asset": "usd",
      "network": "ach"
    }
  },
  "label": "Inbound USDC deposits"
}

Field	Required	Meaning
`customerId`	Yes	The customer the address belongs to.
`expectedSourceAsset`	Yes	The inbound stablecoin the address expects: `usdc` or `usdt` (lowercase).
`expectedSourceNetwork`	Yes	The chain the address accepts funds on. One of the supported crypto networks. Availability depends on the provider that issues the address; an unsupported network returns `422 ExpectedSourceNetworkUnsupported`. `GET /networks` lists what your project can receive on.
`destination`	Yes	Where deposits are delivered: a registered bank-type external account (`bankUs` on `ach`, `achSameDay`, `wire`, `rtp`, `instant`, or `intraBank`; `bankIban`; or `bankCanada`), the customer’s fiat wallet (`walletFiat`), or a registered external wallet (`walletExternal`, see Forward deposits to a wallet). With `instant`, name the instant rail in `details.instantRail` (`rtp` or `fednow`); `rtp` is accepted as an alias of `instant`. With `intraBank`, name the same-bank rail in `details.intraBankRail`; it requires your project’s configured outgoing US rails to include that option (`422 IntraBankNotSupported` otherwise). OMS validates the `details` against the resolved destination. Certain destinations accept an optional `details.memo` or, for ACH, `details.companyDiscretionaryData`; see Payout memo.
`returnDestination`	No	Where to return the inbound crypto if the payout cannot be completed: a multi-asset OMS wallet or a registered external wallet, plus the `network` to return on, which must match `expectedSourceNetwork`. When omitted, funds return to the onchain sender. See failed transactions and returns.
`sponsorGas`	No	When `true` (the default), OMS absorbs the onchain gas cost for the destination delivery. Only `true` is currently supported.
`label`, `metadata`	No	A display label and free-form string metadata.

The 201 response returns the deposit address with depositInstructions carrying the accepted asset and network. The onchain address is left out until the provider issues it; a provider that issues it during the create call returns it in the 201 response, and otherwise the deposit address moves from pending to active once the address is issued.

Deposit instructions

The depositInstructions field carries the details to display in your UI. asset and network are present from creation, and address is present once the provider issues it:

{
  "asset": "usdc",
  "network": "ethereum",
  "address": "0xabc123..."
}

Field	Meaning
`asset`	The stablecoin the address accepts: the `expectedSourceAsset` it was created with.
`network`	The chain the address accepts funds on: the `expectedSourceNetwork` it was created with.
`address`	The onchain address senders deposit to. Give this to your customer. Left out until the provider issues it.

Crypto sent to address is delivered to the configured destination.

The OMS-managed wallet that backs a deposit address is reserved for that address’s auto-conversion flow. Referencing the same custodial wallet on a quote, a transaction, or a cash-in is refused with 422 WalletBoundToCustodialFlow. The wallet is also filtered out of a project-wide wallet listing so it does not appear as an independent balance. Use a different wallet for those flows.

Sender wallet registration

Some deposit addresses accept a deposit only from a sender wallet you have registered in advance. The deposit address response tells you which kind you have: requiresCounterpartyWalletRegistration is present and true when each sender’s wallet must be registered as a walletExternal external account under the deposit address’s customer before it deposits.

{
  "id": "da_...",
  "status": "active",
  "provider": "...",
  "requiresCounterpartyWalletRegistration": true,
  "depositInstructions": { "asset": "usdc", "network": "ethereum", "address": "0xabc123..." }
}

OMS derives the field from the provider that issued the deposit address; you never set it. When the field is absent, the address accepts deposits from any onchain address. The field is also left out when OMS cannot identify the issuing provider, which is the case when provider is absent too. Read it from each deposit address rather than caching one value for your project. When the field is true, register each sender’s wallet with POST /external-accounts as a walletExternal account owned by the customer, or by one of the customer’s counterparties when someone else is sending, before you share depositInstructions.address. An EVM address registered once covers every EVM chain. The deposit addresses guide walks through this. A deposit from an unregistered wallet still arrives, but OMS cannot attribute it. Its transaction moves to awaitingAction with subStatus: awaitingAction.awaitingSenderAttribution and a hold naming the wallet to register:

"hold": {
  "code": "senderAttribution",
  "message": "The sender of this deposit is not identified. Register its wallet as an external account to release the deposit.",
  "deadline": "2026-06-14T17:32:48.000Z",
  "match": { "address": "0xeB3eCfb244E94a407bfb1EEcFEDe27D920cc00F5", "network": "evm" }
}

Registering a walletExternal account for hold.match.address on hold.match.network releases the deposit, and the transaction continues to processing. Release is asynchronous; see Released sender-attribution holds. If no matching account is registered by hold.deadline, the transaction fails with failed.attributionTimeout.

Forward deposits to a wallet

A deposit address can forward inbound crypto to a wallet instead of a bank account. Set the destination to a registered walletExternal external account, referenced by its ext_ ID. Raw blockchain addresses are not accepted, and a walletCrypto destination is rejected with 422 DestinationWalletCryptoNotSupported.

"destination": {
  "type": "walletExternal",
  "details": { "id": "ext_...", "asset": "usdc", "network": "polygon" }
}

Each deposit creates a cryptoToCrypto transaction that delivers the funds to the wallet. The destination network must be one the deposit address’s provider serves, or the create is rejected with 422 DestinationNetworkUnsupported. To forward deposits to a custodial wallet owned by another customer in your project, such as an omnibus account, register that wallet’s address as a walletExternal external account under the depositing customer and use its ext_ ID. OMS settles the delivery as an internal ledger movement, with no onchain transfer and no network fee.

Payout memo

A deposit address destination can carry an optional payment memo that OMS delivers to the beneficiary’s bank with each payout. Set destination.details.memo on create or on a PATCH that replaces destination.

Rail	Character set	Max length
`bankUs` with `network: "ach"` or `"achSameDay"` (carried as the ACH addenda)	Uppercase letters, digits, space, and `.&()-+=':?@_#%`	80
`bankUs` with `network: "wire"`, `"rtp"`, or `"instant"`	Letters, digits, space, and `/?:().,'+-`	140
`bankIban` or `bankCanada` with `network: "swift"`	Letters, digits, space, and `/?:().,'+-`	140

The published schema’s paymentMemo pattern is the union of the ACH addenda and ISO 20022 character sets. The published pattern is deliberately permissive so a client validating locally will not reject a memo the server would have accepted; the narrower per-rail rules above are still enforced server-side on write, with a 422 on violation. OMS reads the memo when it builds each payout, so an edit applies only to payouts built after it. A payout already sent keeps the memo it was built with. Set memo to null, omit it, or send only whitespace to use no memo of your own; the payout then carries the memo OMS composes for the rail, if any. A memo outside its rail’s character set or length is rejected server-side with 422. The CAD local leg of bankCanada has no remittance field, so a non-empty memo there is rejected with 422 MemoNotSupported.

pattern and maxLength describe the normalized memo: the server trims leading and trailing whitespace before validating. A whitespace-only memo, or a 140-character memo wrapped in spaces, is accepted after trimming even though a strict local check against the raw string would reject it.

The same memo field is available on virtual account bank destinations, which offer no rtp rail, and on quotes with a walletFiat source or with a walletCrypto source paying a bankUs destination. Any other quote corridor rejects a non-empty memo with 422 MemoNotSupported.

{
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "ext_...",
      "asset": "usd",
      "network": "wire",
      "memo": "INVOICE 4482 CUSTOMER 991"
    }
  }
}

ACH company discretionary data

For a bankUs destination with network: "ach" or network: "achSameDay", set an optional destination.details.companyDiscretionaryData. OMS carries the value in the NACHA batch header on every outbound ACH payout from the deposit address. This is the originator’s internal metadata and never reaches the beneficiary; it is distinct from memo, which does. Responses report the value as payout.companyDiscretionaryData.

Rule	Value
Type	Optional string or `null`, up to 20 characters.
Character set	Uppercase NACHA set: `A-Z`, `0-9`, space, and `& - . $ * / # @ %`.
Honored on	`bankUs` destinations with `network: "ach"` or `network: "achSameDay"`.
Rejected on	`bankUs` with `network: "wire"`, `"rtp"`, or `"instant"`; `422 MemoNotSupported`.

Destination and payout rail

In responses, destination is the typed instrument deposits are paid out to, with type, id, asset, and a details block. A bank account destination carries no rail; the rail and ACH options are reported next to it in payout:

"destination": {
  "type": "bankUs",
  "id": "ext_...",
  "asset": "usd",
  "details": {
    "bankName": "Example Bank, N.A.",
    "accountNumberLast4": "1234",
    "routingNumber": "123456789",
    "accountType": "checking"
  }
},
"payout": {
  "rail": "ach",
  "secCode": "ppd"
}

payout.rail is the rail payouts move on. On ach and achSameDay, payout also carries secCode, derived from the destination owner’s and the customer’s entity type and left out while either is unknown, and companyDiscretionaryData when you set it. A crypto destination has no payout.

Payout origin

Deposit address responses and webhook payloads carry a top-level payoutOrigin. It describes whose name a payout from the address is sent under: the holder stored when the deposit address was created, with the customer’s legal name resolved onto accountHolderName where applicable. A walletFiat destination or an address with no payout destination carries no payoutOrigin. See the shared payout origin shape.

Customer reference

Deposit addresses carry a customer reference resolving the owning customer in one hop:

"customer": { "id": "cst_..." }

Read the customer’s name and status from the customer resource. Render the destination from its details block; see Rendering an instrument and the shared customer reference.

Listing and retrieving

GET /deposit-addresses lists deposit addresses across every customer in your organization. Both filters are optional: customerId scopes the list to one customer, and status to one lifecycle state. Paginate with limit (default 50, maximum 100), startingAfter, and endingBefore. Pass a page’s nextCursor as startingAfter for the next page, or its previousCursor as endingBefore for the previous one. Cursors are opaque; do not parse them. GET /deposit-addresses/{depositAddressId} fetches a single deposit address by ID.

Updating

PATCH /deposit-addresses/{depositAddressId} accepts destination (re-point to a different destination), returnDestination, label, metadata, and sponsorGas; any other key in the body is rejected with 400. Re-pointing destination to a healthy external account recovers a deposit address from inactiveActionRequired back to active. A re-point on an already active address updates the target without a status transition. Deposit address responses also carry a read-only returnDestinationTypes array that lists the walletCrypto and walletExternal return targets this address accepts, derived from the issuing provider and depositInstructions.network. An empty array means no return destination can be configured. A deposit address is permanent: there is no delete endpoint. The onchain 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 reached through the provider’s own lifecycle or an operator action, and a closed address stays retrievable by ID. To stop using one, stop handing its address to senders.

Statuses

Status	Meaning
`pending`	Created; OMS is waiting for the provider to issue the onchain address. `depositInstructions.address` is left out.
`active`	Provisioned and accepting deposits.
`frozen`	Deposits are held, for example for a compliance review. Set by the provider.
`closed`	Permanently closed.
`failed`	Provisioning failed; the `failure` object identifies the cause.
`inactiveActionRequired`	The destination external account is unusable. A `hold` with `code: payoutDestinationMissing` says what to do: re-point `destination` to a healthy account to recover to `active`.

Simulating inbound deposits

Sandbox deposit addresses accept testnet transfers. Send testnet stablecoins to the address from a public testnet faucet or wallet, and OMS reacts to the onchain confirmation as it would to a mainnet deposit: the transaction is auto-created and moves through the transaction lifecycle, firing the same webhook events. There is no simulation endpoint for deposit addresses. Virtual accounts have one (see Simulating inbound deposits) because bank rails have no public testnet.

Webhook events

Event	Fires when
`depositAddress.created`	The address was created (`status: pending`).
`depositAddress.statusChanged`	The address’s status changed. `previousStatus` names the status it left.
`depositAddress.updated`	An announced field changed; `changedFields` names it (`destination`, `payout`, `returnDestination`, `label`, `metadata`, or `depositInstructions`).

Each deposit also creates a transaction that fires its own transaction.* and transfer.* events. See the webhook events catalog.

Deposit address vs. virtual account

Both are persistent auto-route configurations. The difference is which side is fiat:

	Deposit address	Virtual account
Incoming funds	Crypto (onchain)	Fiat (bank rail)
Deposit details	Onchain inlet address	Bank account number and routing
Direction	`cryptoToFiatAccount` or `cryptoToCrypto`	`fiatAccountToCrypto` or `fiatAccountToFiatAccount`
Destination	Bank account, fiat wallet, or external crypto wallet	Crypto wallet, bank account, or fiat wallet

Deposit addresses guide: walkthrough of the inbound flow and webhook handling
Virtual accounts: the fiat equivalent, a bank account number that auto-converts to crypto
External accounts: registering the bank account or wallet a deposit address delivers to
Transaction lifecycle: statuses, sub-statuses, and webhook events for the auto-created transaction
Failed transactions and returns: where inbound crypto goes when the payout cannot complete, and how to configure it

​How it works

​Creating a deposit address

​Deposit instructions

​Sender wallet registration

​Forward deposits to a wallet

​Payout memo

​ACH company discretionary data

​Destination and payout rail

​Payout origin

​Customer reference

​Listing and retrieving

​Updating

​Statuses

​Simulating inbound deposits

​Webhook events

​Deposit address vs. virtual account

​Related

How it works

Creating a deposit address

Deposit instructions

Sender wallet registration

Forward deposits to a wallet

Payout memo

ACH company discretionary data

Destination and payout rail

Payout origin

Customer reference

Listing and retrieving

Updating

Statuses

Simulating inbound deposits

Webhook events

Deposit address vs. virtual account

Related