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

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

string

required

The subscription ID (e.g. sub_2QkP9aB7xN...).

Body

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.

Show Address object fields

string

required

CAIP-2 chain identifier. Supported values: tron:mainnet, tron:nile, tron:shasta.

string

required

Base58check-encoded TRON address (starts with T).

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

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.

{
  "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"
      }
    ]
  }
}

object

The full updated subscription resource, reflecting the state after the patch has been applied.

array

Address objects that were successfully added.

array

Address objects that were successfully removed.

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.

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.

Subscriptions

Address Filters

Events

Utilities

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

Request

Path parameters

Body

Response

Errors

​Request

​Path parameters

​Body

​Response

​Errors

Request

Path parameters

Body

Response

Errors