{"openapi":"3.1.0","info":{"title":"nockscan public API","version":"1.0.0","description":"Free public API for Nockchain data, served from nockscan's self-hosted indexer. No API key required. Rate limit: 120 requests per minute per IP (429 with Retry-After when exceeded; X-RateLimit-* headers on every response). All amounts are in nicks (65,536 nicks = 1 NOCK). The legacy form /api/data?endpoint=<name> is supported as an alias."},"servers":[{"url":"https://nockscan.com"}],"paths":{"/api/v1/tip":{"get":{"operationId":"tip","tags":["Chain"],"summary":"Current chain tip","description":"Latest block hash, height and timestamp.","parameters":[],"responses":{"200":{"description":"OK. Cached 5s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/stream":{"get":{"operationId":"stream","tags":["Chain"],"summary":"Live tip stream (SSE)","description":"Server-Sent Events stream. Emits a `tip` event with the current tip on connect and whenever a new block is indexed (~1s latency). Connect with EventSource; the connection counts once against the rate limit.","parameters":[],"responses":{"200":{"description":"OK. Cached 0s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/recent-blocks":{"get":{"operationId":"recent-blocks","tags":["Chain"],"summary":"Most recent blocks","parameters":[{"name":"count","in":"query","required":false,"description":"Number of blocks, newest last.","schema":{"type":"integer","default":"5"}}],"responses":{"200":{"description":"OK. Cached 30s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/blocks-range":{"get":{"operationId":"blocks-range","tags":["Chain"],"summary":"Blocks in a height range","parameters":[{"name":"startHeight","in":"query","required":true,"description":"First height (inclusive).","schema":{"type":"integer"}},{"name":"endHeight","in":"query","required":true,"description":"Last height (inclusive).","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/block/{id}":{"get":{"operationId":"block","tags":["Chain"],"summary":"Single block with PoW stats","description":"Block by height or hash, including chain-canonical PoW stats decoded from the block header: difficulty (2^n of expected proof attempts), proofs/sec, epoch counter, target and accumulated work.","parameters":[{"name":"id","in":"path","required":true,"description":"Block height (numeric) or block hash.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK. Cached 60s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/block-transactions/{id}":{"get":{"operationId":"block-transactions","tags":["Chain"],"summary":"Transactions of a block, with resolved parties","parameters":[{"name":"id","in":"path","required":true,"description":"Block height (numeric) or block hash.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK. Cached 60s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/latest-transactions":{"get":{"operationId":"latest-transactions","tags":["Transactions"],"summary":"Paginated list of latest transactions","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","default":"30"}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (newest first).","schema":{"type":"integer","default":"0"}}],"responses":{"200":{"description":"OK. Cached 30s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/transaction-details/{txId}":{"get":{"operationId":"transaction-details","tags":["Transactions"],"summary":"Full transaction drilldown","description":"Spends (with sender addresses, spent-note values, coinbase flags and the creating transaction for tracing), outputs (with resolved owner, owner type, spend status) and fees.","parameters":[{"name":"txId","in":"path","required":true,"description":"Transaction id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK. Cached 3600s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/search/{q}":{"get":{"operationId":"search","tags":["Transactions"],"summary":"Universal search","description":"Resolves a query as block height, block hash, transaction id and/or address in one call.","parameters":[{"name":"q","in":"path","required":true,"description":"Height, block hash, tx id or address.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK. Cached 10s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/address/{address}":{"get":{"operationId":"address","tags":["Addresses & Holders"],"summary":"Address balance, stats and ledger","description":"Double-entry ledger per address: current balance (sum of unspent notes), totals, and a paginated transaction list with counterparties. Coinbase rows use synthetic ids (coinbase-<blockId>).","parameters":[{"name":"address","in":"path","required":true,"description":"Address (pkh, or v0 public key).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Ledger page size.","schema":{"type":"integer","default":"20"}},{"name":"offset","in":"query","required":false,"description":"Ledger offset (newest first).","schema":{"type":"integer","default":"0"}}],"responses":{"200":{"description":"OK. Cached 30s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/address-flows/{address}":{"get":{"operationId":"address-flows","tags":["Addresses & Holders"],"summary":"Daily in/out flows for an address","parameters":[{"name":"address","in":"path","required":true,"description":"Address.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Window in days (anchored to chain tip).","schema":{"type":"integer","default":"90"}}],"responses":{"200":{"description":"OK. Cached 60s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/holders":{"get":{"operationId":"holders","tags":["Addresses & Holders"],"summary":"Top holders by balance","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","default":"50"}},{"name":"offset","in":"query","required":false,"description":"Offset.","schema":{"type":"integer","default":"0"}}],"responses":{"200":{"description":"OK. Cached 120s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/holder-stats":{"get":{"operationId":"holder-stats","tags":["Addresses & Holders"],"summary":"Holder distribution statistics","description":"Average and median holding over ordinary holders: wallets with at least 100 NOCK, leaving out the Base bridge lock, NCC's community wallet, Zorp treasury wallets and exchange wallets (named in excludedWallets). Also the holder count and schedule-derived supply figures.","parameters":[],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/network":{"get":{"operationId":"network","tags":["Mining & Network"],"summary":"Peers of nockscan's nodes, by area","description":"Who nockscan's own nodes are connected to over p2p, refreshed every five minutes: areas with at least three peers (smaller groups join their country or continent), countries, hosting networks, and round-trip and block-propagation medians. A sample of the network, not a census. No IP address is ever published. IP geolocation by DB-IP (CC BY 4.0).","parameters":[],"responses":{"200":{"description":"OK. Cached 120s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/address-growth":{"get":{"operationId":"address-growth","tags":["Addresses & Holders"],"summary":"Cumulative unique addresses over time","parameters":[{"name":"dataPoints","in":"query","required":false,"description":"Number of sample points.","schema":{"type":"integer","default":"50"}},{"name":"windowSize","in":"query","required":false,"description":"Window size in blocks (informational).","schema":{"type":"integer","default":"30572"}}],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/proof-rate":{"get":{"operationId":"proof-rate","tags":["Mining & Network"],"summary":"ZK proof-rate history","description":"Realized ZK proof rate (ZK puzzle only — AI-PoW is reported separately by `ai-pow-rate`): ZK work summed over a trailing 100-ZK-block window ÷ the wall time it took. `latest` carries the current realized rate plus the ZK target rate (work ÷ the height-selected ZK ideal: 500s from 147500, 214s from Logos, 150s before Logos), its own height, and the average ZK block interval. Rates are raw: post-147500 Tip5 attempts/s must be divided by 10,000 for display as ZK proof equivalents. Rolling windows reset at that boundary. Downsampled for charting.","parameters":[],"responses":{"200":{"description":"OK. Cached 120s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/epoch-proof-rate":{"get":{"operationId":"epoch-proof-rate","tags":["Mining & Network"],"summary":"ZK proof rate, rolling 2,016-block window","parameters":[],"responses":{"200":{"description":"OK. Cached 120s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/prover-stats":{"get":{"operationId":"prover-stats","tags":["Mining & Network"],"summary":"Prover leaderboard","description":"Blocks mined, rewards and share per prover group over a period (anchored to the chain tip). Fixed protocol cuts (NCC) are listed after the prover.","parameters":[{"name":"period","in":"query","required":false,"description":"One of 24h, 7d, 30d.","schema":{"type":"string","default":"24h"}}],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/block-time-stats":{"get":{"operationId":"block-time-stats","tags":["Mining & Network"],"summary":"Average block times","description":"epochAvg is a rolling 24h window (576 blocks at the 150s target); last100Avg covers the last 100 blocks.","parameters":[],"responses":{"200":{"description":"OK. Cached 60s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/epoch-progress":{"get":{"operationId":"epoch-progress","tags":["Mining & Network"],"summary":"Emission era progress","description":"Progress through the current emission era (eon) with an ETA to the next reward drop.","parameters":[],"responses":{"200":{"description":"OK. Cached 60s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/mining-metrics":{"get":{"operationId":"mining-metrics","tags":["Mining & Network"],"summary":"One-call mining dashboard","description":"Current difficulty, target and realized proof rate (difficulty ÷ actual avg block time over the last 100 blocks), block cadence vs the 150s ASERT target, current block reward and legacy epoch counter. `puzzles` splits the last 100 blocks by puzzle: block share, and work share in normalized work — ZK in Tip5 hashes, AI in MACs ÷ the network's normalized work rate (`workNormalization`: 14,285,714 MAC per hash from block 154500). Ideal for bots and status pages.","parameters":[],"responses":{"200":{"description":"OK. Cached 30s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/supply-audit":{"get":{"operationId":"supply-audit","tags":["Mining & Network"],"summary":"On-chain supply audit","description":"Ground truth: the sum of all unspent notes. Matching the emission schedule proves no NOCK exists outside consensus.","parameters":[],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/export-transactions/{address}":{"get":{"operationId":"export-transactions","tags":["Addresses & Holders"],"summary":"Address transaction history (CSV)","description":"Accounting-style CSV export of an address's full history — one row per transaction or coinbase with credit/debit/fee amounts and a running balance, modeled on the iris-blocks audit ledger. Fees are included in debit amounts (informational column). Capped at 50,000 rows; page longer histories with from/to height bounds.","parameters":[{"name":"address","in":"path","required":true,"description":"Address (pkh) to export.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Start block height (inclusive).","schema":{"type":"integer","default":"0"}},{"name":"to","in":"query","required":false,"description":"End block height (inclusive).","schema":{"type":"integer","default":"tip"}}],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/export-blocks":{"get":{"operationId":"export-blocks","tags":["Chain"],"summary":"Historic block data (CSV)","description":"CSV export of block history: hash, timestamps, transaction count, fees, coinbase reward, difficulty, proof rate and ASERT epoch per block. Max 25,000 blocks per request — page the full chain with from/to.","parameters":[{"name":"from","in":"query","required":false,"description":"Start block height (inclusive).","schema":{"type":"integer","default":"to − 9999"}},{"name":"to","in":"query","required":false,"description":"End block height (inclusive).","schema":{"type":"integer","default":"tip"}}],"responses":{"200":{"description":"OK. Cached 600s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/block-proof/{id}":{"get":{"operationId":"block-proof","tags":["Mining & Network"],"summary":"Raw block STARK proof (.jam)","description":"The block's full zero-knowledge proof of work as a jammed noun. Verify it independently with vanilla nockchain tooling: `cargo build --release -p roswell` in the nockchain repo, then `roswell check-proof --proof <file>` — exit code 0 means the STARK proof is valid. Recent proofs are served from storage; older ones are fetched from the node on demand. ~90–120 KB binary.","parameters":[{"name":"id","in":"path","required":true,"description":"Block hash or height.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK. Cached 86400s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/ai-pow-rate":{"get":{"operationId":"ai-pow-rate","tags":["Mining & Network"],"summary":"AI-PoW work-rate history (MAC/s)","description":"Realized AI-PoW work rate in multiply-accumulates per second: the MAC work of the AI blocks stamped within a trailing window of time ÷ that window (AI blocks only; the ZK puzzle is `proof-rate`). `window` is 3h, 12h (the protocol's 43,200 s ASERT half-life, what the site shows), 24h or 7d (the default, as before); the response names it (`window`, `windowSeconds`, `windowHours`; `windowDays` kept for older clients). The series restarts at block 154500, Nockchain's balance upgrade (both difficulty lanes restarted from their anchors, AI from 10 ExaMAC/s, and AI work was repriced against ZK work; MACs are counted as before), so no average mixes blocks from both sides; `since` (a height) returns the series from that height on at full chart resolution, its `ath` and `first` included, and `last` (a block count) the trailing blocks. `latest` carries realized, the difficulty-implied target (work ÷ the AI ideal: 500s before 147500, 214s from that height), data and target heights, and the mean AI block interval over the window; `ath` and `first` are the exact maximum and first reading of the full series; `firstAiBlock` is the first AI-PoW block. Downsampled for charting.","parameters":[{"name":"window","in":"query","required":false,"description":"Smoothing window: 3h, 12h, 24h or 7d.","schema":{"type":"string","default":"7d"}},{"name":"since","in":"query","required":false,"description":"Only points from this height on (e.g. 154500), downsampled within that range.","schema":{"type":"integer"}},{"name":"last","in":"query","required":false,"description":"Only the trailing blocks (e.g. 2016): since = tip − last.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK. Cached 60s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/merge-mining":{"get":{"operationId":"merge-mining","tags":["Mining & Network"],"summary":"Pearl merge-mining forensics","description":"AI-PoW blocks can be merge-mined with the Pearl chain. `declared` counts AI blocks whose consensus cert embeds a Pearl coinbase committing to this exact Nockchain block (verified by nockchain consensus itself); `pearl` counts Pearl chain blocks carrying the NOCKCHAIN-AI-POW-AUX commitment and how many are matched to their Nockchain AI block by exact 32-byte commitment equality. `recentPairs` lists the latest matched pairs.","parameters":[],"responses":{"200":{"description":"OK. Cached 120s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/v1/forensics":{"get":{"operationId":"forensics","tags":["Mining & Network"],"summary":"Mining forensics aggregates","description":"Proof-level forensic data across the chain: an independent digest≤target integrity re-check of every indexed proof, proof-version eras, trace-commitment reuse (grinding fingerprint), timestamp anomalies, and per-prover proof behavior (average luck, near-target share).","parameters":[],"responses":{"200":{"description":"OK. Cached 300s (s-maxage).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded."}}}}}}