API Reference

Foreign exchange overview

Use the Foreign Exchange API to find currency pairs, retrieve rates and quotes, and create, track or cancel FX orders. Today, only the NGN and USDC pair is set up for OTC (over-the-counter) orders, and only after Gravv sets an OTC rate for your business. Gravv sets up other pairs on request. Sandbox has no OTC rates yet.

Discover supported currencies or browse the operations in this category.

Review rates, quotes, and OTC order workflows.

How it works

The FX API has three layers:

Rates. GET /v1/fx/supported-currencies lists the currency pairs Gravv knows, fiat and crypto. It reads no query parameters. GET /v1/fx/rates returns indicative rates. A pair in either list is not necessarily one you can quote.
Quotes. POST /v1/fx/quote takes currency_pair (FROM_TO) and the amount you sell, as a string. It returns a quote with a quote_id that expires after about 5 minutes. You can use the quote_id once, and only to create an OTC order. It does not lock a rate for a transfer.
OTC orders. Create an order with POST /v1/fx/orders, and send quote_id, source and destination. An order you create with an API key needs no approval. It starts as pending, and Gravv debits the source at once. destination.type sets where the converted funds settle: internal_account, internal_crypto_wallet, or external_account for a saved settlement instruction. Gravv sends no webhook for FX orders.

Endpoints

Rates and quotes

Endpoint	Description
`GET /v1/fx/supported-currencies`	List the currency pairs Gravv knows
`GET /v1/fx/rates`	Get indicative exchange rates
`POST /v1/fx/quote`	Create a quote with a `quote_id` and expiry

OTC orders

Endpoint	Description
`POST /v1/fx/orders`	Create an OTC order from a quote. An order you create with an API key starts as `pending`
`GET /v1/fx/orders`	List orders, most recent first. `status` (lower case) is the only filter. The API ignores date filters
`GET /v1/fx/orders/pending-approvals`	List Dashboard orders waiting for approval. Orders you create with an API key never appear
`GET /v1/fx/orders/{order_id}`	Retrieve a single order
`POST /v1/fx/orders/{order_id}/cancel`	Cancel an order that is `waiting_approval`. Do not cancel a `pending` order. Once its debit completes, the API accepts a cancel but does not return the money

List filters that match nothing, including unknown status values and unsupported currency codes, don't return an error. They return 200 with an empty result array.

Authentication

All requests use https://api.gravv.xyz/v1/ and authenticate with the Api-Key header. Requests that create a quote, create an order or cancel an order require an Idempotency-Key header. The API rejects a request without one.

Was this page helpful?