READ-ONLY API
API v1
A small, versioned, read-only API for network figures, recent blocks and the site's reviewed catalogs. It cannot send transactions, look up balances or reach arbitrary node methods. Network data comes from the project's public mainnet node and is an observation, not a consensus proof.
Conventions
- Base path
/api/v1/. Use the trailing slash; each endpoint is a directory. GETandHEADonly. Any origin may read responses (Access-Control-Allow-Origin: *); no cookies or credentials are used.- Success:
{"schema":"monzero-api-v1","data":{…},"observed_at":…,"source":…}.observed_at(Unix seconds) andsourceappear on node-backed responses. - Errors:
{"schema":"monzero-api-v1","error":{"code":"…","message":"…"}}with codesinvalid_parameter(400),not_found(404),method_not_allowed(405),rate_limited(429),node_unavailable(502) andunavailable(503). RespectRetry-After. - Unknown query parameters are rejected. Atomic XMZ amounts and difficulties are decimal strings; 1 XMZ = 100,000,000,000 atomic units.
- Rate limit: 60 requests per minute per client, plus a site-wide ceiling. Network responses are cached for 15 seconds, so polling faster gains nothing.
Endpoints
| Path | Returns |
|---|---|
/api/v1/ | Version and endpoint list. |
/api/v1/network/stats/ | height (block count), top block height, hash, timestamp and reward, difficulty, hashrate_estimate, target block time, synchronized, tx_pool_size. |
/api/v1/network/hashrate/ | hashrate_estimate in H/s: next-block difficulty ÷ 120 seconds. An estimate from difficulty, not a measurement of miners. |
/api/v1/network/difficulty/ | Next-block difficulty and the top block's difficulty. |
/api/v1/supply/ | Exact supply from the chain: circulating_supply and total_supply (decimal XMZ strings, also in atomic units), max_supply (null: tail emission) and height. Circulating leaves out the rewards of the newest 60 blocks, which are still locked. |
/api/v1/supply/circulating/, /api/v1/supply/total/ | The same figures as a plain number (text/plain), the format CoinGecko and CoinMarketCap ask for. |
/api/v1/network/upgrade/ | The scheduled v1.0.0 upgrade (hard fork 17 at block 21,000): height, blocks_left, estimated_at (at the 120-second target), active and public_node_ready. |
/api/v1/network/nodes/ | Observed nodes counted by country only (ISO 3166 codes; ZZ = not in the database): observed, reachable, connected, totals, stale. Add ?history=daily for one total per UTC day. Never includes IP addresses, regions or coordinates. |
/api/v1/blocks/latest/?count=10 | Newest-first block headers, count 1–30 (default 10). The window is checked to be linked by prev_hash and to end at the observed tip. |
/api/v1/blocks/?height=N | One block header: hash, previous hash, timestamp, difficulty, reward_atomic, transaction count (excluding the miner transaction), size, weight, depth, orphan flag and major version. Headers less than 60 blocks deep can still change in a reorganisation. |
/api/v1/mining/pools/ | Pools from the reviewed ecosystem directory, with operator and last-checked date. |
/api/v1/mining/benchmarks/ | Reviewed CPU benchmark records, each with its verification status. |
/api/v1/exchanges/ | Exchange listing records. Only status live means verified trading. No prices or volume. |
/api/v1/ecosystem/ | The full reviewed ecosystem directory. |
Example
curl --fail-with-body https://monzero.org/api/v1/network/stats/{"schema":"monzero-api-v1","data":{"height":9001,"top_block_height":9000,"top_block_hash":"…","top_block_timestamp":1789000000,"top_block_reward_atomic":"…","difficulty":"…","hashrate_estimate":270.5,"target_block_seconds":120,"synchronized":true,"tx_pool_size":0},"observed_at":1789000010,"source":"node.monzero.org public node"}The values above show the shape only. They are not real network figures.
Limits of this data
One public node is the source. If it falls behind, is on a fork or is unreachable, the API reports what it saw or returns node_unavailable; it never fills gaps with estimates. For payments or anything that needs finality, run your own monzerod and wallet. See the merchant guide. Not yet available: historical aggregates (use network history), transaction lookup and a roadmap feed.