API Reference

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.

Response

{
  "peggedAssets": [StablecoinData, ...],
  "fxFallbackRates": { "peggedEUR": 1.082, "peggedGBP": 1.26 }
}

fxFallbackRates is present when the ECB FX-rate cron has run; keys are pegType strings (e.g. "peggedEUR"), values are rates in USD.

`StablecoinData` fields

`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.

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.

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.

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
}

Returns historical non-USD stablecoin market share data from supply_history, split into commodity-pegged (gold/silver) and fiat non-USD buckets. 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

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

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,
  "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:

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.

Cache: dynamic

• Live snapshots: slow (public, s-maxage=3600, max-age=300)
• Bootstrap / fallback / stale 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.

When present, displayBadge has:

When present, provenance has:

Response (404): { "error": "Not found" }

Aggregate historical supply chart data across all stablecoins, broken down by peg type. 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
    }
  }
]

Freeze, blacklist, and token-destruction events currently ingested for USDC, USDT, PAXG, XAUT, PYUSD, and USD1. EURC is intentionally excluded from the live filter set for now because Circle frequently mirrors the same blacklist actions on both USDC and EURC, which creates many zero-balance EURC rows. 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 hourly sync-blacklist writer timestamp. Public freshness stays fresh through that hourly budget and only degrades once the scheduled blacklist sync is actually late.

Query parameters

Response

{
  "events": [BlacklistEvent, ...],
  "total": 13422,
  "methodology": {
    "version": "3.6",
    "versionLabel": "v3.6",
    "currentVersion": "3.6",
    "currentVersionLabel": "v3.6",
    "changelogPath": "/methodology/blacklist-tracker-changelog/",
    "asOf": 1772606400,
    "isCurrent": true
  }
}

`BlacklistEvent`

`methodology`

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.activeFrozenTotal reflects Pharos' local 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. 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.

Cache: realtime

Freshness note: Shares the same 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
  },
  "chart": [
    { "quarter": "Q1 '24", "USDT": 1200000, "USDC": 850000, "PAXG": 0, "XAUT": 0, "total": 2050000 }
  ],
  "chains": [
    { "id": "ethereum", "name": "Ethereum" },
    { "id": "tron", "name": "Tron" }
  ],
  "totalEvents": 13422,
  "methodology": {
    "version": "3.6",
    "versionLabel": "v3.6",
    "currentVersion": "3.6",
    "currentVersionLabel": "v3.6",
    "changelogPath": "/methodology/blacklist-tracker-changelog/",
    "asOf": 1772606400,
    "isCurrent": true
  }
}

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, ...],
  "total": 4080,
  "methodology": {
    "version": "4.9",
    "versionLabel": "v4.9",
    "currentVersion": "4.9",
    "currentVersionLabel": "v4.9",
    "changelogPath": "/methodology/depeg-changelog/",
    "asOf": 1772606400,
    "isCurrent": true
  }
}

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

`DepegEvent`

`methodology`

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": "4.9",
    "versionLabel": "v4.9",
    "currentVersion": "4.9",
    "currentVersionLabel": "v4.9",
    "changelogPath": "/methodology/depeg-changelog/",
    "asOf": 1772606400,
    "isCurrent": true
  }
}

`PegSummaryCoin`

`DexPriceCheck`

`PegSummaryStats`

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

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
}

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.

{
  "usdt-tether": BluechipRating,
  "usdc-circle": BluechipRating
}

`BluechipRating`

`BluechipSmidge` — each field is string | null:

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.

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

`DexLiquidityData`

`ScoreComponents`

`DexLiquidityPool`

extra may include:

`DexPriceSource`

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"
  }
]

Per-coin circulating supply and price history, snapshotted once daily at 08:00 UTC.

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

Required query parameter

Optional query parameters

Response: Array sorted by date ascending.

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

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 (max 2 h). The bootstrap { "digest": null } response carries only Cache-Control.

Response

{
  "digest": "USDC absorbed $812M of the market's $1.36B weekly inflow…",
  "editionNumber": 214
}

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

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,
      "digestType": "daily",
      "editionNumber": 214
    }
  ]
}

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

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.

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

Authentication: exempt

Response

{
  "status": "healthy",
  "timestamp": 1771856453,
  "warnings": [],
  "caches": {
    "stablecoins": { "ageSeconds": 323, "maxAge": 600, "healthy": true },
    "stablecoin-charts": { "ageSeconds": 323, "maxAge": 3600, "healthy": true },
    "usds-status": { "ageSeconds": 47118, "maxAge": 86400, "healthy": true },
    "fx-rates": {
      "ageSeconds": 1223,
      "maxAge": 1800,
      "healthy": true,
      "mode": "live",
      "sourceUpdatedAt": 1771855200,
      "sourceAgeSeconds": 323,
      "sourceStatus": "fresh",
      "warning": null,
      "consecutiveFallbackRuns": 0
    },
    "bluechip-ratings": { "ageSeconds": 22815, "maxAge": 86400, "healthy": true },
    "dex-liquidity": { "ageSeconds": 290, "maxAge": 43200, "healthy": true },
    "yield-data": { "ageSeconds": 820, "maxAge": 3600, "healthy": true },
    "dews": { "ageSeconds": 240, "maxAge": 1800, "healthy": true }
  },
  "blacklist": {
    "totalEvents": 13422,
    "missingAmounts": 0,
    "recentMissingAmounts": 0,
    "recentWindowSec": 86400,
    "missingRatio": 0
  },
  "mintBurn": {
    "totalEvents": 112345,
    "latestEventTs": 1771856430,
    "latestHourlyTs": 1771855200,
    "freshnessAgeSec": 23,
    "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": "success"
  }
}

`CacheStatus`

The /status/ page consumes the richer blacklist fields directly so it can distinguish long-tail historical cleanup from fresh incoming amount gaps.

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.

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.

Lightweight Telegram adoption metrics for the public /telegram/ landing page. Returns only aggregate watcher/subscription counts plus the most subscribed coin symbols.

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

Response

{
  "activeWatchers": 1842,
  "coinSubscriptions": 5621,
  "topCoins": ["USDT", "USDC", "USDe"]
}

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

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.

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
  }
}

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 for unknown coin IDs or unknown OG routes
• 503 when required cached data is not yet available

/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.

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": "usde-ethena", "to": "usdc-circle", "weight": 0.9, "type": "collateral" }, ...]
  },
  "methodology": {
    "version": "6.8",
    "weights": { "pegStability": 0, "liquidity": 0.30, "resilience": 0.20, "decentralization": 0.15, "dependencyRisk": 0.25 },
    "pegMultiplierExponent": 0.2,
    "thresholds": [{ "grade": "A+", "min": 87 }, { "grade": "A", "min": 83 }, ...]
  },
  "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. Low-confidence redemption routes stay visible but do not uplift the score, and stale DEX inputs are not blended.

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.

GET /api/report-cards treats the stablecoins cache and redemption-backstop snapshot as hard dependencies. DEX liquidity, bluechip ratings, and live-reserve inputs are soft dependencies: if one of those loaders is temporarily unavailable, the endpoint continues serving a degraded snapshot instead of failing closed.

`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 } — upstream stablecoin ID + fraction of collateral from that source (0–1). Weights sum to ≤ 1.0; the remainder represents non-stablecoin collateral.

