> ## 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 quickstart

> List an account's destinations, choose one, collect a payment, and confirm the value landed.

Four calls take an account from no destination to settled value. You need an account with at least one connected wallet; create one on [Universal Payment Account](/universal-payment-account).

Every call uses the sandbox base URL. Swap it for production when you go live; see [Environments](/environments).

## 1. 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",
      "type": "crypto_wallet",
      "status": "active",
      "preferred": true,
      "capabilities": {
        "settlementSupported": true,
        "unavailableReason": null,
        "network": { "code": "base", "chainId": 8453, "chainFamily": "evm" },
        "assets": [
          { "symbol": "USDC", "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6 }
        ]
      }
    }
  ],
  "nextCursor": null
}
```

Pick a row where `status` is `active` and `capabilities.settlementSupported` is `true`, and take its `id`.

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

```json theme={null}
{
  "id": "settle_123",
  "accountId": "acct_123",
  "version": 2,
  "connectedWalletId": "wallet_123",
  "settlementDestinationId": "destination_123",
  "status": "draft",
  "destinationType": "smart_wallet",
  "chainId": 42161,
  "destinationAddress": "11111111111111111111111111111111",
  "assetSymbol": "USDC",
  "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "snapshot": {}
}
```

Read `status` rather than assuming it: a newly created account's profile is returned as `draft`, and the enum is `draft`, `active`, `inactive`, `failed`. Repeating the same selection returns the existing profile, and `GET /v2/accounts/{accountId}/settlement-profile` returns `null` when nothing is selected.

## 3. Collect a payment into the account

Create a receive payment addressed to the account. The destination is not in this request, and never is.

```bash theme={null}
curl -X POST https://staging-api-v2.stableyard.fi/v2/payments \
  -u "$APP_ID:$APP_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "receive",
    "recipient": { "accountId": "acct_123" },
    "amountMode": "collect_exact",
    "paymentAmount": {
      "amount": "25.00",
      "assetType": "crypto",
      "assetCode": "USDC",
      "chainId": 42161
    },
    "description": "Invoice #1042",
    "externalReference": "order_1042",
    "expiresInSeconds": 600
  }'
```

The response freezes the settlement snapshot and the fees onto the payment:

```json theme={null}
{
  "payment": {
    "id": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
    "intent": "receive",
    "status": "requires_payment_method",
    "stage": "awaiting_payment",
    "operationalState": "normal",
    "settlement": {
      "type": "settlement_destination",
      "settlementDestinationId": "destination_123",
      "destinationType": "connected_wallet",
      "destinationAddress": "0x1111111111111111111111111111111111111111",
      "chainId": 42161,
      "assetCode": "USDC",
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "decimals": 6
    },
    "fees": {
      "version": 1,
      "pricingStatus": "quoted",
      "platformFeeBps": 50,
      "partnerFeeBps": 0,
      "platformFeeAmountAtomic": "125000",
      "partnerFeeAmountAtomic": "0",
      "merchantNetAmountAtomic": "24875000"
    },
    "expiresAt": "2026-08-28T10:10:00.000Z"
  }
}
```

`merchantNetAmountAtomic` is what the destination receives. Fees are deducted from the verified amount, not recalculated at settlement time.

<Warning>
  A recipient account with no active settlement profile is refused with a `409` conflict naming the account. Set the profile before you point any value at an account.
</Warning>

## 4. Confirm the value landed

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

| Field | Reading it |
| - | - |
| `status` | `accepted`: the deposit was verified and settlement is not finished. `succeeded`: the destination was credited |
| `stage` | Moves through `settlement_pending`, `settlement_broadcast`, `settlement_confirming` |
| `operationalState` | A `succeeded` payment with `requires_intervention` still needs someone to look at it |

Subscribe to `payment.accepted` and `payment.succeeded` rather than polling, and treat each event as a prompt to read the payment. `payment.settlement_returned` fires when a broadcast settlement comes back. See [Webhooks](/webhooks).

The account now has a standing destination. Every later deposit into it settles there, net of fees, with no destination in any request body.

<Card title="Next: Settlement lifecycle" icon="timeline" href="/settlement/receiving-settlement">
  When `accepted` becomes `succeeded`, and what to read in between.
</Card>


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