{
  "schema_version": "1.5.0",
  "name": "XR-Vault",
  "provider": "XRPL-Utilities™",
  "description": "Real-world asset tracker for the XRP Ledger. POST /scan accepts {issuer: wallet OR logical_label OR currency} and returns a per-issuer deep dive: current obligations + net-circulating supply (treasury-adjusted where applicable), trustline count, last 24h mint and burn flow, AMM-of-RWA pool exposure (pools whose asset/asset2 includes this issuer's IOU, with native-unit balances + LP supply), and a daily history series that accrues from each Vault deploy. Native unit-of-account only — Justoken JMWH stays in MWh, Ondo OUSG stays in OUSG, Schuman EURØP stays in EURØP. No fabricated USD valuation. Issuer-stated metrics (marketed AUM, off-chain redemption status) are not surfaced. Tracked issuer set as of 2026-05-10: Ondo OUSG (permissioned + public), Schuman EURØP, Braza USDB, Braza BBRL, SG-FORGE EURCV, Guggenheim DCP (Zeconomy SPV), Justoken JMWH (tracked in MWh; marketed USD is issuer-stated), OpenEden TBL (net-circulating excludes the OpenEden treasury wallet), Ripple RLUSD, AUDD, plus Archax abrdn USD Liquidity Fund as rails-only for first-mint capture.",
  "contact": "hello@xrpl-utilities.com",
  "getting_started": "GET /schema once to learn the response shape. POST /scan with {issuer: 'rHuiXX...' OR 'Ondo OUSG' OR 'OUSG'} and a PAYMENT-SIGNATURE header to receive the deep-dive payload. The 402 response carries two PaymentRequirements (XRP and RLUSD); pick one, sign an XRPL Payment matching it, base64-encode the JSON envelope, and resubmit as the PAYMENT-SIGNATURE header. The server verifies, builds the payload, then settles via the t54 facilitator and attaches PAYMENT-RESPONSE.",
  "location": "Cloud-Native / Global",
  "data_residency": "agnostic",
  "pii": "none",
  "capabilities": {
    "scan_input_resolution": "The `issuer` field accepts three input shapes: (1) an r-prefix XRPL classic address (exact match), (2) a logical_label string ('Ondo OUSG', 'Justoken JMWH', case-insensitive), or (3) a currency ASCII code ('OUSG', 'TBL', 'RLUSD', case-insensitive). Resolution priority: wallet > logical_label > currency. A 404 is returned when no tracked issuer matches. Logical-label and currency queries aggregate across every wallet sharing that label (Ondo OUSG operates a permissioned + public wallet pair; queries by label sum state across both); querying by exact wallet returns just that wallet's row. The response carries issuer.wallets_aggregated (count) and issuer.wallets[] (per-wallet breakdown) so consumers can tell whether aggregation happened.",
    "native_units_policy": "RWA tokens are reported in their native unit-of-account exclusively. Justoken JMWH is in megawatt-hours; OUSG, TBL, USDB, BBRL, EURØP, EURCV, AUDD, RLUSD are in their token units; Guggenheim DCP is in face-value tranches keyed by maturity. We do not multiply by an off-chain price feed to fabricate a USD figure.",
    "history_accrual": "The /scan response carries a `history.series[]` block built from local once-per-UTC-day snapshots. Days-of-history equals the number of complete prior days since the Vault deploy. The `note` field surfaces when days_of_history < 7 so consumers can tell whether the series is mature.",
    "amm_of_rwa": "The `amm_exposure` block lists every XLS-30 AMM pool whose asset or asset2 includes the queried issuer's IOU. Pool balances are in the same native units used elsewhere; LP supply is the issuer-side LP token total. Pools with dust-level liquidity are NOT filtered out — consumers decide their own threshold.",
    "issuer_caveats": "The `caveat` field carries a short operator-curated note when an issuer's data has a meaningful gotcha. Examples: OpenEden TBL net-circulating subtracts the OpenEden treasury wallet from obligations; Justoken JMWH marketed USD valuation is issuer-stated, not on-chain attested; Archax abrdn rails are configured but no tokens have been minted yet.",
    "cross_issuer_daily_flow": "GET /stats/daily-flow?days=N (free, public, N up to 90, default 30) returns two cross-issuer views built from Vault's accruing daily snapshots. settlement_events_daily counts mint + burn events per UTC day stacked by logical_label and is currency-agnostic (BRL/EUR/AUD/MWh issuers contribute alongside USD ones). usd_pegged_net_flow_daily sums net dollar inflow per UTC day across asset classes where the native unit is at or near 1 USD — fiat_stable_usd, treasuries, commercial_paper, money_market — and deliberately omits EUR/BRL/AUD/MWh issuers from the dollar aggregate; those still appear in per_issuer_series in native units. The issuer set in the rollup mirrors Pulse's operator-curated registry on the snapshot cadence; new issuers promoted upstream appear automatically with no Vault redeploy.",
    "historical_flow_backfill": "On startup (when HIST_BACKFILL_AUTO_START is enabled) the service walks account_tx for every tracked issuer over the prior 90 UTC days, classifies each successful IOU Payment as a mint (Account=issuer) or burn (Destination=issuer with Amount.issuer=issuer), buckets by UTC date, and writes per-day rows via INSERT OR IGNORE so the forward-going snapshot writer is never clobbered. The result populates the same daily_snapshot table /stats/daily-flow reads from, so charts come alive with 90 days of real history instead of starting cold from each deploy. Source field on backfilled rows is _source='historical_backfill_v1'. Trustline counts, obligations, and AMM exposure are NOT historically reconstructed; only mint/burn counts and amounts, which is what the cross-issuer chart actually needs.",
    "trust_fingerprint": "When the scanned issuer's wallet (or any wallet in an aggregated logical-label match) also operates one or more XLS-80 PermissionedDomains, the /scan response carries an optional top-level `trust_fingerprint` block. Fields: operates_permissioned_domain (boolean), matched_wallet_count, operators_directory_size, wallets[] (per-matched-wallet domain_count, credentials_issued/outstanding, unique_subjects_count, first_seen_unix, last_active_unix, permissioned_offers_24h, unique_traders_24h, amm_events_24h, has_did_identity, org_name, status), source ('xr-trust:/permissioned-domains/operators'), and a caveat reminding consumers that domain operation is a descriptive on-chain fact, not a compliance certification or legitimacy verdict. Sourced backend-to-backend via a sister-product key, configured operator-side. Cached 5 minutes; the block is omitted from the response when the upstream is unavailable or the key is unset.",
    "outputs": [
      "issuer_metadata",
      "current_state",
      "flow_24h",
      "amm_exposure",
      "history_series",
      "caveat",
      "data_status",
      "trust_fingerprint",
      "schema_version",
      "fetched_at"
    ],
    "not_provided": [
      "usd_valuation_of_rwa_tokens",
      "yield_or_apr_projections",
      "nav_reconciliation_against_off_chain",
      "editorial_legitimacy_scoring",
      "aml_or_sanction_screening_of_holders"
    ]
  },
  "payment": {
    "spec": "x402",
    "x402_version": 2,
    "scheme": "exact",
    "network": "xrpl:0",
    "facilitator_url": "https://xrpl-facilitator-mainnet.t54.ai",
    "amount_usd": "0.10",
    "amount_drops_xrp_pinned": 40000,
    "amount_drops_pinning_note": "Per-call price is pinned in XRP drops, not floated against a live XRP/USD oracle. The current pin (40,000 drops) corresponds to ~$0.10 USD at $2.50/XRP. Operator repins by setting VAULT_PRICE_DROPS when the spot rate moves substantially.",
    "currencies_accepted": ["XRP", "RLUSD"],
    "rlusd": {
      "amount": "0.10",
      "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De",
      "currency_hex": "524C555344000000000000000000000000000000"
    },
    "auth_header": "PAYMENT-SIGNATURE",
    "settlement_header": "PAYMENT-RESPONSE",
    "verify_before_settle": true,
    "recipient_resolution": "shared_with_xr_sentinel",
    "recipient_resolution_note": "The treasury wallet that receives x402 receipts is the same wallet XR-Sentinel uses. Per-service accounting via destination tags is queued as a portfolio-wide follow-up. Until that lands, per-service revenue attribution requires a destination-tag-side filter at reconciliation time.",
    "refund_policy": "Verify-before-settle. If the upstream issuer-state read fails after the buyer's payment is verified, settlement is skipped and the presigned tx is never broadcast. Successful payloads are paid; no refunds otherwise."
  },
  "endpoints": {
    "base_url": "https://vault.xrpl-utilities.io",
    "scan": "/scan",
    "schema": "/schema",
    "manifest": "/agents.json",
    "health": "/healthz",
    "stats": "/stats",
    "stats_daily_flow": "/stats/daily-flow",
    "tos": "/tos",
    "docs": "/docs",
    "openapi": "/openapi.json"
  },
  "rate_limits": {
    "requests_per_minute": 30
  },
  "legal": {
    "notice": "Deterministic on-chain measurement. Native unit-of-account only — no USD valuation is applied to RWA tokens by this service. Issuer-stated metrics (marketed AUM, yield, redemption status) are not on-chain attested and may differ from on-chain figures. DYOR. Not investment, legal, or regulatory advice.",
    "user_responsibility": "XRPL-Utilities provides on-chain measurement data. We do not provide financial advice, NAV reconciliation, yield projections, or counterparty-credit assessments. Users are responsible for ensuring their use of this data complies with local digital asset and AI regulations, including the California Digital Financial Assets Law and the Colorado AI Act where applicable. This service is offered void where prohibited; use is not authorized in California or Colorado."
  }
}