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

# Stablecoin payouts

> Send tokens from your balance to a wallet address.

A stablecoin payout sends tokens from your balance to a wallet-rail beneficiary. Read
[Payouts](/guides/payouts) first — idempotency, beneficiaries, error codes and how `status` behaves
are shared with the fiat rail and are not repeated here.

<Note>
  Every example on this page is a signed request. `$SIGNATURE` is computed per request over a
  canonical string — see [Authentication](/guides/authentication). Bearer tokens are not accepted.
</Note>

## Create a payout

```bash theme={null}
curl -X POST https://api.stablemint.net/v1/payouts/token \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "settlement-2026-09-15-0001",
    "beneficiaryId": "9c6a8e0f-1d2b-3c45-7b5e-3f2a9c147b5e",
    "currency": "USD",
    "amount": 2500.00,
    "reference": "settlement-4471"
  }'
```

<ParamField body="idempotencyKey" type="string" required>
  Your own unique key for this payout. See [Idempotency](/guides/payouts#idempotency).
</ParamField>

<ParamField body="beneficiaryId" type="string" required>
  A wallet-rail beneficiary you own. The destination address is taken from the beneficiary — you do
  not send an address on the payout.
</ParamField>

<ParamField body="currency" type="string" required>
  The ISO-4217 code of the currency to send — `USD` or `EUR`. Exactly three characters.
</ParamField>

<ParamField body="amount" type="number" required>
  The amount to send.
</ParamField>

<ParamField body="reference" type="string">
  Optional. Echoed back on the response and surfaced on the transaction.
</ParamField>

<Note>
  **Send the currency code, not the token symbol.** `USD` sends the StableMint stablecoin for US
  dollars; `USDSM` is the token's own symbol and is rejected — `'Currency' must be 3 characters in
      length`. The response echoes back the code you sent.
</Note>

<Note>
  **There is no network or chain field.** The chain is selected for you from the beneficiary. If you
  need the same token on a different chain, that is a [bridge](/bridge/overview) operation, not a
  payout parameter.
</Note>

## Response

`201 Created` on first submission, `200 OK` on an idempotent replay.

```json theme={null}
{
  "reference": "SM-2026-0000004472",
  "status": "Pending",
  "amount": 2500.00,
  "currency": "USD",
  "beneficiaryName": "Acme Treasury",
  "destinationAddress": "0xYourBeneficiaryAddress",
  "idempotencyKey": "settlement-2026-09-15-0001"
}
```

The response mirrors the fiat rail, with `destinationAddress` in place of `beneficiaryAccount`.

<Warning>
  **`status` never implies on-chain finality at creation time.** The payout is accepted before it is
  broadcast, and confirmation is established by watching the chain afterwards — not by the
  submission succeeding.

  Treat the payout as settled only when `transaction.status.changed` says so. An address typo cannot
  be undone once the transfer confirms, so verify the beneficiary, not the response.
</Warning>