> ## 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.

# PATCH /v1/subscriptions/:id/filters/addresses

> Atomically add and remove address filters in a single request. Returns per-item results showing what was added, removed, or skipped.

PATCH is the recommended way to modify specific addresses without touching the rest of the subscription's filter list. You can add and remove addresses in a single atomic request — if the operation fails, no partial changes are applied. The response includes a per-item breakdown so you know exactly what happened to each address you submitted.

## Request

```
PATCH /v1/subscriptions/:id/filters/addresses
```

### Path parameters

<ParamField path="id" type="string" required>
  The subscription ID (e.g. `sub_2QkP9aB7xN...`).
</ParamField>

### Body

<ParamField body="add" type="array">
  Address objects to add to the subscription's filter list. Each object must include `chainId` and `address`. At least one of `add` or `remove` should be non-empty.

  <Expandable title="Address object fields">
    <ParamField body="chainId" type="string" required>
      CAIP-2 chain identifier. Supported values: `tron:mainnet`, `tron:nile`, `tron:shasta`.
    </ParamField>

    <ParamField body="address" type="string" required>
      Base58check-encoded TRON address (starts with `T`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="remove" type="array">
  Address objects to remove from the subscription's filter list. Same shape as `add`. Items that are not currently in the subscription are returned in `results.skipped` with `reason: "not_found"`.
</ParamField>

```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" },
      { "chainId": "tron:nile", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" }
    ],
    "remove": [
      { "chainId": "tron:mainnet", "address": "TOldAddress..." }
    ]
  }'
```

## Response

**200 OK** — `PatchAddressesResponse` containing the updated subscription and a per-item result breakdown.

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

<ResponseField name="subscription" type="object">
  The full updated subscription resource, reflecting the state after the patch has been applied.
</ResponseField>

<ResponseField name="results.added" type="array">
  Address objects that were successfully added.
</ResponseField>

<ResponseField name="results.removed" type="array">
  Address objects that were successfully removed.
</ResponseField>

<ResponseField name="results.skipped" type="array">
  Address objects that could not be processed. Each skipped item includes the original `input`, a `reason` code (`not_found`, `invalid_address`, `invalid_chain`, `chain_not_enabled`), and an optional `detail` string with a human-readable explanation.
</ResponseField>

## Errors

| Code                       | HTTP | Description                                                           |
| -------------------------- | ---- | --------------------------------------------------------------------- |
| `not_found`                | 404  | The subscription ID does not exist or belongs to a different API key. |
| `invalid_address`          | 400  | One or more addresses failed base58check validation.                  |
| `invalid_chain`            | 400  | One or more `chainId` values are not recognized.                      |
| `chain_not_enabled`        | 400  | The `chainId` is valid but not currently enabled on this account.     |
| `addresses_limit_exceeded` | 400  | The `add` or `remove` array exceeds the per-request size limit.       |
| `unauthorized`             | 401  | The `Authorization` header is missing or the key is invalid.          |