> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Deposit addresses

> Reusable receive addresses, the deposits they record, their states, the manual check and the events.

A deposit address is a reusable on-chain address that belongs to one account on one chain, with no amount, no expiry and no order attached. Every transfer that lands on it becomes its own `Deposit`, which settles to the account's settlement destination.

## When to use it

| | Deposit address | Receive payment |
| - | - | - |
| Amount | Any amount at or above the asset's minimum | One fixed amount |
| Lifetime | Permanent | Expires, 60 seconds to 24 hours |
| Your reference | None. Each arrival is a separate `Deposit` | `externalReference` on the payment |
| Fees and destination | Frozen per deposit, at detection | Frozen at payment creation |
| Fits | A returning customer topping up the same account | One order or invoice |

Do not create a payment to obtain an address, and do not treat one deposit as one order: a deposit carries nothing that ties it to an order. See [Payments](/concepts/payments) and [Depositing funds](/payments/depositing-funds#choose-a-route).

## Before you issue one

The account needs an active preferred settlement destination, a connected wallet on a settlement chain. Without one, issuing is refused with `400 bad_request`. See [Wallets and handles](/concepts/wallets-and-handles#link-wallets).

Then read the network catalog. It is read-only and safe to cache for a minute.

```bash theme={null}
curl https://staging-api-v2.stableyard.fi/v2/deposit-networks \
  -u "$APP_ID:$APP_SECRET"
```

| Field | What it tells you |
| - | - |
| `code`, `chainId`, `chainFamily` | The network. `chainFamily` is `evm`, `tron`, `btc`, `solana` or `movement` |
| `live` | Whether a new address can be issued and monitored on this network now. A particular cross-chain route can still be unavailable |
| `depositAddresses.disabledReason` | Why not: `deposit_addresses_not_supported_on_network`, `deposit_address_issuance_paused`, `deposit_webhook_not_configured`, `deposit_webhook_provider_not_configured`, or null |
| `supportedAssets[]` | `symbol`, `tokenAddress`, `decimals`, `kind` (`token` or `native`) and `feeModel` for each accepted asset |
| `supportedAssets[].minimumDeposit` | The smallest accepted source amount. A smaller transfer is detected, recorded as `ignored`, and stays on the address |
| `supportedAssets[].configuredMaximumDeposit` | The enforced per-deposit cap, or null when none is set. A larger confirmed deposit goes to manual review |
| `supportedAssets[].sourceDeduction`, `sourceSetupCharge` | Fixed source-side charges: `btc_fee_reserve`, `tron_sweep_charge`, and a `tron_address_setup` charge taken once per address |
| `supportedAssets[].maximumDeposit`, `liquidity` | Indicative samples of Routing quotes. Neither is a limit or evidence that a deposit will be accepted |
| `fees` | Your current `platformFeeBps`, `partnerFeeBps` and `totalFeeBps`. Rates freeze on each deposit when it is detected |

Minimums per asset are listed on [Supported regions and currencies](/supported-regions-and-currencies#deposit-minimums). Show the minimum next to the address every time.

## The deposit address

| Field | What it holds |
| - | - |
| `id` | `deposit_addr_` prefix |
| `accountId` | The owning account |
| `chainId` | Arbitrum `42161`, Ethereum `1`, Base `8453`, Polygon `137`, BNB Smart Chain `56`, Avalanche `43114`, Robinhood Chain `4663`, Tempo `4217`, Solana `10103`, Movement `10002`, Tron `728126428`, Bitcoin `10001` |
| `address` | The address to show the payer |
| `supportedAssets[]` | `chainId`, `tokenAddress`, `symbol`, `decimals`, `kind` for each asset this address accepts |
| `metadata` | `networkCode` and `chainFamily` only |
| `status` | `active`, or `disabled`: a disabled address is no longer monitored for new deposits, and deposits already in flight continue |
| `createdAt`, `updatedAt` | Timestamps |

## Create and list

```bash theme={null}
curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/deposit-addresses \
  -u "$APP_ID:$APP_SECRET" \
  -H "Idempotency-Key: address:acct_123:v1" \
  -H "Content-Type: application/json" \
  -d '{ "chainIds": [42161, 8453] }'
```

```json theme={null}
{
  "accountId": "acct_123",
  "depositAddresses": [
    {
      "id": "deposit_addr_123",
      "accountId": "acct_123",
      "chainId": 42161,
      "address": "0x3333333333333333333333333333333333333333",
      "supportedAssets": [
        { "chainId": 42161, "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6, "kind": "token" }
      ],
      "metadata": { "networkCode": "arbitrum", "chainFamily": "evm" },
      "status": "active",
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:00:00.000Z"
    }
  ]
}
```

| Rule | Detail |
| - | - |
| `chainIds` | 1 to 12 unique chain IDs. The body takes nothing else |
| Create or reuse | Where the account already has an active, monitored address on a requested chain, that address is returned |
| All or nothing | If any requested chain is paused or unsupported, the whole batch fails before any address is provisioned. Check `live` first |
| `Idempotency-Key` | Optional, up to 128 characters. The same key with different `chainIds` returns `409 idempotency_conflict` |
| List | `GET /v2/accounts/{accountId}/deposit-addresses`, filtered by `status`, with `limit` up to 100 (default 50) and `cursor` |

A browser holding a client session uses the same calls under `/v2/client/me/`, fixed to the session's account. See [Create deposit addresses for the client account](/api-reference/client-deposits/create-deposit-addresses).

## The deposit

| Field | What it holds |
| - | - |
| `id` | `deposit_` prefix |
| `accountId`, `depositAddressId` | The account and the address it arrived at |
| `status` | See [States](#states) |
| `amount` | The source transfer as `{ asset, amount }`, with `amount` in atomic units |
| `sourceTransfer` | The same amount, with `txHash`, `logIndex` and the sender's `fromAddress` when captured |
| `fees` | `partnerAmountAtomic`, `platformAmountAtomic`, `networkAmountAtomic`, `setupAmountAtomic`, `denomination`, `basis`, `actualReceivedAmountAtomic` |
| `netSettlementAmount` | What the destination receives after fees, or null until it is known |
| `settlement` | `status` (`pending`, `settled`, `failed`, `requires_intervention`), `txHash`, `settledAt`, and a `reasonCode` when it needs review |
| `settlementProfileSnapshot` | The destination frozen when the deposit was detected |
| `txHash`, `observedAt`, `settledAt`, `createdAt`, `updatedAt` | Evidence and timestamps |

`fees.basis` is `source_amount` before final settlement evidence exists and `verified_destination_receipt` once the received destination amount is independently verified; only then is the net final. A deposit detected before a settlement-profile change still settles to its snapshot. See [Settlement fees](/settlement/assessing-fees#deposits-carry-their-own-fee-basis).

```bash theme={null}
curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/deposits?status=settled \
  -u "$APP_ID:$APP_SECRET"
```

```json theme={null}
{
  "accountId": "acct_123",
  "deposits": [
    {
      "id": "deposit_123",
      "accountId": "acct_123",
      "depositAddressId": "deposit_addr_123",
      "status": "settled",
      "amount": {
        "asset": { "chainId": 42161, "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6 },
        "amount": "100000000"
      },
      "sourceTransfer": {
        "amount": {
          "asset": { "chainId": 42161, "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6 },
          "amount": "100000000"
        },
        "txHash": "0xabc123...",
        "logIndex": 4,
        "fromAddress": "0x4444444444444444444444444444444444444444"
      },
      "fees": {
        "partnerAmountAtomic": "0",
        "platformAmountAtomic": "500000",
        "networkAmountAtomic": "0",
        "setupAmountAtomic": "0",
        "denomination": { "chainId": 42161, "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6 },
        "basis": "verified_destination_receipt",
        "actualReceivedAmountAtomic": "100000000"
      },
      "netSettlementAmount": {
        "asset": { "chainId": 42161, "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6 },
        "amount": "99500000"
      },
      "settlement": { "status": "settled", "txHash": "0xdef456...", "settledAt": "2026-10-01T12:03:00.000Z" }
    }
  ]
}
```

The fee figures are a labelled example, not a rate card. Filter by `status`, with `limit` up to 100 (default 50) and `cursor`.

## States

| `status` | Meaning | Can move to |
| - | - | - |
| `detected` | Seen on chain, not yet confirmed | `confirming`, `settling`, `settled`, `ignored`, `failed`, `requires_intervention` |
| `confirming` | Waiting for the required confirmations | `detected`, `settling`, `settled`, `ignored`, `failed`, `requires_intervention` |
| `settling` | Moving to the snapshotted settlement destination | `detected`, `confirming`, `settled`, `ignored`, `failed`, `requires_intervention` |
| `settled` | Delivered to the destination. Credit here | `reversed` only |
| `reversed` | Stableyard invalidated the settled accounting record. This does not imply an on-chain clawback | Nothing |
| `failed` | Did not complete | Nothing |
| `ignored` | Recorded and not credited, typically below the asset's minimum. The funds stay on the address and are not returned | `detected` if the same transfer is re-evaluated, `requires_intervention` |
| `requires_intervention` | A person must decide: for example above the configured cap, an asset not enabled on the chain, or settlement needing review (`settlement.reasonCode`) | `detected`, `confirming`, `settling`, `settled`, `failed`, `ignored` |

```mermaid theme={null}
stateDiagram-v2
  direction LR
  state "In flight" as inflight {
    direction LR
    detected --> confirming
    confirming --> settling
  }
  [*] --> detected
  inflight --> settled
  settled --> reversed
  inflight --> ignored: below minimum
  ignored --> detected: re-evaluated
  inflight --> failed
  inflight --> requires_intervention
  ignored --> requires_intervention
  requires_intervention --> inflight
  requires_intervention --> settled
  requires_intervention --> failed
  requires_intervention --> ignored
```

<Warning>
  Credit your customer on `settled`, never on `detected`. A detected transfer can still be ignored, fail or need intervention, and only `settled` means the destination received it.
</Warning>

## Check a missing transfer

Detection is automatic. When a transfer has not appeared, ask Stableyard to look for it:

```bash theme={null}
curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/deposit-addresses/check \
  -u "$APP_ID:$APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "chainId": 42161, "depositAddress": "0x3333333333333333333333333333333333333333", "transactionHash": "0xabc123..." }'
```

| Source chain | Manual check | Evidence |
| - | - | - |
| Arbitrum, Ethereum, Base, Polygon, BNB Chain | Yes | Transaction hash. `tokenAddress` and `logIndex` pick out one token transfer |
| Solana | Yes | Transaction signature |
| Movement | Yes | Transaction hash |
| Bitcoin | Yes | Transaction ID |
| Tron | No | Detected through the provider webhook only |

The evidence is only a candidate: Stableyard verifies the address, chain, token, amount, finality and that the evidence has not been used before. Known check failures return `200` with `isTransferDone: false`, so read the body:

| Response field | Meaning |
| - | - |
| `isTransferDone` | True only when the hash is a supported deposit to an active address of this account and passes the minimum |
| `hashExists`, `depositAddressExists`, `supported` | Which check failed: hash not found, address not active for this account and chain, or not a supported, confirmed transfer above the minimum |
| `ignored`, `minimumTransactionAmount` | The transfer was recorded below the minimum, and what the minimum is |
| `error` | `{ code, message }` for a known validation, not-found, conflict or check failure |
| `deposit`, `transaction` | The recorded `Deposit` and its ledger row, or null |

## Errors

| Code | HTTP | When |
| - | - | - |
| `bad_request` | 400 | The account has no active preferred settlement destination, or a chain does not support deposit addresses (`details.code: "deposit_addresses_not_supported_on_network"`) |
| `not_found` | 404 | No such account in your app environment |
| `idempotency_conflict` | 409 | The same `Idempotency-Key` with different `chainIds` |
| `request_in_progress` | 409 | An identical create is still running. Retry with the same key |
| `provider_unavailable` | 503 | Issuance is paused on a requested chain (`details.reason: "deposit_address_issuance_paused"`) |
| `deposit_webhook_registration_failed` | 502 | The address could not be registered for monitoring, so it was not issued |

## Webhooks

| Event | Meaning |
| - | - |
| `deposit.detected` | Funds first observed. Carries `depositId`, `depositAddressId`, the source `chainId` and `tokenAddress`, `txHash`, `amountAtomic`, and `transactionId` when available |
| `deposit.settled` | Settlement complete. There is no `deposit.completed` |
| `deposit.reversed` | A settled accounting record was invalidated. Not an on-chain clawback |
| `deposit.requires_intervention` | Automation needs manual review |
| `deposit.failed` | Reserved for terminal failures |

`confirming` and `settling` are not delivered as events: poll `GET /v2/accounts/{accountId}/deposits` for that detail. See [Webhooks](/webhooks/event-catalog#deposit-events).

## Related

<CardGroup cols={2}>
  <Card title="Depositing funds" icon="arrow-down-to-line" href="/payments/depositing-funds#give-a-returning-customer-a-deposit-address">
    Issue an address to a returning customer and read arrivals.
  </Card>

  <Card title="Settlement transactions" icon="receipt" href="/settlement/transactions#deposits-report-settlement-on-the-deposit">
    Follow a deposit's settlement record.
  </Card>

  <Card title="Status codes" icon="signal" href="/status-codes">
    Deposit and payment states side by side.
  </Card>

  <Card title="Supported regions and currencies" icon="globe" href="/supported-regions-and-currencies">
    Which chains issue addresses, and each asset's minimum.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.