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 Create settlement instruction 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 '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 '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 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 settlement instruction 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 Update settlement instruction 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 settlement instruction:

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