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 (plan 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 only and locks the rate until it is consumed by the matching executor or expires; 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",
  "toAmount": "100",
  "toCurrency": "GBP"
}
'

import requests

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

payload = {
    "fromCurrency": "NGN",
    "intent": "payout",
    "toAmount": "100",
    "toCurrency": "GBP"
}
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', toAmount: '100', toCurrency: 'GBP'})
};

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',
    'toAmount' => '100',
    'toCurrency' => 'GBP'
  ]),
  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  \"toAmount\": \"100\",\n  \"toCurrency\": \"GBP\"\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  \"toAmount\": \"100\",\n  \"toCurrency\": \"GBP\"\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  \"toAmount\": \"100\",\n  \"toCurrency\": \"GBP\"\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",
  "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 requires toAmount (the beneficiary amount); a convert quote requires fromAmount (the source debit). The opposite side is rejected with a stable not-yet-supported 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"

toAmount

string

required

Amount the beneficiary receives, in toCurrency (required). Fixes the delivered leg; the pair takes exactly one of fromAmount / toAmount.

Example:

"100"

toCurrency

string

required

Target currency (received by the beneficiary)

Example:

"GBP"

rail

enum<string>

The rail the payout will use. A plan's rate row for that rail prices the quote, falling back to its rail-agnostic row. Required whenever the plan prices the pair on any specific 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

Response

The minted quote. Every intent returns the same shape.

expiresAt

string

required

Quote expiry timestamp (ISO 8601)

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. The quote prices FX + markup only, so this is the FX base; a payout's per-transaction fee (a flat amount, or basis points of the debit floored at that amount) is added at payout creation.

Example:

"252447.5600"

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",
  "toAmount": "100",
  "toCurrency": "GBP"
}
'

import requests

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

payload = {
    "fromCurrency": "NGN",
    "intent": "payout",
    "toAmount": "100",
    "toCurrency": "GBP"
}
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', toAmount: '100', toCurrency: 'GBP'})
};

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',
    'toAmount' => '100',
    'toCurrency' => 'GBP'
  ]),
  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  \"toAmount\": \"100\",\n  \"toCurrency\": \"GBP\"\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  \"toAmount\": \"100\",\n  \"toCurrency\": \"GBP\"\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  \"toAmount\": \"100\",\n  \"toCurrency\": \"GBP\"\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",
  "status": "active"
}

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