OpenAPI reference

Source bitcoinuniverseio/docs-core

Path public/openapi/core-public-read.json

Chain bitcoin

Network mainnet

Verified 2026-09-01

Everything below is rendered at build time from the OpenAPI document this repository publishes. Continuous integration validates that the document parses as OpenAPI 3.1 and that it contains no operation other than GET, because a mutation route appearing in a public read document would be a mistake with consequences.

The document is served from this site and can be fed straight to a client generator.

Documentcore-public-read.json· OpenAPI 3.1.0 · version 2026-09-01

Server https://api.bitcoinuniverse.io · Production. The only public origin.

GET/health

Application health, release identity, and marketplace profile

The readiness contract. It reports the exact release commit, whether read traffic is ready, whether mutation traffic is open, and the reasons it is not. Read availability and transaction availability are reported separately on purpose: a healthy page is not evidence that trading is open.

Status	Media type	Schema	Meaning
200	application/json	object	Health report. A 200 does not by itself mean the service is ready: read `readTraffic.ready` and `mutationTraffic.ready`.

GET/indexer-health

Per-protocol index identity, tip, lag, and freshness

One entry per marketplace protocol. This is the answer to "where did that number come from, and how old is it", for every protocol at once.

Read `tip` against `nodeTip` rather than trusting `lag` alone: a protocol that has never been read successfully reports zeroes and a null `lastSuccess`, which is not a chain at height zero.

Status	Media type	Schema	Meaning
200	application/json	object	Freshness report for every protocol the deployment serves.

GET/ordinals/status

The Ordinals index status page

The status page of the Ordinals index that Core reads, served through the public facade. It answers with HTML, not JSON: it is the index's own page rather than a Core-shaped response. It reports the chain, the indexed height, inscription counts, and index uptime.

Use `/indexer-health` instead when you want a machine-readable answer about Ordinals freshness.

Status	Media type	Schema	Meaning
200	text/html	string	The index status page.

GET/mempool/api/blocks/tip/height

Current Bitcoin chain tip height

Status	Media type	Schema	Meaning
200	text/plain	string	The tip height as a bare decimal integer in the body.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/blocks/tip/hash

Current Bitcoin chain tip block hash

Status	Media type	Schema	Meaning
200	text/plain	string	The tip block hash as a bare hex string in the body.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/block-height/{height}

Block hash at a height

Parameter	In	Type	Description
height	path	integer	A block height.

Status	Media type	Schema	Meaning
200	text/plain	string	The block hash at that height, as a bare hex string.
404	application/json	object	No such record, or the path is not a registered public reader route. A 404 on an unregistered path is intentional and does not imply that an internal service exists there.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/blocks

Recent blocks

A compact summary of the most recent blocks. Each entry carries the block id, height, timestamp in seconds, transaction count, and median fee rate.

Status	Media type	Schema	Meaning
200	application/json	array of BlockSummary	Recent block summaries, newest first.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/mempool

Mempool transaction count and total virtual size

Status	Media type	Schema	Meaning
200	application/json	object	Mempool summary.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/v1/fees/recommended

Recommended fee rates in satoshis per virtual byte

Fee estimates read from Universe-operated infrastructure. There is no public-provider fallback: when the service is unavailable the API answers with an explicit failure rather than a stale or invented rate.

Status	Media type	Schema	Meaning
200	application/json	object	Fee rates in satoshis per virtual byte.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/address/{address}

Funded and spent output totals for an address

Confirmed chain totals and mempool totals are reported separately, so an unconfirmed change is never folded into a confirmed balance.

Parameter	In	Type	Description
address	path	string	A Bitcoin address.

Status	Media type	Schema	Meaning
200	application/json	object	Address statistics.
400	application/json	object	The request did not validate. The facade rejects a malformed identifier rather than passing it upstream.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/address/{address}/utxo

Unspent outputs held by an address

