> ## 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. # Settlement destinations > List an account's destinations, check which can settle, and set its settlement profile. A destination is a typed target an account owns, with a stable `destination_` id. The settlement profile is the one destination currently chosen, and every payment and deposit snapshots it at the moment that object is created. ## List the account's destinations ```bash theme={null} curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/settlement-destinations \ -u "$APP_ID:$APP_SECRET" ``` ```json theme={null} { "accountId": "acct_123", "destinations": [ { "id": "destination_123", "accountId": "acct_123", "type": "crypto_wallet", "status": "active", "preferred": true, "capabilities": { "directions": ["receive"], "settlementSupported": true, "unavailableReason": null, "network": { "code": "base", "chainId": 8453, "chainFamily": "evm" }, "assets": [ { "symbol": "USDC", "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6 } ] }, "resource": { "type": "crypto_wallet", "connectedWalletId": "wallet_123", "chainId": 8453, "address": "0x1111111111111111111111111111111111111111", "walletKind": "external", "label": "Primary wallet", "ownershipVerificationStatus": "unverified" }, "disabledAt": null } ], "nextCursor": null } ``` The list is cursor-paginated, takes `limit` from 1 to 100, and filters on `type` and `status`. `resource` is a privacy-safe projection of the linked wallet, bank account or rail identifier; provider tokens are never returned. ## Only crypto wallets can receive settlement today The list describes everything the account holds, not a menu of what is selectable. | `type` | Points at | Selectable as the profile | | - | - | - | | `crypto_wallet` | A connected wallet on one chain | Yes | | `bank_account` | A bank account saved against the account | No | | `payment_rail_identifier` | A tokenised local alias, held as a provider token and a masked display value | No | Every kind is normalised behind one `settlementDestinationId`, so a payment body never carries a wallet address, an account number or a currency. Every supported settlement chain can hold a crypto destination; see [Supported regions and currencies](/supported-regions-and-currencies). **A verified bank account cannot yet receive settlement.** Verification confirms the recipient, but receiving settlement also needs the destination provider configured for that route, and it is not. Value collected for an account lands in stablecoin and nothing else. A bank or rail destination returns `settlementSupported: false` with an `unavailableReason` such as `bank_settlement_provider_not_configured`, `linked_bank_payout_execution_not_enabled` or `linked_bank_receive_settlement_not_enabled`. Selecting one is refused with `payment_method_not_supported` and the message that fiat settlement is unavailable until the destination provider is configured and verified. ## Offer a destination only when `settlementSupported` is true ```mermaid theme={null} stateDiagram-v2 direction LR [*] --> pending_verification: bank_account or payment_rail_identifier linked [*] --> active: crypto_wallet on a chain that can settle [*] --> restricted: crypto_wallet on a chain that cannot settle pending_verification --> disabled: withdrawn active --> disabled: withdrawn, refused while preferred restricted --> disabled: withdrawn ``` | `status` | What it means | | - | - | | `pending_verification` | Created and awaiting the destination provider. Bank accounts and rail identifiers start here, with `capabilities.settlementSupported: false` | | `active` | Usable. A wallet destination reaches this when its chain supports settlement | | `restricted` | Known, and blocked for settlement. `capabilities.unavailableReason` names why; a wallet on a chain that cannot settle reports `network_settlement_not_supported` | | `disabled` | Withdrawn from use. Financial history is preserved. Disabling the preferred destination is refused until you select another active one | Build your picker from `capabilities.settlementSupported`, not from `status` alone. A destination can be past its provider checks and still report `settlementSupported: false` with an `unavailableReason`. Selection fails closed on that flag rather than falling back to another destination. ## Set the settlement profile ```bash theme={null} curl -X PUT https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/settlement-profile \ -u "$APP_ID:$APP_SECRET" \ -H "Content-Type: application/json" \ -d '{ "settlementDestinationId": "destination_123", "assetSymbol": "USDC" }' ``` The body takes those two keys and nothing else. `assetSymbol` is optional and accepts `USDC`, `USDT`, `THBT`, `JPYC` or `USDG`: `THBT` is Movement-only, `JPYC` is Polygon-only and `USDG` is Robinhood Chain-only (4663). A native asset is never a destination. The response is the versioned profile: ```json theme={null} { "id": "settle_123", "accountId": "acct_123", "version": 2, "connectedWalletId": "wallet_123", "settlementDestinationId": "destination_123", "status": "active", "destinationType": "connected_wallet", "chainId": 8453, "destinationAddress": "0x1111111111111111111111111111111111111111", "assetSymbol": "USDC", "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "snapshot": {} } ``` | Field | Values | | - | - | | `status` | `draft`, `active`, `inactive` or `failed`. A newly created account's profile is returned as `draft` | | `destinationType` | `smart_wallet`, `connected_wallet` or `external_wallet` | | `version` | Increments on each change. A payment records the version in force when it was created | * **Read `status`; don't assume it.** What moves a profile from `draft` to `active` is not stated in the contract, so do not build a promotion step around a guess. * **A recipient needs an active profile.** Naming an account whose profile is not active as a payment recipient is refused with a `409` conflict naming the account. * **Repeats are safe.** Repeating the same selection returns the existing profile rather than writing a new one. * **Changes apply forward only.** Payments already created and deposits already detected keep the destination captured at that moment. * **No profile reads as `null`.** `GET /v2/accounts/{accountId}/settlement-profile` returns `{ "settlementProfile": null }` when nothing is selected. Design your settings screen around that state. ## Override the destination for one payment A receive payment can name a different eligible destination without touching the profile: ```json theme={null} { "intent": "receive", "recipient": { "accountId": "acct_123" }, "amountMode": "collect_exact", "paymentAmount": { "amount": "50.00", "assetType": "crypto", "assetCode": "USDC", "chainId": 42161 }, "settlement": { "settlementDestinationId": "destination_456" } } ``` The override is snapshotted on that payment alone, and it still has to be an active crypto destination. ## An account without a destination cannot receive value | Situation | What happens | | - | - | | The account has never had a profile | The first settlement-capable wallet linked becomes preferred. Once a profile exists, linking another wallet never moves settlement. Set the profile explicitly rather than relying on this | | The account has no eligible destination | Nothing queues. A receive payment naming the account is refused, and so is a request for a deposit address, with `settlement_profile_required` or `bad_request` naming the missing destination | ## Errors | Code | HTTP | Cause | | - | - | - | | `not_found` | 404 | No destination with that id on that account | | `conflict` | 409 | The named destination is not `active` | | `payment_method_not_supported` | 422 | A bank account or rail identifier was selected | | `settlement_profile_required` | 422 | Money was pointed at an account with no destination | `account.updated` fires when a destination is linked, changed or disabled. Treat it as a prompt to read the account. The event catalog, signature verification and delivery rules. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.