Developer Platform
View as Markdown Open in ChatGPT Open in Claude

Manage settlement instructions

Create, list, update and delete the bank accounts and wallets your FX proceeds go to, with the Stellar memo rule.

This page shows how to create, list, update and delete settlement instructions. A settlement instruction is one of your own bank accounts or crypto wallets that FX proceeds settle to. Once you save one, use its id as the destination of an OTC order.

A money example. You receive USDC on Stellar and naira at your bank. You add a Stellar USDC wallet (with its memo) and make it the USDC default. When your old naira account closes, you delete its instruction, so Gravv refuses an order that still points at it instead of paying a closed account.

If you use a scoped API key, it needs payee:create to create and update instructions, and payee:delete to delete them. Reading needs no permission.

Create a settlement instruction

Use Create settlement instruction. Send a new Idempotency-Key for each instruction.

Bank account

curl --request POST \
     --url https://api.gravv.xyz/v1/settlement-instructions \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 0abe4221-51cd-4247-b96c-9992317dd50a' \
     --header 'Content-Type: application/json' \
     --data '
{
  "instruction_type": "bank_account",
  "account_name": "Harbor Digital Ltd",
  "currency": "NGN",
  "is_default": true,
  "account_number": "0123456789",
  "bank_name": "Example Bank",
  "bank_code": "011",
  "country": "NG"
}
'

Crypto wallet

A Stellar wallet needs memo:

curl --request POST \
     --url https://api.gravv.xyz/v1/settlement-instructions \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 2eee315c-23dd-4414-b10d-2312e25427e5' \
     --header 'Content-Type: application/json' \
     --data '
{
  "instruction_type": "crypto_wallet",
  "account_name": "Harbor Treasury Stellar",
  "currency": "USDC",
  "wallet_address": "GC3ONVVSIG2XZHHZCLJPDIR7ZAHR4IJ2AH34DFVDQVEFSPPX46DYJMJ2",
  "network": "stellar",
  "memo": "208117"
}
'

{
  "data": {
    "id": "132c8884-fe71-46b0-8c73-2fdb614f7bb8",
    "type": "crypto_wallet",
    "instruction_type": "crypto_wallet",
    "account_name": "Harbor Treasury Stellar",
    "currency": "USDC",
    "is_default": false,
    "status": "active",
    "wallet_address": "GC3ONVVSIG2XZHHZCLJPDIR7ZAHR4IJ2AH34DFVDQVEFSPPX46DYJMJ2",
    "network": "stellar",
    "memo": "208117",
    "created_at": "2026-10-13T22:33:13.609822Z",
    "updated_at": "2026-10-13T22:33:13.609822Z",
    "date_created": "2026-10-13T22:33:13.609822Z",
    "date_updated": "2026-10-13T22:33:13.609822Z"
  },
  "error": null
}

The answer leaves out empty fields.

Retrieve settlement instructions

List them with List settlement instructions. Filter with currency and instruction_type. Gravv matches both exactly. The list returns the default first, then the newest. The page size is 10 unless you send items_per_page:

curl --request GET \
     --url 'https://api.gravv.xyz/v1/settlement-instructions?currency=USDC&page=1&items_per_page=50' \
     --header 'Api-Key: <API_KEY>'

Read one by its id:

curl --request GET \
     --url https://api.gravv.xyz/v1/settlement-instructions/132c8884-fe71-46b0-8c73-2fdb614f7bb8 \
     --header 'Api-Key: <API_KEY>'

Update a settlement instruction

Use Update settlement instruction (no Idempotency-Key). Send only what changes:

curl --request PATCH \
     --url https://api.gravv.xyz/v1/settlement-instructions/132c8884-fe71-46b0-8c73-2fdb614f7bb8 \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "is_default": true
}
'
  • The previous default for the same currency stops being the default.
  • You cannot change instruction_type or currency. To change them, delete the instruction and create a new one.
  • An empty string keeps the current value, so you cannot clear a field.
  • Gravv does not check values again on update. If you change network to stellar, send memo in the same call.

Delete a settlement instruction

Use Delete settlement instruction. There is no undo:

curl --request DELETE \
     --url https://api.gravv.xyz/v1/settlement-instructions/132c8884-fe71-46b0-8c73-2fdb614f7bb8 \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "status": "deleted"
  },
  "error": null
}

The instruction disappears from every read. Gravv refuses an order sent to it with bad destination: [400] invalid order destination. Orders already completed keep its id as their destination. If you deleted the default, make another one the default.

What can go wrong

Response Why Fix
400 memo is required for the stellar network: invalid input The Stellar wallet has no memo Add memo
400 wallet address is required for crypto wallets: invalid input wallet_address is missing Add it
400 network is required for crypto wallets: invalid input network is missing Add it
400 settlement instruction <id>: resource not found The id is unknown, belongs to another business, or was already deleted List your instructions to get current ids
400 invalid id The path id is not a UUID Use the id from the list
Two defaults for the same currency You saved one as usdc and one as USDC Always send upper case
Was this page helpful?