Docs
Tiers and keys
Every request is counted against a tier at the origin. Anonymous callers are counted by address; an agent mints a token in one call, no account, no e-mail; a Nostr key or an account (t4) signs in; larger quotas come with a key. The live numbers are in GET /v1/status under tiers — the table below is what the origin serves right now, enforcement enforce.
| Tier | Who | Per minute (burst) | Per day | Bulk lookup | Feedback per day |
|---|---|---|---|---|---|
t0 | anonymous, by client address | 120 (240) | 10,000 | 20 subjects | 10 |
t1 | a btci_anon_ token minted with POST /v1/keys/anon or the MCP initialize | 300 (600) | 50,000 | 200 subjects | 20 |
t2 | an agent that signs: a key bound to its npubs, which publishes and proposes as them (identity page) | 300 (600) | 50,000 | 200 subjects | 50 |
t3 | a human with an npub: a NIP-98 login, or a NIP-98 header on the request (identity page) | 600 (1,200) | 100,000 | 500 subjects | 50 |
t4 | an account (e-mail and password, a passkey) and the btci_ keys it or its organisation issues; the quota row stays as seeded until paid plans arrive | 3,000 (6,000) | 1,000,000 | 1,000 subjects | 100 |
Minting a token
curl -s -X POST https://api.btcintel.io/v1/keys/anon
# {"token":"btci_anon_…","key_id":12,"tier":"t1","expires_at":"…","quota":{…}}
curl -s -H 'Authorization: Bearer btci_anon_…' https://api.btcintel.io/v1/keys/meThe token is shown once and never logged; keep it. It expires 90 days after the last day it was used. At most ten tokens per address per hour.
Headers
Every counted answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix seconds) and X-RateLimit-Tier. Over the limit the answer is 429 with the usual error envelope, code quota_exceeded, and Retry-After in seconds: to the bucket refilling for the minute limit, to UTC midnight for the day limit. While a deployment runs in log-only mode the decision is logged instead and the answer carries X-RateLimit-Policy: log-only.
What a key never contains
A key is 24 random bytes with a prefix that says what it is: btci_anon_ for a minted token, btci_ for an issued key. It carries no name, no email, no address, no account: the server stores only its SHA-256, the tier, the scopes, an optional label and expiry, and for agents that sign the npubs the key may publish as. Nothing in a key identifies a person, and nothing about a request is stored with it beyond daily totals per route class. Send it as Authorization: Bearer …; never put it in a URL.
Revocation and expiry
A minted token expires 90 days after the last day it was used; ops revoke an issued key with DELETE /v1/keys/{id} (audited), and a revoked or expired key answers 401 unauthorized on its next request — within a minute, the lifetime of the key cache. Lost a key? Mint or ask for another; nothing can be recovered from the hash.
What is not counted or stored
Health probes, metrics and the contract are never limited. Usage is kept per key and per route class as daily totals; anonymous addresses are never written to the database, so an anonymous day counter starts again when the origin restarts. The rules every route obeys are on the semantics page.