> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Book

> List, add, rename, and remove the wallet addresses saved to your key

Manage the addresses saved to your API key — the same list you see in [Octav Pro](https://pro.octav.fi). Entries are keyed by address.

<Info>
  **Cost:** 1 credit per call
</Info>

<Note>
  **Interactive Playground:** Test these endpoints in the [API Playground](/api-reference/addressbook). Get your API key at [data.octav.fi](https://data.octav.fi/)
</Note>

***

## The entry object

<ResponseField name="address" type="string">
  Wallet address.
</ResponseField>

<ResponseField name="label" type="string">
  Your name for the address.
</ResponseField>

<ResponseField name="plan" type="string">
  `FREE`, `LITE`, or `PRO`.
</ResponseField>

<ResponseField name="expiresAt" type="string | null">
  When the plan lapses. `null` on `FREE`.
</ResponseField>

<ResponseField name="isPaid" type="boolean">
  Whether the plan is currently active.
</ResponseField>

```json theme={null}
{
  "address": "0xe760ad8df0a54aafd95e3bc271b65d224abeaa57",
  "label": "Treasury",
  "plan": "PRO",
  "expiresAt": "2026-11-01T00:00:00.000Z",
  "isPaid": true
}
```

***

## List Entries

### Endpoint

```bash theme={null}
GET https://api.octav.fi/v1/addressbook
```

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.octav.fi/v1/addressbook" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.octav.fi/v1/addressbook', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const { data } = await response.json();
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": [
    {
      "address": "0xe760ad8df0a54aafd95e3bc271b65d224abeaa57",
      "label": "Treasury",
      "plan": "PRO",
      "expiresAt": "2026-11-01T00:00:00.000Z",
      "isPaid": true
    },
    {
      "address": "EPa1MBU21RjhoyZTEDcDj4yLVemtzxpVy35rVpgTcoV3",
      "label": "",
      "plan": "FREE",
      "expiresAt": null,
      "isPaid": false
    }
  ]
}
```

***

## Add Entries

### Endpoint

```bash theme={null}
POST https://api.octav.fi/v1/addressbook
```

### Parameters

<ParamField body="entries" type="array" required>
  1–100 entries per request. Up to 50 addresses without a paid plan — contact us to raise it.
</ParamField>

<ParamField body="entries[].address" type="string" required>
  Wallet address. Must be unique within the request.
</ParamField>

<ParamField body="entries[].label" type="string">
  Up to 255 characters.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.octav.fi/v1/addressbook" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entries": [
        { "address": "0xe760ad8df0a54aafd95e3bc271b65d224abeaa57", "label": "Treasury" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.octav.fi/v1/addressbook', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entries: [{ address: '0xe760ad8df0a54aafd95e3bc271b65d224abeaa57', label: 'Treasury' }]
    })
  });

  const { data } = await response.json();
  ```
</CodeGroup>

### Response

Returns the full address book.

***

## Rename Entry

### Endpoint

```bash theme={null}
PATCH https://api.octav.fi/v1/addressbook/{address}
```

### Parameters

<ParamField path="address" type="string" required>
  Wallet address.
</ParamField>

<ParamField body="label" type="string" required>
  Up to 255 characters. `""` clears it.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.octav.fi/v1/addressbook/0xe760ad8df0a54aafd95e3bc271b65d224abeaa57" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "label": "Cold Wallet" }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://api.octav.fi/v1/addressbook/${address}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ label: 'Cold Wallet' })
    }
  );

  const { data } = await response.json();
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": {
    "address": "0xe760ad8df0a54aafd95e3bc271b65d224abeaa57",
    "label": "Cold Wallet",
    "plan": "PRO",
    "expiresAt": "2026-11-01T00:00:00.000Z",
    "isPaid": true
  }
}
```

***

## Remove Entry

### Endpoint

```bash theme={null}
DELETE https://api.octav.fi/v1/addressbook/{address}
```

### Parameters

<ParamField path="address" type="string" required>
  Wallet address.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.octav.fi/v1/addressbook/0xe760ad8df0a54aafd95e3bc271b65d224abeaa57" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://api.octav.fi/v1/addressbook/${address}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
  ```
</CodeGroup>

### Response

`204` with no body. Entries on a paid plan, or authorized by the wallet owner, return `409` — remove those in [Octav Pro](https://pro.octav.fi).

***

## Address Matching

**EVM** addresses match case-insensitively. **Solana**, **Tron**, and **Starknet** addresses are case-sensitive.

***

## Error Responses

| Code                              | Status | Meaning                                                   |
| --------------------------------- | ------ | --------------------------------------------------------- |
| `VALIDATION_ERROR`                | 400    | Invalid or duplicate address                              |
| `ADDRESSBOOK_ENTRY_NOT_FOUND`     | 404    | Address is not in your book                               |
| `ADDRESSBOOK_ENTRY_NOT_DELETABLE` | 409    | Entry is on a paid plan or authorized by the wallet owner |
| `ADDRESSBOOK_QUOTA_REACHED`       | 422    | Address limit reached                                     |
| `INTERNAL_ERROR`                  | 500    | Unexpected failure                                        |

```json theme={null}
{
  "error": {
    "code": "ADDRESSBOOK_QUOTA_REACHED",
    "message": "Address book quota reached",
    "quota": 50,
    "current": 50
  }
}
```

<Note>
  **Rate limit:** 360 requests/min.
</Note>

***

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Bundles" icon="layer-group" href="/api/endpoints/bundles">
    Group saved addresses together
  </Card>

  <Card title="Portfolio" icon="wallet" href="/api/endpoints/portfolio">
    Holdings for an address
  </Card>
</CardGroup>