Unavailable index or empty balance
The difference between a service that cannot answer and an answer of zero, and why confusing them causes most false alarms.
Universe implementation Verified 2026-10-07
Describes what a Bitcoin Universe service actually does today. It is not a statement about the protocol in general.
- Page ID
-
guides/unavailable-indexer-vs-empty-balance - Normative authority
- Universe implementation documentation
- Networks
- mainnet
- Documentation version
- 2026.08
- Audience
- everyone, holder, developer, operator
- Owner
- bitcoin-universe-docs
- Sources
-
- Universe Atomicals NFT, Realm, and Subrealm index
at
1d9109c68d95private repository - Universe ARC-20 index and Marketplace v1 authority
at
670030e50071private repository
- Universe Atomicals NFT, Realm, and Subrealm index
at
Este conteúdo não está disponível em sua língua ainda.
The states, and what each means
Section titled “The states, and what each means”| State | What it means | What to do |
|---|---|---|
| Ready, result empty | The service answered, and there is nothing there | Check the address and asset type |
| Unavailable | The service cannot answer at all | Wait and retry. Nothing is lost |
| Degraded | Answering, but not from a complete view | Do not act on the answer |
| Stale | Answering from an old chain position | Check the indexed height |
| Mixed tip | The generation spans more than one provider tip | Do not act on the answer |
| Not covered | This asset type is not in this projection | Use the right service |
| Configured but not ready | Set up, not yet able to answer | Wait for readiness |
How to tell them apart
Section titled “How to tell them apart”Every Universe read service exposes readiness separately from liveness:
GET /livesays the process is running.GET /readysays whether it can answer correctly, and why not when it cannot.GET /healthgives the state, which can beunavailable.GET /versiongives the service and provider revisions.
Read /ready before concluding anything from an empty result. It reports the generation
identifier, the indexed height, whether the view is stale, and whether the tip is mixed.
While an index is recovering
Section titled “While an index is recovering”A restored database still needs integrity checks, a successful application start, and synchronization before its answers can be treated as current. Download completion and a running process are separate from readiness.
If a service is restoring or catching up, show that state and its indexed height. Do not show an unavailable response as an empty balance, treat an older height as the chain tip, or substitute an external blockchain provider. Recovery reuses the existing Universe-operated indexer and its protected runtime; it does not change asset ownership or protocol rules.
Wait for the service’s readiness and freshness checks before using recovered results for a transaction or market decision. A recovery in progress is not a statement that an asset is missing.
Projection coverage
Section titled “Projection coverage”An empty answer can simply mean the asset type is out of scope. The Universe NFT and Realm read model projects plain NFTs, Realms, and Subrealms, and excludes fungible tokens, Containers, and DMINT items by declaration.
Asking it about a Container returns nothing, correctly.
For product builders
Section titled “For product builders”The Core ARC-20 repair candidate prepared on 9 October 2026 separates balance summary, current output inventory and seller-book reads. A missing UTXO count stays unknown. A readable summary cannot authorize listing while inventory is unavailable; retained rows are display evidence until fresh checks succeed. The candidate offers independent lot and seller-book retries. Read retry does not sign again and is separate from resolving an earlier mutation’s unknown outcome under its original request key.
Component coverage is not a current mainnet readiness receipt. Funded wallet flows, consumer source qualification, private Signet challenge, rules, interpreter and isolated database attestation and publisher gates remain outstanding. Do not use another network or a public data provider as an outage workaround. The existing verified dates and recovery history remain unchanged.
Never render an unavailable service as a zero balance. Render the state:
- “We cannot reach the index right now” for unavailable.
- “Showing data from block N” for stale.
- “This view does not cover that asset type” for out of scope.
- “No assets found” only when the service is ready and the result is genuinely empty.