API Reference

The Pharos API is a REST API served by a Cloudflare Worker backed by a D1 database. It powers the pharos.watch stablecoin analytics dashboard through a split website-data lane plus an external integration API. On https://api.pharos.watch, all public routes are API-key protected unless this reference explicitly marks them as exempt.

Base URL: https://api.pharos.watch

Unless noted otherwise, responses are Content-Type: application/json. Exceptions: GET /api/og/* / HEAD /api/og/* return image/png for known image routes, and POST /api/telegram-webhook returns a plain-text ok body. CORS headers are added to every response, but Access-Control-Allow-Origin is restricted by the Worker CORS_ORIGIN allowlist (production repo config: https://pharos.watch,https://ops.pharos.watch). When the request Origin matches an allowlisted entry, the Worker echoes that origin and sets Vary: Origin; when a request includes a foreign Origin, the worker omits Access-Control-Allow-Origin, and OPTIONS preflights from foreign origins receive 403. Requests without an Origin header keep the existing first-allowlisted-origin fallback. Non-exempt /api/* requests on api.pharos.watch require a valid X-API-Key; missing or invalid keys return 401 Unauthorized. Per-key rate-limit overages return 429, and cold auth/limiter dependency failures can still return 503.

Surface Split

The runtime now uses three HTTP lanes:

• https://api.pharos.watch is the external integration API. Protected public routes require X-API-Key.
• https://site-api.pharos.watch is the website-internal Worker host. It accepts only allowlisted GET reads plus X-Pharos-Site-Proxy-Secret.
• /_site-data/* is the same-origin Pages Functions proxy used by browsers on pharos.watch, ops.pharos.watch, stablecoin-dashboard.pages.dev, and subdomains of stablecoin-dashboard.pages.dev.

Static dataset exports are served from the public website, not from the Worker API, and do not require X-API-Key. The Stablecoin Cemetery export is available as JSON at https://pharos.watch/datasets/stablecoin-cemetery.json and CSV at https://pharos.watch/datasets/stablecoin-cemetery.csv.

Machine-readable integration artifacts are also served from the public website for onboarding. The OpenAPI endpoint catalogue is available at https://pharos.watch/openapi.json, and Postman artifacts are available at https://pharos.watch/postman/pharos-api.postman_collection.json plus https://pharos.watch/postman/pharos-api.postman_environment.json. Import both Postman files, then replace the environment apiKey placeholder with a real X-API-Key. The generated OpenAPI artifact includes named schemas for the richer Yield Intelligence ranking and history payloads, and the Postman collection includes both best-source and source-key yield-history examples. These are public integration/read onboarding artifacts, not a complete dump of every no-key route; they intentionally exclude Cloudflare-Access-gated admin routes, self-serve key issuance POST endpoints, feedback submission, Telegram webhook ingestion, Telegram Mini App endpoints, and dynamic OG image routes. Request keys through https://pharos.watch/api/.

Browser consumers should use same-origin /_site-data/* via the frontend helpers in src/lib/api.ts. In production, that Pages proxy targets https://site-api.pharos.watch through SITE_API_ORIGIN. Direct integrations, CI smoke, and build-time sync scripts should target https://api.pharos.watch and send X-API-Key for protected public reads, including /api/telegram-pulse.

Production Pages does not proxy public self-serve /api/* POST requests. The public form at https://pharos.watch/api/ calls https://api.pharos.watch/api/api-key-requests and https://api.pharos.watch/api/api-key-requests/verify with normal CORS preflights for JSON POST requests.

Self-serve API-key request honeypot submissions are intentionally no-op accepted: POST /api/api-key-requests returns 200 { "ok": true } when the optional website field is non-empty, without creating an API-key request or sending email. Normal non-honeypot submissions return 202 Accepted with pending_verification.

The direct Worker cache profiles below describe responses from api.pharos.watch / site-api.pharos.watch. The Pages /_site-data/* proxy adds a separate same-origin Cache API layer for successful responses without Set-Cookie, without Cache-Control: no-store, and without freshness Warning: 110; it does not cache no-store routes such as /api/health.

Public API Auth

Unless a route is explicitly called out below as exempt, requests to https://api.pharos.watch must send:

• header: X-API-Key: ph_live_<16 hex prefix>_<32 char base64url secret>
• example shape: ph_live_0123456789abcdef_abcdefghijklmnopqrstuvwxyzABCDEF

Public, non-admin routes on https://api.pharos.watch that do not require X-API-Key are limited to:

• GET /api/health
• GET /api/og/*
• HEAD /api/og/*
• POST /api/feedback
• POST /api/api-key-requests
• POST /api/api-key-requests/verify
• POST /api/telegram-webhook
• POST /api/telegram-mini-app/session
• POST /api/telegram-mini-app/mutate

POST /api/telegram-webhook is externally reachable but not anonymous: it requires X-Telegram-Bot-Api-Secret-Token instead of X-API-Key.

POST /api/telegram-mini-app/session and POST /api/telegram-mini-app/mutate are also externally reachable but not anonymous. They require Telegram Mini App initData signed for @PharosWatchBot; the worker validates the HMAC, auth_date, and user payload before any D1-backed state write. These endpoints are denied on the website-internal site-data lane and are intended only for the Mini App at https://pharos.watch/pharoswatchbot/app/.

Admin/operator routes are also outside the public API-key gate, but they remain Cloudflare-Access-gated and are supported only through ops-api.pharos.watch or the ops.pharos.watch/api/admin/* Pages proxy. The public API host rejects registered admin paths and configured admin-like root families before API-key auth, so a public API key cannot be used to reach registered admin routes or malformed children of configured roots such as /api/api-keys*, /api/api-key-requests-admin*, and /api/discovery-candidates* on api.pharos.watch.

The public self-serve request form lives at https://pharos.watch/api/. It sends an email verification link, then exchanges that one-time token for a default key after verification. Default self-serve keys are tier="self-serve", trafficClass="external", limited to 30 requests per minute, expire after 60 days, and allow one active/pending self-serve claim per normalized email. Request details are available only in the private ops.pharos.watch/admin-api/ UI.

The worker stores only the key prefix plus a peppered HMAC of the secret portion. Admin callers create, rotate, and deactivate keys through the operator lane (ops.pharos.watch / ops-api.pharos.watch); plaintext tokens are returned only once at creation/rotation time. Self-serve issuance uses the same storage model and returns the plaintext token only once after verification.

For protected cacheable GET routes, the worker keeps a bounded isolate-local verified-key cache and a bounded isolate-local limiter. A recently verified non-self-serve key can use that local path for hot edge-cache hits, and can continue to read cached routes during a brief D1 auth/limiter outage. Self-serve, unknown, stale-cache, or not-yet-verified keys still fail closed.

Stablecoin IDs

Most endpoints use the Pharos stablecoin ID in ticker-issuer format (e.g. usdt-tether). IDs are checked through the shared stablecoin-ID registry (shared/lib/stablecoin-id-registry.ts). Unknown or non-canonical IDs return 404.

Canonical IDs use ticker-issuer format — lowercase ticker symbol hyphenated with the issuer/protocol name:

The full list is exported from shared/lib/stablecoins/registry.ts, with editable per-coin metadata stored in shared/data/stablecoins/coins/*.json, the checked-in generated aggregate at shared/data/stablecoins/coins.generated.json, and validation in shared/lib/stablecoins/schema.ts. The API accepts canonical IDs only. Non-canonical stablecoin detail URLs and legacy frontend route aliases are retired and unsupported.

Response Headers

Endpoints backed by the cron cache include these additional headers:

Generic freshness status is fresh through 8x maxAge, degraded through 12x maxAge, then stale. Generic freshness headers emit Warning and downgrade Cache-Control to no-store after age > 8x maxAge so edge/browser caches do not keep serving an old payload after the underlying cron data recovers. Some routes also use Warning for dependency or quality advisories even when the age is still inside that runway; clients should treat body _meta.status as authoritative when it exists.

Response Body Freshness (_meta)

Endpoints that emit _meta into plain-object (non-array) response bodies do so through createCacheHandler() or route-specific manual injection, alongside the HTTP freshness headers above. This provides inline freshness metadata for consumers that prefer not to parse response headers.

Shape:

{
  "_meta": {
    "updatedAt": 1710500000,
    "ageSeconds": 42,
    "status": "fresh"
  }
}

Route-specific manual _meta injectors can be stricter. GET /api/chains uses its 1800-second budget directly (fresh <= 1x, degraded <= 2x, then stale) and switches its response to no-store whenever the chain snapshot is not fresh.

Endpoints with _meta:

Array-typed responses (e.g., endpoints returning a JSON array at the top level) do not include _meta. They receive X-Data-Age / Warning only when their handler wires freshness metadata explicitly. Supply history, safety score history, and non-USD share are explicit history-endpoint exceptions that emit freshness headers; DEX liquidity history currently exposes cache headers but no freshness headers.

The frontend apiFetchWithMeta() helper (in src/lib/api.ts) reads _meta from the response body when present, falling back to the X-Data-Age header for endpoints that do not include it.

Cache-Control Profiles

These profiles apply while the dataset is within its generic freshness runway. Once a cache-backed response exceeds 8x its endpoint max age, the worker overrides that response to Cache-Control: no-store until a fresh response is generated.

All rows below are members of the centralized API_CACHE_PROFILES map (shared/lib/api-cache-profiles.ts) except immutable-snapshot, which is a route-local constant (IMMUTABLE_CACHE_CONTROL in worker/src/api/snapshot.ts) reused for the immutable public-snapshot routes.

POST /api/feedback, POST /api/api-key-requests, POST /api/api-key-requests/verify, POST /api/telegram-webhook, POST /api/telegram-mini-app/session, POST /api/telegram-mini-app/mutate, and admin POST endpoints bypass edge caching because they are non-GET request paths. The self-serve API-key endpoints and Telegram Mini App endpoints explicitly return no-store responses so verification tokens, plaintext API keys, and per-chat alert state are never cacheable.

Polling Guidance

Recommended minimum polling cadence for external integrations:

Client best practices:

• Add interval jitter (±10%) to avoid synchronized bursts.
• Read X-Data-Age + Warning for freshness/stale decisions when those optional headers are present.
• Back off exponentially on 429 and 5xx responses.

Rate Limits

Public API traffic enforces per-key rate limiting to ensure fair usage. Non-exempt /api/* requests require a valid X-API-Key; the no-key public exceptions are GET /api/health, GET /api/og/*, HEAD /api/og/*, POST /api/feedback, POST /api/api-key-requests, POST /api/api-key-requests/verify, POST /api/telegram-webhook, POST /api/telegram-mini-app/session, and POST /api/telegram-mini-app/mutate. The Telegram webhook is authenticated separately with X-Telegram-Bot-Api-Secret-Token; Telegram Mini App endpoints are authenticated with signed Telegram initData.

Per-key limit

Per-key overrides are stored in api_keys.rate_limit_per_minute.

Self-serve keys are issued with a fixed default of 30 requests per minute and a 60 day expiry. The request workflow has separate abuse limits: initial submissions are throttled by salted IP hash (5/hour) and private email hash (3/day), verification attempts are throttled by salted IP hash (20/10 minutes) and token hash (5/10 minutes), and successful issuance allows one self-serve key creation per salted IP hash per 24 hours.

When the per-key limiter is exceeded, the API returns 429 Too Many Requests:

{
  "error": "Rate limit exceeded"
}

Rate-limited responses include the retry delay in the HTTP Retry-After header when the worker can compute one.

POST /api/feedback also has a form-specific limiter. Its 429 body is { "error": "Too many submissions. Please wait a few minutes." }, and it should be handled as a local submission throttle rather than as a public API quota response. If the feedback limiter's D1 dependency is unavailable, the endpoint returns 503 Service Unavailable with { "error": "Feedback service temporarily unavailable. Please try again." } and Retry-After: 60.

API-key authentication and per-key limiter storage normally rely on D1. For protected cacheable GET edge-cache hits, the worker can serve a recently verified non-self-serve key through a bounded isolate-local auth/limiter path. It can also continue serving a recently verified non-self-serve key during a brief D1 outage by reusing its bounded verified-key cache and isolate-local limiter. Self-serve keys are refused when their D1 lookup is unavailable because revocation and claim state cannot be rechecked from stale isolate cache. Unknown or not-yet-verified keys still fail closed with 503 Service Unavailable, { "error": "Public API temporarily unavailable" }, and Retry-After: 60. Best-effort API-key usage timestamp updates do not fail otherwise successful reads.

Retry Guidance

• Respect the Retry-After header when present
• Add random jitter (0–2 seconds) to avoid thundering-herd retries
• Use exponential backoff for sustained 429 responses
• Combine with the polling cadences in the section above to stay well under limits

Error Response Conventions

JSON API handlers use { "error": "message" } JSON format. GET /api/og/* and HEAD /api/og/* return image/png on success for known image routes; unknown OG route patterns return the normal JSON error body, while OG data/render failures inside known image routes can return text/plain.

Rule: Cache-passthrough handlers return 503 when data hasn't been populated yet or when the stored cache payload is malformed and rejected at read time. Query handlers that find no matching rows return 200 with empty results (e.g., { events: [], total: 0 }). When MAINTENANCE_MODE is set to "true", all non-OPTIONS requests immediately return 503 with { "error": "maintenance", "message": "..." } — used during DB migrations. OPTIONS CORS preflights are handled before the maintenance gate.

Method Gating Policy

HTTP method allowance is defined centrally in shared/lib/api-endpoints/ and enforced by worker/src/router.ts (validateEndpointMethod).

• GET is accepted for read endpoints (plus admin debug/status endpoints, GET /api/backfill-dews, and dry-run repair previews for GET /api/backfill-dews?repair=...&dry-run=true).
• POST is accepted for mutating admin endpoints, POST /api/feedback, POST /api/api-key-requests, POST /api/api-key-requests/verify, POST /api/telegram-webhook, POST /api/telegram-mini-app/session, and POST /api/telegram-mini-app/mutate.
• GET, POST is accepted on /api/api-keys so operators can list keys and create a new key through the same route.
• POST is accepted on /api/api-keys/:id/update, /api/api-keys/:id/deactivate, and /api/api-keys/:id/rotate.
• /api/audit-depeg-history allows GET only with ?dry-run=true; otherwise it is POST-only.
• /api/backfill-dews allows GET for the historical backtest and for repair=...&dry-run=true previews; mutating repair runs are POST-only.
• Unknown public /api/* requests can return 401 first when the API key is missing or invalid. After lane auth succeeds, unregistered paths return 404 because no route dependencies can be hydrated. Once a static or dynamic route family is registered, known paths with disallowed methods return 405 with Allow; unsupported verbs on known endpoint families return 405 with Allow: GET, POST.

The same shared endpoint descriptors now also carry static worker dependency-hydration hints consumed by worker/src/routes/registry.ts, where the worker binds shared endpoint keys directly to handlers through a single static route-definition list. That keeps endpoint metadata, router behavior, method guards, admin status-page actions, and worker-side static route wiring aligned from one source of truth plus one worker binding table.

Public Endpoints

Unless an endpoint section explicitly says Authentication: exempt, routes in this section require X-API-Key when called on https://api.pharos.watch.

Public Endpoints Quick Reference

Generated from public/openapi.json (Pharos API v1.0.0). The OpenAPI artifact intentionally excludes Cloudflare-Access-gated admin routes, self-serve key issuance POST endpoints, feedback submission, Telegram webhook ingestion, Telegram Mini App endpoints, and dynamic OG image routes. Those endpoints are documented in the hand-written sections below.

Total documented public operations: 38.

GET /api/events

Tape events surface, backed by worker/src/api/events.ts. The handler already accepts type, class, coin (multi-value), pegCurrency, chain, q (case-insensitive free-text search), severityFloor, since / until (epoch ms), cursor, limit, and includeTotal per the quick-reference table above. The response envelope is { events[], nextCursor, total, totalExact, _meta }: nextCursor is a keyset cursor string (null when there are no more rows), total is the exact count only when includeTotal=true (otherwise null), and totalExact mirrors that boolean.

As of the May 2026 detail-page pass, the frontend hook useChartAnnotations (src/hooks/use-chart-annotations.ts) consumes this endpoint to drive per-coin chart annotations on the stablecoin detail route. The hook is gated by NEXT_PUBLIC_PHAROS_CHART_ANNOTATIONS — see process/feature-flags.md.

Phase 1 (shipped May 2026): the hook is wired through the consumer surface (<ChartAnnotationDots> + screen-reader-only legend) but returns an empty array. Charts render byte-identically to the pre-flag baseline; the flag-off path never fetches.

Phase 2 (planned): align the hook's URL params to the handler's existing shape — coin=<id> + since / until in epoch ms — or extend the worker to accept chart-friendly aliases (stablecoin, from, to). Phase 2 will also wire useApiQueryWithMeta, map tape-event rows into ChartAnnotation, and clamp results to the rendered chart's [fromMs, toMs] window inside the memo so out-of-range markers cannot push the data domain.

GET /api/stablecoins

Full stablecoin list with current supply, price, chain breakdown, and FX rates. Data is refreshed by cron every 15 minutes; the cache entry has a 10-minute max-age.

Cache: realtime — X-Data-Age and Warning headers included.

The canonical stablecoins cache is written only after StablecoinListResponseSchema validation. Worker consumers that require the published public contract can opt into the same schema on cache read and return 503 for schema-invalid cached objects. Compatibility readers that only need critical fields may still salvage valid entries from older or partially malformed payloads, but they surface that state as degraded with a filtered-entry count instead of treating the filtered payload as fully healthy.

Response

{
  "peggedAssets": [StablecoinData, ...],
  "fxFallbackRates": { "peggedEUR": 1.082, "peggedGBP": 1.26 },
  "_meta": { "updatedAt": 1710500000, "ageSeconds": 42, "status": "fresh" }
}

fxFallbackRates is present when the FX-rate state loaded by sync-stablecoins has usable fresh or static references; inputs can come from Frankfurter/ECB, secondary or tertiary FX mirrors, commodity references, or cached/static fallback rates. Keys are pegType strings (e.g. "peggedEUR"), values are rates in USD.

StablecoinData fields

ContractDeployment

PriceSourceConfidenceProfile

ChainCirculating

{
  "current": 50000000,
  "circulatingPrevDay": 49000000,
  "circulatingPrevWeek": 47000000,
  "circulatingPrevMonth": 44000000
}

All circulating values are already in USD (the list endpoint does not return native-currency values for non-USD pegs). Do not multiply by price.

GET /api/stablecoin/:id

Historical price and supply chart data for a single stablecoin. Proxies DefiLlama (or CoinGecko for commodity/CG-only tokens) with a 5-minute server-side cache. All upstream calls use fetchWithRetry with explicit per-request timeouts; on upstream/parse failures, or when CoinGecko-derived history is empty/stale, logs include source tags and stablecoin ID before stale-cache fallback or supply_history reconstruction. CoinGecko history is treated as stale when its newest point is more than 72 hours old.

When a D1 detail cache row exists but is older than the 5-minute TTL and younger than 24 hours, the Worker serves that stale row immediately with Warning: 110, X-Data-Age, and Cache-Control: no-store, then refreshes the coin in the background. Refresh work is best-effort single-flight per coin within a Worker isolate, so bursts of stale reads do not all fan out to upstream providers. Rows older than 24 hours are not served as stale fallback; they force the same synchronous refresh path used by cold misses, sharing an in-flight refresh where one already exists in the same isolate.

Path parameter: :id — Pharos stablecoin ID.

Cache: per-coin — custom Cache-Control with a 5-minute server-side D1 TTL (public, s-maxage<=300, max-age=10)

Response

{
  "tokens": [TokenPoint, ...]
}

TokenPoint

For regular stablecoins the response still includes the raw DefiLlama detail fields, but the worker now also materializes totalCirculatingUSD and totalCirculating on each token row for contract consistency. Commodity and CG-only tokens are returned directly in the normalized shape above.

For non-USD pegs, totalCirculating remains in native units while totalCirculatingUSD is converted to USD using the current token price before caching, so the USD field always reflects market cap regardless of peg type.

GET /api/stablecoin-summary/:id

Lightweight per-coin snapshot sourced from cached stablecoins data. Designed for integrators that need current price/supply context without transferring full /api/stablecoin/:id history payloads. Browser surfaces on pharos.watch and ops.pharos.watch should reach this route through same-origin /_site-data/stablecoin-summary/:id, which proxies onto the internal site-api lane instead of the external API-key lane.

Path parameter: :id — Pharos stablecoin ID.

Cache: realtime — X-Data-Age and Warning headers included.

Error responses: 503 when the shared stablecoins cache is missing or structurally corrupt; 404 when the requested coin ID is absent from an otherwise valid cache snapshot.

Response

{
  "id": "usdt-tether",
  "name": "Tether",
  "symbol": "USDT",
  "pegType": "peggedUSD",
  "pegMechanism": "fiat-backed",
  "priceUsd": 1.0001,
  "priceSource": "coingecko+defillama-list",
  "priceConfidence": "high",
  "supplySource": "defillama",
  "supplyByPegUsd": { "peggedUSD": 183883564940.52 },
  "supplyUsd": {
    "current": 183883564940.52,
    "prevDay": 183697699496.48,
    "prevWeek": 183673067145.19,
    "prevMonth": 185316486043.16,
    "change1d": 185865444.03,
    "change7d": 210497795.33,
    "change30d": -1432921102.64
  },
  "chainCount": 17,
  "updatedAt": 1772718367
}

GET /api/non-usd-share

Returns historical non-USD stablecoin market share data from supply_history, split into commodity-pegged (gold/silver) and non-commodity non-USD buckets. The response keeps the legacy fiatNonUsd* field names for wire compatibility, but those fields include currency-linked plus other non-commodity non-USD pegs. Data is downsampled: daily for the last 90 days, weekly for the last 2 years, monthly beyond that.

Cache: slow — public, s-maxage=3600, max-age=300

Freshness headers are emitted from the latest completed snapshot-supply run when available. Stale responses include X-Data-Age and can downgrade to Cache-Control: no-store with Warning: 110 once the daily history runway is exceeded. Rows newer than the completed daily snapshot marker are hidden so a failed chunked write cannot expose a partial latest day.

Unlike most numeric-query handlers, this endpoint defaults missing or malformed days values to 5000 and clamps most out-of-range values into 30..5000 instead of returning 400. Current parser quirk: days=0 is treated like a missing value and returns the default 5000 rather than the minimum 30.

Response: Array<{ date, commodityShare, fiatNonUsdShare, commodity, fiatNonUsd, total }>

GET /api/chains

Returns chain-level stablecoin aggregates with Chain Health Scores. Computed on-the-fly from the stablecoins cache and report-card cache (two D1 reads) — no dedicated chain table is required for the live leaderboard. The response body also carries _meta, so the frontend can distinguish fresh, degraded, and missing-dependency states without inferring freshness from fetch timing alone.

Cache: realtime — public, s-maxage=60, max-age=10

Freshness threshold: 1800 seconds. Returns 503 when the stablecoins cache is unavailable or structurally corrupt. When dependent snapshots lag, the endpoint stays readable but the body _meta.status degrades and the frontend surfaces stale-data warnings.

Status codes:

Response (ChainsResponse):

{
  "_meta": {
    "updatedAt": 1710500000,
    "ageSeconds": 42,
    "status": "fresh",
    "dependencies": {
      "reportCards": {
        "updatedAt": 1710499800,
        "ageSeconds": 242,
        "status": "fresh"
      }
    }
  },
  "chains": [ChainSummary, ...],
  "globalTotalUsd": 230000000000,
  "chainAttributedTotalUsd": 218000000000,
  "unattributedTotalUsd": 12000000000,
  "globalChange24hPct": 0.0012,
  "globalChange7dPct": 0.0045,
  "globalChange30dPct": 0.018,
  "updatedAt": 1710500000,
  "healthMethodologyVersion": "1.2"
}

_meta.dependencies.reportCards is present when the endpoint can determine report-card freshness. When that dependency is stale or unavailable, healthScore degrades to null and the route UI surfaces the dependency reason instead of pretending the chain is fully fresh.

ChainSummary fields:

ChainHealthFactors fields:

GET /api/stablecoin-reserves/:id

Returns the resolved reserve presentation for a stablecoin with liveReservesConfig.

• Unknown IDs or coins without live reserve support return 404.
• Live-enabled coins return 200 even before the first successful sync; the payload includes fallback mode + sync state.
• This endpoint powers the stablecoin detail-page reserve card. The same underlying live-reserve dataset also feeds report-card collateral quality, reserve-drift monitoring, and /status, but those surfaces read D1-backed reserve snapshots directly rather than calling this endpoint.
• A response is treated as live only when the stored reserve snapshot matches the latest successful sync state and passes strict integrity validation; orphaned partial writes or corrupt stored snapshots fall back to the curated/template presentation instead of presenting malformed live data as authoritative.
• Successful responses are covered by the shared StablecoinReservesResponseSchema; frontend API clients validate 200 payloads strictly while preserving 404 as the not-live-enabled/null path.

Cache: dynamic

• Live snapshots: slow (public, s-maxage=3600, max-age=300)
• live-stale snapshots: public, s-maxage=1800, max-age=120
• Bootstrap / fallback / unavailable presentations: shorter (public, s-maxage=300, max-age=60) so pre-sync fallback responses do not stay pinned at the edge after the first successful live sync

Response (200):

sync.warnings can include both adapter-emitted warnings from the latest attempt and storage-integrity warnings when a stored live snapshot is rejected and the endpoint fails closed to a fallback presentation. sync.failureCategory is copied from reserve_sync_state.metadata.failureCategory when available. sync.uncertainWrite=true means the latest attempt hit the D1 write-timeout / finalize-rejection path, so the endpoint may be serving the last consistent snapshot or fallback while the attempted write remains ambiguous until the next clean run.

displayUrl and evidenceUrls are intentionally different:

• displayUrl is the curated reserve-card destination
• evidenceUrls are adapter-emitted URLs tied to the authoritative live snapshot metadata
• some live feeds expose only displayUrl, while others expose both

When present, displayBadge has:

When present, provenance has:

Response (404): unknown or non-canonical IDs, known active coins without live reserve support, and live-enabled coins with no resolved reserve result return { "error": "Not found" }.

GET /api/stablecoin-charts

Aggregate historical supply chart data across the live homepage market-cap universe, broken down by peg type. The hourly stablecoin-charts cache still starts from DefiLlama's aggregate chart history, but the worker now reconciles structurally supplemental tracked assets (for example wrapper NAV tokens and commodity tokens that are not present in DefiLlama's aggregate chart feed) from D1 supply_history before publishing the cache. At read time the handler also appends or replaces the latest point with a live snapshot derived from the current stablecoins cache so the endpoint's trailing point matches the homepage KPI card. sync-stablecoin-charts is triggered every 30 minutes, but a stablecoin-charts:last-write cooldown caps successful refreshes at once per hour; /api/health treats the cache as healthy for up to 1 hour.

Cache: standard — X-Data-Age and Warning headers included. This array response gets freshness headers only; it does not receive a response-body _meta envelope.

Response: A top-level array.

[
  {
    "date": 1511913600,
    "totalCirculatingUSD": {
      "peggedUSD": 110105,
      "peggedEUR": 14967600
    }
  }
]

GET /api/blacklist

Freeze, blacklist, block/unblock, account-pause, and token-destruction events for symbols in the shared BLACKLIST_STABLECOINS set. EURC mirror-zero rows are preserved with suppression metadata and excluded from public aggregates. Data is sourced from on-chain logs via Etherscan, Tron, and EVM RPCs.

Cache: realtime

Freshness note: X-Data-Age / Warning track the latest successful 6-hourly sync-blacklist writer timestamp. Public freshness stays fresh through that 6-hour budget and only degrades once the scheduled blacklist sync is actually late.

Query parameters

Response

{
  "events": [BlacklistEvent, ...],
  "total": 13422,
  "methodology": {
    "version": "3.99",
    "versionLabel": "v3.99",
    "currentVersion": "3.993",
    "currentVersionLabel": "v3.993",
    "changelogPath": "/methodology/blacklist-tracker-changelog/",
    "asOf": 1776729600,
    "isCurrent": false
  }
}

BlacklistEvent

methodology

GET /api/blacklist-summary

Server-side aggregates for the Blacklist Tracker overview cards, chart, and filter options. This lets the frontend render summary state without hydrating the full blacklist history first.

stats.destroyedTotal remains an event-history total. stats.activeAddressCount, stats.activeFrozenTotal, and stats.activeAmountGapCount are legacy wire-compatible fields for Pharos' local net-active blacklist state machine. stats.trackedFrozenTotal is the persistent freeze-ledger total sourced from blacklist_current_balances, including reconciled historical bootstrap rows where later seizures or unblacklists would otherwise hide the frozen amount. New consumers should prefer trackedAddressCount, trackedFrozenTotal, and trackedAmountGapCount for public freeze-ledger exposure, and use the active fields only when they specifically need the current local net-frozen state. These current-balance totals are last-known successful snapshots, not a live guarantee; provider refresh failures preserve the last successful amount and should be interpreted through freshness, status, and provenance metadata when present. New snapshot rows are contract/config-scoped; older rows can still fall back to the legacy symbol/chain/address identity until remediated. stats.recentCount covers the last 30 days, while stats.recentCount24h is the last-24-hours subset used by chrome-level monitoring surfaces. The chart now uses that same freeze ledger and attributes each tracked balance back to its latest recorded blacklist quarter, so the quarterly buckets explain the trackedFrozenTotal headline rather than raw event-time intake.

The four perCoin* maps power the per-coin "Blacklist Activity" block on stablecoin detail pages. perCoinFrozenAddressCount counts addresses whose latest event is blacklist (net-frozen). perCoinFrozenTotal sums last-known successful blacklist_current_balances.balance_usd snapshots per coin. perCoinDestroyedTotal sums amount_usd_at_event over destroy events per coin. perCoinQuarterlyEventTypes contains each coin's quarterly breakdown of event-type counts, zero-filled between the coin's first and last event quarters so bars render contiguously. All per-coin aggregations exclude rows where suppression_reason is set (e.g. EURC mirror zero-balance entries).

Cache: realtime

Freshness note: Shares the same 6-hourly freshness headers as GET /api/blacklist, keyed to the latest successful sync-blacklist write rather than the request time of the summary endpoint itself.

Response

{
  "stats": {
    "usdcBlacklisted": 1204,
    "usdtBlacklisted": 3881,
    "goldBlacklisted": 19,
    "frozenAddresses": 5071,
    "destroyedTotal": 158938221.19,
    "activeAddressCount": 5071,
    "activeFrozenTotal": 2120456789.42,
    "activeAmountGapCount": 17,
    "trackedAddressCount": 9466,
    "trackedFrozenTotal": 3235360796.7,
    "trackedAmountGapCount": 0,
    "recentCount": 42,
    "recentCount24h": 3,
    "recoverableGapCount": 17,
    "perCoinBlacklistCounts": { "USDC": 1204, "USDT": 3881 },
    "perCoinTotalEvents": { "USDC": 1210, "USDT": 3945 },
    "perCoinFrozenAddressCount": { "USDC": 1151, "USDT": 3794 },
    "perCoinFrozenTotal": { "USDC": 143000000, "USDT": 1800000000 },
    "perCoinDestroyedTotal": { "USDC": 0, "USDT": 158900000 },
    "perCoinQuarterlyEventTypes": {
      "USDC": [{ "quarter": "Q1 '26", "blacklist": 42, "unblacklist": 0, "destroy": 1 }]
    }
  },
  "chart": [{ "quarter": "Q1 '24", "USDT": 1200000, "USDC": 850000, "PAXG": 0, "XAUT": 0, "total": 2050000 }],
  "chains": [
    { "id": "ethereum", "name": "Ethereum" },
    { "id": "tron", "name": "Tron" }
  ],
  "coverage": {
    "supported": [
      {
        "symbol": "USDT",
        "stablecoinId": "usdt-tether",
        "chainId": "ethereum",
        "chainName": "Ethereum",
        "contractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "configKey": "ethereum-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "providerSource": "evm-logs",
        "eventFamilies": ["USDT legacy"],
        "eventTypes": ["blacklist", "unblacklist", "destroy"]
      }
    ],
    "unsupportedDeferred": [
      { "symbol": "TUSD", "chainId": "bsc", "reason": "deferred_contract_creation_verification" }
    ],
    "counts": {
      "supportedConfigs": 71,
      "unsupportedDeferredConfigs": 10,
      "bySymbol": { "USDT": 8 },
      "byChain": { "ethereum": 35 },
      "byProviderSource": { "evm-logs": 70, "trongrid": 1 }
    }
  },
  "freezeLedgerMeta": {
    "totalRows": 9466,
    "scopedRows": 240,
    "legacyRows": 9226,
    "oldestObservedAt": 1710000000,
    "newestObservedAt": 1776729600,
    "oldestAgeSec": 66600000,
    "newestAgeSec": 1200,
    "statusDistribution": { "resolved": 9466 },
    "sourceDistribution": { "current_balance": 240, "bootstrap_kyc_rip": 9226 },
    "freshnessDistribution": { "fresh": 9450, "degraded": 10, "stale": 6 },
    "currentFreshnessDistribution": { "fresh": 240, "degraded": 0, "stale": 0 },
    "providerFailedCount": 0,
    "lastErrorClassDistribution": {},
    "sourceCategoryCounts": { "bootstrap": 9226, "current": 240, "destroy": 0, "other": 0 },
    "gaps": {
      "tracked": 0,
      "recoverable": 17,
      "unrecoverable": 0,
      "recentRecoverable": 0,
      "neverAttempted": 0,
      "repeatedFailures": 0,
      "oldestRecoverableAgeSec": null,
      "amountStatusDistribution": { "resolved": 13405, "recoverable_pending": 17 },
      "amountSourceDistribution": { "historical_balance": 9000, "event": 4405, "unavailable": 17 }
    }
  },
  "dataQuality": {
    "status": "ok",
    "warnings": [],
    "amountGaps": {
      "totalEvents": 13422,
      "recoverable": 17,
      "unrecoverable": 0,
      "recentRecoverable": 0,
      "missingRatio": 0.0013,
      "recentWindowSec": 86400
    },
    "freezeLedger": {
      "providerFailedCount": 0,
      "staleSnapshotCount": 0,
      "trackedGapCount": 0,
      "scopedRows": 240,
      "legacyRows": 9226
    },
    "coverage": { "supportedConfigs": 71, "unsupportedDeferredConfigs": 10 }
  },
  "totalEvents": 13422,
  "methodology": {
    "version": "3.993",
    "versionLabel": "v3.993",
    "currentVersion": "3.993",
    "currentVersionLabel": "v3.993",
    "changelogPath": "/methodology/blacklist-tracker-changelog/",
    "asOf": 1776729600,
    "isCurrent": true
  }
}

coverage is the machine-readable tracker coverage inventory. supported entries are contract/config-level rows; each row includes the required tracked fields symbol, stablecoinId, chainId, chainName, contractAddress, configKey, providerSource, eventFamilies, and eventTypes. unsupportedDeferred identifies known deferred or explicitly de-scoped deployments from the runtime manifest and the reason they are not live; current examples use chainId values from the same shared chain registry as event rows. freezeLedgerMeta describes the last-known snapshot ledger used by trackedFrozenTotal, including scoped-vs-legacy row counts, observed-age bounds, source/status distributions, provider failures, and amount-gap distributions. freshnessDistribution covers every historical ledger row; currentFreshnessDistribution isolates rows produced by the current-balance provider when present and is what current API versions use for dataQuality.freezeLedger.staleSnapshotCount. dataQuality.status summarizes those coverage, gap, and current-provider snapshot signals into ok, degraded, or stale; clients should display or alert on warnings rather than inferring quality from null amount fields alone.

GET /api/depeg-events

Peg deviation events (≥ 100 bps for USD-pegged, ≥ 150 bps for non-USD pegs). Events are detected every 15 minutes by the cron.

Cache: realtime

Query parameters

Response

{
  "events": [DepegEvent, ...],
  "pending": [DepegPendingIncident, ...],
  "total": 4080,
  "totalExact": true,
  "nextCursor": "eyJ2IjoxLCJ2YWx1ZXMiOlsxNzcyNjA2NDAwLDQwODBdfQ",
  "methodology": {
    "version": "6.0",
    "versionLabel": "v6.0",
    "currentVersion": "6.0",
    "currentVersionLabel": "v6.0",
    "changelogPath": "/methodology/depeg-changelog/",
    "asOf": 1772606400,
    "isCurrent": true
  }
}

Results are ordered by startedAt DESC, id DESC. Prefer cursor/nextCursor for deep pagination; offset pagination is retained for shallow compatibility only.

Results are ordered by startedAt descending (most recent first).

DepegEvent

DepegPendingIncident — returned only when includePending=true

methodology

GET /api/depeg-resolver

Cache-backed Depeg Duration Resolver readouts for active/current confirmed depeg incidents. DDRv2 emits one row per canonical incident projection, keyed by incidentKey, and separates live facts from the official public lock outcome.

Cache: standard — X-Data-Age and Warning headers included. Freshness threshold: 900 s. Missing or invalid snapshots return 200 with _meta.degraded=true and rows: []; stale snapshots mark _meta.degraded=true, include the read overlay when available, and keep pre-publication rows free of verdict/duration details.

Row states

Response

{
  "_meta": {
    "schemaVersion": 2,
    "dataAsOf": 1779700000,
    "modelAsOf": 1779700000,
    "computedAt": 1779700000,
    "expiresAt": 1779701800,
    "snapshotToken": "ddrpub_...",
    "snapshotGeneration": 2,
    "publicPredictionIds": [101, 102],
    "publicPredictionRowHashes": { "101": "..." },
    "basePayloadHash": "...",
    "readOverlay": {
      "degradedLockDeferralIncidentKeys": [],
      "closedPendingReviewIncidentKeys": [],
      "suppressedIncidentKeys": []
    },
    "degraded": false,
    "degradedReason": null,
    "publicWarning": "Probabilistic estimate from Pharos historical data. Not investment advice or a credit rating.",
    "resolutionRubricVersion": "resolution-rubric-v1",
    "durationModelVersion": "duration-landmark-v1",
    "incidentGroupingVersion": "incident-group-v1",
    "supportRulesVersion": "support-rules-v1",
    "lineage": { "eventCount": 34129, "incidentCount": 1820, "coinCount": 142, "quarantinedCoins": 7 }
  },
  "rows": [DdrV2ResponseRow, ...],
  "methodology": { "version": "2.0", "versionLabel": "v2.0", "changelogPath": "/methodology/depeg-resolver-changelog/" }
}

DdrV2ResponseRow.kind is one of pending, prediction, no_call, or invalidated_prediction. prediction.state carries the public state above. Prediction rows include frozen.resolution and frozen.duration; no-call rows include noCall.missingReasons; invalidated rows include originalOutcome, latestErratum, and errata history. All rows include a live overlay with current event age, peak/current deviation, event state, freshness, and degraded reason.

GET /api/depeg-resolver-review

Cache-backed Depeg Duration Resolver Reviewer snapshot. DDRR v2 reviews frozen public predictions and no-calls that reached first publication, then reports the full incident-scoped policy universe so missing predictions are visible coverage debt rather than silently excluded.

Cache: standard — X-Data-Age and Warning headers included. Freshness threshold: 900 s. Missing or invalid snapshots return 200 with _meta.degraded=true, an empty summary, and rows: []; stale snapshots keep review rows but set _meta.degraded=true and degradedReason="stale-cache".

Headline fields

Response

{
  "_meta": {
    "computedAt": 1779700000,
    "expiresAt": 1779701800,
    "degraded": false,
    "degradedReason": null,
    "reviewerVersion": "ddr-reviewer-v2",
    "assessedEventCount": 12,
    "reviewedEventCount": 12,
    "pendingEventCount": 8,
    "durationScoredCount": 6,
    "verdictScoredCount": 10,
    "methodologyVersions": ["2.0"]
  },
  "summary": {
    "headlineScope": "current_policy",
    "headlineLabel": "DDR v2 public predictions",
    "headline": {
      "policyUniverseIncidentCount": 20,
      "predictionRatePct": 0.65,
      "finalizedCoveragePct": 0.9,
      "noCallRatePct": 0.1,
      "invalidatedPct": 0.05,
      "recoveryLikelihoodAccuracyPct": 0.7,
      "meanSignedDurationErrorSec": 3600,
      "meanAbsoluteDurationErrorSec": 7200,
      "horizonHitRates": [{ "horizon": "6h", "scored": 5, "hits": 3, "misses": 2, "hitRate": 0.6 }]
    },
    "byPredictionPolicy": []
  },
  "rows": [DdrrRow, ...],
  "methodology": { "version": "2.0", "versionLabel": "v2.0", "changelogPath": "/methodology/depeg-resolver-changelog/" }
}

DdrrRow.kind is one of prediction_review, no_call_review, coverage, or invalidated_prediction. Only prediction_review rows enter recovery-likelihood and duration accuracy. no_call_review rows are deliberate lock outcomes but unscored. coverage rows include states such as resolved_before_prediction, terminal_before_prediction, missed_lock_recovered, missed_lock_terminal, publication_retry_pending, and publication_failed. invalidated_prediction rows retain original exposure and attach errata history.

GET /api/peg-summary

Composite peg scores and aggregate statistics for tracked stablecoins. Scores are computed over a 4-year window from live depeg events, DEX prices, and current prices. The coins array can still include NAV / other non-peg rows with currentDeviationBps = null, while the summary counters only cover rows with a live peg-status deviation.

Cache: realtime

Response

{
  "coins": [PegSummaryCoin, ...],
  "summary": PegSummaryStats,
  "methodology": {
    "version": "6.0",
    "versionLabel": "v6.0",
    "currentVersion": "6.0",
    "currentVersionLabel": "v6.0",
    "changelogPath": "/methodology/depeg-changelog/",
    "asOf": 1772606400,
    "isCurrent": true
  }
}

PegSummaryCoin

DexPriceCheck

PegSummaryStats

methodology — same fields and semantics as /api/depeg-events

GET /api/usds-status

Sky/USDS protocol status — whether the freeze module is currently active.

Cache: standard — X-Data-Age and Warning headers included.

Response

{
  "freezeActive": false,
  "implementationAddress": "0x1923dfee706a8e78157416c29cbccfde7cdf4102",
  "lastChecked": 1771809338,
  "_meta": { "updatedAt": 1710500000, "ageSeconds": 42, "status": "fresh" }
}

GET /api/bluechip-ratings

Safety ratings from bluechip.org for covered stablecoins. Updated daily at 08:05 UTC.

Cache: slow — X-Data-Age and Warning headers included.

Response: Object keyed by Pharos stablecoin ID, plus top-level _meta freshness metadata.

{
  "usdt-tether": BluechipRating,
  "usdc-circle": BluechipRating,
  "_meta": { "updatedAt": 1710500000, "ageSeconds": 42, "status": "fresh" }
}

BluechipRating

BluechipSmidge — each field is string | null:

GET /api/dex-liquidity

DEX liquidity scores, pool breakdowns, source-confidence metadata, and on-chain DEX price data for all tracked stablecoins. Updated every 30 minutes. Trend data is only returned when a trusted historical baseline exists.

Cache: custom — public, s-maxage=300, max-age=300

Freshness note: In addition to stale-data warnings, this endpoint can also emit a Warning header when the latest sync-dex-liquidity run finished in degraded or error state and the API is serving the last successful dataset.

Response: Object keyed by Pharos stablecoin ID plus a __global__ aggregate sentinel row.

{
  "usdt-tether": DexLiquidityData,
  "usdc-circle": DexLiquidityData,
  "__global__": DexLiquidityData
}

DexLiquidityData

ScoreComponents

DexLiquidityPool

extra may include:

DexPriceSource

GET /api/dex-liquidity-history

Per-coin historical DEX liquidity snapshots. Snapshots are recorded daily (UTC midnight, first sync after day rollover). Baseline consumers should use coverageClass / coverageConfidence before treating a history point as trend-worthy.

Cache: slow — public, s-maxage=3600, max-age=300

Required query parameter

Optional query parameters

Response: Array sorted by date ascending.

[
  {
    "tvl": 1658000000,
    "volume24h": 1700000000,
    "score": 93,
    "date": 1771500000,
    "coverageClass": "mixed",
    "coverageConfidence": 0.85,
    "liquidityEvidenceClass": "partial_measured",
    "hasMeasuredLiquidityEvidence": true,
    "trendworthy": true,
    "methodologyVersion": "3.1"
  }
]

GET /api/supply-history

Per-coin circulating supply and price history. The snapshot-supply cron writes one snapshot per UTC day; it runs on the quarter-hourly trigger once the previous day's snapshot is at least 20 hours old, with an 08:00 UTC daily trigger as a safety-net fallback.

Cache: slow — public, s-maxage=3600, max-age=300

Freshness headers are emitted from the latest completed snapshot-supply run when available. Rows newer than the completed daily snapshot marker are hidden so a failed chunked write cannot expose a partial latest day.

Required query parameter

Optional query parameters

Response: Array sorted by date ascending.

[
  {
    "date": 1771500000,
    "circulatingUsd": 138000000000,
    "price": 1.0001
  }
]

GET /api/daily-digest

Latest AI-generated market summary, produced daily at 08:05 UTC via the Claude API.

Cache: standard. When a digest exists, the response includes X-Data-Age and Warning freshness headers keyed to a 24 h endpoint budget. The bootstrap { "digest": null } response carries only Cache-Control.

Response

{
  "digest": "USDC absorbed $812M of the market's $1.36B weekly inflow…",
  "editionNumber": 214,
  "riskSignal": {
    "kind": "depeg",
    "symbol": "PMUSD",
    "bps": -5284,
    "mcapUsd": 65610000,
    "severity": "critical",
    "activeCount": 7,
    "date": null
  },
  "riskTape": [{ "id": "risk-tape:depegs", "label": "Depegs", "value": "PMUSD 5284bps", "tone": "critical" }],
  "nextTriggers": [
    {
      "id": "trigger:depeg:pmusd",
      "label": "PMUSD depeg widening",
      "metric": "depeg-bps",
      "comparator": "abs-gte",
      "thresholdLabel": "5500 bps off peg",
      "thresholdValue": 5500,
      "symbol": "PMUSD",
      "rationale": "A wider deviation raises severity.",
      "detail": "If PMUSD reaches 5500 bps off peg, severity rises."
    }
  ]
}

If no digest exists yet, the endpoint returns only { "digest": null }.

GET /api/digest-archive

Newest-first archive of up to 365 daily and weekly digests.

Cache: standard

Response

{
  "digests": [
    {
      "digestText": "USDC absorbed $812M…",
      "digestTitle": "USDC Eats the Week",
      "digestExtended": "Longer editorial…",
      "generatedAt": 1771839719,
      "psiScore": 81.1,
      "psiBand": "STEADY",
      "totalMcapUsd": 234500000000,
      "riskSignal": {
        "kind": "depeg",
        "symbol": "PMUSD",
        "bps": -5284,
        "mcapUsd": 65610000,
        "severity": "critical",
        "activeCount": 7,
        "date": "2026-05-05"
      },
      "riskTape": [{ "id": "risk-tape:depegs", "label": "Depegs", "value": "PMUSD 5284bps", "tone": "critical" }],
      "nextTriggers": [
        {
          "id": "trigger:depeg:pmusd",
          "label": "PMUSD depeg widening",
          "metric": "depeg-bps",
          "comparator": "abs-gte",
          "thresholdLabel": "5500 bps off peg",
          "thresholdValue": 5500,
          "symbol": "PMUSD",
          "rationale": "A wider deviation raises severity.",
          "detail": "If PMUSD reaches 5500 bps off peg, severity rises."
        }
      ],
      "digestType": "daily",
      "editionNumber": 214
    }
  ]
}

Each element uses digestText (note: differs from the singular /api/daily-digest which uses digest).

DigestRiskSignal

Digest intelligence fields

GET /api/digest-snapshot

Contextual data snapshot for a specific digest date — includes the digest's input data, active depeg events, and blacklist events for that day. Used by SSG builds for individual digest pages.

Cache: archive

Required query parameter

Response

{
  "date": "2026-02-27",
  "inputData": { "totalMcapUsd": 230000000000, "mcap7dDelta": 0.012, ... },
  "prevInputData": { ... },
  "depegEvents": [{ "stablecoinId": "usdt-tether", "symbol": "USDT", "direction": "below", "peakDeviationBps": -150, ... }],
  "blacklistEvents": [{ "stablecoin": "USDT", "chainName": "Ethereum", "eventType": "blacklist", ... }]
}

Error responses: 400 for missing/invalid date, 404 if no digest exists for that date.

GET /api/snapshots/index

Lists immutable public daily dataset snapshots written by the snapshot-public-dataset cron. Each row points to a dated payload that can be fetched through GET /api/snapshots/:date.json.

Cache: archive

Response

{
  "snapshots": [
    {
      "snapshotDate": "2026-05-17",
      "methodologyVersions": { "safetyScore": "5.9", "psi": "3.0" },
      "contentHash": "sha256-hex",
      "byteSize": 1234567,
      "createdAt": 1778976000
    }
  ]
}

GET /api/snapshots/:date.json

Returns the full immutable public dataset snapshot for a UTC date. The worker reads the gzipped payload from D1, decompresses it, and returns the original JSON envelope.

Cache: immutable-snapshot

Path parameters

Response

PublicSnapshotEnvelope {
  snapshotDate,
  generatedAt,
  methodologyVersions,
  stablecoinRows,
  fxFallbackRates,
  reportCards,
  psi,
  dewsRows,
  liquidityRows
}

Headers: ETag: "<contentHash>".

Error responses: 400 for invalid date format, 404 if no snapshot exists for that date, 500 if the stored snapshot payload is unreadable or corrupted.

GET /api/snapshot/:date/stablecoin/:id

Returns a per-stablecoin projection from a dated public dataset snapshot. The projection includes the stablecoin row plus the matching report-card, DEWS, and liquidity rows when those datasets were present in the snapshot.

Cache: immutable-snapshot

Path parameters

Response

{
  snapshotDate: "2026-05-17",
  stablecoinId: "usdt-tether",
  generatedAt: 1778976000,
  methodologyVersions: { safetyScore: "5.9", psi: "3.0" },
  stablecoin: { id: "usdt-tether", symbol: "USDT" },
  scores: {
    reportCard,
    psi,
    dews,
    liquidity
  }
}

Headers: ETag: "<contentHash>-<stablecoinId>".

Error responses: 400 for invalid date format, 404 if no snapshot exists or the stablecoin is absent from that snapshot, 500 if the stored snapshot payload is unreadable or corrupted.

GET /api/health

Worker health check. Reports cache freshness, blacklist integrity, mint/burn freshness, and circuit-breaker states. Not served from Cloudflare edge cache (no-store).

Cache freshness in /api/health separates producer cadence, endpoint freshness, and availability impact. caches[*].maxAge is the availability budget used by /api/health, /api/status, and the public/admin status pages. endpointMaxAge is the endpoint freshness basis used for _meta, X-Data-Age, and the generic freshness warning runway when it differs. producerIntervalSec is the expected writer cadence.

Authentication: exempt

Response

{
  "status": "healthy",
  "timestamp": 1771856453,
  "warnings": [],
  "caches": {
    "stablecoins": {
      "ageSeconds": 323,
      "maxAge": 600,
      "healthy": true,
      "producerJob": "sync-stablecoins",
      "producerIntervalSec": 900,
      "endpointMaxAge": 600,
      "availabilityMaxAge": 600
    },
    "stablecoin-charts": {
      "ageSeconds": 323,
      "maxAge": 3600,
      "healthy": true,
      "producerJob": "sync-stablecoin-charts",
      "producerIntervalSec": 3600,
      "endpointMaxAge": 3600,
      "availabilityMaxAge": 3600
    },
    "usds-status": {
      "ageSeconds": 47118,
      "maxAge": 86400,
      "healthy": true,
      "producerJob": "sync-usds-status",
      "producerIntervalSec": 86400,
      "endpointMaxAge": 86400,
      "availabilityMaxAge": 86400
    },
    "fx-rates": {
      "ageSeconds": 1223,
      "maxAge": 1800,
      "healthy": true,
      "producerJob": "sync-fx-rates",
      "producerIntervalSec": 1800,
      "endpointMaxAge": 1800,
      "availabilityMaxAge": 1800,
      "mode": "live",
      "sourceUpdatedAt": 1771855200,
      "sourceAgeSeconds": 323,
      "sourceStatus": "fresh",
      "warning": null,
      "consecutiveFallbackRuns": 0
    },
    "bluechip-ratings": {
      "ageSeconds": 22815,
      "maxAge": 86400,
      "healthy": true,
      "producerJob": "sync-bluechip",
      "producerIntervalSec": 86400,
      "endpointMaxAge": 43200,
      "availabilityMaxAge": 86400
    },
    "dex-liquidity": {
      "ageSeconds": 290,
      "maxAge": 43200,
      "healthy": true,
      "producerJob": "sync-dex-liquidity",
      "producerIntervalSec": 1800,
      "endpointMaxAge": 3600,
      "availabilityMaxAge": 43200
    },
    "yield-data": {
      "ageSeconds": 820,
      "maxAge": 3600,
      "healthy": true,
      "producerJob": "sync-yield-data",
      "producerIntervalSec": 3600,
      "endpointMaxAge": 3600,
      "availabilityMaxAge": 3600
    },
    "dews": {
      "ageSeconds": 240,
      "maxAge": 1800,
      "healthy": true,
      "producerJob": "compute-dews",
      "producerIntervalSec": 1800,
      "endpointMaxAge": 1800,
      "availabilityMaxAge": 1800
    }
  },
  "blacklist": {
    "totalEvents": 13422,
    "missingAmounts": 0,
    "recentMissingAmounts": 0,
    "recentWindowSec": 86400,
    "missingRatio": 0
  },
  "mintBurn": {
    "totalEvents": null,
    "latestEventTs": null,
    "latestHourlyTs": null,
    "freshnessAgeSec": null,
    "majorStaleCount": 0,
    "staleMajorSymbols": [],
    "sync": {
      "lastSuccessfulSyncAt": 1771856400,
      "freshnessStatus": "fresh",
      "warning": null,
      "criticalLaneHealthy": true
    }
  },
  "circuits": {
    "defillama-stablecoins": { "state": "closed", "consecutiveFailures": 0, "lastSuccessAt": 1772190029 },
    "coingecko-prices": { "state": "closed", "consecutiveFailures": 0, "lastSuccessAt": 1772190030 }
  },
  "telegramSummary": {
    "totalChats": 142,
    "pendingDeliveries": 0,
    "lastDispatchAt": 1771856400,
    "lastDispatchStatus": "ok",
    "safetyAlertSourceState": "ok",
    "safetyAlertSourceAgeSeconds": 120,
    "safetyAlertsSuppressed": false,
    "safetyAlertSourceGeneration": "safety-7.12-alert-source-v1"
  }
}

CacheStatus

The /status/ page consumes the richer blacklist fields directly so it can distinguish long-tail historical cleanup from fresh incoming amount gaps. Blacklist amount-gap severity is intentionally tolerant of isolated parser/provider misses: data-quality degrades when the missing-amount ratio reaches 1% or when at least 5 recent events are missing amounts, and becomes stale at 2% or at 25 recent missing events.

dex-liquidity, yield-data, and dews compute freshness from producer-owned cache sentinels first (freshness:dex-liquidity, freshness:yield-data, freshness:dews). A sentinel is trusted only when its JSON payload has updatedAt, the expected producer source, and publishStatus: "ok"; optional rowsWritten and coverageRatio fields may also be present. If the sentinel is missing or fails validation, the worker falls back to the legacy table query. If that freshness diagnostic also fails, it can fall back again to the latest successful producer cron timestamp. Invalid sentinels surface freshnessSource, sentinelValidationReason, and a cache warning instead of making the sentinel row authoritative.

Overall status logic:

• healthy — every cache impact is healthy, the public mint/burn lane is healthy, fewer than 3 public-impact circuit groups are open, and the health subqueries all resolved cleanly
• degraded — any cache impact is degraded (including FX cached-fallback or source-cadence lag), any of the blacklist/mint-burn/circuit health subqueries failed, the public mint/burn lane is warning-only, or 3+ public-impact circuit groups are open
• stale — any cache impact is stale, or the public mint/burn lane is stale versus its critical-lane cadence

/api/health still emits every circuit record under circuits, including dynamic per-coin live-reserves:* scopes, but those reserve-specific breakers do not change the top-level public status on their own; reserve sync health is evaluated on the dedicated reserve/data-quality lanes instead.

Blacklist ratio fields are still emitted here for the public surface, but threshold-based blacklist severity lives under /api/status data-quality; /api/health only escalates its top-level status when the blacklist health loader itself fails.

GET /api/public-status-history

Public transition history for the read-only /status/ page. Returns the current public status plus recent state transitions within a requested time window. Not edge-cached beyond the standard 60-second response cache.

Query parameters

Response

{
  "timestamp": 1771856453,
  "currentStatus": "healthy",
  "lastChangedAt": 1771770000,
  "transitions": [
    {
      "id": 418,
      "from": "degraded",
      "to": "healthy",
      "transitionType": "recover",
      "reason": "raw-healthy-recovery-threshold",
      "at": 1771770000
    }
  ]
}

This endpoint powers two separate public /status/ views: the hero Status runway always uses window=30d, while the transition table owns its own user-selected 24h / 7d / 30d filter.

Browser consumers on pharos.watch and ops.pharos.watch should use same-origin /_site-data/public-status-history, which proxies onto the internal website lane instead of calling the external API host directly.

Public-impact filtering (2026-04-13): The endpoint filters the admin state-machine transitions down to incidents opened by at least one public-facing impact code (cache_ratio_*, cache_freshness_query_failed, cache_warning, fx_source_*, fx_cached_fallback, mint_burn_public_*, mint_burn_health_query_failed, open_circuit_groups, circuit_query_failed, cron_error_runs, multiple_unhealthy_crons, unhealthy_crons_present, db_unhealthy). Admin-only data-quality causes (missing_prices_*, blacklist_gaps_*, reserve_sync_*, onchain_*, watch_*) are excluded, and info-severity causes cannot open a public incident. Once a public-impact incident is retained, the endpoint also retains the recovery path needed to return that incident to healthy, even when those recovery rows only carry info-level causes. This ensures the public /status/ hero (driven by /api/health) and the uptime bar / transition timeline (driven by this endpoint) always agree. The unfiltered admin view is still available via the admin /api/status endpoint.

GET /api/telegram-pulse

Lightweight Telegram adoption metrics for the public PharosWatchBot page. The canonical page route is /pharoswatchbot/; the legacy /telegram alias redirects there. Returns aggregate watcher/subscription counts, explicit vs preset-implied alert follows, the most subscribed coin symbols, and snapshot-backed watcher history when available. When active chats predate the first daily snapshot row, the history is prefixed with live active-chat cohort points so the public lifecycle chart shows the full available bot lifecycle. The common path serves the five-minute telegram:pulse:snapshot cache written by the Telegram cron sidecar; live aggregation is a stale/missing snapshot fallback.

Direct https://api.pharos.watch/api/telegram-pulse access is protected and requires X-API-Key. Public browser access on pharos.watch and ops.pharos.watch uses same-origin /_site-data/telegram-pulse, which proxies to the internal site-api lane with X-Pharos-Site-Proxy-Secret.

Cache: public, max-age=300, s-maxage=300

Response

{
  "activeWatchers": 1842,
  "coinSubscriptions": 5621,
  "explicitCoinSubscriptions": 5000,
  "presetImpliedCoinSubscriptions": 621,
  "activePresetFollowers": 81,
  "newWatchersToday": 12,
  "churnedWatchersToday": 3,
  "reactivatedWatchersToday": 5,
  "historySource": "snapshot",
  "pendingDeliveries": 3,
  "quietHoursEnabledChats": 42,
  "miniAppSessionsToday": 88,
  "miniAppMutationsToday": 31,
  "miniAppDeniedToday": 2,
  "miniAppReplayClaimsToday": 1,
  "miniAppOpenToFirstMutationP50Sec": null,
  "alertTypeChats": {
    "dews": 1701,
    "depeg": 1644,
    "safety": 1512,
    "launch": 1208,
    "allTypes": 1191
  },
  "currentSnapshotAt": 1771856400,
  "lifecycleHistoryUpdatedAt": 1775088900,
  "lifecycleHistoryEverySeconds": 900,
  "quality": {
    "status": "complete",
    "unavailableFields": []
  },
  "privacy": {
    "exactActiveWatchers": true,
    "lowCardinalityThreshold": 5,
    "suppressedFields": []
  },
  "updatedAt": 1771856400,
  "updatedEverySeconds": 300,
  "topCoins": ["USDT", "USDC", "USDe"],
  "watcherHistory": [
    {
      "date": "2026-04-01",
      "timestamp": 1775001600000,
      "snapshotAt": 1775002500,
      "newWatchers": 12,
      "activeWatchers": 12
    },
    {
      "date": "2026-04-02",
      "timestamp": 1775088000000,
      "newWatchers": 9,
      "activeWatchers": 21,
      "churnedWatchers": 1,
      "reactivatedWatchers": 2
    }
  ]
}

Low-cardinality privacy rule: nonzero values below privacy.lowCardinalityThreshold are hidden for public daily deltas, pending deliveries, quiet-hours chats, Mini App session/mutation adoption counts, and lifecycle-history delta fields. Consumers should treat null as "not publicly shown", not as zero. Mini App denied/replay counters are an explicit exception because they are abuse/health counters; they remain visible when available and are not listed in privacy.suppressedFields.

GET /api/stability-index

Latest Pharos Stability Index (PSI) sample plus daily history. The PSI is a composite ecosystem health score (0–100) computed from active depeg severity, affected-market breadth, DEWS stress breadth, and 7-day ecosystem trend across the PSI-eligible universe (tracked coins plus shadow assets used for historical continuity). If a dependency failure prevents a safe fresh sample, the endpoint continues serving the last healthy stored PSI sample instead of publishing a degraded substitute.

Cache: standard — X-Data-Age and Warning headers included after at least one PSI sample/history row exists. Before bootstrap, the empty response carries Cache-Control only and contains { current: null, history: [], methodology: ... } without malformedRows.

Error responses: 503 when the canonical current PSI components or input_snapshot payload is missing or malformed.

Optional query parameters

Response

{
  "current": {
    "score": 81.1,
    "band": "STEADY",
    "components": { "severity": 4.59, "breadth": 15, "stressBreadth": 1.8, "trend": 0.65 },
    "computedAt": 1771977600,
    "methodologyVersion": "3.2"
  },
  "history": [{ "date": 1771891200, "score": 81.0, "band": "STEADY", "methodologyVersion": "2.1" }],
  "methodology": {
    "version": "3.2",
    "versionLabel": "v3.2",
    "currentVersion": "3.2",
    "currentVersionLabel": "v3.2",
    "changelogPath": "/methodology/stability-index-changelog/",
    "asOf": 1771977600,
    "isCurrent": true
  }
}

GET /api/og/* / HEAD /api/og/*

Dynamic Open Graph PNG images used by share buttons and page metadata.

Authentication: exempt

Supported routes

• /api/og/stablecoin/:id
• /api/og/safety-scores
• /api/og/depeg
• /api/og/stability-index

Content-Type: image/png

Cache: public, max-age=900, s-maxage=900

Error cases

• 404 with text/plain for unknown coin IDs inside /api/og/stablecoin/:id; unknown OG route patterns return the standard JSON { "error": "Unknown OG route" }
• 503 when required cached data is not yet available
• 400 for malformed URI encoding in /api/og/stablecoin/:id
• 500 with text/plain body when OG image rendering fails

/api/og/stablecoin/:id accepts tracked public stablecoin IDs only. The renderer assembles each card from cached stablecoin, DEWS, PSI, report-card, depeg, liquidity, and mint/burn data on the worker.

GET /api/report-cards

Stablecoin risk grade cards with dimension-level scores. Output includes 5 dimensions; overall score is the weighted base (exit-liquidity/resilience/decentralization/dependency) plus peg-multiplier adjustment.

Cache: standard

Response

{
  "cards": [ReportCard, ...],
  "dependencyGraph": {
    "edges": [{ "from": "usdc-circle", "to": "usde-ethena", "weight": 0.9, "type": "collateral" }, ...]
  },
  "methodology": {
    "version": "7.13",
    "weights": { "pegStability": 0, "liquidity": 0.30, "resilience": 0.20, "decentralization": 0.15, "dependencyRisk": 0.25 },
    "pegMultiplierExponent": 0.4,
    "activeDepegSeveritySource": "open-event-peak",
    "activeDepegCaps": {
      "d": { "thresholdBps": 1000, "score": 49 },
      "f": { "thresholdBps": 2500, "score": 39 }
    },
    "thresholds": [{ "grade": "A+", "min": 87 }, { "grade": "A", "min": 83 }, ...]
  },
  "liquidityStale": false,
  "redemptionStale": false,
  "inputFreshness": {
    "dexLiquidity": { "updatedAt": 1771977600, "ageSeconds": 120, "stale": false },
    "redemptionBackstops": { "updatedAt": 1771977600, "ageSeconds": 300, "stale": false }
  },
  "collateralDriftCoins": [{ "id": "jupusd-jupiter", "liveScore": 80, "curatedScore": 65, "delta": 15 }],
  "liveToFallbackCoins": ["usdaf-asymmetry"],
  "updatedAt": 1771977600
}

The Liquidity dimension now represents effectiveExitScore: the public DEX liquidity score remains the floor, while redeemable assets can receive uplift from redemptionBackstopScore when a meaningful direct exit path exists. Documented offchain issuer exits with eventual-only capacity can add only a DEX-gated primary-market bonus; they do not replace missing DEX liquidity. Last-known DEX liquidity remains usable even after its freshness runway, with staleness surfaced through liquidityStale and inputFreshness.dexLiquidity.stale. Low-confidence redemption routes stay visible but do not uplift the score, and materially stale redemption inputs are not blended. Report-card redemption inputs are treated as materially stale after more than twice the 4-hourly redemption sync cadence, so normal cron lag does not globally remove medium- or high-confidence redemption uplift.

When present, collateralDriftCoins lists live-reserve scoring deltas that exceed the reserve-drift threshold, and liveToFallbackCoins lists live-reserve-enabled assets whose report card used curated fallback reserves because no scoring-eligible live snapshot was available.

For peg handling, rawInputs.pegScore is the effective peg input used by report-card scoring. Most coins use their direct peg-summary value. Configured NAV wrappers can inherit peg stability from a referenced base stablecoin when the wrapper share price is not the right peg-tracking surface; pure NAV tokens without a configured reference remain null and keep neutral handling. rawInputs.activeDepegBps is the open active depeg event's absolute peak deviation used for final Safety Score caps; it is not the latest spot deviation.

GET /api/report-cards normally serves the full report-card payload from the private report-cards:snapshot cache envelope published by publish-report-card-cache. That envelope pins the expected cache generation and Safety Score methodology version; compute-on-read is used when the published snapshot is missing, malformed, generation-mismatched, or methodology-mismatched. The published envelope is also the preferred Safety Score source for yield hydration, while the smaller report_card_cache score map remains available for lightweight Chain Health/OG consumers.

Report-card generation treats the stablecoins cache and readable redemption-backstop table as hard dependencies. The stablecoins cache is read in published-contract mode, so malformed cached objects that fail StablecoinListResponseSchema validation fail closed instead of being partially filtered for scoring. DEX liquidity, bluechip ratings, live-reserve inputs, and materially stale redemption rows are soft dependencies: if one of those loaders is temporarily unavailable or stale beyond its scoring freshness runway, generation continues with a degraded snapshot instead of failing closed, with stale inputs suppressed from scoring.

dependencyGraph.edges: Pre-computed forward edges. from = upstream stablecoin ID, to = dependent stablecoin ID. weight and type carry the worker's canonical dependency metadata, so frontend graph consumers can use the snapshot directly instead of re-deriving edge semantics from static stablecoin metadata.

ReportCard

DependencyWeight: { id: string, weight: number, type?: DependencyType } — upstream stablecoin ID + fraction of collateral from that source (0–1), with optional dependency category. When total dependency weight is ≤ 1.0, the remainder represents non-stablecoin collateral; when declared dependency weight exceeds 1.0, dependency scoring normalizes by raw total and uses no self-backed remainder.

RawDimensionInputs

rawInputs.canBeBlacklisted is the canonical resolved blacklist status used by report-card-backed product surfaces. It can therefore differ from the raw StablecoinMeta.canBeBlacklisted override field, which only carries manual metadata and never stores computed "inherited" values. Product labels map the wire values to the four-status model: true -> Yes, "inherited" -> Upstream, "possible" -> Possible, and false -> No. Admin mint authority is reviewed separately in Mint Authority and is not a FreezeWatch status. "inherited" / Upstream can be produced by any reserve, backing, custody, parent-asset, or CEX/custody-rail exposure; it does not require a majority reserve weight.

rawInputs.collateralFromLive is true when score-grade live reserve data drove collateral scoring for the card.

Dimensions: pegStability, liquidity, resilience, decentralization, dependencyRisk

GET /api/redemption-backstops

Current redemption-backstop dataset for redeemable assets.

Cache: standard

Error responses: 503 when redemption_backstop has no rows yet, or when the current snapshot cannot be read cleanly.

Rows written by the current worker are grouped by a completed snapshot run manifest. The API serves the latest valid completed run when one exists, which prevents a partially written hourly sync from being treated as a fresh complete dataset. If the newest completed manifest is incomplete or its rows are unreadable, the reader tries recent earlier completed runs before returning 503. If no completed manifest exists but the manifest table has run records and the current table contains rows with a non-null snapshot_run_id, the reader returns 503 instead of treating those partial manifested rows as legacy data. Legacy rows without a completed run remain readable during bootstrap and migration fallback only when the current table has no manifested rows.

Response

{
  "coins": {
    "cusd-cap": {
      "stablecoinId": "cusd-cap",
      "score": 88,
      "effectiveExitScore": 56,
      "dexLiquidityScore": 29,
      "accessScore": 100,
      "settlementScore": 100,
      "executionCertaintyScore": 80,
      "capacityScore": 100,
      "outputAssetQualityScore": 80,
      "costScore": 40,
      "routeFamily": "basket-redeem",
      "accessModel": "permissionless-onchain",
      "settlementModel": "atomic",
      "executionModel": "deterministic-basket",
      "outputAssetType": "stable-basket",
      "provider": "supply-full-model",
      "immediateCapacityUsd": null,
      "immediateCapacityRatio": null,
      "sourceMode": "estimated",
      "resolutionState": "resolved",
      "routeStatus": "open",
      "routeStatusSource": "static-config",
      "holderEligibility": "any-holder",
      "capacityConfidence": "heuristic",
      "capacitySemantics": "eventual-only",
      "capacityKind": "documented-eventual",
      "freshnessKind": "reviewed-static",
      "sourceTimestamp": 1773350300,
      "sourceUrls": ["https://example.com/redemption-source"],
      "settlementDelaySec": 86400,
      "queueDepthUsd": 12000000,
      "dailyLimitUsd": 5000000,
      "minRedeemUsd": 100000,
      "liveHolderEligibility": "any-holder",
      "feeConfidence": "undisclosed-reviewed",
      "feeModelKind": "undisclosed-reviewed",
      "modelConfidence": "low",
      "feeBps": null,
      "queueEnabled": false,
      "updatedAt": 1773350400,
      "methodologyVersion": "4.06"
    }
  },
  "methodology": {
    "version": "4.06",
    "versionLabel": "v4.06",
    "currentVersion": "4.06",
    "currentVersionLabel": "v4.06",
    "changelogPath": "/methodology/#safety-scores-methodology",
    "asOf": 1773350400,
    "isCurrent": true,
    "componentWeights": {
      "access": 0.2,
      "settlement": 0.15,
      "executionCertainty": 0.15,
      "capacity": 0.25,
      "outputAssetQuality": 0.15,
      "cost": 0.1
    },
    "effectiveExitModel": {
      "model": "best-path",
      "diversificationFactor": 0.1,
      "modeledExitSize": {
        "supplyRatio": 0.05,
        "floorUsd": 100000,
        "capUsd": 25000000
      },
      "capacityFactor": {
        "formula": "min(1, currentExecutableCapacityUsd / modeledExitSizeUsd)",
        "missingCapacityBehavior": "unbounded"
      },
      "confidenceFactors": {
        "high": 1,
        "medium": 0.75,
        "low": 0.35
      },
      "diversificationPolicy": "Only independent issuer rails receive the secondary-path diversification bonus in v4 snapshots."
    },
    "routeFamilyCaps": {
      "queueRedeem": 70,
      "offchainIssuer": 65
    }
  },
  "updatedAt": 1773350400
}

score is the direct redemption-quality score.

effectiveExitScore is the raw best-path exit score written into the redemption snapshot when the route resolved cleanly and is not currently impaired. It reuses last-known DEX liquidity even when the DEX input is stale; the cron records that operational state through metadata.liquidityStale. In v4, redemption contribution is adjusted by capacityFactor = min(1, currentExecutableCapacityUsd / modeledExitSizeUsd) and by route confidence (high = 1, medium = 0.75, low = 0.35) before the best-path blend. modeledExitSizeUsd is min(max(supplyUsd × 0.05, 100000), 25000000). When both DEX liquidity and adjusted redemption exist, only independent issuer rails receive the 10% secondary-path diversification bonus. Report cards may still recompute liquidity from the same underlying redemption score with additional confidence, eligibility, and active-depeg gating, so this raw endpoint value can differ numerically from dimensions.liquidity.score.

methodology.version is attributed from the latest completed redemption snapshot run, falling back to the latest stored row for legacy snapshots. methodology.currentVersion remains the live code version when the API is serving an older snapshot that has not yet been recomputed.

sourceMode:

• dynamic = live reserve/protocol telemetry
• estimated = modelled from current supply and conservative route assumptions
• static = route remains configured, but current runtime inputs did not resolve a usable score

resolutionState:

• resolved = the route produced a usable score
• missing-cache = the stablecoins snapshot did not include the asset or its current supply
• missing-capacity = the route is configured, but the snapshot could not resolve enough capacity to score it
• failed = a route-specific resolver failed
• impaired = the route shape is known but current market or route-availability evidence contradicts broad par redemption

routeStatus / routeStatusSource describe current route availability separately from the static route shape. Normal rows use routeStatus: "open" and routeStatusSource: "static-config". A severe active depeg (>=2500 bps) can publish routeStatus: "degraded" and routeStatusSource: "market-implied" for static or non-live-direct routes; those impaired rows have score = null, effectiveExitScore = null, and modelConfidence = "low". holderEligibility describes the modeled holder cohort, such as any-holder, verified-customer, whitelisted-primary, pre-incident-holder, issuer-discretionary, or unknown.

For v4-compatible snapshots, route-status and capacity telemetry remain part of the four-hour sync-redemption-backstops snapshot. The worker does not fetch a separate real-time route-status feed during this sync; route status comes from live-reserve adapter metadata, static reviewed policy, and market-implied severe-depeg overlays.

Top-level fields:

RedemptionBackstopEntry highlights:

Response (503): { "error": "Data not yet available" } or { "error": "Redemption backstop snapshot unavailable" }

GET /api/safety-score-history

Per-coin Safety Score grade transition history (seed row + grade changes only). Rows are written by the daily snapshot-safety-grade-history cron and returned in ascending date order.

Cache: slow

Required query parameter

Optional query parameters

Response: Array sorted by date ascending.

[
  {
    "date": 1771977600,
    "grade": "B+",
    "score": 78,
    "prevGrade": "B",
    "prevScore": 74,
    "methodologyVersion": "5.5"
  }
]

GET /api/yield-rankings

Cache-backed yield rankings written by the sync-yield-data cron. The endpoint rehydrates safetyScore, safetyGrade, yieldToRisk, and pharosYieldScore from the cron-published report-card snapshot so Yield Intelligence stays aligned with /api/report-cards without rebuilding the full Safety Score envelope on every read. Compute-on-read is used only when the published snapshot is unavailable. Royco Dawn structured-tranche rows use the attached underlying asset's report-card snapshot as input, then expose an opportunity-level tranche Safety Score in the yield row. PYS v8 is benchmark-aware and source-risk-aware: it starts from cached APY inputs, adds a weighted slice of the row's benchmark spread, divides by the nested sourceRisk.sourceRiskPenalty populated from measured source evidence, then applies the current Safety Score and volatility multiplier. Missing source-risk evidence is neutral. The response also includes source-selection provenance, the default USD benchmark (riskFreeRate), and the structured benchmark registry used for row-level excess-yield selection. If a ranking row has no matching live report-card snapshot, the API now retains the row and falls back to DEFAULT_SAFETY_SCORE (40) and grade NR instead of dropping coverage.

Cache: standard — X-Data-Age and Warning headers included. Freshness threshold: 3600 s (1 hour, aligned to the hourly sync-yield-data publisher).

Error responses: 503 when the cached rankings payload is missing, unparseable JSON, or parseable JSON that fails the YieldRankingsResponseSchema cache-read validation. Schema-invalid cached objects are not served because the endpoint cannot safely hydrate or trust their row shape.

Response

{
  "rankings": [YieldRanking, ...],
  "riskFreeRate": 4.25,
  "benchmarks": {
    "USD": { "key": "USD", "label": "USD 3M T-Bill", "currency": "USD", "rate": 4.25, "recordDate": "2026-03-25", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "fred-dgs3mo", "isFallback": false, "fallbackMode": null, "isProxy": false },
    "EUR": { "key": "EUR", "label": "EUR 3M compounded €STR", "currency": "EUR", "rate": 1.9358, "recordDate": "2026-03-26", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "ecb-estr-3m", "isFallback": false, "fallbackMode": null, "isProxy": false },
    "CHF": { "key": "CHF", "label": "CHF 3M compounded SARON", "currency": "CHF", "rate": -0.0539, "recordDate": "2026-03-25", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "six-sar3mc", "isFallback": false, "fallbackMode": null, "isProxy": false }
  },
  "scalingFactor": 8,
  "medianApy": 4.21,
  "updatedAt": 1772000000,
  "provenance": {
    "selectionMethod": "confidence-weighted",
    "benchmark": { "key": "USD", "label": "USD 3M T-Bill", "currency": "USD", "rate": 4.25, "recordDate": "2026-03-25", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "fred-dgs3mo", "isFallback": false, "fallbackMode": null, "isProxy": false },
    "benchmarks": {
      "USD": { "key": "USD", "label": "USD 3M T-Bill", "currency": "USD", "rate": 4.25, "recordDate": "2026-03-25", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "fred-dgs3mo", "isFallback": false, "fallbackMode": null, "isProxy": false },
      "EUR": { "key": "EUR", "label": "EUR 3M compounded €STR", "currency": "EUR", "rate": 1.9358, "recordDate": "2026-03-26", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "ecb-estr-3m", "isFallback": false, "fallbackMode": null, "isProxy": false },
      "CHF": { "key": "CHF", "label": "CHF 3M compounded SARON", "currency": "CHF", "rate": -0.0539, "recordDate": "2026-03-25", "fetchedAt": 1774425600, "ageSeconds": 0, "source": "six-sar3mc", "isFallback": false, "fallbackMode": null, "isProxy": false }
    },
    "dlPools": { "mode": "dex-cache", "ageSeconds": 240, "poolCount": 812 },
    "safetySnapshot": { "kind": "ok", "coverageRatio": 0.98 }
  },
  "warnings": [],
  "publication": {
    "generationId": "yield-1772000000",
    "updatedAt": 1772000000,
    "cutoffAt": 1772000000,
    "schemaVersion": 1,
    "status": "published"
  },
  "methodology": {
    "version": "8.19",
    "currentVersion": "8.19",
    "changelogPath": "/methodology/yield-changelog/"
  },
  "_meta": { "updatedAt": 1710500000, "ageSeconds": 42, "status": "fresh" }
}

Optional v8 fields are nullable and omittable. Publication-generation fields are populated by the generation-aware publisher when available; legacy rows and old payloads may still omit them. Public source-risk values are nested under the sourceRisk object; flattened top-level fields such as sourceRiskPenalty or rewardShare are not part of the public API contract.

Current v8.19 scoring treats missing source-risk evidence as neutral: omitted or null sourceRisk, sourceRisk.sourceRiskPenalty, or sourceRisk.venueRiskTier values resolve to a neutral source-risk penalty and do not change PYS or report-card scoring. sourceRisk.sourceRiskScore is now derived from the resolved source-risk penalty when no upstream value is provided. Royco Dawn structured-tranche rows additionally carry opportunity-level Safety Score evidence under sourceRisk.tranche*; this changes only the yield row's safety input and PYS, not the underlying stablecoin's report-card Safety Score. DEWS methodology v5.99 consumes only populated structured yield stress evidence inside its Yield Anomaly sub-signal; neutral, malformed, or missing structured rows remain no-ops. Saved payloads used by calibration tooling should normalize from the nested sourceRisk.* fields before analysis rather than assuming flattened row properties.

YieldRanking

When present, YieldRanking.provenance includes:

• sourceObservedAt / sourceAgeSeconds: the timestamp and age of the latest observation actually backing the row
• comparisonAnchorObservedAt / comparisonAnchorAgeSeconds: optional prior-anchor timing for APYs derived from two observations, such as price-derived and on-chain exchange-rate rows
• benchmarkKey, benchmarkLabel, benchmarkRate, benchmarkIsFallback, benchmarkSelectionMode, and related fields for the exact benchmark applied to that row

GET /api/yield-adapter-manifest

Yield adapter manifest for every yield-bearing asset. The route is public-read, uses the standard cache profile (s-maxage=300), and requires X-API-Key on the public API lane.

sourceKey is an exact runtime key only when it can join to /api/yield-history?sourceKey=..., rankings provenance, or decision-ledger rows. Runtime-resolved DeFiLlama variant strategies and disabled/quarantined readers return sourceKey: null with sourceKeyPattern set to the runtime pattern or would-be disabled key instead of a synthetic non-runtime value.

Response

{
  "methodologyVersion": "v8.16",
  "updatedAt": 1779210000,
  "entries": [
    {
      "stablecoinId": "susde-ethena",
      "coinSymbol": "sUSDe",
      "family": "defillama",
      "sourceKey": "66985a81-9c51-46ca-9977-42b4fe7bc6df",
      "sourceKeyPattern": null,
      "label": "Curated DeFiLlama pool UUID",
      "chain": null,
      "project": null,
      "lifecycle": "active",
      "quarantineReason": null,
      "methodologyVersion": "v8.16",
      "updatedAt": 1779210000
    }
  ]
}

GET /api/yield-history

Historical yield data for a single stablecoin. If a stored warning_signals payload is malformed, the API treats it as an empty array rather than failing the entire response. Generation-aware rows are returned only after their publication generation is marked published; legacy rows remain readable through the existing cutoff fallback. Returned rows are capped at the latest published /api/yield-rankings snapshot so history cannot advance past an unpublished yield cache state. If the cached rankings payload is missing or malformed, the cap degrades to the latest successful sync-yield-data cron timestamp instead of wall-clock now.

For tracked savings-wrapper handoffs (USDe, USDS, DAI, frxUSD, crvUSD, avUSD), legacy parent-owned wrapper rows are filtered immediately at read time and are also purged by the hourly publisher plus the operator cleanup tool. The discontinuity is intentional: those old child-owned series no longer remain queryable through the parent id or through mode=source&sourceKey=.... New linked parent rows use linked-variant:<variantId>:<sourceKey> source keys when a tracked variant's eligible native/wrapper source is intentionally exposed on the active parent for comparison and coverage context.

Cache: slow — X-Data-Age and Warning headers included. Freshness threshold: 3600 s (1 hour, aligned to the hourly sync-yield-data publisher).

Required query parameter

Optional query parameters

Response

{
  "current": {
    "date": 1772000000,
    "apy": 4.21,
    "sourceKey": "onchain:susde-ethena",
    "yieldSource": "Ethena staking (sUSDe)"
  },
  "history": [YieldHistoryPoint, "..."],
  "publication": {
    "generationId": "yield-1772000000",
    "updatedAt": 1772000000,
    "cutoffAt": 1772000000,
    "schemaVersion": 1,
    "status": "published"
  },
  "methodology": {
    "version": "8.13",
    "currentVersion": "8.13",
    "changelogPath": "/methodology/yield-changelog/"
  }
}

YieldHistoryPoint

{
  "date": 1771500000,
  "apy": 12.4,
  "apyBase": 10.2,
  "apyReward": 2.2,
  "exchangeRate": 1.052,
  "sourceTvlUsd": 5200000000,
  "warningSignals": [],
  "sourceKey": "rate-derived",
  "yieldSource": "T-bill proxy",
  "yieldSourceUrl": "https://ondo.finance/usdy",
  "yieldType": "nav-appreciation",
  "dataSource": "rate-derived",
  "isBest": true,
  "sourceSwitch": false,
  "publicationGenerationId": "yield-1771500000"
}

GET /api/mint-burn-flows

Mint/burn flow data across tracked stablecoins — aggregate gauge score, per-coin net-flow + pressure-shift signals, and hourly timeseries. Updated every 30 minutes by the sync cron. Aggregate responses without stablecoin are served cache-first; the critical sync lane pre-publishes the default 24h and 168h windows after successful runs so public reads avoid rescanning hourly mint/burn aggregates.

Cache: standard

Error responses: 503 when the cached fallback payload is missing or malformed and live recomputation cannot satisfy the request. Malformed embedded freshness fields inside an otherwise valid cached payload no longer reset freshness to synthetic values; the API logs the corruption and falls back to the cache row timestamp.

Optional query parameters

Response (aggregate mode — no stablecoin param)

{
  "gauge": {
    "score": 2.3,
    "band": "NEUTRAL",
    "flightToQuality": false,
    "flightIntensity": 0,
    "trackedCoins": 8,
    "trackedMcapUsd": 215000000000,
    "intensitySemantics": "signed-v2",
    "classificationSource": "report-card-cache"
  },
  "coins": [CoinFlow, ...],
  "hourly": [HourlyFlow, ...],
  "updatedAt": 1772000000,
  "windowHours": 24,
  "scope": { "chainIds": ["ethereum", "arbitrum"], "label": "Configured issuance chains" },
  "sync": { "lastSuccessfulSyncAt": 1772000200, "freshnessStatus": "fresh", "warning": null, "criticalLaneHealthy": true }
}

gauge

Top-level metadata

CoinFlow

HourlyFlow

Response (per-coin mode — with stablecoin param)

Returns per-chain breakdown and hourly timeseries for a single coin. Returns 404 if the stablecoin is not tracked for mint/burn flows.

{
  "stablecoinId": "usdt-tether",
  "symbol": "USDT",
  "mintVolumeUsd": 50000000,
  "burnVolumeUsd": 30000000,
  "netFlowUsd": 20000000,
  "mintCount": 12,
  "burnCount": 8,
  "chains": [{ "chainId": "ethereum", "mintVolumeUsd": 40000000, ... }],
  "hourly": [HourlyFlow, ...],
  "updatedAt": 1772000000,
  "windowHours": 24,
  "scope": { "chainIds": ["ethereum"], "label": "Ethereum-only" },
  "sync": { "lastSuccessfulSyncAt": 1772000200, "freshnessStatus": "fresh", "warning": null, "criticalLaneHealthy": true }
}

GET /api/mint-burn-events

Paginated list of individual mint/burn events for a specific stablecoin. Events are sourced from on-chain logs via Alchemy JSON-RPC.

Cache: realtime

Required query parameter

Optional query parameters