USDX Public Surface

Transparency API
Reference

The public transparency API is a read-only surface for supply, reserves, proof metadata, status, and the canonical phase 1 domain registry. It is intentionally narrow and should not be confused with the internal operational API used for mint, redeem, or treasury workflows.

Status: Public read-only
Auth: None for public reads
Rate limits: Implemented
Updated: 2026-04-26

01 Overview

The public surface currently exposes five route families: /domains, /supply, /supply/{identifier}, /reserves, /proof, and /status. Only /domains is safe to publish without live contract reads.

In self-hosted deployments, the same public API server can also serve a lightweight dashboard at / and Prometheus-style metrics at /metrics. Those are companion surfaces around the JSON routes above.

Static endpoint

/domains returns the canonical phase 1 domain registry and does not depend on live RPC state.

Live endpoints

/supply, /reserves, /proof, and /status require a real --public-registry.

⚠️

Placeholder registry files must not be presented as production data. The website should surface degraded or unavailable state rather than implying that real USDX contract addresses are configured.

02 Endpoints

Route Description Dependency
GET /domains Canonical phase 1 registry of USDX domains. Static phase 1 mapping
GET /supply Global supply plus per-domain supply breakout. Live EVM reads + public registry
GET /supply/{identifier} Supply for one domain resolved by alias or domain ID. Live EVM reads + public registry
GET /reserves Total reserves, liquid reserves, freshness, and report hash. Reserve oracle + public registry
GET /proof Latest on-chain report hash enriched by matching local publication metadata. Reserve oracle + local snapshot match
GET /status Derived system health using pause flags, reserve freshness, and reconciliation signals. Live EVM reads + public registry
Aliases supported Anonymous read-only No websocket in repo Polling-friendly

03 Response Schemas

GET /domains

{
  "domains": [
    {
      "domain_id": 1,
      "chain": "Ethereum",
      "network": "ethereum-mainnet",
      "network_family": "evm",
      "evm_chain_id": 1
    }
  ],
  "timestamp": 1710000000
}

GET /supply

{
  "global_supply": 1850000,
  "by_domain": [
    {
      "domain_id": 1,
      "chain": "Ethereum",
      "network": "ethereum-mainnet",
      "network_family": "evm",
      "evm_chain_id": 1,
      "supply": 1600000,
      "source": "onchain_local",
      "available": true
    }
  ],
  "block_number": 22000000,
  "timestamp": 1710000000,
  "reserve_fresh": true,
  "source": "onchain",
  "issues": []
}

GET /reserves

{
  "total_reserves": 2000000,
  "liquid_reserves": 500000,
  "snapshot_timestamp": 1700000000,
  "max_reserve_age": 86400,
  "fresh": true,
  "report_hash": "0xabc123...",
  "source_network": "ethereum-mainnet",
  "timestamp": 1710000000,
  "breakdown": [
    {
      "asset_class": "us_treasury_bills",
      "amount": 1200000,
      "currency": "USD",
      "source": "attestation"
    },
    {
      "asset_class": "cash_regulated_banks",
      "amount": 400000,
      "currency": "USD",
      "source": "attestation"
    }
  ],
  "issues": []
}

GET /proof and GET /status

{
  "report_hash": "0xabc123...",
  "snapshot_timestamp": 1700000000,
  "cadence": "weekly",
  "attestation_url": "https://proof.example/latest",
  "attestor": "Independent Auditor LLP",
  "published_at": "2026-04-26T12:00:00Z",
  "archive_url": "https://proof.example/archive/report-001.pdf",
  "fresh": true,
  "source_network": "ethereum-mainnet",
  "publication_status": "published",
  "timestamp": 1710000000,
  "issues": []
}

{
  "status": "ok",
  "timestamp": 1710000000,
  "components": {
    "api": "ok",
    "registry": "configured",
    "reconciliation": "ok",
    "reserve_snapshot": "fresh",
    "mint": "enabled",
    "redeem": "enabled"
  },
  "issues": []
}

The reserve breakdown and proof publication fields above are optional enrichments. When no matching published local reserve snapshot exists, those same fields may still appear as null.

ℹ️

The canonical unit of supply is domain_id, not a short chain ticker. This keeps the supply model consistent across EVM and non-EVM networks.

04 Error Behavior

  • 404 is returned for unknown routes and unresolved domain aliases.
  • 400 is returned for invalid input or malformed configuration requests.
  • 503 is returned when live public data is unavailable, including missing registry or no successful EVM snapshots.
  • 429 is returned when deployment-configured public rate limits are exceeded.
{
  "error": "public registry is not configured on this API server"
}
{
  "error": "rate limit exceeded",
  "limit": 300,
  "window_seconds": 60,
  "retry_after_seconds": 12
}
Display Rule
503/429 → explicit state, never implied healthy defaults
The website should never flatten 503 or 429 responses into a default green state. Unavailable or rate-limited public data must stay visibly explicit.

05 Operational Notes

  • The repository currently implements HTTP polling only. There is no websocket or SSE transport in the public layer.
  • The website should poll /status and /supply more frequently than /reserves and /proof.
  • Public rate limiting is implemented and deployment-configurable. The production policy example defaults to 300 requests / 60 seconds per client IP.
  • The self-hosted public API server can also expose /metrics and serve a built-in dashboard at /.
  • Paid tiers, commercial API packaging, and historical data products remain TBD.
  • Commercial mint and redeem integrations are separate from this public surface and should not be inferred from these endpoints.
Read Data Provenance Read Public Registry Rules Open the Live Hub