`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.

Dimensions: pegStability, liquidity, resilience, decentralization, dependencyRisk

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.

Response

{
  "coins": {
    "cusd-cap": {
      "stablecoinId": "cusd-cap",
      "score": 88,
      "effectiveExitScore": 56,
      "dexLiquidityScore": 29,
      "routeFamily": "basket-redeem",
      "accessModel": "permissionless-onchain",
      "settlementModel": "atomic",
      "outputAssetType": "stable-basket",
      "immediateCapacityUsd": null,
      "immediateCapacityRatio": null,
      "sourceMode": "estimated",
      "resolutionState": "resolved",
      "capacityConfidence": "heuristic",
      "capacitySemantics": "eventual-only",
      "feeConfidence": "undisclosed-reviewed",
      "feeModelKind": "undisclosed-reviewed",
      "modelConfidence": "low",
      "updatedAt": 1773350400,
      "methodologyVersion": "1.2"
    }
  },
  "methodology": {
    "version": "1.2",
    "componentWeights": {
      "access": 0.2,
      "settlement": 0.15,
      "executionCertainty": 0.15,
      "capacity": 0.25,
      "outputAssetQuality": 0.15,
      "cost": 0.1
    },
    "effectiveExitWeights": {
      "liquidity": 0.55,
      "redemption": 0.45
    }
  },
  "updatedAt": 1773350400
}

score is the direct redemption-quality score.

effectiveExitScore is the blended exit score written into the redemption snapshot when the route resolved cleanly and the reused DEX liquidity input was fresh. Report cards may still recompute liquidity from the same underlying redemption score with additional confidence gating.

methodology.version is attributed from the latest stored redemption snapshot row. 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

Top-level fields:

RedemptionBackstopEntry highlights:

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

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"
  }
]

Cache-backed yield rankings written by the sync-yield-data cron. The endpoint rehydrates safetyScore, safetyGrade, yieldToRisk, and pharosYieldScore from the current report-card snapshot at read time so Yield Intelligence stays aligned with /api/report-cards. PYS is benchmark-aware: it starts from cached APY inputs, adds a weighted slice of the row's benchmark spread, and then applies the current Safety Score. 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 or malformed.

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 }
  }
}

`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

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. 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.

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:usde-ethena",
    "yieldSource": "Ethena staking (sUSDe)"
  },
  "history": [YieldHistoryPoint, "..."],
  "methodology": {
    "version": "5.5",
    "currentVersion": "5.5",
    "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
}

