stablecoin-attestations

Stablecoin issuer reserve attestations as JSON. Each issuer's monthly (or quarterly) reserve report is parsed once into a fixed schema, joined with the current on-chain supply from DefiLlama, and served to agents over MCP and plain HTTP. $0.02 per call, free sample, no signup for the first call.

curl "https://agentwares-stablecoin.vercel.app/v1/reserves/USDC?sample=1"   # free example, no key

{
  "issuer": "Circle Internet Financial, LLC",
  "symbol": "USDC",
  "as_of": "2026-07-31",
  "period": "2026-07",
  "total_reserves_usd": 71904101332,
  "tokens_in_circulation_reported": 71826453410,
  "composition": [
    {
      "category": "us_treasury_repo",
      "label": "U.S. Treasury Repurchase Agreements",
      "amount_usd": 52723000000,
      "share": 0.733241
    },
    {
      "category": "cash_at_banks",
      "label": "Cash held at regulated financial institutions",
      "amount_usd": 10607410596,
      "share": 0.147521
    },
    {
      "category": "us_treasury_bills",
      "label": "TOTAL U.S. TREASURY SECURITIES (Circle Reserve Fund)",
      "amount_usd": 7179080057,
      "share": 0.099842
    }
  ],
  "attestor": "Deloitte & Touche LLP",
  "source_url": "https://www.circle.com/transparency",
  "report_url": "https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/USDCAttestationReports/2026/…July%2026%20(1).pdf",
  "onchain_supply": {
    "amount": 73724026944,
    "currency": "USD",
    "as_of": "2026-09-02T…",
    "source": "defillama",
    "defillama_id": "2"
  },
  "reserve_ratio": 1.001081,
  "reserve_ratio_vs_onchain_supply": 0.975314,
  "confidence": "high",
  "history_available": ["2026-07", "2026-06", "…", "2025-08"],
  "notice": "Informational only, not financial, investment or legal advice. …"
}

(abridged; the full response also carries checks, sources, issued_on, cadence, attestation_type, sample.)

Use it

| Surface | How | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP | GET /v1/reserves/{symbol}[?period=YYYY-MM] with Authorization: Bearer <key> → 200. No key → 402 with x402 (USDC on Base) + Stripe MPP terms. ?sample=1 → free USDC example. | | MCP (Streamable HTTP) | https://agentwares-stablecoin.vercel.app/mcp — tools stablecoin_reserves (paid, sample: true free) and stablecoin_list_issuers (free). | | MCP (stdio, local) | npx @agentwares/stablecoin-attestations — serves the bundled snapshot; every call is free locally. | | Registry / issuers | GET /v1/issuers (free): symbol, issuer, attestor, cadence, source URL, months parsed. | | Machine docs | /llms.txt · /pricing.json · /server.json · /bazaar.json |

Claude Desktop / Cursor:

