Payout Quotes

Hold the rate and fee for a payout before you send it.

Open the interactive version or read this guide as markdown.

API reference

POST /api/v1/payouts/quote: Quote a payout
POST /api/v1/payouts: Initiate a payout

A quote shows what a payout costs before you send it. Use one when the recipient receives a different currency from the one you pay with, e.g. KES or ETH paid from your USDT balance. The quote holds the rate and the fee for two minutes, and you create the payout at that price.

How it works

Save the recipient with POST /api/v1/recipients.
Get a quote with POST /api/v1/payouts/quote.
Create the payout with POST /api/v1/payouts, passing the quote's id as quoteId.
Wait for the payout.success or payout.failed webhook.

Quote fields

Field	Type	Required	Description
`currency`	string	Yes	Currency the recipient receives, e.g. `KES` or `ETH`.
`sourceCurrency`	string	Yes	Stablecoin you pay with, e.g. `USDT`.
`sourceAmount`	string	Conditional	Amount you pay, in `sourceCurrency`.
`targetAmount`	string	Conditional	Amount the recipient receives, in `currency`. Accepted when `currency` is a coin, e.g. `ETH`.
`chain`	string	Conditional	Blockchain the recipient is paid on, e.g. `base`. Required when `currency` is a coin.

Send one of sourceAmount and targetAmount.

Get a quote

This request prices 100 USDT paid out as ETH on Base.

POST https://api.coincircuit.io/api/v1/payouts/quote

{
  "currency": "ETH",
  "sourceCurrency": "USDT",
  "chain": "base",
  "sourceAmount": "100.00"
}

The response:

{
  "success": true,
  "message": "Payout quote",
  "data": {
    "id": "cpq_2f6b1c8e-9a47-4d3b-b0e5-71c4a8d92f10",
    "conversion": {
      "fromCurrency": "USDT",
      "toCurrency": "ETH",
      "sourceAmount": "100.00",
      "sourceFee": "0.50",
      "targetAmount": "0.03979281",
      "rate": "0.000397928146"
    },
    "fee": "0.00019896",
    "total": "0.03999177",
    "expiresAt": "2026-10-14T09:32:00.000Z"
  }
}

Field	Meaning
`id`	The quote. Pass it as `quoteId` when you create the payout.
`conversion.sourceAmount`	What you pay, before the fee.
`conversion.sourceFee`	The fee, in the currency you pay with.
`conversion.targetAmount`	What the recipient receives.
`conversion.rate`	`sourceAmount` x `rate` = `targetAmount`.
`fee`	The same fee, in the currency the recipient receives.
`total`	`targetAmount` plus `fee`.
`expiresAt`	When the quote expires.

Your balance is debited sourceAmount plus sourceFee: 100.50 USDT here.

Set what the recipient receives

Send targetAmount in place of sourceAmount. The quote returns what you pay as conversion.sourceAmount.

{
  "currency": "ETH",
  "sourceCurrency": "USDT",
  "chain": "base",
  "targetAmount": "0.04000000"
}

Cross-border currencies

Quote a cross-border currency by sourceAmount. Cross-border payouts are available to verified businesses.

{
  "currency": "KES",
  "sourceCurrency": "USDT",
  "sourceAmount": "100.00"
}

Create the payout

Pass the quote's id as quoteId. The quote sets the amount.

POST https://api.coincircuit.io/api/v1/payouts

{
  "currency": "ETH",
  "sourceCurrency": "USDT",
  "quoteId": "cpq_2f6b1c8e-9a47-4d3b-b0e5-71c4a8d92f10",
  "recipientId": "8d3f5a17-6c2e-4b9a-a1f4-0e7d92c5b386"
}

The response:

{
  "success": true,
  "message": "Crypto payout initialized successfully",
  "data": {
    "id": "5b0e7c94-2a61-4f38-9d15-c3a8f6e1b472",
    "reference": "CPAY-6KD2QX-T4BN1WCE5RJY7H3MZ0V9A2PL",
    "method": "crypto",
    "status": "pending",
    "amount": "0.03979281",
    "fee": "0.00019896",
    "total": "0.03999177",
    "currency": "ETH",
    "conversion": {
      "fromCurrency": "USDT",
      "toCurrency": "ETH",
      "sourceAmount": "100.00",
      "sourceFee": "0.50",
      "targetAmount": "0.03979281",
      "rate": "0.000397928146"
    },
    "narration": "Payout transfer",
    "recipient": {
      "id": "8d3f5a17-6c2e-4b9a-a1f4-0e7d92c5b386",
      "type": "crypto_address",
      "details": {
        "chain": "base",
        "address": "0x7a3b9c2d4e5f60718293a4b5c6d7e8f901234567"
      }
    },
    "channel": "api",
    "txHash": null,
    "sessionId": null,
    "failureReason": null,
    "completedAt": null,
    "createdAt": "2026-10-14T09:30:41.207Z",
    "updatedAt": "2026-10-14T09:30:41.352Z"
  }
}

A payout.success webhook confirms the transfer. GET /api/v1/payouts/{id} then returns its txHash.

When a quote is refused

A quote works once and lasts two minutes. The payout request returns a 400 asking for a new quote when:

the quote has expired or been used
the price has moved since the quote
sourceCurrency or the recipient's blockchain differs from the quote

Get a new quote and send the payout again.

Pay out at the current rate

Send amount in place of quoteId. amount is what the recipient receives, in currency, and the payout is priced when you create it.

Use cases

Showing a customer the cost before they confirm
Paying staff or suppliers in the coin they ask for
Sending mobile money from a stablecoin balance

Blockchain transfers cannot be reversed. Validate the recipient with POST /api/v1/recipients/validate before you send.