Documentación
Chain and blocks
Status, the tip, blocks by height or hash and their transactions. Facts from btcintel's own index; the node tip rides along for confirmations.
Generated from openapi.yaml (Btcintel native API 0.1.0). Every hash is canonical display order; every answer carries the index and node heights; errors use one envelope — see Semantics.
- GET
/v1/status— Chain, node and mempool status - GET
/v1/blocks— Recent blocks - GET
/v1/blocks/tip/height— Index tip height - GET
/v1/blocks/tip/hash— Index tip hash - GET
/v1/blocks/{id}— Block by height or canonical hash - GET
/v1/blocks/{id}/txs— Txids of a block - GET
/v1/blocks/stale— Stale blocks and forks the node knows (spec M3) - GET
/v1/blocks/reorgs— The reorgs the mempool engine saw (spec M3) - GET
/v1/blocks/{id}/status— Block chain-status
GET /v1/status
Chain, node and mempool status
- MCP tool
get_status— see For agents
Response 200
Index tip, live node info, mempool summary, fee estimates.
Headers: X-Btcintel-Index-Height, X-Btcintel-Node-Height
schema
communityobject — Spec S4.1 §8: the embedded relay and the ingester. Absent when neither runs on this deployment.relayobjecturlstringconnectionsintegerwrite_enabledbooleanmin_powinteger — The effective proof-of-work floor (24 while attack_mode is on).attack_modeboolean
ingestobject — One entry per public relay the ingester follows.relaysarray of objecturlstringconnectedbooleansincestring | null (date-time) — The newest created_at seen.events_totalintegerlast_errorstring | null
publishobject — Spec S5.1 FR-8: the API write path — whether it is open (WRITES_ENABLED) and the outbound relays.enabledbooleanqueuedinteger — The deepest backlog among the outbound relays; each relay has its own queue and worker (codex#111).dropped_totalintegerrelaysarray of objecturlstringconnectedbooleansent_totalintegerfailed_totalintegerqueuedinteger
signerobject — The custodied signer (spec S5.6 §5): counts only. Absent when the deployment runs without one or it does not answer.keysinteger required — Live custodied keys.clientsinteger required — NIP-46 apps connected to them.signingboolean required — The signer signs and exports (SIGNING_ENABLEDon its side).bunkerboolean required — The signer listens on the relay for NIP-46 requests.
featuresobject — Routes a client may switch on when present (spec S3.4); a key absent here means the deployment predates the route.feedbackboolean —POST /v1/feedbackis served; the web renders its feedback sheet.sessionsboolean — The NIP-98 login and the session cookie are served (spec S5.1 FR-1).login_nonceboolean —GET /v1/auth/nonceis served and the login reads thenoncetag (spec S5.8); absent on a deployment that predates it.writesboolean — The API write path is open: publish, delete, propose (spec S5.1 §10; on since CP3, P60).accountsboolean — Sign-up and sign-in with an e-mail account, the t4 band, are served (spec S5.5 §10;ACCOUNTS_ENABLED).sign_inarray of string — The sign-in providers configured (spec S5.5 FR-13, phase D) while accounts are on; empty otherwise. The web renders one button per entry.signingboolean — The custodied signer signs and exports (spec S5.6 §10;SIGNING_ENABLED, off until CP4).
intelobject — Intel pipeline: active sources and the latest fetch per source (fetched_at, sha256, status, last_error).sources_activeintegersources_totalintegerpushboolean — The push endpoint is configured.schedulerboolean — The in-process fetch scheduler is running.last_fetchobject
chainstringtip_heightinteger — Index tip.tip_hashstring — Canonical display byte order.bitcoind_heightinteger — Live node tip.bitcoind_okbooleanbitcoindobject — Subset of getblockchaininfo.network_hashpsnumbermempool_sizeinteger — getmempoolinfo.size, not the mirrored sample.mempoolobjectsizeintegerbytesintegerusageintegertotal_feeinteger — satsmempoolminfeenumber — sat/vBminrelaytxfeenumber — sat/vB
fee_estimatesobject — estimatesmartfee sat/vB by confirmation target ("1", "3", "6").updated_atstring (date-time)
Errors
401— Missing or invalid bearer (unauthorized).
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/status | jq '{chain, tip_height, tip_hash}'GET /v1/blocks
Recent blocks
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer · ≤ 50 · default 10 | — |
start_height | query | integer | Defaults to the index tip. |
Response 200
Blocks, newest first.
schema
Example
curl y jq, en cualquier shell.
curl -s 'https://api.btcintel.io/v1/blocks?limit=10' | jqGET /v1/blocks/tip/height
Index tip height
Response 200
Height the index has reached (not the node tip).
schema
heightinteger
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/blocks/tip/height | jqGET /v1/blocks/tip/hash
Index tip hash
Response 200
Canonical hash of the index tip.
schema
hashstring — Canonical display byte order.
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/blocks/tip/hash | jqGET /v1/blocks/{id}
Block by height or canonical hash
By hash the block may be off the best chain: it then carries stale with the best chain's block at its height (spec M3). By hash a block six or more deep is cached for a week; a younger one, which a reorg could still make stale, for 10 s.
- MCP tool
get_block— see For agents
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | Height (decimal) or canonical block hash (64 hex). |
include | query | string · one of "expired" | expired to include expired and retracted claims in annotations (attributions and hop-0 stay current-only). |
Response 200
Block header facts with the intel siblings.
schema
BlockDetail
Errors
301— Legacy internal-order hash; Location holds the canonical URL.400— Malformed input (bad hex, wrong-network address, bad vout).404— Unknown to the index and, for transactions, to the node mempool.
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/blocks/968212 | jqGET /v1/blocks/{id}/txs
Txids of a block
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | Height (decimal) or canonical block hash (64 hex). |
Response 200
Canonical txids in block order.
schema
heightintegertxidsarray of string
Errors
301— Legacy internal-order hash; Location holds the canonical URL.404— Unknown to the index and, for transactions, to the node mempool.
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/blocks/968212/txs | jqGET /v1/blocks/stale
Stale blocks and forks the node knows (spec M3)
The node's chain tips other than the active one (Bitcoin Core's getchaintips), newest first. Each carries its branch length and the active chain's block at its fork point (fork_point.height is height − branchlen); a valid-fork tip, whose block the node holds, adds its header's time. The API computes no fork of its own. Read from the node at most every 30 s.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer · ≥ 1 · ≤ 50 · default 20 | — |
Response 200
The tips, newest first; an empty list when the node knows no fork.
schema
tipsarray of StaleTip requiredheightinteger requiredhashstring required — Canonical display byte order.branchleninteger required — The branch's length from the tip back to the active chain.statusstring required — The node's own word for the branch (getchaintips). · one of "valid-fork", "valid-headers", "headers-only", "invalid"fork_pointobject requiredheightinteger requiredhashstring required — Canonical display byte order.
timestring (date-time) — The header's time; only on avalid-forktip.
as_ofstring (date-time) required
Errors
400— Malformed input (invalid_input).503—index_unavailable: the node did not answer.
Example
curl y jq, en cualquier shell.
curl -s 'https://api.btcintel.io/v1/blocks/stale?limit=20' | jqGET /v1/blocks/reorgs
The reorgs the mempool engine saw (spec M3)
The chain reorganisations the engine saw on bitcoind's sequence feed, newest first, at most 50. A reorg's depth is the number of blocks disconnected before the next connect; old_tip is the first block disconnected and new_tip the block connected after them. The list lives in memory and starts empty at each restart: since is when the engine started.
Response 200
The reorgs since the engine started; an empty list when it saw none.
schema
reorgsarray of Reorg requiredatstring (date-time) requireddepthinteger required · ≥ 1old_tipBlockRef requiredheightinteger — Absent when the node did not answer for the header.hashstring required — Canonical display byte order.
new_tipBlockRef requiredheightinteger — Absent when the node did not answer for the header.hashstring required — Canonical display byte order.
sincestring (date-time) required
Errors
429—quota_exceeded(spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day.Retry-Aftersays when to try again; every rate-limited answer carriesX-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-ResetandX-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead andX-RateLimit-Policy: log-onlyis set.501— The mempool engine is not enabled on this deployment (BITCOIN_ZMQ_SEQUENCEunset).
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/blocks/reorgs | jqGET /v1/blocks/{id}/status
Block chain-status
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | Height (decimal) or canonical block hash (64 hex). |
Response 200
Whether the block is in the best indexed chain and its successor.
schema
in_best_chainbooleanheightintegerhashstring — Canonical display byte order.next_beststring — Canonical display byte order.
Errors
404— Unknown to the index and, for transactions, to the node mempool.
Example
curl y jq, en cualquier shell.
curl -s https://api.btcintel.io/v1/blocks/968212/status | jq '{in_best_chain, height, hash}'