{
  "mcpServers": {
    "stablecoin-attestations": {
      "url": "https://agentwares-stablecoin.vercel.app/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

Coverage

26 issuers in src/registry.ts, each with a verified public source (verified_at, verification), attestor, cadence and a fetch mode:

• scrape (the job finds the newest PDF itself): USDC, EURC, USDtb, USD1
• static (newest report recorded by hand): USDT, EURT, RLUSD
• manual (reports exist but links are not machine-resolvable yet): FDUSD, PYUSD, USDP, USDG, GUSD, AUSD, XSGD, EURS, TUSD, USDY, USDe
• none (on-chain collateral, no attestation document): USDS, DAI, USDD, frxUSD, crvUSD, GHO, LUSD, USD0

Issuers without a parsed month still answer with the registry data and the on-chain supply, confidence: "none" and a notice saying so.

How it works

1. resolve — newest report URL per issuer (regex over the index page, or the recorded URL).
2. pdf-text — PDF → text with unpdf in memory; only the relevant pages are kept (≤ 60k chars). The PDF itself is never stored.
3. extract — one judge.extract() call (cheap Sonnet route) into the fixed zod schema in src/schema.ts. Identical text is a cache hit at $0. Global $5/day cap applies.
4. normalize — month-end snapshot, composition must sum to the stated total (±0.5%), reserves ÷ circulation, confidence grade.
5. The result is stored as the parsed month in data/snapshot.json (committed, bundled into every deploy — the shelf has no database of its own) and served with the live DefiLlama supply.

Cost per issuer-month: ~$0.019 (measured, 14 Sonnet calls). A paid call has no LLM on its path.

Fetch job

pnpm fetch --dry-run                                   # resolve report links, no model calls
pnpm fetch --live --issuer usdc                        # parse the newest USDC report → data/snapshot.json
pnpm fetch --live --issuer usdc --history 12 --fixtures   # the acceptance run (cached after the first time)

Deployed: Vercel Cron hits GET /api/cron/refresh monthly (bearer CRON_SECRET), which runs the same job with the Postgres-backed judge (results cached in llm_cache); POST /api/refresh?issuer=usdc&force=1 is the on-demand variant. Commit the refreshed snapshot with pnpm fetch --live (a cache hit, $0).

Acceptance: 12 months of USDC against hand-checked values

fixtures/usdc/<period>.expected.json holds every figure of Circle's Aug 2025 – Jul 2026 examination reports, taken with an independent text extractor (poppler pdftotext) and arithmetically reconciled (fund + other = total = fair value ≥ circulation). fixtures/usdc/<period>.txt is the text the pipeline fed the model and <period>.extracted.json the model's answer, recorded once. src/pipeline/usdc-history.test.ts asserts, for all 12 months: as_of, both report dates, total reserves, tokens in circulation, reserve ratio, signing date, every category subtotal and that the composition sums exactly to the total. All 12 pass on the cheap route.

Pricing and payment

• $0.02 per successful stablecoin_reserves call. sample=true and stablecoin_list_issuers are free and need no key.

• An agent buys its own access, with no human and no signup:

  curl -sX POST https://agentwares-stablecoin.vercel.app/v1/keys      # → key + Stripe Checkout URL
  # open fund_url, pay by card (TEST mode: 4242 4242 4242 4242, any future expiry and CVC)
  curl -H "Authorization: Bearer $KEY" \
       -H "Idempotency-Key: $(uuidgen)" \
       https://agentwares-stablecoin.vercel.app/v1/reserves/USDC      # 200, $0.02 off the balance
  curl -H "Authorization: Bearer $KEY" https://agentwares-stablecoin.vercel.app/v1/credits

  The balance is prepaid credit in $10 / $50 / $200 packs. Debits are atomic and never go negative; a retry that repeats Idempotency-Key is charged once; a call that fails is refunded. POST /v1/credits/sync reconciles a paid session whose webhook never arrived.

• SHELF_API_KEYS still works: operator-issued keys are entitled without touching a balance.

• The 402 advertises both rails — x402 (eip155:8453, USDC) and the card rail (Stripe) — plus the x402 Bazaar discovery extension (extensions.bazaar, also at /bazaar.json). Only the card rail is settled: x402/USDC needs a Coinbase CDP facilitator account that does not exist yet, so it is advertised with no payTo and its verifier still refuses. Money never leaves Stripe.

Disclaimer

Informational only, not financial, investment or legal advice. Every number is parsed from the issuer's own published attestation (source_url, report_url) and DefiLlama's public supply feed; the attestation date and the supply date differ. Verify against the source document before relying on any figure. The response notice field repeats this on every call.

Develop

pnpm --filter @agentwares/stablecoin-attestations dev        # Next.js on :3010 (serves the same Web-standard app)
pnpm --filter @agentwares/stablecoin-attestations test       # fixtures only, no network, no model calls
pnpm --filter @agentwares/stablecoin-attestations gen:docs   # regenerate server.json, llms.txt, pricing.json, bazaar.json
pnpm --filter @agentwares/stablecoin-attestations build      # tsup (stdio bin, worker, CLIs) + next build
pnpm --filter @agentwares/stablecoin-attestations pack:dry   # what the npm tarball would contain

Env: SHELF_API_KEYS, CRON_SECRET, NEXT_PUBLIC_APP_URL (serving); DATABASE_URL_AGENTCHECK, ANTHROPIC_API_KEY, JUDGE_GLOBAL_DAILY_CAP_USD (fetch job only). All documented in packages/config/src/env.ts.

Layout: src/ (registry, schema, tool, HTTP app, pipeline, CLIs), app/[[...path]]/route.ts (Next.js catch-all → the app), src/worker.ts + wrangler.toml (Cloudflare Workers, same handler), apify/ (Actor, pay-per-event), fixtures/, data/snapshot.json.