# Send a payout

> Markdown version of the public documentation of the Bifrost Crypto API v1, for AI agents and code generators. Same content as the HTML pages, generated from the same source, without navigation or styling.
>
> HTML version: https://bifrostcrypto.com/en/docs/guide-payout
> Related files: [ai.md](https://bifrostcrypto.com/ai.md) · [Postman](https://bifrostcrypto.com/postman-collection.json) · [OpenAPI](https://bifrostcrypto.com/openapi.json) · [llms.txt](https://bifrostcrypto.com/llms.txt)
> Other languages: [Português](https://bifrostcrypto.com/ai/pt-BR/guide-payout.md) · [Español](https://bifrostcrypto.com/ai/es/guide-payout.md) · [Français](https://bifrostcrypto.com/ai/fr/guide-payout.md)
> API v1 · contract last changed on 2026-10-10

From checking the balance to confirming the transfer, for one payout or a batch of up to 50.

## 1. Check the balance

GET /v1/balances returns one balance per token; the key of each token is the balance_key returned by GET /v1/summary/tokens. When available has a key, use it: the rest is held by deposits that are not final yet. min_withdrawal and max_withdrawal per token come from GET /v1/summary/tokens.

```bash
curl "https://bridge.bifrostcrypto.com/v1/balances" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY"
```

## 2. Create the payout

POST /v1/payout with one object or a list of up to 50. Give each payout its own reference_id and send an Idempotency-Key per request. feetakenfromamount 1 takes the fees from the amount; 0 adds them to the debit.

```bash
curl -X POST "https://bridge.bifrostcrypto.com/v1/payout" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-0000-4000-8000-000000000001" \
  -d '{"reference_id":"withdraw_2001","wallet":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0","crypto_currency":"USDT","network":"Ethereum","process_by":"crypto_amount","crypto_amount":"100","feetakenfromamount":0,"webhook_url":"https://your-site.com/webhook"}'
```

## 3. Read the result of each item

200 means every item was created, 207 some were, 400 none. results has one entry per item, in the order sent, with its index. Keep the internal_reference of each created payout.

## 4. Receive the webhook

payment_processed (data.status success, with the transaction hash in data.transactions) when the transfer is done, or payment_failed when it cannot be completed. Verify the signature and deduplicate on data.internal_reference together with event.

## 5. Reconcile

GET /v1/check-payout/{internal_reference} returns the payout at any time. GET /v1/statements lists WITHDRAWAL for the debit and RATE and FEE for the charges.

## What to do when something fails

Two things protect you from paying twice: the Idempotency-Key of the request and the reference_id of each payout.

| Situation | What to do |
| --- | --- |
| Timeout or no answer | Resend the same body with the same Idempotency-Key within 24 hours: you get the original answer and nothing is processed again. |
| 409 idempotency_key_in_progress | The first request is still running. Wait and retry with the same key. |
| 207 | Fix and resend only the refused items, with a new Idempotency-Key. The created ones stay created. |
| 500 with summary.not_processed | Resend the items that were not processed. A reference_id already used is refused with duplicate_payment_reference, never paid twice. |
| duplicate_payment_reference | The payout already exists. Use the internal_reference and original_status in the result. |
| 429 | Wait the seconds in Retry-After. |

> Payouts created in the panel are not returned by the API.