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.

Daily snapshot of reviewed protocol and DAO treasury stablecoin sleeves. This endpoint is intentionally scoped to public onchain treasury wallets, EVM-first, and best-effort coverage.

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

Response

{
  "entities": [
    {
      "protocolId": "maker",
      "name": "Sky / Maker",
      "treasuryUsd": 123456789,
      "stablecoinSleeveUsd": 45678901,
      "trackedStableUsd": 43000000,
      "decentralizedStableUsd": 21000000,
      "decentralizedStablePctOfTreasury": 17.0,
      "decentralizedStablePctOfStableSleeve": 46.0,
      "weightedSafetyScore": 82.4,
      "weightedSafetyGrade": "B+",
      "holdings": []
    }
  ],
  "updatedAt": 1743321600,
  "coverage": {
    "entityCount": 12,
    "registryCount": 14,
    "launchEligibleCount": 12,
    "ownerChainTuples": 54,
    "launchOwnerChainTuples": 42,
    "evmOnly": true,
    "extractionModes": {
      "staticSeeded": 14,
      "customReviewed": 0,
      "dynamicUnresolved": 0,
      "missing": 0
    }
  }
}

Important response semantics:

• treasuryUsd is the full wallet-balance denominator from the same provider snapshot used for the stable sleeve.
• stablecoinSleeveUsd combines direct stablecoin balances from Sim's stablecoin filter with supported LP, vault, and lending positions decomposed to their underlying stablecoins.
• trackedStableUsd is the subset of the stable sleeve that Pharos can map to tracked stablecoins by chain + contract.
• decentralizedStablePctOfStableSleeve therefore uses the full stable sleeve denominator, not only the tracked subset.
• coverage.untrackedStableUsd discloses the stablecoin value that could not be mapped into a Pharos stablecoin ID.
• coverage.notes may state when LP, vault, or lending positions were decomposed into underlying stablecoin exposure, or when that supplement failed and treasury-only coverage remained.
• weightedSafetyScore is USD-weighted across tracked stable holdings that have a current report card; coverage.ratedTrackedStablePct shows how much of the tracked sleeve that score covers.

Cold-start behavior: if no treasury snapshot has been published yet, the endpoint returns 200 with entities: [] plus stale _meta freshness fields so UI and smoke checks can treat the dataset as temporarily empty rather than transport-failed.

Error responses: 503 only when the cached treasury snapshot exists but is structurally malformed.

For integrations that only need current per-coin metrics (without full historical arrays), prefer 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
}

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.

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

Freshness threshold: 600 seconds. Returns 503 when the stablecoins cache is unavailable.

Status codes:

Response (`ChainsResponse`):

{
  "chains": [ChainSummary, ...],
  "globalTotalUsd": 230000000000,
  "updatedAt": 1710500000,
  "healthMethodologyVersion": "1.1"
}

