USDX Public Surface

Data Provenance
and Interpretation

This document explains where each public field comes from, how local enrichment works, and what the website is expected to display when data is partial, stale, unpublished, or unavailable.

Bias: Evidence-first
Audience: Integrators, reviewers, operators
Updated: 2026-04-26

01 Overview

The public API intentionally mixes three kinds of information: static protocol registry data, live on-chain contract reads, and limited local enrichment from the backend state store. The website should preserve that distinction.

Type Examples Publication expectation
Static registry /domains Always safe to publish
Live on-chain /supply, /reserves, /status Requires a real public registry and working RPC paths
Local enrichment /proof.attestor, /proof.published_at Only when the local snapshot matches the live on-chain hash and timestamp

02 Domains

/domains is built from the canonical phase 1 registry bundled in the public aggregation layer. A domain means a protocol-defined cross-chain supply identifier, not a DNS domain and not a legal jurisdiction.

  • domain_id is the canonical unit used across supply reconciliation.
  • evm_chain_id is present for all Phase 1 domains — Phase 1 is EVM-only.
  • network_family is evm for all 11 Phase 1 networks.
  • The endpoint also defines alias resolution for /supply/{identifier}.

03 Supply

Supply is aggregated from live EVM snapshots. The aggregator prefers a local on-chain reading for the domain currently being read, then falls back to remote supply views exposed by the primary or any other successful snapshot.

Source Semantics
onchain_local | onchain_remote | unavailable
The source field is an explanation, not decoration. Frontends should keep it visible to show whether a domain's figure is direct local supply or a remote reported supply.
  • global_supply is taken from live controller reads.
  • source = onchain_partial means at least one configured network failed to read.
  • reserve_fresh mirrors the primary live snapshot and should remain visible beside supply.
  • issues may include controller inconsistencies and paused contracts.

04 Reserves & Proof

Reserves

/reserves is sourced from the reserve oracle and chooses the freshest successful reserve snapshot across configured EVM networks. When a matching published local reserve snapshot includes asset-class disclosure, the response can surface concrete breakdown amounts. When no matching disclosed breakdown exists, the endpoint falls back to placeholder structure with amount = null.

Proof

/proof starts from the live on-chain latestReportHash and only enriches metadata such as cadence, attestation_url, archive_url, attestor, published_at, and publication_status when the latest local reserve snapshot matches both hash and snapshot timestamp. 

if local.report_hash == onchain.report_hash
and local.snapshot_timestamp == onchain.snapshot_timestamp:
    enrich proof payload
else:
    keep metadata fields null
⚠️

Frontends must not invent reserve composition charts or third-party attestor branding when the current payload still returns null for those fields. When the payload does carry published disclosure, frontends may render it directly.

05 Status

/status is derived, not hand-authored. It reflects actual pause flags, reserve freshness, and accumulated reconciliation issues from the same live snapshot set used by other endpoints.

  • mint = degraded when token, controller, or reserve freshness signals make minting unsafe.
  • redeem = degraded when token or mint-burn controller pause signals are active.
  • reserve_snapshot = stale when the on-chain oracle marks reserves stale.
  • status = degraded whenever issues, pauses, stale reserves, or no successful reads are present.

06 Known Gaps

  • Public rate limiting is implemented, but public API SLAs, commercial tiers, and monetization policy remain TBD.
  • Asset-class reserve amounts depend on matching published local reserve snapshots and may still be absent in some deployments.
  • Proof URLs, archive links, cadence labels, and named attestors depend on matching published local reserve snapshots and may still be null in some deployments.
  • The website should announce those gaps instead of smoothing them over.
Back to API Reference Read Registry Rules Open the Live Hub