Manage Address Filters

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

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.

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.

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:

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

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.

curl https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN.../filters/addresses \
  -H "Authorization: Bearer oth_YOUR_API_KEY"

{
  "items": [
    { "chainId": "tron:mainnet", "address": "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy" },
    { "chainId": "tron:mainnet", "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }
  ],
  "nextPageToken": "v1:..."
}

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

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

Get Started

Core Concepts

Guides

Reference

Add or remove specific addresses

Replace the full address list

List addresses

Error codes

​Add or remove specific addresses

​Replace the full address list

​List addresses

​Error codes

Add or remove specific addresses

Replace the full address list

List addresses

Error codes