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

# Quotes

> Get the rate, fees and total cost before converting funds or sending a payment.

A quote tells you what you will pay and what you will receive. It includes the exchange rate, amounts, fees and expiry time. Creating a quote does not move funds. Create a [transfer](https://docs.ledig.io/guides/transfers.md) when you are ready to proceed.

## Discover currencies and rates

Call `GET /v1/currencies` for currency codes, decimal precision and supported networks. Call `GET /v1/rates` for indicative exchange rates. Indicative rates are useful for estimates; a quote gives you the rate you can use for a transaction.

Send amounts as decimal strings using the currency's supported precision. For example, use `"100.00"` where two decimal places are supported. Do not assume that every currency uses two decimals.

Use `GET /v1/liquidity/routes` to check which conversions are available and their minimum and maximum amounts. See [Limits](https://docs.ledig.io/guides/limits.md) for the difference between conversion, payout and account limits.

## Discover payment methods and fees

| Operation | Use it to |
| - | - |
| `GET /v1/quotes/payment-options` | Find payment methods for your currency, amount and recipient. |
| `GET /v1/payouts/catalogue` | View payout methods, fee bands and amount limits. |
| `POST /v1/payouts/fee-estimate` | Estimate a payout fee before requesting a quote. |
| `GET /v1/quotes/payout-fees` | View your payout fee schedule, including payments to Ledig businesses. |

These operations require the `quotes:read` scope.

For a payout, request payment options with `type=withdraw`, the destination `currency` and the approved `recipientId`. Include `amount` to find methods that support the amount the recipient will receive. For crypto, include the destination's `chain`.

For a payment to a Ledig business, use `businessId` instead of `recipientId`. Do not send both.

Select a value from `paymentMethodIds` and use it as `payOut.paymentMethodId`. The option's own `id` is a different value. An empty list means no payment method is available for that request.

External payout options include `amountBands`. Their minimum and maximum are outer bounds; amounts in gaps remain unsupported. See [Limits](https://docs.ledig.io/guides/limits.md#payout-limits).

Payment options are read-only and do not approve a payment. `423 COMPLIANCE_REVIEW_REQUIRED` means the recipient needs review; keep the recipient and wait instead of retrying automatically. `404 NOT_FOUND` means the requested recipient was not found.

If the selected option has `invoiceRequired: true`, upload the invoice through your dashboard or the upload process agreed for your integration, then include `payOut.invoiceDocumentId`. Contact [support@ledig.io](mailto:support@ledig.io) if you need help with invoice uploads. `payOut.transferPurpose` is optional and does not replace a required invoice.

To discover receiving methods instead, use `type=deposit`. Receiving funds follows the [funding flow](https://docs.ledig.io/guides/funding.md); it does not use a deposit quote.

## Estimate a payout fee

`POST /v1/payouts/fee-estimate` requires `currency`, `payoutType` and a positive decimal `amount`. Crypto payouts also require the exact `network`. If more than one fee band matches, include the `bandId` from the catalogue.

This request does not create a quote or move funds. You can call it with a Read Only key that has `quotes:read`.

Check the returned availability and `amountWithinLimits` along with the fee. A fee may be listed even when sending is temporarily unavailable. Missing pricing does not mean a zero fee. Use a quote to confirm the final cost, and do not cache these responses.

## Create the quote

This example converts 100 USDT to NGN and sends the result to a bank recipient. Replace the recipient and payment method IDs with values from your API responses:

```http theme={null}
POST /v1/quotes
Content-Type: application/json
```

```json theme={null}
{
  "reference": "order-1042",
  "sourceCurrency": "USDT",
  "destinationCurrency": "NGN",
  "sourceAmount": "100",
  "payOut": {
    "type": "fiat",
    "recipientId": "RECIPIENT_ID",
    "paymentMethodId": "PAYMENT_METHOD_ID"
  }
}
```

| Field | Meaning |
| - | - |
| `sourceCurrency` | The currency you are paying with. |
| `destinationCurrency` | The currency you want to receive or send. |
| `sourceAmount` | The amount to convert or pay, before fees. |
| `reference` | Your optional reference, up to 64 characters. Reusing it recovers the original quote. |
| `payOut` | Where to send the funds. Required for same-currency payments. |

For a conversion that stays in your Ledig balance, omit `payOut`. For an external payment, use `payOut.type: "fiat"` or `"crypto"`, an approved `recipientId` and an available `paymentMethodId`. Include `chain` for crypto when required by the destination.

## Read fees and the total debit

Use the amounts in the response to show your customer the cost:

| Field | Meaning |
| - | - |
| `sourceAmount` | Amount before fees, in the source currency. |
| `destinationAmount`, `rate` | Amount you receive and the exchange rate. |
| `feeAmount`, `feeCurrency` | Conversion fee in the source currency. |
| `sourceDebitAmount` | Source amount plus the conversion fee. |
| `payoutFeeAmount`, `payoutFeeCurrency` | Payout fee in the destination currency. |
| `payoutFeeSourceAmount` | Payout fee expressed in the source currency. |
| `totalFeeAmount`, `totalFeeCurrency` | Both fees combined in the source currency. |
| `totalSourceDebitAmount` | The full amount deducted from your source balance, including fees. |

For example, a source amount of **100 USDT**, conversion fee of **1 USDT** and payout fee equivalent to **0.5 USDT** would produce:

```json theme={null}
{
  "sourceAmount": "100",
  "sourceDebitAmount": "101",
  "totalFeeAmount": "1.5",
  "totalFeeCurrency": "USDT",
  "totalSourceDebitAmount": "101.5"
}
```

These fictional values illustrate the calculation, not a fee schedule. `totalSourceDebitAmount` already includes both fees. Do not add a payout fee to it again or add amounts in different currencies.

Show `totalSourceDebitAmount` before confirmation. Save the quote ID and `expiresAt`.

## Pay a Ledig business

Call `GET /v1/ledig-businesses/{businessId}` with the recipient business's exact ID. Confirm the returned business name before continuing.

Use this `payOut` shape in your quote:

```json theme={null}
{
  "type": "ledig",
  "businessId": "DESTINATION_BUSINESS_ID",
  "paymentMethodId": "ledig"
}
```

Do not send `recipientId` or `chain` for this payment. You do not need a saved recipient. You cannot use this flow to pay the same business account you are sending from.

## Expiry and readback

Use the quote before `expiresAt`. Read it with `GET /v1/quotes/{id}`, or list quotes with `GET /v1/quotes` and [cursor pagination](https://docs.ledig.io/guides/pagination.md).

Each quote can create one transfer. Both new and replayed quote responses use HTTP `201`. Top-level `replayed: false` means a new quote; `true` means the original quote was returned for the same reference without refreshing its expiry. A replay may return an accepted or expired quote.

If an unused quote expires, request a new quote with a fresh reference. If you already submitted a transfer but did not receive the response, follow [transfer retries](https://docs.ledig.io/guides/transfers.md#retries) using the original identifiers before requesting another quote.

## Handle quote failures

| Error | What to do |
| - | - |
| `404 RATE_NOT_FOUND` | Check whether the currency pair is currently available. |
| `422 RATE_ROUTE_AMOUNT_OUT_OF_RANGE` | Adjust `sourceAmount` to the returned minimum and maximum for the source currency. |
| `409 INSUFFICIENT_BALANCE` | Add funds or reduce the amount. Your balance must cover the full amount including fees. |
| `422 RATE_EXPIRED`, `RATE_STALE` or `RATE_NOT_YET_VALID` | Request a fresh quote when pricing is available. |
| `501 NOT_IMPLEMENTED` for `payIn.type: temporary_bank_account` | Use the [funding flow](https://docs.ledig.io/guides/funding.md) to receive funds. This quote option is not available. |

A rejected quote does not move funds. If a request times out, follow the [retry rules](https://docs.ledig.io/guides/idempotency.md). See [example error responses](https://docs.ledig.io/errors/errors-and-troubleshooting.md#quote-error-examples).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.