A failure to read is reported as unavailable. It is never presented as a confirmed empty wallet. An empty array means the address was read and holds nothing.

This response says nothing about whether an output carries an inscription, a rune balance, or any other protocol asset. Treat every output as potentially asset-bearing until an index says otherwise.

Parameter	In	Type	Description
address	path	string	A Bitcoin address.

Status	Media type	Schema	Meaning
200	application/json	array of Utxo	Unspent outputs. An empty array is a confirmed empty result.
400	application/json	object	The request did not validate. The facade rejects a malformed identifier rather than passing it upstream.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/address/{address}/txs

Transactions involving an address

Parameter	In	Type	Description
address	path	string	A Bitcoin address.

Status	Media type	Schema	Meaning
200	application/json	array of Transaction	Transactions, most recent first.
400	application/json	object	The request did not validate. The facade rejects a malformed identifier rather than passing it upstream.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

GET/mempool/api/tx/{txid}

One transaction, with its inputs and outputs

Parameter	In	Type	Description
txid	path	string	A transaction id, 64 lowercase hexadecimal characters.

Status	Media type	Schema	Meaning
200	application/json	object	The transaction.
404	application/json	object	No such record, or the path is not a registered public reader route. A 404 on an unregistered path is intentional and does not imply that an internal service exists there.
429	application/json	object	The caller exceeded its rate budget. Wait for the interval the rate-limit headers indicate before retrying.
503	application/json	object	The Universe-operated service behind this reader could not answer. There is no public-provider fallback, so this is an explicit unavailable answer rather than a zero or a stale value. Treat the quantity as unknown.

Schemas

Error

The error envelope every public route uses.

Field	Type	Required	Notes
message	string	yes	Plain-language description.
error	string	yes	Stable error code, for example NOT_FOUND.
statusCode	integer	yes
requestId	string

Health

Field	Type	Required	Notes
ok	boolean	yes
timestamp	string	yes
release	string	yes	The commit this deployment was built from.
marketplaceProfile	string	yes	Which profile the deployment is running. `read-only` keeps browsing open while every trading action stays closed.
service	object
readTraffic	object		Whether reads are ready. Reported separately from mutation readiness on purpose.
mutationTraffic	object		Whether trading actions are open. A read-only deployment reports `ready: false` here while read traffic stays available.
dependencies	object		Named dependencies and their state, for example database and bitcoinNetwork.
networks	object		Keyed by `chain:network`.
indexers	array of object		A compact per-protocol summary. `/indexer-health` carries the full form.

MutationTraffic

Whether trading actions are open. A read-only deployment reports `ready: false` here while read traffic stays available.

Field	Type	Required	Notes
enabled	boolean
preflightReady	boolean
ready	boolean
status	string
reasons	array of string		Stable reason codes naming every gate that is closed.
authorityCycles	object		The mutation gate. Every protocol authority must report current, agreeing evidence for `requiredHealthyCycles` consecutive refresh cycles before trading can open. Any missing, stale, conflicting, or failed authority resets the count.
authoritiesReady	boolean

AuthorityCycles

The mutation gate. Every protocol authority must report current, agreeing evidence for `requiredHealthyCycles` consecutive refresh cycles before trading can open. Any missing, stale, conflicting, or failed authority resets the count.

Field	Type	Required	Notes
completedCycles	integer
consecutiveHealthyCycles	integer
requiredHealthyCycles	integer
lastCycleAt	string or null
lastCycleHealthy	boolean
ready	boolean
total	integer		Protocol authorities in the cycle.
current	integer
stale	integer
unknown	integer
error	integer

NetworkState

Field	Type	Required	Notes
chainTip	integer		The verified chain head.
indexedHeight	integer
lag	integer
ready	boolean
synchronized	boolean
lastSuccessfulUpdate	string or null
indexers	array of string

IndexerHealth

