Create an FX quote
Returns a foreign exchange rate quote for a given currency pair and amount.
The quote includes a quote_id and an expiry time. Use the quote_id when
submitting a transfer to lock in the quoted rate.
The Idempotency-Key header is required; requests without it are rejected.
Headers
A unique key to prevent duplicate requests. Required on all FX write operations; requests without it are rejected with a 400.
Request Body
Source currency code (ISO 4217).
Target currency code (ISO 4217).
Amount in the source currency to convert. Must be greater than zero.
Direction of the trade.
Possible values: BUY, SELL
Request Examples
{
"from_currency": "USD",
"to_currency": "ZAR",
"amount": 10,
"direction": "BUY"
}
Responses
| Status | Description |
|---|---|
200 |
FX quote returned successfully |
400 |
Invalid request |
401 |
Missing or invalid API key |
500 |
Internal server error |
200 response
Possible values: BUY, SELL
Human-readable display rate for the quote.
Formatted label expressing the rate in plain language.
The amount received in the target currency after applying the rate.
{
"data": {
"amount": 10,
"direction": "BUY",
"display_rate": 16.283561522388,
"display_rate_label": "1 USD = 16.2836 ZAR",
"expires_at": "2026-07-03T16:30:05.640502651+01:00",
"from_currency": "USD",
"quote_id": "QT-rypoCbnP",
"rate": 16.283561522388,
"to_currency": "ZAR",
"to_currency_amount": 162.83561522388
},
"error": null
}
400 response
Always null for error responses.
Human-readable error message.
{
"data": null,
"error": "missing idempotency key in request headers"
}
{
"data": null,
"error": "missing required field 'amount'"
}
{
"data": null,
"error": "missing required field 'from_currency', missing required field 'to_currency', missing required field 'amount', missing required field 'direction'"
}
{
"data": null,
"error": "field 'amount' must be greater than 0"
}
{
"data": null,
"error": "field 'direction' must be one of: BUY SELL"
}
{
"data": null,
"error": "currency pair KWD/NGN not supported"
}
401 response
Always null for error responses.
Human-readable error message.
{
"data": null,
"error": "Invalid or missing Api-Key header. Api-Key is required!"
}
{
"data": null,
"error": "Invalid token!"
}
500 response
Always null for error responses.
Human-readable error message.
{
"data": null,
"error": "failed to retrieve FX quote"
}
Authorization
- ApiKeyAuth