{"schema_version":"1.20.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 three PaymentRequirements: XRP and RLUSD on XRPL (settled via the t54 facilitator) plus USDC on Base (settled via the Coinbase facilitator). Pick one, sign the matching payment, base64-encode the JSON envelope, and resubmit as the PAYMENT-SIGNATURE header. The server verifies, builds the payload, then settles 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 is a free sample: the last 7 days at most (N up to 7), tracked issuers without wallets and no candidates. GET /stats/daily-flow-history?days=N (N up to 90, default 30) returns the full rollup at $0.01 per call over x402 (free on xrpl-utilities.com): 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, measured as the change in ledger supply between 00:00 UTC readings (null on a day that could not be measured). 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.","auto_discovered_candidates":"The /stats/daily-flow-history response also carries `candidates` and `candidates_summary`, pulled from Pulse /stats/rwa-summary's auto-discovery walk over XRPL issuer wallets. Each candidate is auto-classified headless into one of two tiers: `provisional` (fingerprints like a regulated/institutional issuer: non-vanity wallet, ISIN-like or fiat-suffix currency code, RequireAuth or allow-clawback flags), or `noise` (fingerprints like a meme/community token: vanity wallet plus cute all-caps currency code, no institutional flags). Each candidate carries a `signals` block detailing the heuristic inputs so consumers can audit the classification. Tier is descriptive, not a compliance verdict. Operator promotion to the canonical rwa_issuers registry remains manual, but the tier label lets public surfaces and headless agents prefer signal over noise without manual triage.","historical_flow_backfill":"On startup (operator-toggleable) the service walks on-chain history 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","auto_discovered_candidates_classified","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_cold_oracle_fallback":70500,"amount_drops_pricing_note":"Per-call drops are computed at request time from a cached XRP/USD oracle (sourced from XR-Telemetry's healthz). The fallback 70,500 drops corresponds to ~$0.10 USD at $1.42/XRP and is only used when the oracle is unreachable on a cold cache. Reading the live drops amount is done by issuing a 402-challenged request to /scan and inspecting accepts[].amount; /stats also surfaces config.scan_price_drops_live + config.xrp_usd_oracle for non-paid visibility.","currencies_accepted":["XRP","RLUSD","USDC"],"rlusd":{"amount":"0.10","issuer":"rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De","currency_hex":"524C555344000000000000000000000000000000"},"auth_header":"PAYMENT-SIGNATURE","settlement_header":"PAYMENT-RESPONSE","optional_idempotency_header":"X-Idempotency-Key","optional_idempotency_note":"OPTIONAL, and only meaningful for baseline (standard) x402 envelopes -- the ones carrying no echoed `accepted` block. Those envelopes have no server-issued invoiceId, so the paid-replay key is derived from the payment proof, and that proof is public on-chain once the payment lands (an XRPL signedTxBlob is what a `tx` call with binary:true returns for the tx hash). The key therefore also covers the endpoint and the request body. A caller that can hold its own nonce should send one -- as this header, or as `extra.clientNonce` inside the envelope -- and its replay is bound to that instead, which is a value no on-chain observer can reconstruct. Omitting it is fully supported and changes nothing else about the call. Baseline replays are honoured for 60 seconds, not the 600 seconds an `accepted`-bearing payment gets.","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.","rails":[{"network":"xrpl:0","currency":"XRP","amount_usd":"0.10","note":"XRP amount is dynamic - equivalent to $0.10 USD at current spot."},{"network":"xrpl:0","currency":"RLUSD","amount":"0.10","issuer":"rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De","currency_hex":"524C555344000000000000000000000000000000"},{"network":"eip155:8453","currency":"USDC","recipient":"0xa9c371e166229AAaA4C3999FB8a203e43c7329F8","amount_atomic":"100000","decimals":6,"contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","note":"USDC-on-Base settled via the Coinbase x402 facilitator. Same $0.10 price as the XRPL rails."}],"data_routes":{"amount_usd":"0.01","applies_to":["/stats/daily-flow-history"],"rails":["RLUSD on XRPL","XRP on XRPL","USDC on Base"],"method":"GET with x402 PAYMENT-SIGNATURE; an unpaid call returns the 402 offer","charged_only_on_success":true,"free_access":"The same data is free to read on xrpl-utilities.com."}},"mcp_capability":{"hosted_endpoint":"https://mcp.xrpl-utilities.io","stdio_command":"npx -y @xrpl-utilities/mcp","npm_package":"@xrpl-utilities/mcp","github_repo":"https://github.com/XRPL-Utilities/xrpl-utilities-mcp","tools":["xrpl_vault_scan"],"note":"Same read endpoints are also exposed as MCP tools for AI clients (Claude Desktop, Cursor, anything Model Context Protocol-aware). Stateless passthrough - the MCP server forwards the caller's own x402 payment header to the backend; no billing aggregation."},"destination_tag_partition":{"scheme":"32-bit XRPL DestinationTag; top 8 bits encode the service that minted the tag.","service_prefix_hex":"0x05","service_prefix_int":5,"tag_range_inclusive":[83886080,100663295],"tag_range_hex":["0x05000000","0x05ffffff"],"decoder_pseudocode":"service_id = (destination_tag >> 24) & 0xFF","portfolio_prefix_map":{"0x01":"Sentinel","0x02":"Pulse (reserved, not yet minting tags)","0x03":"Telemetry","0x04":"Trust (reserved, not yet minting tags)","0x05":"Vault (reserved, not yet minting tags)","0x06":"Flows (reserved, not yet minting tags)"},"note":"Reserved-only for Vault today. Vault's paid surface (/scan) settles via x402 inline-payment with invoiceId in the payment payload, not via DestinationTag. The prefix is declared here so operators can reconcile incoming Payments at the shared treasury wallet by service, and so future invoice-flow tags from Vault stay within its reserved range."},"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","uptime":"/uptime?days=30","stats_daily_flow_history":"/stats/daily-flow-history"},"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."},"data_status":{"unreadable_is_not_zero":"Every figure in /scan sourced from the upstream RWA summary is null when the field was absent or unparseable, never 0. data_status.unreadable_fields[] names each collapsed field on a fetch that otherwise succeeded (pulse_last_error stays null in that case), and a non-empty list IS a fault indicator. Mint and burn COUNTS are null for XLS-33 MPT issuers because discrete mint/burn events are not observable for that standard; flow_24h.flow_basis and flow_24h.token_standard say which basis produced the amounts. Those deliberate nulls land in data_status.not_observable_fields[], NOT unreadable_fields -- they are a normal state, not a fault. A field the upstream renames becomes absent rather than null, so it still lands in unreadable_fields even for an MPT issuer.","token_escrow_24h.pct_of_net_circulating":"Computed from net_lockup_delta_24h (EscrowCreate amount minus Finish and Cancel amounts) over net circulating supply. token_escrow_24h.amount_sum is GROSS event throughput -- create, finish and cancel amounts summed -- which is a 24h flow and is not divisible by a point-in-time supply stock: an escrow created and released inside the window contributes twice, so dividing it by supply can exceed 100% while nothing is locked. When the per-type split is not available upstream, or the two figures are not on the same basis, the percentage is null and pct_of_net_circulating_note carries the reason. It is never approximated from amount_sum and never clamped.","amm_exposure.pools_on_ledger":"Count of every AMM pool on the ledger holding this issuer's token, from XRPSCAN /amm/pools (discovery only, one request). It is the DENOMINATOR for pools_containing, which counts the pools we actually measure via a curated probe carrying live reserves. The gap is large and deliberate: measured 2026-08-21, 486 ledger pools touch a tracked RWA issuer against 20 measured, but sampling shows the remainder is overwhelmingly memecoins opening a nominal pair against a regulated ticker, holding 1-450 units of the RWA asset. Count is not exposure, so the measured set is not widened to match. null when XRPSCAN has never been readable -- not 0, which would be a denominator smaller than the numerator."}}