Create a settlement instruction
Saves one of your own bank accounts or crypto wallets to receive FX order proceeds. Pass its id as the order destination with type external_account. Its currency must match the currency the order buys. Gravv does not check the details with a bank or check for duplicates.
Headers
1 to 255 printable ASCII characters. A retry with the same key within 24 hours returns the first response, including a 400. After you correct a request, send a new key.
Request Body
Send it in lower case, exactly as listed
Possible values: bank_account, crypto_wallet
Name on the account or wallet
Currency this destination receives, such as USD or USDC. Gravv stores it as sent and filters match it exactly, so always send upper case.
Makes this the default for its currency and unsets the old default.
Required for bank_account
Required for bank_account
The bank's address, stored as sent
Required for crypto_wallet. Gravv does not check its format, so check it yourself.
Required for crypto_wallet, such as polygon or stellar. Send lower case.
Required when network is stellar
Request Examples
{
"instruction_type": "bank_account",
"account_name": "Acme Treasury LLC",
"currency": "USD",
"is_default": true,
"account_number": "000987654321",
"bank_name": "Example Bank",
"routing_number": "026009593",
"country": "US"
}
{
"instruction_type": "crypto_wallet",
"account_name": "Acme Treasury",
"currency": "USDC",
"wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
"network": "polygon"
}
Responses
| Status | Description |
|---|---|
200 |
The saved settlement instruction |
400 |
A missing or invalid field |
200 response
A settlement instruction. The response leaves out empty fields.
Use it as an FX order destination.id
The same value as instruction_type
Possible values: bank_account, crypto_wallet
Send it in lower case, exactly as listed
Possible values: bank_account, crypto_wallet
Always active; the API does not return deleted instructions
Possible values: active
{
"data": {
"id": "b7e1c2d3-4f5a-4b6c-9d8e-7f6a5b4c3d2e",
"tenant_id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"type": "bank_account",
"instruction_type": "bank_account",
"account_name": "Acme Treasury LLC",
"currency": "USD",
"is_default": true,
"status": "active",
"account_number": "000987654321",
"bank_name": "Example Bank",
"routing_number": "026009593",
"country": "US",
"created_at": "2026-10-12T09:20:00Z",
"updated_at": "2026-10-12T09:20:00Z",
"date_created": "2026-10-12T09:20:00Z",
"date_updated": "2026-10-12T09:20:00Z"
},
"error": null
}
400 response
{
"data": null,
"error": "memo is required for the stellar network: invalid input"
}
Authorization
- ApiKeyAuth