Quotes

Create a quote

Mints a single-use held quote for the requested currency pair. intent selects the action: ‘payout’ prices a held cross-rate / fiat-source / same-currency quote (the corridor picks the engine), ‘convert’ prices an in-wallet conversion between the caller’s own balances, and ‘order’ prices a trade-desk order (your markup + order-channel spread, no fee). Exactly one of fromAmount / toAmount fixes a leg of the pair: payout fixes toAmount (the beneficiary amount), convert fixes fromAmount (the source debit), and order fixes either side. The quote prices FX + markup, plus the per-conversion fee on convert intent, and locks the rate until it is consumed by the matching executor or expires. Read expiresAt for how long the quote is valid rather than assuming a duration. A payout’s per-transaction fee (a flat amount, or basis points of the debit floored at that amount) is applied at payout creation, not here. Every intent returns the same QuoteResponseDto, always carrying a rate (1 for a same-currency or stablecoin-par quote).

POST

quotes

Create a quote

curl --request POST \
  --url https://api.example.com/v1/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromCurrency": "NGN",
  "intent": "payout",
  "toCurrency": "GBP",
  "fromAmount": "100",
  "toAmount": "100"
}
'

import requests

url = "https://api.example.com/v1/quotes"

payload = {
    "fromCurrency": "NGN",
    "intent": "payout",
    "toCurrency": "GBP",
    "fromAmount": "100",
    "toAmount": "100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromCurrency: 'NGN',
    intent: 'payout',
    toCurrency: 'GBP',
    fromAmount: '100',
    toAmount: '100'
  })
};

