Keys and quotas

POST /v1/keys/anon

Mint an anonymous t1 token (shown once)

No authentication. Mints a btci_anon_ token of tier t1 (spec S3.1 FR-5): 24 random bytes in lowercase base32, stored only as its SHA-256, valid 90 days and extended by 90 days on every day of use. At most 10 mints per client address per hour. The token is returned once and never logged.

Errors

• 429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.
• 501 — The mempool engine is not enabled on this deployment (BITCOIN_ZMQ_SEQUENCE unset).

Example

curl -s -X POST https://api.btcintel.io/v1/keys/anon | jq

POST /v1/keys/agent

An agent issues its own t2 key, bound to the key that signs the request

Spec S5.10 FR-2 (P70, P12, P55). Sign this request with NIP-98 (kind 27235 naming this URL and POST, payload = the SHA-256 of the body when one is sent): the key that signs it is the only npub the new btci_ key of tier t2 is bound to (allowed_npubs), with t2's scopes, valid 90 days. The proof is the signature; btcintel never sees the agent's private key and never signs for it. A session cookie or a bearer is not a proof here (401). The secret is returned once and never logged. At most 10 issuances per client address per hour (429) and three live t2 keys per npub (409, naming when the oldest expires). Send the secret as Authorization: Bearer to the MCP endpoint or the REST routes: publish_community_event then publishes events this npub signs.

Auth

An operator credential as the bearer; every call is audited.

Request body (optional)

Errors

• 400 — Malformed input (invalid_input).
• 401 — Missing or invalid bearer (unauthorized).
• 409 — The state refuses the change (conflict): an open dispute by this caller exists already, or the dispute or claim is not open any more.
• 422 — The NIP-98 event was refused (nip98_invalid): wrong URL or method, stale, bad signature, wrong payload hash, or used before; the message names the reason.
• 429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.
• 501 — The mempool engine is not enabled on this deployment (BITCOIN_ZMQ_SEQUENCE unset).

Example

curl -s -X POST https://api.btcintel.io/v1/keys/agent \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST /v1/keys

Issue a btci_ key (ops)

Ops bearer today; the operator scope of S3.3 later. Tier t2 (an agent that signs, bound to its npubs) or t4 (extended quotas). The secret is returned once.

Auth

An operator credential as the bearer; every call is audited.

Request body

Errors

• 400 — Malformed input (invalid_input).
• 401 — Missing or invalid bearer (unauthorized).
• 501 — The mempool engine is not enabled on this deployment (BITCOIN_ZMQ_SEQUENCE unset).

Example

curl -s -X POST https://api.btcintel.io/v1/keys \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"tier":"t4","label":"harness"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

DELETE /v1/keys/{id}

Revoke a key (ops)

Auth

An operator credential as the bearer; every call is audited.

Parameters

Errors

• 400 — Malformed input (invalid_input).
• 401 — Missing or invalid bearer (unauthorized).
• 404 — Unknown to the index and, for transactions, to the node mempool.

Example

curl -s -X DELETE https://api.btcintel.io/v1/keys/12 \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET /v1/keys/me

The calling key's tier, quota and usage today

MCP tool

get_auth_identity — see For agents

Auth

An operator credential as the bearer; every call is audited.

Errors

• 401 — Missing or invalid bearer (unauthorized).

Example

curl -s https://api.btcintel.io/v1/keys/me \
  -H 'Authorization: Bearer $BTCI_KEY' | jq '{id, prefix, tier}'

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.