# clearblock — Bitcoin data service

Machine-readable entry points, for agents and for scripts:

- /AGENTS.md           full usage contract: get a key, call the API, error meanings
- /v1                  service descriptor (JSON)
- /v1/openapi.json     OpenAPI 3.1
- /v1/pricing          plans and limits (JSON)
- /health              liveness and chain tip

Wallets (not HTTP — the Electrum protocol over TLS, no key, 5 connections per source address):

    electrum.blocknil.com:50002:s

Data endpoints live under /v1 and need the key: /v1/address/{address}/txs, /utxos, /analyze,
/counterparties; /v1/chain/info; /v1/latest; /v1/block/{height}/analyze;
/v1/tx/{txid}/analyze, /facts, /change, /content, /graph_data, /related.

Mempool index (pending transactions, from this node's pool re-read every 5 s): /v1/mempool/index,
/v1/mempool/txids, /v1/mempool/recent, /v1/fees/mempool-blocks, /v1/replacements,
/v1/fullrbf/replacements. They answer 503 until the first snapshot exists.

Paging: ?page= and ?limit= (max 100). Entity data is not sold yet and has no /v1 paths.

The /api surface carries the same data with no key (address, address txs/chain/utxo,
validate-address, block, header, raw, status, txid(s), txs, block-height, blocks, blocks-bulk, tip
height/hash, block-by-timestamp, tx raw/hex/status/merkle/outspend, mempool summary/txids/recent,
mempool-blocks, transaction-times, precise fees, replacements and fullrbf replacements, cpfp,
block audit summaries and audit scores) in the path
layout most Bitcoin REST clients already expect: same
paths, same JSON shapes, so such a client works unchanged. Limits: no broadcast,
mempool data is one node's pool re-read every 5 s (X-Mempool-Updated; 503 before the first
snapshot), address mempool history is empty, sigops computed, funded_txo_count and spent_txo_count null past 2,000
txs, UTXO order is chain order. Audits exist for blocks this service saw arrive (30-day
summaries). No mining statistics/lightning/price.
Details: /v1 descriptor key "api_surface".

Start here:

    curl -sX POST https://api.blocknil.com/v1/accounts -H 'Idempotency-Key: my-first-key' -d '{}'
    curl -s https://api.blocknil.com/v1/usage -H "Authorization: Bearer <key from the response>"

No browser, no email, no CAPTCHA. Keys are shown once and stored only as a hash.