Deposit addresses - Polygon Developer Docs

A deposit address is a reusable on-chain address assigned to a customer. When crypto arrives at the address, OMS automatically creates and executes a transaction that converts it and pays out to a configured fiat destination (cryptoToFiatAccount). No developer action is required after the address is provisioned. Deposit addresses are persistent. OMS keeps them active until they are frozen or closed.

Deposit addresses must be enabled for your project before you can create them, and the customer must be provisioned for them. To get set up, share your use case below.

Contact us

Tell us about your on-ramp flow and we’ll enable deposit addresses for your project.

How it works

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

Detects the inbound transfer on the source chain.
Creates a transaction with a typed precursor of depositAddress, carrying the depositAddressId and its deposit instructions.
Moves the transaction directly to processing (there is no quote step, because pricing cannot be locked before the funds arrive).
Converts the incoming crypto and delivers it to the configured fiat destination.

The resulting transaction carries sourceToDestination: "cryptoToFiatAccount" and 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_bankUs_...",
      "asset": "usd",
      "network": "ach",
      "accountHolder": "customer"
    }
  },
  "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 (for example, `ethereum` or `base`).
`destination`	Yes	A registered bank-type external account (`bankUs`, `bankIban`, or `bankCanada`) on the standard side shape. OMS validates the `details` (asset, network, and `accountHolder`) against the resolved external account. A `bankUs` destination with `network: "wire"` may also carry an optional `details.memo`; see Wire payout memo.
`sponsorGas`	No	When `true` (the default), OMS absorbs the on-chain 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: null. Provisioning populates the OMS-owned inlet address asynchronously, and the address moves from pending to active once the instructions are ready.

Deposit instructions

The depositInstructions field carries the details to display in your UI. It is null until provisioning completes:

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

Field	Meaning
`address`	The OMS-owned on-chain inlet address for this deposit address. Give this to your customer.
`asset`	The stablecoin the address accepts (matches `expectedSourceAsset`).
`network`	The chain the address accepts funds on (matches `expectedSourceNetwork`).
`expiresAt`	Reserved for a future provider-imposed inlet expiry. Null today.

Crypto sent to address is converted and paid out to the configured fiat destination.

Wire payout memo

For a bankUs destination with network: "wire", set an optional destination.details.memo on create or on a PATCH that replaces destination. OMS carries the value on every outbound wire payout from the deposit address in place of the standard generated memo.

Rule	Value
Type	Optional string or `null`, up to 140 characters.
Character set	Letters, digits, space, and `/?:().,'+-`.
Honored on	`bankUs` destinations with `network: "wire"`.
Edits	Take effect on future payouts only. In-flight payouts keep the memo they were built with.
Clearing	Set `memo` to `null` (or omit `details.memo` on a `PATCH` that replaces `destination`) to fall back to the generated memo.

memo is not honored on network: "ach" or network: "achSameDay" destinations, on virtual accounts, or on quote requests. A non-empty value on those surfaces is rejected with 422 memoNotSupported. A value outside the allowed character set or over 140 characters is rejected with 422 validationError. An omitted, null, or whitespace-only value is accepted everywhere.

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

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, startingAfter, and endingBefore; each page returns nextCursor, previousCursor, and hasMore. GET /deposit-addresses/{depositAddressId} fetches a single deposit address by ID.

Updating

PATCH /deposit-addresses/{depositAddressId} accepts destination (re-point to a different bank-type external account), label, metadata, and sponsorGas; any other key in the body is rejected with 400. Re-pointing destination to a healthy bank 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. There is no delete endpoint for deposit addresses.

Statuses

Status	Meaning
`pending`	Created; OMS is provisioning the on-chain inlet address. `depositInstructions` is null.
`active`	Provisioned and accepting deposits.
`frozen`	Temporarily suspended; inbound deposits are not processed.
`closed`	Permanently closed.
`failed`	Provisioning failed; `failureReason` identifies the cause.
`inactiveActionRequired`	The destination external account is no longer usable. Re-point `destination` to a healthy account to recover to `active`.

Simulating inbound deposits

In sandbox, you can simulate an inbound transfer to test your webhook and reconciliation flows without moving real funds. This endpoint is available in non-production environments only and returns 404 in production. POST /deposit-addresses/{depositAddressId}/simulate/inbound-transfer with the amount to simulate:

{
  "amount": "100.00"
}

The amount is a decimal string in whole units. The asset and network are resolved server-side from the deposit address (limited to ethereum, base, and solana). The response echoes the simulated deposit and returns a synthetic transactionHash you can correlate against the webhook:

{
  "depositAddressId": "da_...",
  "asset": "usdc",
  "network": "ethereum",
  "amount": "100.00",
  "status": "submitted",
  "submittedAt": "2026-01-15T10:32:00Z",
  "transactionHash": "0x..."
}

Use the simulate endpoint to exercise the full auto-created transaction path in sandbox: the simulated inbound funds create a cryptoToFiatAccount transaction just as a real deposit would.

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 (on-chain)	Fiat (bank rail)
Deposit details	On-chain inlet address	Bank account number and routing
Direction	`cryptoToFiatAccount`	`fiatAccountToCrypto`
Destination	Fiat account	Crypto 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 a deposit address pays out to
Transaction lifecycle: statuses, sub-statuses, and webhook events for the auto-created transaction

Contact us

​How it works

​Creating a deposit address

​Deposit instructions

​Wire payout memo

​Listing and retrieving

​Updating

​Statuses

​Simulating inbound deposits

​Deposit address vs. virtual account

​Related

How it works

Creating a deposit address

Deposit instructions

Wire payout memo

Listing and retrieving

Updating

Statuses

Simulating inbound deposits

Deposit address vs. virtual account

Related