---
title: "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](/platform/foreign-exchange/place-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):

```bash title="create a bank settlement instruction"
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`:

```json title="create a bank settlement instruction response"
{
  "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:

```bash title="create a crypto settlement instruction"
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):

```bash title="list settlement instructions request"
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:

```bash title="get a settlement instruction request"
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:

```bash title="update a settlement instruction request"
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}`:

```bash title="delete a settlement instruction request"
curl --request DELETE \
     --url https://api.gravv.xyz/v1/settlement-instructions/a14ec356-f33d-4384-ba68-4d9bfa19765b \
     --header 'Api-Key: <API_KEY>'
```