Settlement instructions
Save your own bank accounts and crypto wallets once, then use them as the destination of FX orders.
This page explains what a settlement instruction is and the rules that apply to it. A settlement instruction is one of your business's own bank accounts or crypto wallets. You save it once, and Gravv pays FX proceeds to it. You reference it by its id instead of sending the bank or wallet details each time.
A money example. You sell 1,000 USDC for naira. You saved your naira bank account as an instruction, so the order's destination is {"type": "external_account", "id": "<instruction id>"}, and the 1,368,270 NGN of proceeds goes to that bank account.
When you place an OTC order with destination.type external_account, destination.id is the settlement instruction. It must exist and be in the order's TO currency.
Settlement instruction vs external account
A settlement instruction is where you receive FX proceeds. An external account is a payee you send money to. They are separate, and an FX order cannot pay a payee.
Instruction types
| Type | Use it for | Required fields |
|---|---|---|
bank_account |
Your bank account | account_number, bank_name. Add routing_number, swift_code, iban, bank_code, country and address as your bank needs |
crypto_wallet |
Your crypto wallet | wallet_address, network, and memo when network is stellar |
Every instruction also needs instruction_type, account_name (the name on the account or wallet) and currency.
Rules to know
- Gravv matches
currencyexactly, so always send upper case (USDC, notusdc). - One instruction per currency can be the default (
is_default). When you make a new instruction the default, the old one stops being the default. Deleting the default leaves no default. - You cannot change
instruction_typeorcurrencyafter you create the instruction. To change them, delete it and create a new one. - Gravv does not check wallet addresses, so copy them carefully. Gravv stores
networkas you send it, so keep one lower-case spelling, such asstellar. - A deleted instruction disappears from every read, and Gravv refuses an order sent to it. Every instruction you can read has
statusactive. - Gravv sends no webhooks for settlement instructions.
Next step
See Manage settlement instructions to create, list, update and delete them.