{ "openapi": "3.1.0", "info": { "title": "Project Blackcoin Public API", "version": "1.3.0", "summary": "Read-only public telemetry and explorer API. NOT a custody API.", "description": "Quorum-verified, read-only telemetry and explorer data for Blackcoin Protocol V4, served from independent v30.1.3 observers and re-validated against an exact schema before leaving the origin. Every response fails closed to an explicit unavailable envelope; nothing is guessed. CORS is open on every endpoint; no authentication. Query keys are validated exactly — sending an unlisted, duplicated, or malformed parameter returns 400 invalid_request with field-level errors. Amounts are canonical integer-sats strings; heights are exact; hashes are lowercase hex.\n\nThis API does not create addresses, hold keys, track deposits, sign, or broadcast. Exchanges and custodians must run the signed-source v30.1.3 daemon (blackcoind) and integrate via its JSON-RPC for custody; this API is a mirror of that daemon, not a substitute for it. Error model: available/not_found/unavailable envelopes (components/schemas); 429 with Retry-After on rate limiting. Amounts are exact integer-sats strings; heights are exact integers. Address-index coverage is disclosed at /api/explorer/status and on affected responses; totals under partial coverage are lower bounds. Rate limit: 240 requests/minute per client on /api/explorer; every /api/explorer response (200/400/404/429/503, after per-request accounting) carries X-RateLimit-Limit/Remaining/Reset, and 429 adds Retry-After. Malformed requests return 400 invalid_request with field-level errors; 404 not_found is reserved for well-formed identifiers that match no record inside disclosed coverage." }, "servers": [ { "url": "https://projectblackcoin.org" } ], "paths": { "/api/v3/quantum": { "get": { "summary": "Current quorum-verified Gold Rush snapshot (schema 3).", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "No query parameters. Quality ladder live/delayed/last_verified by snapshot age; weak ETag on a content hash of the public fields; CORS open." } }, "/api/v3/quantum/stream": { "get": { "summary": "SSE stream of accepted snapshots.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "text/event-stream; each snapshot is an `event: snapshot` frame, id `::`, retry 5000ms. No parameters." } }, "/api/v3/lifecycle": { "get": { "summary": "Quorum-attested schema-12 replay marker, commitment, protocol phase, and consensus schedule.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "No query parameters." } }, "/api/quantum": { "get": { "summary": "Legacy schema-2 snapshot envelope (unchanged for existing consumers).", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "No query parameters." } }, "/api/supply": { "get": { "summary": "Base-chain supply sample (JSON): sats and decimal BLK; phase-locked shadow credits excluded.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "No query parameters. Sampled from gettxoutsetinfo muhash every ~10 min. Reconciled supply taxonomy: base_merkle_utxo_nominal_sats, base_circulating_effective_sats, shadow_issued/unspent_nominal_sats, shadow_outstanding_pool_sats, shadow_scheduled_remaining_sats, protocol_nominal_utxo_sats, protocol_circulating_effective_sats, gold_rush_schedule_cap_sats, absolute_max_supply_sats (null), and dual anchors (periodic base UTXO sample + live shadow ledger, with a consistency flag). Reconciliation equations are machine-tested before any response is served. circulating_sats/total_sats are DEPRECATED aliases for the base UTXO set, unchanged in meaning." } }, "/api/supply/circulating": { "get": { "summary": "Plain-text circulating supply in decimal BLK (aggregator format).", "responses": { "200": { "description": "Decimal BLK amount as plain text (aggregator format).", "content": { "text/plain": { "schema": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{8}$" } } } }, "503": { "description": "Plain-text unavailable response when the sample cannot be served." } }, "description": "text/plain body, no envelope. No parameters." } }, "/api/supply/total": { "get": { "summary": "Plain-text total supply in decimal BLK (aggregator format).", "responses": { "200": { "description": "Decimal BLK amount as plain text (aggregator format).", "content": { "text/plain": { "schema": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{8}$" } } } }, "503": { "description": "Plain-text unavailable response when the sample cannot be served." } }, "description": "text/plain body, no envelope. No parameters." } }, "/api/releases": { "get": { "summary": "Validated signed-release catalog from the GitHub record.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "No query parameters. ETag/304 supported." } }, "/api/health": { "get": { "summary": "Liveness probe.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}" }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } } }, "description": "Returns {status:\"ok\", service:\"projectblackcoin-site\"}. No parameters." } }, "/api/og": { "get": { "summary": "Dynamic Open Graph card (PNG, 1200x630).", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}" }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } } }, "parameters": [ { "name": "t", "in": "query", "required": false, "description": "Card kind: home | block | tx | shadow | address", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Short identifier shown on the card (<=80 chars of [A-Za-z0-9:,#.- ])", "schema": { "type": "string" } } ], "description": "Returns image/png, not JSON." } }, "/api/explorer/status": { "get": { "summary": "Chain status, per-index (tx/shadow/address) sync state, disclosed coverage.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "description": "No query parameters." } }, "/api/explorer/network": { "get": { "summary": "Live network telemetry: hashrate, difficulty, connections, mempool, chain size, aggregate peer-version mix (no peer addresses).", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "description": "No query parameters." } }, "/api/explorer/recent-blocks": { "get": { "summary": "Newest blocks with base and shadow summaries.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Integer 1-50 (default 10)", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Height (1-9 digits); pages backward from this height, exclusive", "schema": { "type": "string" } } ], "description": "Query keys are validated exactly; only limit and/or before are accepted." } }, "/api/explorer/block/{id}": { "get": { "summary": "Full block record: header, paginated transactions, anchored shadow events.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Block height (0 to 100000000) or 64-hex block hash", "schema": { "type": "string" } }, { "name": "tx_offset", "in": "query", "required": false, "description": "Integer 0 to 1000000000", "schema": { "type": "string" } }, { "name": "tx_limit", "in": "query", "required": false, "description": "Integer 1-100", "schema": { "type": "string" } } ] } }, "/api/explorer/tx/{txid}": { "get": { "summary": "Transaction with prevout-resolved inputs; spentness where provable, else null.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "txid", "in": "path", "required": true, "description": "64-hex transaction id", "schema": { "type": "string" } }, { "name": "vin_offset", "in": "query", "required": false, "description": "0 to 1e9", "schema": { "type": "string" } }, { "name": "vin_limit", "in": "query", "required": false, "description": "1-100", "schema": { "type": "string" } }, { "name": "vout_offset", "in": "query", "required": false, "description": "0 to 1e9", "schema": { "type": "string" } }, { "name": "vout_limit", "in": "query", "required": false, "description": "1-100", "schema": { "type": "string" } } ] } }, "/api/explorer/address/{address}": { "get": { "summary": "Base activity within disclosed coverage plus the complete synthetic payout history, paginated independently.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Base58 or bech32 address, 14-128 chars of [A-Za-z0-9:]", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Base activity offset 0 to 1e9", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Base activity page 1-100", "schema": { "type": "string" } }, { "name": "shadow_offset", "in": "query", "required": false, "description": "Shadow activity offset 0 to 1e9", "schema": { "type": "string" } }, { "name": "shadow_limit", "in": "query", "required": false, "description": "Shadow activity page 1-100", "schema": { "type": "string" } } ] } }, "/api/explorer/shadow/tx/{synthetic_txid}": { "get": { "summary": "Synthetic payout record: lifecycle, maturity, demurrage, spend linkage.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "synthetic_txid", "in": "path", "required": true, "description": "64-hex synthetic transaction id", "schema": { "type": "string" } } ] } }, "/api/explorer/shadow/supply": { "get": { "summary": "Anchored shadow supply: pools, materialized and phase-locked totals, claim counts.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "description": "No query parameters. The active_signaler_count field is reserved and currently always null; the reviewed active-signaler count is published in the live snapshot at /api/v3/quantum (data.next_block.active_signalers) — one authoritative disclosure, one source." } }, "/api/explorer/events": { "get": { "summary": "Shadow events — recent scan, or filtered history from the payout index.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "description": "Without parameters: the most recent shadow events (claims, distributions, signals) from a tip scan. With any filter: indexed payout events (pow_claim / pos_distribution only — signal events are not payout records and appear only in the unfiltered scan) served from the local index with a coverage disclosure. Height filters are bounded by disclosed coverage; absence outside coverage is not proof of absence.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "enum": [ "pow_claim", "pos_distribution" ] } }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:]{14,128}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Lowest height (inclusive)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Highest height (inclusive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } } ] } }, "/api/explorer/analytics/leaderboard": { "get": { "summary": "Addresses ranked by materialized Gold Rush payouts, with PoW/PoS split and active range.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Integer 1-100 (default 50)", "schema": { "type": "string" } } ] } }, "/api/explorer/analytics/series": { "get": { "summary": "Bucketed per-block series (payout value, event counts, difficulty, size, fees) for charting; capped at 240 buckets.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start height (1-9 digits)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End height (1-9 digits)", "schema": { "type": "string" } } ] } }, "/api/explorer/analytics/network-series": { "get": { "summary": "Time series of PoW hashrate, network stake weight, and PoS/PoW difficulty sampled every ~5 min.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "hours", "in": "query", "required": false, "description": "Integer 1-336 (default 24)", "schema": { "type": "string" } } ] } }, "/api/explorer/search": { "get": { "summary": "Classify a query into its explorer path.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Height, block hash, txid, or address (1-128 chars of [A-Za-z0-9:])", "schema": { "type": "string" } } ] } }, "/api/explorer/stream": { "get": { "summary": "SSE stream of newly verified blocks.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableEnvelope" } } } }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/InvalidRequest" } }, "description": "text/event-stream; each new block is an `event: block` frame. No parameters." } }, "/explorer/address/{address}/feed.xml": { "get": { "summary": "Atom feed of an address's shadow payouts.", "responses": { "200": { "description": "Available envelope: {status:\"available\", ...}" }, "404": { "description": "Known-shape not-found envelope (explorer records only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } }, "503": { "description": "Fail-closed unavailable envelope: {status:\"unavailable\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Base58 or bech32 address, 14-128 chars of [A-Za-z0-9:]", "schema": { "type": "string" } } ], "description": "Returns application/atom+xml, not JSON." } }, "/api/chain-params": { "get": { "summary": "Machine-readable chain parameters, lifecycle heights, and integration guidance.", "description": "Static-shape JSON: asset identity (ticker, decimals), network params (ports, bech32 HRP, block timing, consensus), lifecycle heights (Gold Rush window, competing-claims activation, final lockout), endpoint listing, and custody-interface guidance. CORS open. Both bech32 (HRP 'blk') and legacy Base58 ('B...') address classes remain valid until the published final-lockout height. Not rate limited (static document).", "responses": { "200": { "description": "Raw chain-parameter document (schema blackcoin.chain-params/2) — not an envelope. Includes the versioned identity manifest: genesis hash/merkle root, message start, base58 prefixes, BIP44 type, quantum replay domain, source commit, shared-history statement, and null future branch anchors." } } } }, "/releases/{tag}": { "get": { "summary": "Immutable HTML record for one exact release tag.", "description": "Server-rendered page describing exactly the named release: validated assets, checksums, signature status, and the exact upstream GitHub record. Unknown tags return 404. RSS/Atom items link here so an item for an older build never opens a newer one.", "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" } } ], "responses": { "200": { "description": "Immutable release record (text/html)." }, "404": { "description": "Unknown tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEnvelope" } } } } } } }, "/api/ready": { "get": { "summary": "Readiness: fails when a required dependency cannot serve its contract.", "description": "Distinct from /api/health (shallow liveness). Returns 200 {status:'ready'} only when the quantum snapshot store and the explorer upstream can both serve; otherwise 503 {status:'not_ready'} with per-component detail. Use this for dependency-aware monitoring.", "responses": { "200": { "description": "All required components ready (per-component detail included)." }, "503": { "description": "One or more components cannot serve; body discloses which and why." } } } }, "/api/explorer/address/{address}/utxos": { "get": { "summary": "Address unspent outputs", "description": "Paginated unspent outputs of an address (txid, vout, value_sats, height, confirmations) with index-coverage disclosure; totals are lower bounds below the indexed window.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Blackcoin address" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "0-based offset" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..100" } ], "responses": { "200": { "description": "available/unavailable envelope" }, "404": { "description": "not_found" }, "429": { "description": "rate limited" } } } }, "/api/explorer/mempool": { "get": { "summary": "Mempool contents", "description": "Current mempool: count, total bytes, and pending txids (capped at 1000 with a truncation flag).", "responses": { "200": { "description": "available/unavailable envelope" }, "404": { "description": "not_found" }, "429": { "description": "rate limited" } } } }, "/api/explorer/tx/{txid}/hex": { "get": { "summary": "Raw transaction hex", "description": "The raw serialized hex of a transaction, for decoding or re-broadcast on your own node.", "parameters": [ { "name": "txid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "64-hex transaction id" } ], "responses": { "200": { "description": "available/unavailable envelope" }, "404": { "description": "not_found" }, "429": { "description": "rate limited" } } } }, "/api/explorer/block/{id}/hex": { "get": { "summary": "Raw block hex", "description": "The raw serialized hex of a block by height or 64-hex hash.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Block height or 64-hex hash" } ], "responses": { "200": { "description": "available/unavailable envelope" }, "404": { "description": "not_found" }, "429": { "description": "rate limited" } } } } }, "components": { "schemas": { "Sats": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer satoshi amount as a decimal string (1 BLK = 100,000,000 sats). Never a float." }, "Height": { "type": "integer", "minimum": 0, "description": "Exact block height." }, "Hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hex block/transaction hash." }, "AvailableEnvelope": { "type": "object", "required": [ "status", "generated_at", "data" ], "properties": { "status": { "const": "available" }, "generated_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "Endpoint-specific payload; see the endpoint description." } }, "description": "Success envelope. Amounts are Sats strings; heights are exact integers." }, "NotFoundEnvelope": { "type": "object", "required": [ "status" ], "properties": { "status": { "const": "not_found" } }, "description": "The identifier is well-formed but no record exists inside disclosed coverage. Records outside coverage may exist on chain but are not yet indexed — check /api/explorer/status coverage before treating absence as proof." }, "UnavailableEnvelope": { "type": "object", "required": [ "status" ], "properties": { "status": { "const": "unavailable" } }, "description": "Fail-closed envelope (HTTP 503): the source cannot prove a response right now. Never a guess or a stale substitute presented as current." }, "RateLimited": { "type": "object", "description": "HTTP 429: per-client request limit exceeded. Honor Retry-After and back off. Limits are enforced at the origin; keep request rates neighborly." }, "Coverage": { "type": "object", "properties": { "from_height": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Exact block height." }, { "type": "null" } ] }, "through_height": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Exact block height." }, { "type": "null" } ] }, "complete": { "type": "boolean", "description": "false while the historical backfill toward genesis is in progress; totals derived from partial coverage are lower bounds, not complete totals." } } }, "InvalidRequestEnvelope": { "type": "object", "required": [ "status", "errors" ], "properties": { "schema_version": { "const": 1 }, "status": { "const": "invalid_request" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "param", "reason" ], "properties": { "param": { "type": "string" }, "reason": { "type": "string" } } } } }, "description": "HTTP 400: the request shape is wrong (unknown/duplicated/malformed parameter or malformed identifier), with one entry per offending field. Distinct from 404 not_found, which means a well-formed identifier matched no record inside disclosed coverage." } }, "responses": { "RateLimited": { "description": "Rate limited. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute (currently 240 per client)." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimited" } } } }, "InvalidRequest": { "description": "Malformed request with field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestEnvelope" } } } } } } }