Manage settlement instructions

Create and manage the bank accounts and crypto wallets you settle funds to. Once saved, reference an instruction by its ID, for example as the destination of an OTC order.

Create a settlement instruction

Use the POST /v1/settlement-instructions endpoint. These fields apply to every instruction:

Field	Type	Description
instruction_type	string	bank_account or crypto_wallet
account_name	string	a label for the destination
currency	string	the settlement currency
is_default	boolean	optional; make this the default for its currency

Bank account

Send the bank fields that match the corridor (routing_number for US accounts, swift_code for international, iban where applicable):

curl --request POST \
     --url https://api.gravv.xyz/v1/settlement-instructions \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: bank-settlement-<UUID>' \
 --header 'content-type: application/json' \
 --data '
{
"instruction_type": "bank_account",
"account_name": "Operating account",
"currency": "USD",
"is_default": true,
"account_number": "0123456789",
"bank_name": "Example Bank",
"routing_number": "123456789",
"country": "US",
"address": {
"address_line1": "201 Allen St",
"city": "New York",
"state": "New York",
"postal_code": "10002",
"country_code": "US"
}
}
'

The response returns the saved instruction with its id and status:

{
"data": {
"id": "a14ec356-f33d-4384-ba68-4d9bfa19765b",
"instruction_type": "bank_account",
"account_name": "Operating account",
"currency": "USD",
"is_default": true,
"status": "active",
"account_number": "0123456789",
"bank_name": "Example Bank",
"routing_number": "123456789",
"country": "US",
"date_created": "2026-06-20T10:29:16.000Z"
},
"error": null
}

Crypto wallet

For a crypto destination, send the wallet fields. Include memo when the network requires one:

curl --request POST \
 --url https://api.gravv.xyz/v1/settlement-instructions \
 --header 'Api-Key: <API_KEY>' \
 --header 'Idempotency-Key: wallet-settlement-<UUID>' \
--header 'content-type: application/json' \
--data '
{
"instruction_type": "crypto_wallet",
"account_name": "USDC treasury",
"currency": "USDC",
"wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
"network": "polygon"
}
'

Retrieve settlement instructions

List them with GET /v1/settlement-instructions. Filter with currency and instruction_type, and page with page and items_per_page (default 20, max 100):

curl --request GET \
--url 'https://api.gravv.xyz/v1/settlement-instructions?currency=USD&instruction_type=bank_account' \
--header 'Api-Key: <API_KEY>'

Get a single instruction with GET /v1/settlement-instructions/{id} by its ID:

curl --request GET \
--url https://api.gravv.xyz/v1/settlement-instructions/a14ec356-f33d-4384-ba68-4d9bfa19765b \
--header 'Api-Key: <API_KEY>'

Update a settlement instruction

Use PATCH /v1/settlement-instructions/{id} to change the label, the saved details, or which instruction is the default for its currency. Send only the fields you want to change:

curl --request PATCH \
--url https://api.gravv.xyz/v1/settlement-instructions/a14ec356-f33d-4384-ba68-4d9bfa19765b \
--header 'Api-Key: <API_KEY>' \
--header 'content-type: application/json' \
--data '
{
"account_name": "Primary operating account",
"is_default": true
}
'

Delete a settlement instruction

Remove one with DELETE /v1/settlement-instructions/{id}:

curl --request DELETE \
--url https://api.gravv.xyz/v1/settlement-instructions/a14ec356-f33d-4384-ba68-4d9bfa19765b \
--header 'Api-Key: <API_KEY>'