fetch('https://api.example.com/v1/quotes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/quotes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromCurrency' => 'NGN',
    'intent' => 'payout',
    'toCurrency' => 'GBP',
    'fromAmount' => '100',
    'toAmount' => '100'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/quotes"

	payload := strings.NewReader("{\n  \"fromCurrency\": \"NGN\",\n  \"intent\": \"payout\",\n  \"toCurrency\": \"GBP\",\n  \"fromAmount\": \"100\",\n  \"toAmount\": \"100\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/quotes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromCurrency\": \"NGN\",\n  \"intent\": \"payout\",\n  \"toCurrency\": \"GBP\",\n  \"fromAmount\": \"100\",\n  \"toAmount\": \"100\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/quotes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromCurrency\": \"NGN\",\n  \"intent\": \"payout\",\n  \"toCurrency\": \"GBP\",\n  \"fromAmount\": \"100\",\n  \"toAmount\": \"100\"\n}"

response = http.request(request)
puts response.read_body

{
  "expiresAt": "2026-04-13T12:00:30Z",
  "fromCurrency": "NGN",
  "id": "uuid-here",
  "rate": "2524.47560000",
  "targetAmount": "100",
  "toCurrency": "GBP",
  "totalDebitAmount": "252447.5600",
  "fee": "2.5000",
  "feeCurrency": "USD",
  "status": "active"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Headers

Idempotency-Key

string

Client-generated idempotency key

Body

application/json

The intent field discriminates the body, and exactly one of fromAmount / toAmount fixes a leg of the pair. A payout quote takes either: toAmount fixes the beneficiary amount, fromAmount fixes the debit before the payout fee (NGN to GBP, EUR and USD take toAmount only). A convert quote requires fromAmount (the source debit). An order quote takes either. A side an intent does not take is rejected with a stable code. The runtime body is a single CreateQuoteDto validated per-intent.

Option 1
Option 2
Option 3

fromCurrency

string

required

Source currency (debited from the client)

Example:

"NGN"

intent

enum<string>

required

Must be 'payout' for this variant.

Available options:

payout

Example:

"payout"

toCurrency

string

required

Target currency (received by the beneficiary)

Example:

"GBP"

fromAmount

string

Fixes the funded leg: the debit in fromCurrency, before the payout fee that is added at payout creation. The quote computes toAmount: on a cross-currency pair it is rounded down to the smallest unit every payout method in the target currency accepts (whole shillings for KES), on a same-currency pair it equals fromAmount. Create the payout for exactly that amount. Provide exactly one of fromAmount / toAmount. NGN to GBP, EUR and USD take toAmount only. Major-unit decimal string, up to 4 dp.

Example:

"100"

rail

enum<string>

The rail the payout will use. Your terms for the pair on that rail price the quote, falling back to your rail-agnostic terms. Required whenever your terms for the pair differ by rail: omitting it there is refused with RAIL_REQUIRED. The payout consuming the quote must run on the same rail, or it is refused with QUOTE_RAIL_MISMATCH.

Available options:

sepa_inst,

sepa_credit,

bank_transfer,

ach,

fedwire,

swift,

crypto,

mobile_money

toAmount

string

Fixes the delivered leg: the amount the beneficiary receives, in toCurrency. Provide exactly one of fromAmount / toAmount. Major-unit decimal string, up to 4 dp.

Example:

"100"

Response

The minted quote. Every intent returns the same shape.

expiresAt

string

required

Quote expiry timestamp (ISO 8601). Read this field for how long the quote is valid rather than assuming a duration.

Example:

"2026-04-13T12:00:30Z"

fromCurrency

string

required

Source currency (debited from the caller)

Example:

"NGN"

string

required

Quote identifier

Example:

"uuid-here"

rate

string

required

All-in rate: fromCurrency per 1 toCurrency. Always present; a same-currency or stablecoin-par quote (no FX leg) reports "1.00000000".

Example:

"2524.47560000"

targetAmount

string

required

Amount received in toCurrency

Example:

"100"

toCurrency

string

required

Target currency (received by the beneficiary, or credited to the caller's own balance for a convert quote)

Example:

"GBP"

totalDebitAmount

string

required

Total amount debited from the caller in fromCurrency. A payout quote prices FX + markup only, so this is the FX base; the payout's per-transaction fee (a flat amount, or basis points of the debit floored at that amount) is added at payout creation. A convert quote includes its fee here: the debit less fee is what converts at rate.

Example:

"252447.5600"

fee

string

Convert intent only: the fee taken out of totalDebitAmount, in feeCurrency. "0.0000" where your policy prices the pair without one.

Example:

"2.5000"

feeCurrency

string

Convert intent only: the currency fee is charged in — the source currency.

Example:

"USD"

status

enum<string>

Quote status (only included on GET)

Available options:

active,

used,

expired

Create a quote

curl --request POST \
  --url https://api.example.com/v1/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromCurrency": "NGN",
  "intent": "payout",
  "toCurrency": "GBP",
  "fromAmount": "100",
  "toAmount": "100"
}
'

import requests

url = "https://api.example.com/v1/quotes"

payload = {
    "fromCurrency": "NGN",
    "intent": "payout",
    "toCurrency": "GBP",
    "fromAmount": "100",
    "toAmount": "100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromCurrency: 'NGN',
    intent: 'payout',
    toCurrency: 'GBP',
    fromAmount: '100',
    toAmount: '100'
  })
};

fetch('https://api.example.com/v1/quotes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/quotes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromCurrency' => 'NGN',
    'intent' => 'payout',
    'toCurrency' => 'GBP',
    'fromAmount' => '100',
    'toAmount' => '100'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/quotes"

	payload := strings.NewReader("{\n  \"fromCurrency\": \"NGN\",\n  \"intent\": \"payout\",\n  \"toCurrency\": \"GBP\",\n  \"fromAmount\": \"100\",\n  \"toAmount\": \"100\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/quotes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromCurrency\": \"NGN\",\n  \"intent\": \"payout\",\n  \"toCurrency\": \"GBP\",\n  \"fromAmount\": \"100\",\n  \"toAmount\": \"100\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/quotes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromCurrency\": \"NGN\",\n  \"intent\": \"payout\",\n  \"toCurrency\": \"GBP\",\n  \"fromAmount\": \"100\",\n  \"toAmount\": \"100\"\n}"

response = http.request(request)
puts response.read_body

{
  "expiresAt": "2026-04-13T12:00:30Z",
  "fromCurrency": "NGN",
  "id": "uuid-here",
  "rate": "2524.47560000",
  "targetAmount": "100",
  "toCurrency": "GBP",
  "totalDebitAmount": "252447.5600",
  "fee": "2.5000",
  "feeCurrency": "USD",
  "status": "active"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}