Skip to main content
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"
      }
    ]
  }
}
FieldDescription
results.addedAddresses that were successfully added
results.removedAddresses that were successfully removed
results.skippedAddresses 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

ErrorCause
invalid_addressThe address is not a valid base58check TRON address
invalid_chainThe chainId value is not a recognized CAIP-2 identifier
chain_not_enabledThe chain exists but is not enabled for your account
addresses_limit_exceededYou have reached the maximum number of addresses allowed per subscription