Mint/burn flow data across tracked stablecoins — aggregate gauge score, per-coin net-flow + pressure-shift signals, and hourly timeseries. Updated every 20 minutes by the sync cron.

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 }
}

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

Response

{
  "events": [MintBurnEvent, ...],
  "total": 1234
}

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

`MintBurnEvent`

Returns Depeg Early Warning Score (DEWS) data for active tracked stablecoins.

All coins (no params): Latest DEWS score + signal breakdown per coin.

Single coin: Add ?stablecoin=ID&days=30 for latest + daily history.

stablecoin must be an active tracked Pharos stablecoin ID. Unknown IDs and tracked-but-non-active IDs return 404 with { "error": "Stablecoin not tracked" }.

Cache: standard (public, s-maxage=300, max-age=60)

Query parameters

Aggregate responses are filtered to active tracked stablecoin IDs only, even if stale rows for non-active or de-tracked IDs still exist in storage.

Response (all coins)

{
  "signals": {
    "usdt-tether": {
      "score": 5,
      "band": "CALM",
      "signals": {
        "supply": { "value": 2, "available": true },
        "price": { "value": 1, "available": true }
      },
      "computedAt": 1740000000,
      "methodologyVersion": "4.9"
    }
  },
  "updatedAt": 1740000000,
  "malformedRows": 0,
  "methodology": {
    "version": "4.9",
    "versionLabel": "v4.9",
    "currentVersion": "4.9",
    "currentVersionLabel": "v4.9",
    "changelogPath": "/methodology/depeg-changelog/",
    "asOf": 1740000000,
    "isCurrent": true
  }
}

Response (single coin)

