Universe NFT and Realm API

The projection

Read this before concluding an asset is missing

Included: plain NFT, Realm, Subrealm. Excluded: FT, DFT, Container, DMItem. Write capabilities: none.

Asking this service about a Container returns nothing, correctly. Fungible tokens are served by the ARC-20 API.

What this service guarantees

• NFT, Realm, and Subrealm rows share one provider scan, one generation, one checkpoint, and one active pointer.
• Publication requires exact final declared source-row coverage and rejects a count shrink or an incomplete page.
• A generation spanning more than one provider tip is published explicitly as mixed and stale, without a single indexed height.
• Realm name, parent, claim, candidate, and payment evidence is retained in asset-specific indexes.
• The upstream provider commit is provenance, not a self-attested observed revision unless the provider reports it.

Routes

Generated from src/server.mjs in Universe Atomicals NFT, Realm, and Subrealm index at 1d9109c68d95. 36 routes. CI fails when this inventory and the OpenAPI document disagree in either direction.

Public route inventory for index-atomicals-nfts-and-realms

Method	Path	Auth	Summary
GET	/live	none	Process liveness
GET	/version	none	Service and pinned provider revisions
GET	/health	none	Health state, 503 when unavailable
GET	/ready	none	Readiness with the reason when not ready
GET	/metrics	none	Operational metrics in text form, when enabled
GET	/token-explorer/status	none	Token explorer source status
GET	/token-explorer/{protocol}	bearer	Token explorer feed page for atomicals or realms
GET	/v1/atomicals/index/status	none	Index status with a provider probe
GET	/v1/atomicals-nfts/index/status	none	Index status, NFT scope
GET	/v1/atomicals-realms/index/status	none	Index status, Realm scope
GET	/v1/atomicals/index/events	none	Recent index events
POST	/v1/atomicals/index/refresh	operator token	Queue a refresh
POST	/v1/atomicals-nfts/index/refresh	operator token	Queue a refresh, NFT scope
POST	/v1/atomicals-realms/index/refresh	operator token	Queue a refresh, Realm scope
POST	/v1/atomicals/index/rollback	operator token	Roll the active pointer back to a generation
GET	/v1/atomicals/assets	none	List assets across every projected type
GET	/v1/atomicals-nfts/assets	none	List plain NFTs
GET	/v1/atomicals-realms/assets	none	List Realms and Subrealms, filterable by kind
GET	/v1/atomicals/assets/{atomicalId}	none	Read one asset of any projected type
GET	/v1/atomicals-nfts/assets/{atomicalId}	none	Read one plain NFT
GET	/v1/atomicals-realms/assets/{atomicalId}	none	Read one Realm or Subrealm
GET	/v1/atomicals/assets/{atomicalId}/history	none	Asset history
GET	/v1/atomicals-nfts/assets/{atomicalId}/history	none	NFT history
GET	/v1/atomicals-realms/assets/{atomicalId}/history	none	Realm history
GET	/v1/atomicals/assets/{atomicalId}/holders	none	Current owner, holder scope current-owner
GET	/v1/atomicals-nfts/assets/{atomicalId}/holders	none	Current owner, NFT scope
GET	/v1/atomicals-realms/assets/{atomicalId}/holders	none	Current owner, Realm scope
GET	/v1/atomicals/assets/{atomicalId}/metadata	none	Metadata, media descriptor, and sealed state
GET	/v1/atomicals-nfts/assets/{atomicalId}/metadata	none	Metadata, NFT scope
GET	/atomicals/media/{atomicalId}/{field}	none	Stored media bytes with integrity and type restrictions
GET	/v1/atomicals-realms/resolve	none	Resolve a name to its verified winner
GET	/v1/atomicals-realms/hierarchy	none	Realm hierarchy for a name
GET	/v1/atomicals-realms/subrealms	none	Direct Subrealms of a name, with a truncation flag
GET	/v1/atomicals/transactions/{txid}	none	Projected assets touched by a transaction
GET	/v1/atomicals/blocks/{height}	none	Projected assets at a block height
GET	/v1/atomicals/utxos/{txid}/{vout}	none	Projected assets at an outpoint

Readiness

Ready requires all of the following: a generation identifier exists, the indexed height is a safe integer, the view is not stale, the tip is not mixed, and the integrity check has not failed.

When any fails, the response is 503 carrying the reason, the state, the source, the network, the generation identifier, the indexed height, the source revision, and the counts. That response is designed to be actionable.

See readiness and freshness.

Media

The media route serves stored bytes with MIME restrictions, a size limit, and digest validation. The service chooses the content type; it does not trust the one the payload declared.

Treat everything it returns as hostile input. See metadata and media.

Names

resolve returns a status, and only verified means the rules awarded the name. A candidate status is not ownership.

hierarchy and subrealms return a truncation flag. Honour it: it means there was more and the response stopped.

Unicode and IDNA errors are surfaced explicitly rather than flattened into a generic validation failure. See Unicode and IDNA.

Holders

A non-fungible object has exactly one holder, so holderScope is always current-owner and the total is one when an owner is known.

Chain lookups

Transaction, block, and outpoint lookups return projected assets scoped to the active generation. The outpoint lookup is the one to use before spending an output, because it tells you whether the output carries more than one Atomical. See splat and mixed outputs.

• OpenAPI document

  Download the validated 3.1 document, or explore it interactively.

• Errors

  The envelope, the named codes, and which ones are safe to retry.