# Payout Quotes

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

Section: Payouts & Swaps
Source: https://coincircuit.io/docs/guides/payout-quotes/
Interactive version: https://coincircuit.io/api-reference?tab=guides&guide=payout-quotes

## API reference

- POST `/api/v1/payouts/quote`: [Quote a payout](https://coincircuit.io/api-reference/#tag/payouts/POST/api/v1/payouts/quote)
- POST `/api/v1/payouts`: [Initiate a payout](https://coincircuit.io/api-reference/#tag/payouts/POST/api/v1/payouts)

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
1. Save the recipient with `POST /api/v1/recipients`.
2. Get a quote with `POST /api/v1/payouts/quote`.
3. Create the payout with `POST /api/v1/payouts`, passing the quote's `id` as `quoteId`.
4. 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.

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

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

The response:

```json
{
  "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`.

```json
{
  "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.

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

## Create the payout
Pass the quote's `id` as `quoteId`. The quote sets the amount.

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

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

The response:

```json
{
  "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.