Settlement destinations

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

curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/settlement-destinations \
  -u "$APP_ID:$APP_SECRET"

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

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

`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

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:

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

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

Next: Webhooks

The event catalog, signature verification and delivery rules.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

Settlement destinations

List the account’s destinations

Only crypto wallets can receive settlement today

Offer a destination only when `settlementSupported` is true

Set the settlement profile

Override the destination for one payment

An account without a destination cannot receive value

Errors

Next: Webhooks

​List the account’s destinations

​Only crypto wallets can receive settlement today

​Offer a destination only when settlementSupported is true

​Set the settlement profile

​Override the destination for one payment

​An account without a destination cannot receive value

​Errors

Next: Webhooks

List the account’s destinations

Only crypto wallets can receive settlement today

Offer a destination only when `settlementSupported` is true

Set the settlement profile

Override the destination for one payment

An account without a destination cannot receive value

Errors