Field	Type	Required	Notes
status	string	yes
total	integer	yes	Number of protocol entries in `data`.
authorityCycles	object		The mutation gate. Every protocol authority must report current, agreeing evidence for `requiredHealthyCycles` consecutive refresh cycles before trading can open. Any missing, stale, conflicting, or failed authority resets the count.
data	array of IndexerEntry	yes

IndexerEntry

Field	Type	Required	Notes
protocolId	string	yes	The registry protocol id.
indexerIdentity	string or null		Which index actually answered.
network	string or null
source	string or null
configuredIndexers	object
observedAt	string or null
ageMs	integer or null		Null when there is no successful observation to age.
freshnessLimitMs	integer or null
lastRefreshAttemptAt	string or null
lastSuccess	string or null		Null means this index has never been read successfully in the current process. It does not mean the protocol is empty.
lastError	string or null
lastTimeout	string or null
errorRate	number or null
schema	object
tip	integer		The index's own height. Zero with a null `lastSuccess` means unread, not height zero.
nodeTip	integer		The node height the index is compared against.
lag	integer		Blocks between `nodeTip` and `tip`.
capabilities	array of string		Actions this authority is currently able to execute.
declaredCapabilities	array of string		Actions the registry declares for this protocol. Compare with `capabilities`: declared is not live.
authority	object
freshness	object		Stale and disagreeing are separate booleans because an old observation and two authorities that disagree are different problems.
status	string	yes
mutationReady	boolean
reasonCode	string or null		A stable code naming the dominant reason for the current status.
reasons	array of string

BlockSummary

Field	Type	Required	Notes
id	string	yes
height	integer	yes
timestamp	integer		Unix seconds.
tx_count	integer
medianFee	number		Satoshis per virtual byte.

MempoolSummary

Field	Type	Required	Notes
count	integer		Transactions in the mempool.
vsize	integer		Total virtual size in virtual bytes.

RecommendedFees

Satoshis per virtual byte.

Field	Type	Required	Notes
fastestFee	number
halfHourFee	number
hourFee	number
economyFee	number
minimumFee	number

AddressStats

Field	Type	Required	Notes
address	string
chain_stats	object		Sums are in satoshis. Subtract `spent_txo_sum` from `funded_txo_sum` for a balance, and keep confirmed and mempool figures apart.
mempool_stats	object		Sums are in satoshis. Subtract `spent_txo_sum` from `funded_txo_sum` for a balance, and keep confirmed and mempool figures apart.

TxoStats

Sums are in satoshis. Subtract `spent_txo_sum` from `funded_txo_sum` for a balance, and keep confirmed and mempool figures apart.

Field	Type	Required	Notes
funded_txo_count	integer
funded_txo_sum	integer
spent_txo_count	integer
spent_txo_sum	integer
tx_count	integer

Utxo

Field	Type	Required	Notes
txid	string	yes
vout	integer	yes
value	integer	yes	Satoshis.
status	object

TxStatus

Field	Type	Required	Notes
confirmed	boolean
block_height	integer
block_hash	string
block_time	integer		Unix seconds.

Transaction

Field	Type	Required	Notes
txid	string	yes
version	integer
locktime	integer
size	integer
weight	integer
fee	integer		Satoshis.
vin	array of Vin
vout	array of Vout
status	object

Vin

Field	Type	Required	Notes
txid	string
vout	integer
is_coinbase	boolean
scriptsig	string
scriptsig_asm	string
witness	array of string
sequence	integer
prevout	object		An output. Nothing here says whether the output carries a protocol asset; an output holding an inscription or a rune balance looks exactly like one that does not.

Vout

An output. Nothing here says whether the output carries a protocol asset; an output holding an inscription or a rune balance looks exactly like one that does not.

Field	Type	Required	Notes
value	integer		Satoshis.
scriptpubkey	string
scriptpubkey_asm	string
scriptpubkey_type	string
scriptpubkey_address	string

Next

• What is public
• Health and readiness
• The public reader boundary