Send a payout

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

  1. 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. 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. 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. 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. 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.

SituationWhat to do
Timeout or no answerResend 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_progressThe first request is still running. Wait and retry with the same key.
207Fix and resend only the refused items, with a new Idempotency-Key. The created ones stay created.
500 with summary.not_processedResend the items that were not processed. A reference_id already used is refused with duplicate_payment_reference, never paid twice.
duplicate_payment_referenceThe payout already exists. Use the internal_reference and original_status in the result.
429Wait the seconds in Retry-After.

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