Watching subjects

A key or a signed-in npub keeps one list of subjects and pulls what changed on them: the change feed of the Curated band restricted to the list, plus a count of the Community notes that arrived. Pull only — btcintel never calls you (decision P31), so nothing about you leaves the box between polls.

The list

A btci_ key of tier t2 or t4, or a session (identity), owns the list; an anonymous token has none. Subjects are canonicalised on the way in (a block hash or txid in display order, an address checked against mainnet). The cap is the tier's watchlist_max: 10 for a t2 key, 25 for a person, 100 on the extended tier (tiers).

PUT    /v1/watch/address/1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa    # 201 added · 200 already there · 429 full
DELETE /v1/watch/tx/a1075db5…                                 # 200 removed · 404 not on the list
GET    /v1/watch
{"items": [{"subject": {"kind": "address", "key": "1A1z…"}, "added_at": "…", "since_seq": 41207}],
 "count": 1, "max": 10, "last_seq": 41230}

since_seq is the feed's position when you added the subject — start polling from it and you miss nothing that happened since. Agents use the MCP tools watch_subject, unwatch_subject, list_watched and get_watch_changes.

Polling the feed

The feed is the same append-only sequence GET /v1/changes serves, filtered to your subjects. Keep the cursor; ask for what came after it; store the new cursor. A row is committed with the claim it describes, so a consumer that stores the last cursor never misses one.

cursor=0
while true; do
  page=$(curl -s -H "Authorization: Bearer $KEY" \
         "https://api.btcintel.io/v1/watch/changes?since=$cursor&limit=500")
  # 429? sleep the Retry-After header and try again
  echo "$page" | jq '.items[] | {seq, action, claim_id, subject}'
  echo "$page" | jq '.community[] | {subject, comments, labels}'
  cursor=$(echo "$page" | jq '.next_cursor')
  sleep 60
done

{"items": [{"seq": 41231, "at": "…", "claim_id": "ann_9990", "kind": "annotation", "action": "updated",
            "subject": {"kind": "address", "key": "1A1z…"}}],
 "community": [{"subject": {"kind": "address", "key": "1A1z…"}, "comments": 2, "labels": 0}],
 "next_cursor": 41231, "watched": 1,
 "_meta": {"notice": "Community content is indexed from Nostr and not endorsed by btcintel.", "endorsement": false}}

items are the Curated changes (a claim created, updated, expired or retracted — fetch the claim by its id for the content and its citation); community counts the comments and labels each watched subject received after the cursor's time, never the notes themselves: read them on the subject's page or with get_community. With since=0 the counts cover everything indexed.

Quotas and expiry

Each poll is one request against your tier's per-minute and per-day quota; a 429 carries Retry-After. The list of a key that was revoked or expired is deleted a month later; a person's list stays with their npub whatever happens to their sessions.