Foreign exchange (FX)
Sell one currency for another with an OTC order. Get a quote, place the order with it, and see what can be traded today.
This page explains how currency exchange works in Gravv and what you can trade today. An exchange is an OTC order (an over-the-counter order). You get a quote for the amount you want to sell, then create an order with that quote. The order takes the amount you sell from a Gravv account or wallet and delivers the proceeds to another one, or to a saved settlement instruction.
A money example. You hold 2,000,000 NGN in an NGN account and want USDC. You ask for a quote on NGN_USDC for "2000000". The quote says you receive 1,300 USDC (a rate of 0.00065) and lasts about 5 minutes. You place the order with a USDC wallet as the destination. Gravv takes the 2,000,000 NGN at once. The order shows completed once the 1,300 USDC is delivered.
What can be traded
| Trade (sell to buy) | Status |
|---|---|
| NGN to USDC, USDC to NGN | Available once Gravv sets an OTC rate for your business |
| Any other pair (USD to EUR, NGN to USD, GBP pairs) | Not yet available by default. Contact support. A quote returns quote currency pair is not supported until Gravv sets up and prices the pair for you |
| From an account with no wallet behind it (bank-held) | Not supported |
To a customer's payee from /v1/external-accounts |
Not supported. Proceeds go to a Gravv account or wallet, or to your own settlement instruction |
| "Buy exactly X", limit orders, target rates | Not supported. The quote amount is always the amount you sell |
The sandbox has no OTC rates yet, so quotes there return quote currency pair is not supported.
OTC order workflow
- Get indicative rates to show prices, if you need them. They are for display only.
- Get a quote for the amount you sell. It lasts about 5 minutes, and you can use it once.
- Create the order with the
quote_id, asourceand adestination. An order placed with an API key needs no approval. It starts aspending, and Gravv debits the source at once. - Track the order until it is
completed. Gravv sends no webhook for FX orders, so poll the order.
Quote direction
A quote's currency_pair is FROM_TO. You sell the FROM currency and receive the TO currency. USDC_NGN sells USDC for NGN. NGN_USDC sells NGN for USDC. The amount is always the amount you sell.
Not an FX order
These tasks are not FX orders:
- To move USDT to USDC between two wallets of the same customer, send a transfer with a conversion.
- To pay someone else in their currency, send a payout. See the recipes.
For step-by-step guides, see the FX recipes.