Deposit addresses

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 and Depositing funds.

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. Then read the network catalog. It is read-only and safe to cache for a minute.

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. 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

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] }'

{
  "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.

The deposit

Field	What it holds
`id`	`deposit_` prefix
`accountId`, `depositAddressId`	The account and the address it arrived at
`status`	See 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.

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

{
  "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`

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.

Check a missing transfer

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

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.

Depositing funds

Issue an address to a returning customer and read arrivals.

Settlement transactions

Follow a deposit’s settlement record.

Status codes

Deposit and payment states side by side.

Supported regions and currencies

Which chains issue addresses, and each asset’s minimum.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

When to use it

Before you issue one

The deposit address

Create and list

The deposit

States

Check a missing transfer

Errors

Webhooks

Depositing funds

Settlement transactions

Status codes

Supported regions and currencies

​When to use it

​Before you issue one

​The deposit address

​Create and list

​The deposit

​States

​Check a missing transfer

​Errors

​Webhooks

​Related

Depositing funds

Settlement transactions

Status codes

Supported regions and currencies

When to use it

Before you issue one

The deposit address

Create and list

The deposit

States

Check a missing transfer

Errors

Webhooks

Related