Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(brownout): serve the degradation proofs and the upstream baseline publicly

nirholas0fe4721764bd
diff --git a/api/brownout.js b/api/brownout.js
new file mode 100644
index 000000000..127218d79
--- /dev/null
+++ b/api/brownout.js
@@ -0,0 +1,89 @@
+// GET /api/brownout — the platform's degradation posture, as data.
+//
+// Two things, and the second is the one that matters:
+//
+// contracts what this platform promises to do when a given upstream fails
+// proofs the last time each of those promises was executed for real,
+// with the upstream actually broken, and what came back
+//
+// Anyone can claim a fallback. The proof block is a receipt from a run where
+// the named provider was made to fail inside the real request path, so a reader
+// can check the claim rather than take it. `not_exercised` is reported as
+// plainly as a failure, because a proof that did not run is not a pass.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cors, json, method, wrap, error } from './_lib/http.js';
+import { limits, clientIp, rateLimited } from './_lib/rate-limit.js';
+
+const ROOT = process.cwd();
+let _cached = null;
+
+// Both files are baked into the image at build time, so this is a disk read
+// once per process, not per request.
+function load() {
+ if (_cached) return _cached;
+ const registry = JSON.parse(readFileSync(join(ROOT, 'data/brownout.json'), 'utf8'));
+ let proofs = null;
+ try {
+ proofs = JSON.parse(readFileSync(join(ROOT, 'public/brownout.json'), 'utf8'));
+ } catch {
+ // A build that has never run the prover is a real state, and saying so is
+ // better than implying the contracts are unverified when they are simply
+ // unrun in this image.
+ proofs = null;
+ }
+ const byId = new Map((proofs?.results || []).map((r) => [r.id, r]));
+ _cached = {
+ updated: registry.updated,
+ summary: registry.summary,
+ proven: proofs?.proven ?? 0,
+ total: registry.contracts.length,
+ last_proof_at: proofs?.generated_at ?? null,
+ contracts: registry.contracts.map((c) => {
+ const proof = byId.get(c.id) || null;
+ return {
+ id: c.id,
+ title: c.title,
+ surface: c.surface ?? null,
+ endpoint: c.endpoint,
+ breaks: c.break,
+ expect: c.expect,
+ why: c.why ?? null,
+ proof: proof
+ ? {
+ verdict: proof.verdict,
+ status: proof.observed?.status ?? null,
+ tier: proof.observed?.tier ?? null,
+ degraded: proof.observed?.degraded ?? null,
+ failed_sources: proof.observed?.failedSources ?? 0,
+ trace: proof.observed?.trace ?? [],
+ ms: proof.ms ?? null,
+ problems: proof.problems ?? [],
+ }
+ : null,
+ };
+ }),
+ };
+ return _cached;
+}
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
+ if (!method(req, res, ['GET'])) return;
+
+ const rl = await limits.publicIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ let payload;
+ try {
+ payload = load();
+ } catch (err) {
+ return error(res, 503, 'registry_unavailable', `the brownout registry could not be read: ${err?.message || err}`);
+ }
+
+ return json(res, 200, payload, {
+ // The registry changes with a deploy and the proofs with a prover run, so
+ // a short shared cache is right and a long one would hide a fresh proof.
+ 'cache-control': 'public, max-age=60, s-maxage=300, stale-while-revalidate=600',
+ });
+});
diff --git a/data/upstream-baseline.json b/data/upstream-baseline.json
new file mode 100644
index 000000000..bd5164334
--- /dev/null
+++ b/data/upstream-baseline.json
@@ -0,0 +1,167 @@
+{
+ "generated": "scripts/audit-upstreams.mjs",
+ "summary": {
+ "total": 183,
+ "grades": {
+ "A": 0,
+ "B": 46,
+ "C": 84,
+ "D": 53,
+ "F": 0
+ },
+ "protections": {
+ "deadline": 183,
+ "retry": 88,
+ "failover": 42,
+ "lastGood": 4,
+ "breaker": 79
+ }
+ },
+ "sites": {
+ "api/_lib/agent-tools.js::api.duckduckgo.com::fetchUpstreamJson": "C",
+ "api/_lib/alerts.js::api.telegram.org::fetchUpstream": "C",
+ "api/_lib/blockchair.js::api.blockchair.com__expr__::fetch": "C",
+ "api/_lib/changelog-push.js::api.telegram.org::fetchUpstream": "C",
+ "api/_lib/coinbase-onramp.js::api.developer.coinbase.com::fetch": "D",
+ "api/_lib/companion/lanes/telegram.js::api.telegram.org::fetch": "D",
+ "api/_lib/elevenlabs.js::api.elevenlabs.io::fetchUpstream": "C",
+ "api/_lib/embeddings.js::integrate.api.nvidia.com::fetch": "D",
+ "api/_lib/embeddings.js::api.openai.com::fetch": "D",
+ "api/_lib/esplora.js::blockstream.info::fetch": "C",
+ "api/_lib/gcp-auth.js::metadata.google.internal::fetchUpstream": "C",
+ "api/_lib/gcp-auth.js::oauth2.googleapis.com::fetchUpstream": "C",
+ "api/_lib/gcp-billing.js::bigquery.googleapis.com::fetch": "D",
+ "api/_lib/github-api.js::api.github.com__expr__::fetchUpstream": "C",
+ "api/_lib/github-api.js::api.github.com::fetchUpstream": "C",
+ "api/_lib/gmgn-feed.js::api.dexscreener.com::fetch": "D",
+ "api/_lib/hyperliquid.js::api.hyperliquid.xyz::fetchUpstreamJson": "B",
+ "api/_lib/indexnow.js::api.indexnow.org::fetch": "D",
+ "api/_lib/ipfs-pin.js::api.pinata.cloud::fetchUpstream": "C",
+ "api/_lib/ipfs-pin.js::api.web3.storage::fetchUpstream": "C",
+ "api/_lib/openrouter-free.js::openrouter.ai::fetch": "D",
+ "api/_lib/oracle/alerts.js::api.telegram.org::fetchUpstream": "C",
+ "api/_lib/persona-wallet.js::sns-api.bonfida.com::fetchUpstreamJson": "C",
+ "api/_lib/privy.js::auth.privy.io::fetchUpstream": "C",
+ "api/_lib/publish-safety.js::integrate.api.nvidia.com::fetch": "D",
+ "api/_lib/pump-go.js::livestream-api.pump.fun__expr__::fetchUpstream": "C",
+ "api/_lib/pump-launch.js::pump.fun::fetchUpstream": "C",
+ "api/_lib/rerank.js::ai.api.nvidia.com::fetch": "D",
+ "api/_lib/rugcheck.js::api.rugcheck.xyz::fetchUpstreamJson": "C",
+ "api/_lib/sketchfab.js::api.sketchfab.com::fetch": "D",
+ "api/_lib/sniper/notify.js::api.telegram.org::fetchUpstream": "C",
+ "api/_lib/sol-price.js::api.coingecko.com::fetchFirst": "B",
+ "api/_lib/sol-price.js::lite-api.jup.ag::fetchFirst": "B",
+ "api/_lib/sol-price.js::api.kraken.com::fetchFirst": "B",
+ "api/_lib/sol-price.js::api.coinbase.com::fetchFirst": "B",
+ "api/_lib/sol-price.js::coins.llama.fi::fetchFirst": "B",
+ "api/_lib/sol-price.js::api.diadata.org::fetchFirst": "B",
+ "api/_lib/sol-price.js::api-pub.bitfinex.com::fetchFirst": "B",
+ "api/_lib/token-market.js::api.dexscreener.com::fetchUpstreamJson": "B",
+ "api/_lib/tokens-xyz.js::api.tokens.xyz::fetch": "D",
+ "api/_lib/tts-edge.js::speech.platform.bing.com::fetch": "D",
+ "api/_lib/watsonx.js::openrouter.ai::fetch": "D",
+ "api/_lib/x-post.js::api.twitter.com::fetchUpstream": "C",
+ "api/_lib/x-post.js::api.x.com::fetchUpstream": "C",
+ "api/_mcp/tools/garments.js::storage.googleapis.com::fetchUpstream": "C",
+ "api/_providers/meshy.js::api.meshy.ai__expr__::fetchUpstream": "C",
+ "api/_providers/nvidia-cosmos.js::api.nvcf.nvidia.com::fetch": "D",
+ "api/_providers/nvidia.js::ai.api.nvidia.com::fetch": "D",
+ "api/_providers/nvidia.js::api.nvcf.nvidia.com::fetch": "D",
+ "api/_providers/replicate.js::api.replicate.com::fetchUpstream": "C",
+ "api/_providers/rodin.js::api.hyper3d.com::fetchUpstream": "C",
+ "api/_providers/stability.js::api.stability.ai::fetchUpstream": "C",
+ "api/_providers/tripo.js::api.tripo3d.ai::fetchUpstream": "C",
+ "api/agents/[id]/memory-seed-x.js::api.twitter.com::fetchUpstream": "C",
+ "api/agents/alpha.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",
+ "api/agents/alpha.js::api.dexscreener.com::fetchUpstreamJson": "C",
+ "api/agents/register/[action].js::api.web3.storage::fetchUpstream": "C",
+ "api/agents/register/[action].js::api.pinata.cloud::fetchUpstream": "C",
+ "api/agents/sns.js::sns-api.bonfida.com__expr__::fetchUpstreamJson": "C",
+ "api/agents/wallet-intents.js::api.anthropic.com::fetch": "D",
+ "api/agents/wallet-intents.js::openrouter.ai::fetch": "D",
+ "api/auth/github/[action].js::github.com::fetchUpstream": "C",
+ "api/auth/github/[action].js::api.github.com::fetchUpstream": "C",
+ "api/auth/x/[action].js::api.twitter.com::fetchUpstream": "C",
+ "api/avatars/_actions.js::api.anthropic.com::fetchUpstream": "C",
+ "api/chat/proxy.js::openrouter.ai::fetch": "D",
+ "api/coin/fear-greed.js::api.alternative.me::fetchUpstreamJson": "C",
+ "api/coin/fear-greed.js::pro-api.coinmarketcap.com::fetchUpstreamJson": "C",
+ "api/coin/global.js::api.alternative.me::fetchUpstreamJson": "C",
+ "api/coin/trending.js::api.geckoterminal.com::fetch": "D",
+ "api/cron/[name].js::api.twitter.com::fetchUpstream": "C",
+ "api/cron/copy-fanout.js::api.telegram.org::fetch": "D",
+ "api/cron/gmgn-seed.js::raw.githubusercontent.com::fetch": "D",
+ "api/cron/oracle-digest.js::api.telegram.org::fetchUpstream": "C",
+ "api/cron/quota-check.js::api.upstash.com::fetch": "D",
+ "api/cron/quota-check.js::qstash.upstash.io::fetch": "D",
+ "api/crypto/portfolio.js::api.dexscreener.com::fetchUpstreamJson": "B",
+ "api/defi/chains.js::api.llama.fi::fetchUpstream": "C",
+ "api/defi/dex-volumes.js::api.llama.fi::fetchUpstream": "C",
+ "api/defi/hacks.js::api.llama.fi::fetchUpstream": "C",
+ "api/defi/protocols.js::api.llama.fi::fetchUpstream": "C",
+ "api/defi/stablecoins.js::stablecoins.llama.fi::fetchUpstream": "C",
+ "api/defi/yields.js::yields.llama.fi::fetchUpstream": "C",
+ "api/demo-economy.js::api.geckoterminal.com::fetchUpstreamJson": "B",
+ "api/erc8004/[action].js::api.web3.storage::fetchUpstream": "C",
+ "api/erc8004/[action].js::api.nft.storage::fetchUpstream": "C",
+ "api/healthz.js::api.resend.com::fetch": "D",
+ "api/oracle-share.js::api.dexscreener.com::fetchUpstreamJson": "C",
+ "api/oracle-share.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",
+ "api/oracle/og.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",
+ "api/oracle/test-alert.js::api.telegram.org::fetchUpstream": "C",
+ "api/pinning/[action].js::api.pinata.cloud::fetch": "D",
+ "api/pinning/[action].js::api.web3.storage::fetch": "D",
+ "api/portfolio/[action].js::coins.llama.fi::fetchFirstOrNull": "B",
+ "api/pump-fun-mcp.js::publish.twitter.com::fetch": "D",
+ "api/pump/[action].js::api.github.com::fetch": "D",
+ "api/pump/dex-trades.js::api.geckoterminal.com::fetch": "D",
+ "api/pump/launch-detail.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",
+ "api/pump/launch-detail.js::swap-api.pump.fun::pumpFetchJson": "C",
+ "api/pump/launch-og.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",
+ "api/tts/eleven.js::api.elevenlabs.io::fetch": "D",
+ "api/tts/eleven/library.js::api.elevenlabs.io::fetch": "D",
+ "api/tts/speak.js::api.openai.com::fetch": "D",
+ "api/tx/explain.js::api.helius.xyz::fetchUpstream": "C",
+ "api/x402/crypto-intel.js::api.coingecko.com::fetch": "D",
+ "api/x402/crypto-intel.js::api.exchange.coinbase.com::fetch": "D",
+ "api/x402/defi-radar.js::api.llama.fi__expr__::fetchUpstream": "C",
+ "api/x402/hack-check.js::api.llama.fi::fetchUpstream": "C",
+ "api/x402/market-heatmap.js::api.coinpaprika.com::fetch": "D",
+ "api/x402/market-mood.js::api.alternative.me::fetchUpstream": "C",
+ "api/x402/market-mood.js::www.deribit.com::fetchUpstream": "C",
+ "api/x402/stablecoin-health.js::stablecoins.llama.fi::fetchUpstream": "C",
+ "api/x402/telegram-health.js::api.telegram.org::fetch": "D",
+ "api/x402/yield-scan.js::yields.llama.fi::fetchUpstream": "C",
+ "mcp-server/src/tools/_studio-core.js::api.replicate.com::fetch": "D",
+ "public/studio/fees-panel.js::api.github.com::fetch": "D",
+ "src/artifact/entry.js::esm.sh::loadModule": "B",
+ "src/auth/walletconnect-bridge.js::esm.sh::loadModule": "B",
+ "src/character.js::api.dexscreener.com::fetchFirstOrNull": "B",
+ "src/character.js::api.geckoterminal.com::fetchFirstOrNull": "B",
+ "src/character.js::lite-api.jup.ag::fetchFirstOrNull": "B",
+ "src/coin3d/main.js::api.geckoterminal.com::fetchFirstOrNull": "B",
+ "src/coin3d/main.js::api.dexscreener.com::fetchFirstOrNull": "B",
+ "src/coin3d/main.js::lite-api.jup.ag::fetchFirstOrNull": "B",
+ "src/home-bento.js::lite-api.jup.ag::fetch": "D",
+ "src/kol/kolscan-live.js::kolscan.io::fetch": "D",
+ "src/pinning/pinata.js::api.pinata.cloud::fetch": "C",
+ "src/privy-login.js::auth.privy.io::fetch": "D",
+ "src/shared/leaflet-loader.js::esm.sh::loadModule": "B",
+ "src/shared/leaflet-loader.js::nominatim.openstreetmap.org::fetchFirstOrNull": "B",
+ "src/shared/leaflet-loader.js::photon.komoot.io::fetchFirstOrNull": "B",
+ "src/shared/leaflet-loader.js::api.bigdatacloud.net::fetchFirstOrNull": "B",
+ "src/shared/usd-price.js::lite-api.jup.ag::fetchFirst": "B",
+ "src/shared/usd-price.js::api.coingecko.com::fetchFirst": "B",
+ "src/shared/usd-price.js::api.coinbase.com::fetchFirst": "B",
+ "src/shared/usd-price.js::coins.llama.fi::fetchFirst": "B",
+ "src/shared/usd-price.js::api.kraken.com::fetchFirst": "B",
+ "src/solana/jupiter-swap.js::lite-api.jup.ag::fetchFirst": "B",
+ "src/solana/jupiter-swap.js::tokens.jup.ag::fetchFirst": "B",
+ "src/solana/jupiter-swap.js::raw.githubusercontent.com::fetchFirst": "B",
+ "src/solana/sns.js::sns-api.bonfida.com__expr__::fetch": "D",
+ "src/swap-jupiter.js::lite-api.jup.ag::fetch": "D",
+ "workers/agent-sniper/intel/learn.js::frontend-api-v3.pump.fun::fetch": "D",
+ "workers/agent-sniper/llm-judge.js::openrouter.ai::fetch": "D",
+ "workers/okx-chat-bot/state.js::storage.googleapis.com::fetch": "D"
+ }
+}
diff --git a/docs/resilience.md b/docs/resilience.md
new file mode 100644
index 000000000..04896c43a
--- /dev/null
+++ b/docs/resilience.md
@@ -0,0 +1,144 @@
+<!-- GENERATED by scripts/audit-upstreams.mjs. Run `npm run audit:upstreams -- --map`. -->
+# Upstream resilience map
+
+Every third-party service this platform calls, and what happens to a user when
+that service is down. Generated from the source by an AST pass, so it cannot
+drift from the code the way a hand-written list does.
+
+## How a call site is graded
+
+| Grade | Meaning |
+|---|---|
+| A | Bounded, and survives the upstream being down (a second source, plus a remembered value or a retry) |
+| B | Bounded, with one way to survive: either another source or a remembered value |
+| C | Bounded, retries or trips a breaker, but has no second source |
+| D | Bounded only: a deadline and nothing behind it |
+| F | Unbounded: one stalled socket can outlive the request that opened it |
+
+A deadline is the floor rather than one grade among five, because without one
+no other protection ever gets a turn.
+
+## Totals
+
+183 outbound call sites across 72 upstreams.
+
+| A | B | C | D | F |
+|---|---|---|---|---|
+| 0 | 46 | 84 | 53 | 0 |
+
+## Weakest upstreams
+
+These carry at least one call site with no second source behind it. They are
+the list to work down, worst first.
+
+| Upstream | Call sites | Worst grade |
+|---|---|---|
+| `api.telegram.org` | 10 | D |
+| `lite-api.jup.ag` | 9 | D |
+| `api.dexscreener.com` | 8 | D |
+| `api.github.com` | 7 | D |
+| `api.coingecko.com` | 6 | D |
+| `frontend-api-v3.pump.fun` | 6 | D |
+| `openrouter.ai` | 5 | D |
+| `api.geckoterminal.com` | 5 | D |
+| `api.elevenlabs.io` | 4 | D |
+| `api.pinata.cloud` | 4 | D |
+| `api.web3.storage` | 4 | D |
+| `api.replicate.com` | 4 | D |
+| `integrate.api.nvidia.com` | 2 | D |
+| `api.openai.com` | 2 | D |
+| `auth.privy.io` | 2 | D |
+| `ai.api.nvidia.com` | 2 | D |
+| `api.sketchfab.com` | 2 | D |
+| `storage.googleapis.com` | 2 | D |
+| `api.nvcf.nvidia.com` | 2 | D |
+| `sns-api.bonfida.com__expr__` | 2 | D |
+| `api.anthropic.com` | 2 | D |
+| `raw.githubusercontent.com` | 2 | D |
+| `api.developer.coinbase.com` | 1 | D |
+| `bigquery.googleapis.com` | 1 | D |
+| `api.indexnow.org` | 1 | D |
+
+## Every upstream
+
+| Upstream | Call sites | Worst grade | A | B | C | D | F |
+|---|---|---|---|---|---|---|---|
+| `api.telegram.org` | 10 | D | 0 | 0 | 7 | 3 | 0 |
+| `lite-api.jup.ag` | 9 | D | 0 | 5 | 0 | 4 | 0 |
+| `api.dexscreener.com` | 8 | D | 0 | 4 | 2 | 2 | 0 |
+| `api.github.com` | 7 | D | 0 | 0 | 5 | 2 | 0 |
+| `api.coingecko.com` | 6 | D | 0 | 5 | 0 | 1 | 0 |
+| `frontend-api-v3.pump.fun` | 6 | D | 0 | 0 | 5 | 1 | 0 |
+| `openrouter.ai` | 5 | D | 0 | 0 | 0 | 5 | 0 |
+| `api.geckoterminal.com` | 5 | D | 0 | 3 | 0 | 2 | 0 |
+| `api.elevenlabs.io` | 4 | D | 0 | 0 | 2 | 2 | 0 |
+| `api.pinata.cloud` | 4 | D | 0 | 0 | 3 | 1 | 0 |
+| `api.web3.storage` | 4 | D | 0 | 0 | 3 | 1 | 0 |
+| `api.replicate.com` | 4 | D | 0 | 0 | 2 | 2 | 0 |
+| `integrate.api.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `api.openai.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `auth.privy.io` | 2 | D | 0 | 0 | 1 | 1 | 0 |
+| `ai.api.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `api.sketchfab.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `storage.googleapis.com` | 2 | D | 0 | 0 | 1 | 1 | 0 |
+| `api.nvcf.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `sns-api.bonfida.com__expr__` | 2 | D | 0 | 0 | 1 | 1 | 0 |
+| `api.anthropic.com` | 2 | D | 0 | 0 | 1 | 1 | 0 |
+| `raw.githubusercontent.com` | 2 | D | 0 | 1 | 0 | 1 | 0 |
+| `api.developer.coinbase.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `bigquery.googleapis.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.indexnow.org` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.tokens.xyz` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `speech.platform.bing.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.upstash.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `qstash.upstash.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.resend.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `publish.twitter.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.exchange.coinbase.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.coinpaprika.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `kolscan.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.twitter.com` | 8 | C | 0 | 0 | 8 | 0 | 0 |
+| `api.llama.fi` | 5 | C | 0 | 0 | 5 | 0 | 0 |
+| `api.x.com` | 4 | C | 0 | 0 | 4 | 0 | 0 |
+| `api.hyper3d.com` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `api.tripo3d.ai` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `api.alternative.me` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `yields.llama.fi` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `api.meshy.ai__expr__` | 2 | C | 0 | 0 | 2 | 0 | 0 |
+| `stablecoins.llama.fi` | 2 | C | 0 | 0 | 2 | 0 | 0 |
+| `api.duckduckgo.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.blockchair.com__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `blockstream.info` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `metadata.google.internal` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `oauth2.googleapis.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.github.com__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `sns-api.bonfida.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `livestream-api.pump.fun__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `pump.fun` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.rugcheck.xyz` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.stability.ai` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `github.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `pro-api.coinmarketcap.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.nft.storage` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `swap-api.pump.fun` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.helius.xyz` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.llama.fi__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `www.deribit.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `coins.llama.fi` | 6 | B | 0 | 6 | 0 | 0 | 0 |
+| `esm.sh` | 5 | B | 0 | 5 | 0 | 0 | 0 |
+| `api.kraken.com` | 4 | B | 0 | 4 | 0 | 0 | 0 |
+| `api.coinbase.com` | 4 | B | 0 | 4 | 0 | 0 | 0 |
+| `nominatim.openstreetmap.org` | 2 | B | 0 | 2 | 0 | 0 | 0 |
+| `photon.komoot.io` | 2 | B | 0 | 2 | 0 | 0 | 0 |
+| `api.hyperliquid.xyz` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api.diadata.org` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api-pub.bitfinex.com` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api.bigdatacloud.net` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `tokens.jup.ag` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+
+## Keeping this true
+
+`npm run audit:upstreams` fails when a call site regresses below the grade
+recorded in `data/upstream-baseline.json`, or when a new unbounded call appears.
+Improving a call site lowers the baseline automatically; raising it back needs an
+explicit `--accept`, which is a reviewable line in the diff.
diff --git a/scripts/resilience/README.md b/scripts/resilience/README.md
new file mode 100644
index 000000000..19ad30791
--- /dev/null
+++ b/scripts/resilience/README.md
@@ -0,0 +1,126 @@
+# Upstream resilience toolkit
+
+Three parts, each answering a question the previous one cannot.
+
+| Part | Question it answers | Entry point |
+|---|---|---|
+| [`analyze.mjs`](analyze.mjs) | Where do we call other people's services, and what protects each call? | `npm run audit:upstreams` |
+| [`contracts.mjs`](contracts.mjs) | When a service is down, what is an endpoint allowed to say? | `tests/upstream-degradation.test.js` |
+| The baseline | Can this get worse without anyone noticing? | `data/upstream-baseline.json` |
+
+## Why this exists
+
+Adding a fallback is easy. Knowing whether it made things better is not.
+
+In one week this repo added deadlines, retries, provider ladders and last-good
+caches across 147 modules, and shipped four bugs in the process. Every one came
+from the same mistake: serving a remembered value on a path where a remembered
+value is the wrong answer.
+
+- The post-402 payment retry re-signed the exact blockhash the facilitator had
+ just refused. Same payer, same payee, same amount, same hash: byte-identical
+ bytes, refused again for the same reason.
+- `/api/v1/token/security` assembled a live `200` out of remembered on-chain
+ state. Mint authority and holder concentration *are* the verdict, so that was
+ a clean bill of health for a chain nobody could read.
+- An access gate answered from a cached verdict.
+- `/api/ca2x402/resolve` told callers a real token did not exist, because on a
+ cold instance the remembered payload it was supposed to fall back to did not
+ exist yet.
+
+All four passed review. All four had fallbacks. What none of them had was a
+written answer to a different question, and that question is what this toolkit
+makes mechanical.
+
+## Part 1: the audit
+
+`npm run audit:upstreams` parses every runtime module and records, per call
+site, which of five protections are present: `deadline`, `retry`, `failover`,
+`lastGood`, `breaker`.
+
+It is an AST pass, not a grep, because the property being measured is not
+visible on the line the call is written on. The options object may be built
+three statements earlier, the deadline may arrive through a wrapper, and a
+`signal,` shorthand looks nothing like `signal:`. An earlier regex sweep of this
+same repo reported one unguarded call and was wrong in both directions: it
+missed real findings and invented 507 others, nearly all of them same-origin
+calls it could not tell from third-party ones.
+
+Two passes run. The first collects every module-level string constant, because
+base URLs here are almost always `export const PUMP_FRONTEND_BASE = '...'` in
+one module and imported everywhere else; without it the majority of call sites
+cannot be attributed to the host they actually talk to. The second grades each
+call site with those constants resolved.
+
+Grades:
+
+| Grade | Meaning |
+|---|---|
+| A | Bounded, and survives the upstream being down |
+| B | Bounded, with one way to survive |
+| C | Bounded, retries or trips a breaker, but has no second source |
+| D | Bounded only |
+| F | Unbounded: one stalled socket can outlive the request that opened it |
+
+A deadline is the floor rather than one grade among five, because without one no
+other protection ever gets a turn.
+
+This complements [`scripts/check-fetch-timeouts.mjs`](../check-fetch-timeouts.mjs),
+which enforces that floor as a binary rule. The audit measures everything above
+it and is the tool to reach for when the question is "what happens to users when
+this provider goes down", not "did someone forget a signal".
+
+`--map` regenerates [`docs/resilience.md`](../../docs/resilience.md).
+`--json` emits the full table for other tooling.
+
+## Part 2: degradation contracts
+
+Every endpoint can declare what it is allowed to say during a total outage:
+
+```js
+import { CONTRACT } from '../scripts/resilience/contracts.mjs';
+
+CONTRACT.MAY_SERVE_STALE // a remembered value beats an error, and it is marked as remembered
+CONTRACT.MUST_REFUSE // no honest answer exists without a live read
+CONTRACT.MUST_NOT_SERVE_STALE // acting on a stale answer costs money or grants access
+```
+
+`tests/upstream-degradation.test.js` then makes it true rather than taking it on
+trust: it replaces `fetch` with one that fails the way a dead host fails, calls
+the real handler, and judges the real response. Two failure shapes are injected,
+because a refused connection and a socket that accepts and never answers are
+different bugs and have caught different ones here.
+
+`MAY_SERVE_STALE` requires the response to *say* it is stale (`stale: true`, an
+`as_of` stamp, or an `x-*-stale` header). Degrading silently is how a remembered
+answer gets mistaken for a current one, so an unmarked `200` fails the contract
+even though it looks like a success.
+
+Adding an endpoint is one entry in the `ENDPOINTS` table. The harness found a
+real bug on its first run: `/api/ca2x402/resolve` answered `404 token_not_found`
+on a cold instance during an outage, denying tokens that plainly existed.
+
+## Part 3: the ratchet
+
+`data/upstream-baseline.json` records the grade of every known call site.
+
+- A **new unbounded call** fails the audit.
+- A **call site that gets worse** fails the audit, naming the file, the host and
+ the transition (`D -> F`).
+- A call site that gets **better** lowers the baseline automatically, so nobody
+ has to remember to re-record a fix and the floor only ever rises.
+- Raising the floor back needs `--accept`, which is one reviewable line in a diff
+ rather than a silent drift.
+
+This shape matters because the tail is long and the fix is not always today's
+job. A threshold ("no more than N unguarded calls") gets rounded up until it
+means nothing. A baseline lets the existing tail be paid down at its own pace
+while making it impossible to add to it by accident.
+
+## Adding a new shared helper
+
+The analyzer resolves protections by helper name. A new wrapper needs one entry
+in `GUARDS` in [`analyze.mjs`](analyze.mjs) naming what it provides by
+construction, otherwise every call site using it will be graded as if it were a
+bare `fetch`. That is the toolkit's one maintenance cost, and it is deliberate:
+it is also the list of blessed ways to call an upstream.