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

# Manage Address Filters

> Add, remove, and replace TRON addresses in a subscription's filter list. Off the Hook fires webhooks only for transfers involving these addresses.

Address filters tell Off the Hook which on-chain transfers should trigger a delivery for a given subscription. A subscription with no addresses in its filter list never fires — you must add at least one address before deliveries begin.

Each address entry has two fields:

* `chainId` — a CAIP-2 chain identifier (e.g., `tron:mainnet`, `tron:nile`, `tron:shasta`)
* `address` — a base58check TRON address starting with `T`

<Tip>
  Use PATCH for incremental changes to your address list. Use PUT only when you want to atomically replace the entire list in one operation — for example, when syncing from an authoritative external source.
</Tip>

## Add or remove specific addresses

`PATCH /v1/subscriptions/:id/filters/addresses` accepts `add` and `remove` arrays in a single request. The operation is atomic per item — each address is independently validated and either applied or skipped. The response includes per-item results so you can see exactly what changed.

```bash theme={null}
curl -X PATCH https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../filters/addresses \
  -H "Authorization: Bearer oth_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [
      { "chainId": "tron:mainnet", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" }
    ],
    "remove": [
      { "chainId": "tron:nile", "address": "TOldAddress..." }
    ]
  }'
```

The response includes the updated subscription and a `results` object with three arrays:

```json theme={null}
{
  "subscription": { "id": "sub_2QkP9aB7xN...", "..." : "..." },
  "results": {
    "added": [
      { "chainId": "tron:mainnet", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" }
    ],
    "removed": [],
    "skipped": [
      {
        "input": { "chainId": "tron:nile", "address": "TOldAddress..." },
        "reason": "not_found",
        "detail": "address was not in the filter list"
      }
    ]
  }
}
```

| Field             | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| `results.added`   | Addresses that were successfully added                                 |
| `results.removed` | Addresses that were successfully removed                               |
| `results.skipped` | Addresses that were not applied, with a `reason` and optional `detail` |

## Replace the full address list

`PUT /v1/subscriptions/:id/filters/addresses` replaces the entire address list atomically. All existing addresses are removed and replaced with the list you provide. Send the new list as a JSON array directly in the request body.

```bash theme={null}
curl -X PUT https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../filters/addresses \
  -H "Authorization: Bearer oth_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "chainId": "tron:mainnet", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" },
    { "chainId": "tron:mainnet", "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }
  ]'
```

The response is the updated subscription view. Unlike PATCH, PUT does not return a per-item `results` envelope.

## List addresses

`GET /v1/subscriptions/:id/filters/addresses` returns a paginated list of all addresses on the subscription.

```bash theme={null}
curl https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../filters/addresses \
  -H "Authorization: Bearer oth_YOUR_API_KEY"
```

```json theme={null}
{
  "items": [
    { "chainId": "tron:mainnet", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" },
    { "chainId": "tron:mainnet", "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }
  ],
  "nextPageToken": "v1:..."
}
```

Pass `nextPageToken` as a query parameter to fetch the next page:

```bash theme={null}
curl "https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../filters/addresses?nextPageToken=v1:..." \
  -H "Authorization: Bearer oth_YOUR_API_KEY"
```

When `nextPageToken` is absent from the response, you have reached the last page.

## Error codes

| Error                      | Cause                                                                     |
| -------------------------- | ------------------------------------------------------------------------- |
| `invalid_address`          | The address is not a valid base58check TRON address                       |
| `invalid_chain`            | The `chainId` value is not a recognized CAIP-2 identifier                 |
| `chain_not_enabled`        | The chain exists but is not enabled for your account                      |
| `addresses_limit_exceeded` | You have reached the maximum number of addresses allowed per subscription |