`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. 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,
    "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 all tracked stablecoins. Scores are computed over a 4-year window from live depeg events, DEX prices, and current prices.

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: archive

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: archive

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 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+ circuit groups are open
• stale — any cache impact is stale, or the public mint/burn lane is stale versus its critical-lane cadence

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.

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

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.

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"], "label": "Ethereum-only" },
  "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
• /subscribe <types> <tickers> — Subscribe to alerts (types: dews, depeg, safety, launch)
• /subscribe <types> all — Enable one or more alert types across all tracked stablecoins
• /unsubscribe <tickers> — Remove coin subscriptions
• /unsubscribe all — Remove all per-coin subscriptions and disable the current DEWS/depeg/safety flags; launch flags are not reset by this path today
• /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

Full admin dashboard: cron run history, cache freshness for all keys, data quality metrics, Telegram bot subscriber stats, and operator reconciliation signals.

Preferred access:

• Browser: https://ops.pharos.watch/admin/ -> same-origin /api/admin/status
• CLI: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret> against https://ops-api.pharos.watch/api/status

Response shape: StatusResponse (defined in shared/types/index.ts)

{
  "timestamp": 1771856453,
  "dbHealthy": true,
  "availabilityStatus": "healthy",
  "dataQualityStatus": "healthy",
  "rawOverallStatus": "degraded",
  "overallStatus": "healthy",
  "confidence": 0.94,
  "causes": {
    "availability": [{ "code": "degraded_cron_warning", "severity": "info" }],
    "dataQuality": [],
    "overall": [{ "code": "degraded_cron_warning", "severity": "info" }]
  },
  "state": {
    "currentStatus": "healthy",
    "rawStatus": "degraded",
    "lastEvaluatedAt": 1771856453,
    "lastChangedAt": 1771856200,
    "consecutiveRaw": { "healthy": 3, "degraded": 0, "stale": 0 }
  },
  "staleness": { "ageSeconds": 0, "maxAgeSec": 1800, "isStale": false },
  "probe": {
    "timestamp": 1771856440,
    "status": "healthy",
    "sampleCount": 22,
    "passCount": 22,
    "failCount": 0,
    "p95LatencyMs": 301
  },
  "discrepancy": {
    "hasDivergence": false,
    "severityDelta": 0,
    "consecutiveDivergent": 0
  },
  "timeline": [
    {
      "id": 411,
      "from": "degraded",
      "to": "healthy",
      "rawStatus": "healthy",
      "transitionType": "recover",
      "reason": "raw-healthy-recovery-threshold",
      "confidence": 0.94,
      "at": 1771856200
    }
  ],
  "caches": { ... },
  "crons": {
    "sync-stablecoins": {
      "lastRun": { "startedAt": 1234567890, "durationMs": 2300, "status": "ok", "itemCount": 156 },
      "inFlight": null,
      "recentRuns": [...],
      "expectedIntervalSec": 900,
      "healthy": true
    }
  },
  "dataQuality": {
    "totalStablecoins": 156,
    "missingPrices": 3,
    "blacklistMissingAmounts": 0,
    "blacklistRecentMissingAmounts": 0,
    "blacklistRecentWindowSec": 86400,
    "blacklistMissingRatio": 0,
    "blacklistTotal": 13422,
    "blacklistOldestRecoverableAgeSec": 0,
    "blacklistNeverAttemptedCount": 0,
    "blacklistRepeatedFailureCount": 0,
    "onchainSupplyDivergences": 0,
    "onchainDivergenceRatio": 0,
    "onchainSupplyMonitoring": "active",
    "onchainSupplyLatestAt": 1771856300,
    "onchainSupplyTrackedCoins": 96,
    "activeDepegs": 12,
    "staleOnchainSupply": 0,
    "onchainStaleRatio": 0
  },
  "sectionErrors": {},
  "telegramBot": {
    "totalChats": 128,
    "alertEnabledChats": 123,
    "deliverableChats": 121,
    "subscribedChats": 124,
    "emptyAlertChats": 2,
    "mutedChatsWithSubscriptions": 3,
    "totalSubscriptions": 611,
    "avgSubscriptionsPerSubscribedChat": 4.9,
    "pendingDisambiguations": 1,
    "pendingDeliveries": 6,
    "lastSubscriberActivityAt": 1771856420,
    "customPreferenceChats": 47,
    "quietHoursEnabledChats": 18,
    "alertTypeChats": {
      "dews": 121,
      "depeg": 118,
      "safety": 102,
      "allTypes": 95
    },
    "topStablecoins": [
      { "stablecoinId": "usdc-circle", "symbol": "USDC", "subscribers": 82 },
      { "stablecoinId": "usdt-tether", "symbol": "USDT", "subscribers": 77 }
    ]
  },
  "datasetFreshness": {
    "stablecoins": 1771856400,
    "blacklist": 1771856200,
    "mintBurn": 1771856340,
    "supply": 1771804800,
    "safetyGrades": 1771804800,
    "yield": 1771856320,
    "depegs": 1771856010,
    "dews": 1771856400,
    "digest": 1771804800,
    "discoveryCandidates": 1771856400
  },
  "summary": {
    "unhealthyCrons": 0,
    "degradedCrons": 1,
    "cronErrors": 0,
    "worstCacheRatio": 1.03
  },
  "priceSourceHealth": {
    "sourceDistribution": {
      "coingecko": 14,
      "coingecko+defillama-list": 118,
      "defillama": 10,
      "defillama-list": 0,
      "protocol-redeem": 1,
      "defillama-contract": 4,
      "coinmarketcap": 2,
      "dexscreener": 1,
      "geckoterminal": 0,
      "cached": 4,
      "missing": 3
    },
    "confidenceDistribution": {
      "high": 127,
      "single-source": 15,
      "low": 8,
      "fallback": 6
    },
    "totalAssets": 156,
    "lastSync": 1771856400
  },
  "coingeckoPriceDiff": {
    "checkedAt": 1771856453,
    "trackedWithGeckoId": 152,
    "comparedCoins": 149,
    "mismatchedCount": 2,
    "thresholdPct": 5,
    "rows": [
      {
        "stablecoinId": "pyusd-paypal",
        "symbol": "PYUSD",
        "name": "PayPal USD",
        "geckoId": "paypal-usd",
        "ourPrice": 0.944,
        "coinGeckoPrice": 1.002,
        "diffPct": 5.79,
        "priceSource": "defillama",
        "priceConfidence": "single-source"
      }
    ]
  },
  "d1Usage": {
    "checkedAt": 1771856453,
    "windowStart": 1771770053,
    "windowEnd": 1771856453,
    "databaseId": "8f3f54ca-e035-4cdf-9ec5-a4fbbe48b27a",
    "databaseName": "stablecoin-db",
    "databaseSizeBytes": 1589248000,
    "numTables": 56,
    "region": "EEUR",
    "readReplicationMode": "disabled",
    "readQueries24h": 942012,
    "writeQueries24h": 709241,
    "rowsRead24h": 1633139670,
    "rowsWritten24h": 1555568
  },
  "liquidityHealth": {
    "lastRunStatus": "degraded",
    "currentCoverage": 120,
    "previousCoverage": 125,
    "currentGlobalTvl": 123000000,
    "previousGlobalTvl": 125000000,
    "currentTop10CoveredTvl": 100000000,
    "previousTop10CoveredTvl": 102000000,
    "failedSources": ["defillama-yields"],
    "nearCoverageGuard": false,
    "nearValueGuard": false,
    "nearMajorCoverageGuard": false,
    "currentCoverageClasses": { "primary": 80, "mixed": 20, "fallback": 20, "legacy": 0, "unobserved": 36 },
    "previousCoverageClasses": { "primary": 82, "mixed": 18, "fallback": 25, "legacy": 0, "unobserved": 31 }
  },
  "discoveryCandidates": [
    {
      "id": 12,
      "geckoId": "usdq",
      "llamaId": null,
      "name": "USDQ",
      "symbol": "USDQ",
      "marketCap": 18200000,
      "source": "coingecko",
      "firstSeen": 1771683600,
      "lastSeen": 1771856400,
      "daysSeen": 2,
      "dismissed": false
    }
  ],
  "mintBurnReconciliation": {
    "checkedAt": 1771856453,
    "comparedCoins": 42,
    "criticalCount": 1,
    "warnCount": 3,
    "insufficientCount": 12,
    "rows": [
      {
        "stablecoinId": "usdt-tether",
        "symbol": "USDT",
        "flowNet24hUsd": -240000000,
        "chainSupplyDelta24hUsd": -220000000,
        "absoluteDiffUsd": 20000000,
        "diffRatio": 0.08,
        "status": "warn",
        "coverageStatus": "full"
      }
    ]
  }
}

dataQuality.onchainSupplyTrackedCoins counts only coins with at least one onchain_supply row inside the current 3-day active monitoring window. Older historical rows are excluded from staleOnchainSupply and onchainStaleRatio.

Ratio-based on-chain status thresholds apply only when dataQuality.onchainSupplyTrackedCoins >= 10; below that floor, the counts remain visible but do not by themselves escalate dataQualityStatus.

itemCount and dataQuality.totalStablecoins are illustrative example values. In the live handler they reflect the current cached stablecoin payload size, not TRACKED_STABLECOINS.length.

crons[*].healthy reflects availability impact. Fresh cron runs with status="degraded" are warning-only and counted in summary.degradedCrons, but they do not mark availability unhealthy on their own.

availabilityStatus also inherits the shared public-health floor used by /api/health: cache-impact status, the critical mint/burn lane's public warning/staleness contract, and 3+ open circuit groups can degrade availability even when cron freshness alone is still green.

crons[*].inFlight is present when a leased cron is actively reporting cron_run_progress and the matching cron_leases row is still active for the same owner. It includes startedAt, updatedAt, stage, optional itemsDone/itemsTotal, optional message/metadata, and a stale flag when the heartbeat stops updating.

overallStatus is the effective (hysteresis-smoothed) status. rawOverallStatus is the immediate worst-of availability/data-quality signal.

dbHealthy=false means the DB sentinel failed (SELECT 1), so status is forced to at least degraded and data-quality/database freshness queries are skipped.

telegramBot is null when the Telegram tables are unavailable in the current environment (for example, migrations not yet applied in dev/staging). The rest of /api/status still resolves normally.

sectionErrors is a machine-readable map of subsection loader failures. When an individual status subsection fails (for example Telegram stats, discovery backlog, CoinGecko price drift, D1 usage telemetry, liquidity health, reserve drift, or mint/burn reconciliation), /api/status still returns 200, keeps the unaffected sections intact, and records the degraded subsection under sectionErrors with a stable code plus an operator-facing message.

crons["dispatch-telegram-alerts"].lastRun.metadata now carries a richer delivery breakdown, including fields such as freshAttempted, freshSent, freshRetryQueued, freshPermanentFailures, pendingAttempted, pendingDrained, pendingRetryQueued, pendingDropped, pendingEnqueued, and expanded eventsDetected counters (depegTriggered, depegResolved, depegWorsening, suppressedMethodologyChanges).

datasetFreshness covers the key operator-visible datasets written by the pipeline: cache-backed stablecoins, blacklist, mint/burn, supply snapshots, safety-grade history, yield, depeg/dews tables, daily digest, and discovery backlog timestamps.

priceSourceHealth is derived from the final sync-stablecoins asset payload and summarizes resolved price-source distribution, confidence buckets, total assets, and the timestamp of the latest successful price-health snapshot. CoinGecko-vs-Pharos divergence details live in the separate coingeckoPriceDiff block.

coingeckoPriceDiff is an admin-only live comparison block. It reads the cached tracked assets with geckoId, fetches current CoinGecko spot prices through one or more batched simple/price calls, and reports the rows where abs(pharosPrice - coinGeckoPrice) / coinGeckoPrice > 0.05. The field is null when the comparison is unavailable in the current environment or when the loader fails; failures are surfaced through sectionErrors.coingeckoPriceDiff.

d1Usage is an admin-only live D1 telemetry block. It uses Cloudflare's D1 database info endpoint plus a trailing-24h d1AnalyticsAdaptiveGroups GraphQL query to surface current storage size, table count, replication mode, and recent query/row volume. The field is null until CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_D1_STATUS_API_TOKEN, and CLOUDFLARE_D1_DATABASE_ID are configured on the worker; loader/config failures are surfaced through sectionErrors.d1Usage.

liquidityHealth is derived from the latest sync-dex-liquidity cron metadata and summarizes row coverage, value coverage, major-asset coverage, failed sources, and current/previous coverage-class distribution for the operator dashboard.

discoveryCandidates exposes the current untracked-coverage backlog from discovery_candidates, ordered by market cap for the /status operator workflow.

mintBurnReconciliation compares 24h Ethereum mint/burn net flow (mint_burn_hourly) against the cached stablecoins payload's Ethereum chain-supply delta (chainCirculating.ethereum.current - circulatingPrevDay). It is intended for operator diagnostics, not public scoring.

Machine-readable status timeline endpoint for tooling and incident analysis.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Response shape: StatusHistoryResponse (defined in shared/types/index.ts)

Admin-only public-API attribution summary. Aggregates minute-bucketed request counts into a requested window so operators can estimate what share of api.pharos.watch load is coming from browser-identified Pharos traffic versus external consumers.

This dataset excludes admin-only routes, /api/telegram-webhook, and the internal site-api / /_site-data/* website lane. First-party website traffic on the public API host is recognized from browser evidence: Origin or Referer matching https://pharos.watch, or the browser-safe frontend Accept marker combined with same-site fetch metadata. Everything else in scope is counted as external.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Response shape: PublicApiRequestSourceStatsResponse (defined in shared/types/index.ts)

PublicApiRequestSourceStatsResponse includes:

• generatedAt — Unix seconds when the response was generated
• window — requested from/to, durationSec, bucketSizeSec, routeLimit, and current retentionDays
• totals — aggregate webRequests, externalRequests, totalRequests, webSharePct, externalSharePct
• routes[] — normalized per-route breakdown sorted by total request volume
• buckets[] — time-series rollups using the requested bucketSec

Admin-only API key inventory. Returns masked tokens plus metadata, but never returns stored secret material.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Response shape: ApiKeyListResponse (defined in shared/types/api-keys.ts)

Admin-only API key creation route.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Body shape: ApiKeyCreateRequest

Response shape: ApiKeyCreateResponse

token is returned only once. Persist it immediately; later list/read paths expose only maskedToken.

Admin-only metadata update for an existing API key.

Body shape: ApiKeyUpdateRequest

Accepted fields:

• name
• ownerEmail
• tier
• rateLimitPerMinute
• isActive

Response shape: ApiKeyMutationResponse

Admin-only hard deactivation for an existing API key. This sets isActive=false; the secret cannot be used afterward.

Response shape: ApiKeyMutationResponse

Admin-only secret rotation. The old token stops working immediately and a new plaintext token is returned once.

Response shape: ApiKeyRotateResponse

Backfills historical depeg events from stored price data.

For coins with a registered authoritative historical price provider, the backfill uses that same provider family first (for example, replayed protocol redemption quotes) before falling back to CoinGecko/DefiLlama market history. If the authoritative provider is configured but unavailable, existing source='backfill' rows for that coin are preserved instead of being rebuilt from a weaker source.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Backfills per-coin supply history snapshots.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Backfills historical stability index scores from stored depeg events and supply data.

The rebuild now stops at the last completed UTC day; it does not write a stability_index row for the current UTC day. Historical market-cap denominators in this replay path are bounded to the PSI-eligible universe (tracked coins plus configured shadow assets). Historical depeg severity is replayed from same-day supply_history.price when a usable day price exists, with peak_deviation_bps used only as a fallback for missing/invalid price coverage. For methodology v3.0+, the replay also derives daily stressBreadth from stress_signal_history rows in ALERT, WARNING, or DANGER bands. The response includes the evaluated startDay/endDay so operators can confirm the rebuild window.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Backfills CoinGecko historical prices into the price_cache table for more accurate depeg detection.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Repairs incomplete mint/burn valuation metadata using a historical-first policy. The endpoint now prefers event-day supply_history prices for rows with amount_usd IS NULL and only derives audit fields for already-valued rows. It no longer bulk-fills historical amount_usd from the current price_cache snapshot.

Cron sync-mint-burn automatically heals recent NULL-price events within a 48-hour window and reports the healed count in cron metadata as nullPricesHealed; this endpoint is primarily for historical backfills beyond that window.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Response

{
  "totalUpdated": 15000,
  "rowsValued": 14000,
  "rowsAudited": 1000,
  "rowsStillUnpriced": 85,
  "rowsStillMissingAudit": 320,
  "coins": [
    {
      "id": "usdt-tether",
      "updated": 49,
      "valued": 41,
      "audited": 8,
      "stillUnpriced": 0,
      "stillMissingAudit": 2
    }
  ]
}

Validates DEWS against historical depeg events. Reports true-positive rate and average lead time.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Backfills mint/burn event ingestion for a specific contract config using the same parsing/classification pipeline as the cron. If configKey is omitted, the worker auto-selects one Ethereum config using a critical-first / major-symbol-first / most-behind policy and returns the selected config in the response.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Request body or query parameters

Retroactively tags same-transaction mint+burn pairs for the same stablecoin as flow_type='atomic_roundtrip' and recalculates the affected hourly buckets.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Response

{
  "done": false,
  "updated": 428,
  "hoursRecalculated": 31,
  "batchSize": 1000
}

The endpoint processes up to 1000 (tx_hash, stablecoin_id) groups per request. Repeat until done=true.

Dry-run preview for the depeg audit endpoint. This is the only supported GET mode for /api/audit-depeg-history; all mutating executions require POST.

The same endpoint also supports a dry-run historical repair preview with repair=synthetic-splits, which surfaces adjacent same-direction live events that were likely split by the old DEX-only auto-close behavior.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Audits existing depeg events against CoinGecko historical price data to detect false positives.

POST /api/audit-depeg-history?repair=synthetic-splits instead runs a historical repair pass that consolidates adjacent same-direction live events when the earlier event was closed near peg and the next event reopened one sync later with a still-severe deviation. This is intended for repairing synthetic splits caused by the retired DEX-only auto-close behavior.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

GET is accepted only with dry-run=true; mutating audits require POST.

Query parameters

Queues a background daily-digest regeneration, bypassing the normal 1-hour dedup check. Routed through worker/src/router.ts.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Response

{
  "ok": true,
  "accepted": true,
  "requestId": "manual-digest-..."
}

Status: 202 Accepted

The worker enqueues the digest run in waitUntil() and returns immediately so the Access-gated ops proxy does not need to hold the HTTP request open for the full Anthropic generation window. The background run is still logged against the daily-digest cron history, including manual skipped_locked outcomes when another digest run already holds the lease.

Unhandled pre-enqueue failures are wrapped by the shared error handler and return 500 with { "error": "Internal Server Error" }.

Rolls back blacklist sync state to re-scan missed events. EVM chains are rolled back by 50,000 blocks; Tron is rolled back by 7 days. Routed through worker/src/router.ts.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Response (evmReset / tronReset are row-change counts from the blacklist_sync_state UPDATE, not block numbers)

{
  "ok": true,
  "evmReset": 5,
  "tronReset": 2
}

Returns current blacklist sync state for all configured chains. Useful for diagnosing sync issues. Routed through worker/src/router.ts.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Response

[
  { "config_key": "ethereum-usdc", "last_block": 19500000 },
  { "config_key": "tron-usdt", "last_block": 1740000000000 }
]

Admin-only bounded remediation endpoint for recoverable blacklist rows.

Authentication: same admin auth as other ops endpoints.

Idempotency: supported via optional Idempotency-Key.

Inputs

• chainId?: string
• stablecoin?: "USDC" | "USDT" | "PAXG" | "XAUT" | "PYUSD" | "USD1"
• limit?: number default 25, max 200
• dryRun?: boolean default true
• onlyMissingProvenance?: boolean default true
• maxAttempts?: number default 25

Dry-run response

{
  "ok": true,
  "dryRun": true,
  "candidateCount": 26,
  "resolutionCounts": {
    "resolved": 26,
    "missing_config": 0,
    "ambiguous_config": 0
  }
}

Write-enabled response

{
  "ok": true,
  "dryRun": false,
  "applied": {
    "resolved": 26,
    "resolvedZero": 26,
    "providerFailed": 0,
    "configMissing": 0,
    "configAmbiguous": 0,
    "budgetUsed": 26,
    "budgetLimit": 900
  }
}

Admin-only one-shot backfill endpoint for blacklist_current_balances, intended for blacklist configs whose historical events were ingested before the current-balance cache existed.

Authentication: same admin auth as other ops endpoints.

Idempotency: supported via optional Idempotency-Key.

Query parameters

400 is returned when the filters match no configured blacklist contracts.

Dry-run response

{
  "ok": true,
  "dryRun": true,
  "configs": [
    {
      "configKey": "ethereum-pyusd",
      "stablecoin": "PYUSD",
      "chainId": "ethereum",
      "candidateCount": 12,
      "updated": 0,
      "deleted": 0,
      "failed": 0
    }
  ],
  "totals": {
    "candidates": 12,
    "updated": 0,
    "deleted": 0,
    "failed": 0
  },
  "budgetUsed": 0,
  "budgetLimit": 900
}

Write-enabled response

{
  "ok": true,
  "dryRun": false,
  "configs": [
    {
      "configKey": "ethereum-pyusd",
      "stablecoin": "PYUSD",
      "chainId": "ethereum",
      "candidateCount": 500,
      "updated": 12,
      "deleted": 0,
      "failed": 1
    }
  ],
  "totals": {
    "candidates": 500,
    "updated": 12,
    "deleted": 0,
    "failed": 1
  },
  "budgetUsed": 37,
  "budgetLimit": 900
}

Returns stablecoins tracked by CoinGecko or DefiLlama that Pharos does not yet monitor, surfaced by the Monday CoinGecko discovery scan plus quarter-hourly DefiLlama residual upserts.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Query parameters

Malformed limit / offset values return 400 instead of silently defaulting.

Response

{
  "candidates": [DiscoveryCandidate, ...],
  "total": 12
}

`DiscoveryCandidate` fields

Dismisses a discovery candidate so it no longer appears in the active list. Dismissed candidates will not resurface unless their market cap crosses 10× the value at dismissal time.

Direct ops-api CLI example: CF-Access-Client-Id: <id> and CF-Access-Client-Secret: <secret>

Path parameter: :id — candidate ID from GET /api/discovery-candidates

Response

{ "ok": true }

Error responses: 404 if the candidate is not found or is already dismissed.