{
  "current": {
    "score": 5,
    "band": "CALM",
    "signals": {
      "supply": { "value": 2, "available": true },
      "price": { "value": 1, "available": true }
    },
    "computedAt": 1740000000,
    "methodologyVersion": "4.9"
  },
  "history": [
    {
      "date": 1739900000,
      "score": 3,
      "band": "CALM",
      "signals": {
        "supply": { "value": 1, "available": true },
        "price": { "value": 1, "available": true }
      },
      "methodologyVersion": "4.3"
    }
  ],
  "malformedRows": 0,
  "methodology": {
    "version": "4.9",
    "versionLabel": "v4.9",
    "currentVersion": "4.9",
    "currentVersionLabel": "v4.9",
    "changelogPath": "/methodology/depeg-changelog/",
    "asOf": 1740000000,
    "isCurrent": true
  }
}

`malformedRows` — count of DB rows with unparseable JSON signal data (expected 0 under normal operation)

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

Public feedback ingestion endpoint used by the in-app feedback modal. Validates payloads, applies IP-based rate limiting, and forwards submissions to GitHub Issues.

Authentication: exempt

Cache: no edge cache (POST passthrough)

Rate limits

• Global public API limiter: D1-backed per-IP-hash limiter (300 requests / 60 seconds) for non-admin requests. If the distributed limiter path fails, the worker logs the failure and allows the request instead of switching to an isolate-local fallback limiter.
• Feedback endpoint limiter: 3 submissions / 10 minutes per salted IP hash in D1.

Request body

{
  "type": "bug",
  "title": "Optional short title",
  "description": "Required, 10-2000 characters",
  "expectedValue": "Optional expected behavior/value",
  "stablecoinId": "Optional canonical stablecoin id",
  "stablecoinName": "Optional stablecoin name",
  "pageUrl": "/stablecoin/usdt-tether",
  "pegValue": "Optional UI value snapshot",
  "contactHandle": "@pharos_user",
  "website": ""
}

Response

{ "ok": true }

Error responses

• 400 invalid payload
• 429 rate limited (3 submissions / 10 minutes per salted IP hash)
• 500 forwarding/processing failure
• 503 service misconfigured (missing FEEDBACK_IP_SALT or GITHUB_PAT)

Telegram Bot API webhook endpoint. Receives user messages, processes bot commands, and manages subscriptions.

Authentication: exempt from X-API-Key; requires X-Telegram-Bot-Api-Secret-Token instead. Not the standard X-Admin-Key.

Rate limiting: Exempt from IP rate limiter (Telegram sends from fixed IPs).

Cache: no edge cache (POST passthrough)

Request body: Telegram Update object (JSON, sent by Telegram servers).

Response: Always 200 OK with plain-text body ok (Telegram retries on non-2xx).

Commands handled:

• /start — Welcome message with onboarding examples plus @pharoswatch and @pharoswatchers links
• /presets — List the preset watchlist catalog and example commands
• /subscribe <types> <targets> — Subscribe to alerts for explicit coins or preset watchlists (types: dews, depeg, safety, launch)
• /subscribe <types> all — Enable one or more alert types across all tracked stablecoins
• /unsubscribe <targets> — Remove explicit coin subscriptions or the concrete coin rows covered by a preset watchlist
• /unsubscribe all — Remove all per-coin subscriptions and disable every current alert flag, including launch
• /set <ticker> <setting> <value> — Tune per-coin thresholds and modes
• /set all <setting> <value> — Toggle global all-stablecoin alert types
• /mute <start>-<end> — Enable UTC quiet hours
• /unmutehours — Disable quiet hours
• /cancel — Cancel a pending disambiguation flow
• /list — Show current subscriptions, per-coin settings, and quiet hours
• /help — Command reference

Preset watchlists currently resolve at command time into standard telegram_subscriptions rows. Supported aliases are usd-top10, usd-top25, usd-top50, eur-top10, gold-top5, mcap-ge-1b, and mcap-ge-100m. Presets are supported for dews, depeg, and safety; launch still requires explicit tickers or Pharos coin IDs.