> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.
# Deposit addresses
> Reusable on-chain addresses that auto-convert incoming crypto and pay out to a bank account.
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.
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:
1. Detects the inbound transfer on the source chain.
2. Creates a transaction with a typed `precursor` of `depositAddress`, carrying the `depositAddressId` and its deposit instructions.
3. Moves the transaction directly to `processing` (there is no quote step, because pricing cannot be locked before the funds arrive).
4. Converts the incoming crypto and delivers it to the configured fiat destination.
The resulting transaction carries `sourceToDestination: "cryptoToFiatAccount"` and follows the standard [transaction lifecycle](/payments/core-concepts/transaction-lifecycle), including webhook events.
## Creating a deposit address
Create a deposit address with `POST /deposit-addresses`:
```json theme={null}
{
"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](/payments/external-accounts) (`bankUs`, `bankIban`, or `bankCanada`) on the standard side shape. OMS validates the `details` (asset, network, and `accountHolder`) against the resolved external account. |
| `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:
```json theme={null}
{
"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.
## 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` with the amount to simulate:
```json theme={null}
{
"amount": { "value": "5000" }
}
```
The `value` is the stablecoin amount in cents (greater than 0 and at most 100000). The currency and network are resolved server-side from the deposit address. The response echoes the simulated deposit and returns a synthetic `transactionHash` you can correlate against the webhook:
```json theme={null}
{
"depositAddressId": "da_...",
"amount": { "value": "5000", "currency": "usdc" },
"network": { "...": "..." },
"transactionHash": "0x...",
"status": "submitted",
"submittedAt": "2026-01-15T10:32:00Z"
}
```
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 |
## Related
* [Deposit addresses guide](/payments/guides/deposit-addresses): walkthrough of the inbound flow and webhook handling
* [Virtual accounts](/payments/virtual-accounts): the fiat equivalent, a bank account number that auto-converts to crypto
* [External accounts](/payments/external-accounts): registering the bank account a deposit address pays out to
* [Transaction lifecycle](/payments/core-concepts/transaction-lifecycle): statuses, sub-statuses, and webhook events for the auto-created transaction