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

# Quotes

> See the rate, the fee and what the recipient gets before you send. A quote holds for five minutes by default.

A quote fixes the exchange rate and fee for one amount in one currency pair. Create a quote, show it to your user, then pass its id to a payout or conversion to get exactly those numbers.

## Create a quote

`POST /v1/quotes`

**sourceCurrency** `string` *required*

The currency you pay from: `NGN`, `GHS` or `KES`.

**destinationCurrency** `string` *required*

The currency the recipient gets.

**amount** `integer` *required*

The amount in `sourceCurrency`, in minor units. A positive whole number.

**transactionType** `string` (default: payout)

What the quote is for: `payout` or `conversion`. Set `conversion` when you will use the quote for
a wallet-to-wallet conversion.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/quotes" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "amount": 5000000,
    "transactionType": "payout"
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/quotes`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sourceCurrency: 'NGN',
    destinationCurrency: 'GHS',
    amount: 5000000,
    transactionType: 'payout',
  }),
});
const { data: quote } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/quotes",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
    json={
        "sourceCurrency": "NGN",
        "destinationCurrency": "GHS",
        "amount": 5000000,
        "transactionType": "payout",
    },
)
quote = res.json()["data"]
```

```json Response · 201
{
  "data": {
    "id": "qte_4b1f0c9d2e7a6835",
    "sourceCurrency": "NGN",
    "sourceAmount": "5000000",
    "destinationCurrency": "GHS",
    "destinationAmount": "46500",
    "rate": "0.0093",
    "fee": {
      "amount": "25000",
      "currency": "NGN"
    },
    "expiresAt": "2026-11-18T10:05:00.000Z",
    "createdAt": "2026-11-18T10:00:00.000Z"
  }
}
```

**id** `string`

The quote id. Pass it as `quoteId`.

**sourceAmount** `string`

The amount you asked to send, in minor units.

**destinationAmount** `string`

What the recipient gets, in minor units of `destinationCurrency`.

**rate** `string`

The exchange rate applied, as a decimal string.

**fee** `object`

Payve's fee. `fee.amount` is in minor units of `fee.currency`. It can also carry a `structure`
object describing how the fee is worked out.

**expiresAt** `string`

When the quote stops being usable.

## What you pay

The fee is charged **on top of** the amount, in the source currency. Your wallet is debited `sourceAmount + fee.amount`.

In the sample: ₦50,000.00 is sent, the fee is ₦250.00, your wallet is debited ₦50,250.00, and the recipient gets GH₵465.00.

## Use the quote

Pass `quoteId` to `POST /v1/payouts` or `POST /v1/conversions`, with the **same** currencies and amount.

> [!WARNING]
>
> A quote is for one pair and one amount. Sending a `quoteId` with a different amount or currency
> pair fails. If the amount changes, create a new quote.

A quote can be used once. After a payout or conversion consumes it, a second use returns `409 quote_already_consumed`.

## How long a quote holds

Five minutes by default. `expiresAt` is the authority. Read it instead of assuming.

After `expiresAt`, using the quote returns `422 quote_expired`. Create a new quote and show the new numbers to your user before you send.

> [!TIP]
>
> Create the quote when your user is ready to confirm, not when they open the page. Show a countdown
> to `expiresAt`.

## Sending without a quote

You can omit `quoteId` on a payout or conversion. Payve then prices it at the rate in force at that moment. Use a quote whenever a person needs to see the numbers first.

## Look up quotes

| Request | Returns |
| - | - |
| `GET /v1/quotes/{id}` | One quote, by its `qte_` id. |
| `GET /v1/quotes` | Your quotes, newest first, each with a `status` of `active`, `used` or `expired`. |

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `422 validation_missing_field` | A bad field, an unsupported currency, or a fractional amount. | Fix the field named in `details.fields`. |
| `404 resource_not_found` | No exchange rate exists for that pair. | Use another pair, or ask [support](/support.md). |
| `404 resource_not_found` | The quote id does not exist on your account. | Check the id. |
| `422 quote_expired` | The quote is past `expiresAt`. | Create a new quote. |
| `409 quote_already_consumed` | The quote was already used. | Create a new quote. |

`GET /v1/rates` returns indicative rates without a key. See [Coverage](/essentials/coverage.md#indicative-rates).
