Skip to main content
GET
Get token rate (v2)
Get buy and/or sell quotes on a specific network—either a token + fiat pair or a fiat + fiat corridor (via USDC). This is the recommended public rates URL for v2 integrations.
The legacy endpoint GET /v1/rates/{token}/{amount}/{fiat} (optional network query) returns a single numeric data field. The v2 path below returns a structured buy / sell payload.

Path parameters

Token + fiat: exactly one fiat and one token (.../USDT/100/NGN.../NGN/100/USDT). from/to cannot both be tokens. Path order does not imply trade direction—use side or read data.buy / data.sell for on-ramp vs off-ramp display. Fiat + fiat: both are fiat codes; the server quotes through USDC on the same network. sell.rate = to per 1 from. buy.rate = from per 1 to (inverse corridor, not the reciprocal of sell—each side uses the appropriate leg bid/ask).

Query parameters

Example

Success response (data)

Each populated side includes:
When side=buy or side=sell, only that key is present under data. providerIds is always an array[] when no provider is available, never null. It carries exactly one id when you pass ?provider_id= or ?limit=1. Fewer than 3 ids means fewer eligible providers for that corridor and notional. The fallback provider is never listed.

Errors

Rate resolution

Behavior matches the priority-queue–based resolution used when creating orders: the quote reflects provider selection and validation for the requested side (buy vs sell). Path segment order (from / to) does not select direction—use ?side=, or read data.sell for off-ramp (crypto → fiat) display and data.buy for on-ramp (fiat → crypto) before POST /v2/sender/orders.

The provider queue

providerIds is ranked, best first, and is the same queue an order created from this quote will walk. providerIds[0] is the provider whose rate is quoted in rate; the remaining ids are the ones assignment falls through to if the head declines, expires, or exhausts its retries. The queue is resolved once, at order creation, and the order carries it for its whole life. Two ways to use that:
1

Let the API resolve it

Omit destination.providerId and destination.providerIds on create. The API resolves a fresh queue at creation time. Nothing to do—this is the default.
2

Pass the queue you quoted

Send data.sell.providerIds straight through as destination.providerIds on POST /v2/sender/orders. Routing is then pinned to the providers your user actually saw a rate from. See Pin a provider queue.
Exhausting the queue is not an immediate refund. After the last entry, the order falls through to fallback assignment, and only then to refund after the refund window and its guards. Don’t model this as “3 tries then refund”.
Quotes rank the public book, so providerIds lists only providers open to every sender. If you route to a provider dedicated to you, name it directly in destination.providerIds on create—it will not appear in a public quote. See also Get Token Rate (v1) for the legacy scalar response.

Path Parameters

network
enum<string>
required

Blockchain network identifier (lowercase in URL).

Available options:
ethereum,
base,
bnb-smart-chain,
lisk,
celo,
arbitrum-one,
polygon,
starknet,
tron
from
string
required

Fiat code or token symbol on network (paired with to).

amount
string
required

For token+fiat pairs, the token notional. For fiat+fiat pairs, the amount in from fiat.

to
string
required

Fiat code or token symbol on network (paired with from).

Query Parameters

side
enum<string>

Return only the buy or sell quote. Omit for both sides.

Available options:
buy,
sell
from_source
enum<string>

When from matches both a fiat and a crypto asset on network, set to fiat or crypto to disambiguate. Ignored when from is unambiguous.

Available options:
fiat,
crypto
to_source
enum<string>

When to matches both a fiat and a crypto asset on network, set to fiat or crypto to disambiguate. Ignored when to is unambiguous.

Available options:
fiat,
crypto
provider_id
string

Optional. When set, limits the quote to this provider. Must be exactly 8 alphabetic characters (A–Z, a–z). Returns a single entry in providerIds.

Pattern: ^[A-Za-z]{8}$
limit
integer
default:3

Maximum number of ranked provider ids to return in providerIds, per side. Values outside 1–3 return 400.

Required range: 1 <= x <= 3

Response

Token rate quote(s)

status
string
Example:

"success"

message
string
Example:

"Operation successful"

data
object

Public token rate quote. Omit side to receive both buy and sell; use side=buy or side=sell for a single side.