Pharos API Reference

Reference section

Surface Split

The runtime now uses three HTTP lanes:

• https://api.pharos.watch is the external integration API. Protected public routes require X-API-Key.
• https://site-api.pharos.watch requires X-Pharos-Site-Proxy-Secret for allowlisted GET reads, internal GET /api/stablecoin-detail-snapshot-inputs, and POST /api/telegram-adoption. The build-input read is denied through browser /_site-data/* and the public API host.
• /_site-data/* is the same-origin Pages Functions proxy used by browsers on pharos.watch, ops.pharos.watch, stablecoin-dashboard.pages.dev, and subdomains of stablecoin-dashboard.pages.dev.

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

The same static lane serves https://pharos.watch/datasets/<topic>/latest.{csv,json,ndjson} and dated /datasets/<topic>/<YYYY-MM-DD>.{csv,json,ndjson} artifacts, retained for 90 days. Topic IDs are a never-break external contract owned by PUBLIC_DATASET_TOPICS in shared/lib/api-endpoints/datasets.ts. Each latest URL is a Pages 200 rewrite to the same-extension dated file; https://pharos.watch/sheets/<topic>.csv rewrites directly to dated CSV. Missing dated URLs mean no currently published artifact, including retention pruning—not an observed empty dataset or proof that no refresh ran. Shared current-snapshot freshness gates reject dates beyond two UTC dates; per-topic alias checks do not age-check each topic. These unauthenticated JSON-LD DataDownload URLs have extension-compatible content types, Access-Control-Allow-Origin: *, and cache policies from public/_headers. Generator/backdating mechanics belong to scripts/maintenance/generate-public-datasets.ts.

The depeg-history topic is retrospective windowed history, not a historical point-in-time event-state sample. The dated filename selects the 90-day UTC event-start window ending on that date; peaks, recovery and closure fields come unchanged from the captured event ledger and may describe observations after the market snapshot. Its JSON/NDJSON metadata and CSV preamble report the ledger observation-end clock as asOfISO, the exact shard capture identity as sourceGeneration, the observation-start clock as sourceObservationStartedAtISO, and the separate market snapshot clock as windowSnapshotAsOfISO. Other topics retain the immutable market-envelope clock. A historical regeneration may change retrospective event rows and their capture provenance; it must not relabel later state as information known at the older market clock. Missing or mismatched ledger-capture provenance fails generation rather than inventing historical peaks or masking later recoveries.

The static depeg-history dataset publishes each event's id as a string in JSON and NDJSON (and as text in CSV), preserving the established export contract. This differs from the numeric event IDs in the runtime depeg-events API and internal archive rows.

Public onboarding artifacts are served at https://pharos.watch/openapi.json, https://pharos.watch/postman/pharos-api.postman_collection.json, and https://pharos.watch/postman/pharos-api.postman_environment.json. Import both Postman files and replace the environment apiKey placeholder with a real X-API-Key. OpenAPI includes named Yield Intelligence ranking/history schemas; Postman includes best-source and source-key history examples. The integration/read catalogue is owned by scripts/lib/public-api-artifact-catalog.ts, not an inventory of every no-key route: it excludes admin routes, supporter-key claims, feedback, Telegram webhook/Mini App endpoints, and dynamic OG images. Request keys through https://pharos.watch/api/.

Browser consumers use same-origin /_site-data/* via src/lib/api.ts; production Pages targets https://site-api.pharos.watch through SITE_API_ORIGIN. Direct integrations and CI smoke target https://api.pharos.watch with X-API-Key for protected reads, including /api/telegram-pulse. Pages build-input syncs read allowlisted GET endpoints through https://stablecoin-dashboard.pages.dev/_site-data/* with an allowed site caller header and reject missing/invalid input. A release can retain failed producers' committed snapshots, but fails before build if all three fail or a failed public-dataset refresh cannot roll back cleanly.

Production Pages does not proxy public /api/* POST requests. https://pharos.watch/api/ is the API access page: it presents the free grades feed, the supporter-key claim, and the partner-key contact. Its browser POST is the supporter-key claim, which goes cross-origin to https://api.pharos.watch/api/donor-key-claims with a normal CORS preflight for the JSON POST request.

The direct Worker cache profiles below describe responses from api.pharos.watch / site-api.pharos.watch. Pages /_site-data/* forwards the upstream cache policy, Age, and Date without adding a second Cache API lifetime, so it cannot make a nearly expired Worker response fresh again.

Reference section

Public API Auth

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

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

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

• GET /api/safety-grades (the free lane: one Safety Score and grade per tracked stablecoin)
• GET /api/dependency-graph/v1
• GET /api/dependency-scenarios/v1
• GET /api/health
• GET /api/og/*
• POST /api/feedback
• POST /api/donor-key-claims (the supporter-key claim: a Sign-In-With-Ethereum signature from an eligible donor wallet, rate-limited per IP before the body is read)
• POST /api/telegram-webhook
• POST /api/telegram-mini-app/session
• POST /api/telegram-mini-app/mutate

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

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

Admin/operator routes are also outside the public API-key gate, but remain Cloudflare-Access-gated through ops-api.pharos.watch or the ops.pharos.watch/api/admin/* Pages proxy. The public API host rejects registered admin paths and their configured child families before API-key auth, including /api/api-keys and /api/api-keys/...; a public API key cannot reach them.

Self-serve key issuance is retired: the lane was removed on 2026-09-29, so POST /api/api-key-requests and POST /api/api-key-requests/verify are unregistered and respond like any unknown API path on the public host (401 without a valid X-API-Key, 404 with one), while existing tier="self-serve" keys keep authenticating until they drain through their 60-day expiry (about 2026-11-06). The lane's D1 tables (api_key_requests, api_key_request_rate_limit_v2, api_key_self_serve_email_claims, api_key_self_serve_issuance_limits) are left in place and dropped in a separate follow-up rollout after this Worker is live; the rate-limit table's daily prune continues until then, and the operator may delete the lane's now-unused Worker secrets with Wrangler (names only, never values): API_KEY_SELF_SERVE_IP_SALT, API_KEY_SELF_SERVE_EMAIL_HASH_PEPPER, API_KEY_SELF_SERVE_REQUEST_PEPPER, API_KEY_SELF_SERVE_EMAIL_FROM, API_KEY_SELF_SERVE_EMAIL_REPLY_TO, API_KEY_SELF_SERVE_PUBLIC_BASE_URL, RESEND_API_KEY. Keyed access is a supporter key, claimed by donors on the access page at https://pharos.watch/api/ through POST /api/donor-key-claims, or an operator-issued partner key (internal tier standard) requested through the private channel on that page: Telegram DM to @TokenBrice, with X DM to @PharosWatch as secondary, and a human reply within PARTNER_KEY_REPLY_BUSINESS_DAYS (2) business days. The reply window and the freshness stamped on every response are service commitments, not a contractual SLA.

POST /api/donor-key-claims issues the supporter key and is exempt from X-API-Key. An externally-owned wallet signs an EIP-4361 message with personal_sign for domain pharos.watch and URI https://pharos.watch/api/, valid for 5 minutes, then posts { "message", "signature" }. Eligibility requires at least $10 in receipt-date USD from qualifying-stablecoin donations whose current grades are A+, A, A-, B+, B, or B-. Qualifying stablecoins are the reviewed (chain, token contract) pairs in DONOR_KEY_QUALIFYING_STABLECOINS (shared/lib/funding/donor-eligibility.ts): each coin counts only on its reviewed contract deployments, so bridged or same-ticker tokens never qualify, and EURC is valued at the ECB EUR/USD reference rate for the receipt date, never 1:1. The threshold is inclusive with floating-point tolerance, addresses are matched case-insensitively, founder rows count, and pool payouts do not. The donor list is updated every Sunday. Smart-contract wallets, Giveth streams, and exchange withdrawals cannot claim.

All claim responses use Cache-Control: no-store. 201 returns the plaintext token once, with tier donor, 10 requests per minute, and no expiry. Every failure returns { "error": "message", "reason": "code" }; codes are defined once by DONOR_KEY_CLAIM_FAILURE_REASONS in shared/contracts/api-keys.ts:

The 403 ineligible body additionally returns ledgerUpdatedAt (Unix seconds), qualifyingUsd (number), and countedAssets (string array of counted stablecoin labels). A missing coin grade is unavailable, not a zero observation: if counted donations plus donations with unavailable grades could reach the threshold, the route returns 503 grade_unavailable with Retry-After: 60 instead of 403. Published grades outside A/B do not count. Missing or held canonical accepted V9 publications return 503 safety_scores_unavailable.

One key is issued per wallet, atomically with its api_key_donor_claims row. Existing claim lookup precedes grading; later grade changes do not alter already-issued keys. Re-signing never rotates a key. For a lost key or record removal, message @TokenBrice on Telegram, with @PharosWatch on X as secondary. An operator verifies the donating wallet before rotating a lost key. Claim outcome logs contain codes only, not signed messages, signatures, or wallet addresses.

Claims are enabled by DONOR_KEY_CLAIMS_OPEN in shared/lib/public-api-contract.ts. The DONOR_KEY_CLAIM_RATE_LIMIT binding admits 10 attempts per 60 seconds per client IP before reading the body. Donor keys always use D1-backed auth and quotas, not the isolate fast-cache path. Migration 0238_api_key_donor_claims.sql must precede deployment; docs/api-page.md owns the live claim, quota, replay, and access-gate acceptance sequence.

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

Self-serve authentication also consults durable revocation tombstones in the D1 table api_key_self_serve_revocations (worker/src/lib/api-key-auth.ts). The tombstone is keyed on the key prefix, not on the api_keys row id, so it survives deactivating, rotating, or deleting that row: a revoked prefix stays refused until the tombstone itself is removed. The writer was the retired self-serve admin route, so no new tombstones are written, but existing ones keep blocking their prefixes while self-serve keys drain. Because that check is only answerable from D1, self-serve keys are never served from the isolate-local verified-key cache and fail closed whenever the D1 lookup is unavailable.

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

Reference section

Stablecoin IDs

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

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

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

Reference section

Response Headers

Endpoints backed by the cron cache include these additional headers:

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

DEX liquidity keeps its dataset-wide advisory in Warning and also emits a nullable warning on each coin row. Coin-specific TVL cliffs or pool-count drops produce affected-coin advisories and do not trigger a global advisory on successful runs when they are the only findings. Mixed global advisories can include those flags in their raw flag list; provider failures, near-guard proximity, and unscoped findings remain global. The advisory comes from the latest liquidity producer outcome, excluding neutral or locked skips. Coin detail consumers use the row advisory while retaining the producer timestamp for independent freshness checks; older responses without the field retain their global warning.

DEX full and website table responses assess cohort freshness from the newest published row's updated_at, the producer generation clock. Dormant rows do not age the whole dataset: each retains its own updatedAt, freshness warning, and unavailable reasons. The website coin projection instead assesses headers and cache lifetime from that selected row's own clock; a fresh sibling cannot refresh it.

A failed liquidity producer-status read is not an empty advisory: each row carries advisoryUnavailableReason: "dex-advisory-read-failed" and a non-null warning, the response emits a 199 advisory, and cache policy is no-store. Successful zero-row status reads retain a nullable advisory with no failure reason.

DDR secondary errata/lock-deferral read failures retain immutable forecasts with _meta.degradedReason: "secondary-overlay-unavailable" and errata-overlay-read-failed / lock-deferral-overlay-read-failed details; responses are no-store. Canonical projection failures return 503 for /api/depeg-events, naming incident-projection-read-failed or incident-projection-invalid; see projection admission. /api/peg-summary retains accepted history as degraded/no-store with that reason and its original clock, or returns 503. Non-NAV assets with missing/nominal primary prices expose currentPriceUnavailable: true and null deviation, excluded from observed at-peg counts.

Reference section

Response Body Freshness (_meta)

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

Shape:

{
  "_meta": {
    "updatedAt": 1710500000,
    "ageSeconds": 42,
    "status": "fresh",
    "assessedAt": 1710500042,
    "freshBudgetSec": 4800,
    "degradedBudgetSec": 7200
  }
}

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

Generic, chains, and yield producers publish assessment time and effective budgets, including response-ready cache injection. Readers accept legacy cached metadata without these fields but must treat its assessment/budget as unknown, not infer that it used the current policy. Chains can also be degraded by its named dependencies.reportCards verdict even when snapshot age is fresh. Timestamps over the public 60-second future allowance are degraded and not cacheable; this is timestamp validity, not an age-band change.

GET /api/stress-signals publishes assessedAt, freshBudgetSec, degradedBudgetSec, and newestReturnedComputedAt beside each row's computedAt and ageClassification. The newest-returned clock is the aggregate comparison basis for retainedLastValid; single-coin responses have no peer-generation comparison (null). These are row-generation verdicts, not a claim that every source used by DEWS was observed at that time.

Event feeds (events, depeg-events, blacklist, mint-burn-events) derive freshness from confirmed producer output through cron-output.ts, never request time, the newest matching event, or an ok attempt without output. Productive degraded runs may advance the output clock; explicit outputPublishedAt: null cannot. An empty filtered page is fresh only with a fresh confirmed observation, including a persisted quiet scan. No confirmed output in retained cron history means stale/no authoritative recent output; a failed lookup means unknown. Both use Cache-Control: no-store, Warning: 199, and X-Data-Age: unavailable, with the reason headers above. /api/events also publishes null updatedAt / ageSeconds and status: "stale" | "unknown" plus reason in _meta; admitted observed clocks omit the optional reason, even when their age is stale. Safety-score history uses the same producer-authority headers. Blacklist-summary retains the producing snapshot's clock and lookup state, not its materialization/request time.

For uncounted offset pages, total is a conservative observed lower bound and totalExact is false. A nonempty offset page establishes the offset plus its observed rows (and any lookahead row); an empty page establishes only zero, even at offset 50,000. Uncounted cursor continuations report only their observed page/lookahead bound. Blacklist defaults to uncounted pages; use includeTotal=true for an exact filtered count.

Yield routes override the generic 8x/12x runway: GET /api/yield-rankings (full and summary) and GET /api/yield-history use the shared yield-data bands: fresh through 7,200 seconds (2x the hourly producer interval), degraded through 14,400 seconds (4x), then stale. Both non-fresh states return Cache-Control: no-store; age-based verdicts emit HTTP Warning: 110, while yield-history timestamps beyond the future allowance emit 199. Their _meta includes required assessedAt (response-time Unix seconds), freshBudgetSec, degradedBudgetSec, and nullable reason alongside updatedAt, ageSeconds, and status. Non-fresh publication age names yield-publication-age. History freshness measures the authoritative publication cutoff, not the last point in a requested historical window; unavailable authority is stale with publication-cutoff-unavailable.

Yield wire contract: Full and summary rankings and history publish the expanded evidence directly.

• Summary rows expose benchmarkSelectionMode and provenance.sourceMaxAgeSeconds. Summary benchmarkIsFallback describes feed fallback independently of currency-selection policy; readers use explicit selection mode rather than inferring it from the fallback flag.
• Detailed ranking provenance retains nullable sourceObservedAt and sourceAgeSeconds without dropping the remaining evidence. Unavailable rankings medianApy is null. sourceRisk.rewardShare is nonnegative with no upper bound, preserving raw ratios above 1 in rankings, alternatives, and history.

Yield source freshness is separate from publication freshness. Unknown observation evidence must not be replaced with publication time or treated as refreshed merely because the snapshot was newly served. Source and comparison-anchor ages advance at read time; selected sourceRisk.sourceAgeSeconds follows authoritative provenance, while alternate ages advance from the publication clock and preserve unavailable ages.

Yield history may include a top-level warning explaining publication-cutoff fallback. A point with unreadable stored warnings returns warningSignals: [] with warningSignalsStatus: "unreadable"; that marker is not a clean warning assessment. Each point's pysReproducibility is exact, not-scored, legacy-partial, or invalid: only exact affirms reproduction from the publish-time input snapshot, while legacy/absent evidence and invalid snapshots remain explicit.

Selected endpoints with generic freshness _meta:

The resolver and resolver-review routes instead use domain _meta (computedAt, expiresAt, degraded, and diagnostics), not the generic shape above. Their HTTP freshness headers are assessed from the served snapshot's computedAt.

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

The frontend apiFetchWithMeta() helper (src/lib/api.ts) reads generic _meta when present. For header-only responses it prefers X-Data-Updated-At, then falls back to X-Data-Age; unavailable or invalid clocks remain explicit.

Reference section

Cache-Control Profiles

Active GET /api/stablecoin/{stablecoinId} reads refresh expired detail caches in the background only while buildFreshnessMeta classifies the generation as fresh using API_FRESHNESS_MAX_AGE_SEC.stablecoins. Older generations refresh synchronously so the first visitor receives the refreshed detail; provider failures may retain the original stale generation below the 24-hour cache ceiling, with its original clock and warning.

These profiles are ceilings, not a fresh lifetime renewed on each read. Freshness-aware responses clamp browser max-age, shared s-maxage, and the combined TTL plus stale-while-revalidate window to the remaining fresh runway. At the boundary (no whole second remains), or for a non-fresh/invalid timestamp, the response is no-store. Generic responses retain 8x/12x bands, chains 1x/2x, and yield its own publication bands; no cadence or SLO is changed. Edge cache reads reject entries whose HTTP Age/Date has exhausted that bounded lifetime. Proxies preserve Age and Date; clients interpreting cached _meta must distinguish its assessedAt from the current wall clock.

Profile strings below come from API_CACHE_PROFILES (shared/lib/api-cache-profiles.ts), except route-local immutable snapshots (IMMUTABLE_CACHE_CONTROL in worker/src/api/snapshot.ts) and telegram-pulse's equivalent custom policy.

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

Reference section

Polling Guidance

Recommended minimum polling cadence for external integrations:

Client best practices:

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

Reference section

Rate Limits

Protected public API traffic is limited per key; exemptions are listed in Public API Auth and owned by publicApiAccess in shared/lib/api-endpoints/. The free Safety Score grades, dependency graph, and dependency scenarios routes also use SAFETY_GRADES_RATE_LIMIT: 120 requests per 60 seconds per client IP, with 429 / Retry-After: 60 on exhaustion and 503 if the limiter is unavailable. Telegram ingress and supporter claims use separate limiters and authentication.

Missing or invalid keys receive 401 with Unauthorized: valid X-API-Key required. Safety grades are free at /api/safety-grades; see https://pharos.watch/api/ for supporter and partner keys. Supporter claim throttling is separate from the issued key's quota; see Public API Auth.

Reference section

Error Response Conventions

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

Rule: Cache-passthrough handlers return 503 when data hasn't been populated yet or when the stored cache payload is malformed and rejected at read time. Query handlers that find no matching rows return 200 with empty results (e.g., { events: [], total: 0 }). When MAINTENANCE_MODE is set to "true", all non-OPTIONS requests immediately return 503 with { "error": "maintenance", "message": "..." } — used during DB migrations. OPTIONS CORS preflights are handled before the maintenance gate. The gate is on the Worker fetch path only (worker/src/handlers/http/gates.ts, called from worker/src/handlers/http/request-dispatch.ts); the scheduled() entrypoint in worker/src/index.ts never consults it, so cron jobs keep executing and keep writing D1 while maintenance mode is armed. Arming it sheds HTTP traffic, not scheduled writes: a migration or D1-pressure incident that needs quiet writes must disable the affected cron triggers as a separate step.

Public status history: GET /api/public-status-history returns 503 with { "error": "Public status history unavailable" } and Cache-Control: no-store when its transition-ledger query fails, even when current public health is healthy. Only a successful query may return an empty transitions array and lastChangedAt: null; successful responses retain public, max-age=60. The public status page presents missing or failed runway history as unavailable, not as an empty incident observation.

Reference section

Method Gating Policy

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

• GET is accepted for read endpoints (plus admin debug/status endpoints, GET /api/backfill-dews, and dry-run repair previews for GET /api/backfill-dews?repair=...&dry-run=true).
• HEAD is not accepted as an implicit GET; known routes return 405 with the route's Allow methods.
• POST is accepted for mutating admin endpoints, POST /api/feedback, POST /api/donor-key-claims, POST /api/telegram-webhook, POST /api/telegram-mini-app/session, and POST /api/telegram-mini-app/mutate.
• GET, POST is accepted on /api/api-keys so operators can list keys and create a new key through the same route.
• GET is accepted on /api/api-keys/lifecycle-summary for counts-only Triage credential monitoring.
• POST is accepted on /api/api-keys/:id/update, /api/api-keys/:id/deactivate, and /api/api-keys/:id/rotate.
• /api/backfill-dews allows GET for the historical backtest and for repair=...&dry-run=true previews; mutating repair runs are POST-only.
• Unknown public /api/* requests can return 401 first when the API key is missing or invalid. After lane auth succeeds, unregistered paths return 404. Known paths with disallowed methods, including unsupported verbs, return 405 with the route's allowed methods in Allow, not a generic GET, POST fallback.

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

Reference section

Safety Score Availability

Reference section

Reserve Availability

For GET /api/stablecoin-reserves/{stablecoinId}, optional sync.collectionEligibility is { scheduled, reason } with successful-response reasons active, quarantined, frozen, or delisted; only active is scheduled. Suspended, unconfigured and pre-launch assets return 404, not additional eligibility values. Readable inactive configurations may serve retained historical evidence without refreshing its clocks or admitting it to active collection. See the reserve API contract.

Reference section

Blacklist Valuation Availability

GET /api/blacklist-summary publishes stats.destroyedTotal, recentFreezeAmount24hUsd, recentFreezeAmount7dUsd, and values in perCoinFrozenTotal / perCoinDestroyedTotal as number | null. Null means valuation unavailable, not zero. Mixed cohorts publish only the known subtotal: optional stats.valuationCoverage qualifies destroyed, recent24h, recent7d, perCoinFrozen, and perCoinDestroyed with { knownCount, unavailableCount }. A positive unavailable count makes that subtotal partial; absent coverage means unknown completeness. Fully priced cohorts and observed zero remain numeric, including zero for an empty cohort.

Producer-written blacklist-summary snapshots also publish optional refresh: { observedAt, behindConfigs[] }: when the scheduled producer rebuilt the observed totals, and each config (configKey, symbol, chainName, nullable lastSucceededAt) that did not reach its safe head that run. The freshness headers keep the oldest full-coverage clock; refresh lets clients say which sources hold it back rather than calling the whole tracker stalled. Absent refresh (request-path materialization) means no producer catch-up detail.

Reference section

Supply Provenance

GET /api/stablecoins exposes optional per-asset supply provenance on peggedAssets[]. The owning schemas are SupplyGapFillProvenanceSchema and SupplyChainGuardProvenanceSchema in shared/types/market.ts; Supply Snapshot owns admission and carry limits.

Reference section

Public Endpoints

On https://api.pharos.watch, these routes require X-API-Key unless marked Authentication: exempt. OpenAPI schemas describe bodies; shared/lib/api-endpoints/definitions.ts owns auth/cache flags.

GET /api/stablecoin/{stablecoinId} supply-history/stablecoins-cache fallbacks publish _meta: newest served token source time, response assessment time, 72-hour history budgets and stale floor detail-history-fallback. They emit Warning: 110, Cache-Control: no-store, and neither enqueue detail-cache publication nor renew old rows. Invalid/missing history clocks stay null/unknown with the timestamp-admission reason. Stale external history without fresher D1 rescue uses this same contract.

GET /api/mint-burn-flows aggregate/per-coin _meta preserves the confirmed-output lookup verdict through cached fallbacks. Missing/failed lookup cannot substitute attempt/event-hour clocks for sync.lastSuccessfulSyncAt; unavailable metadata and headers retain their machine-readable reason.

Aggregate FTQ also publishes gauge.classificationReason and independent _meta.dependencies.flightToQuality Safety Score evidence (generationId, original updatedAt, ageSeconds, status, reason, freshBudgetSec). Unavailable classification yields flightToQuality: null / flightIntensity: null, never inactive/zero. Fresh, cached and fallback paths re-admit the canonical index and expose the same advisory without renewing the flow clock; per-coin responses have no market-wide FTQ dependency. See FTQ classification for the separate consumer budget and recovery semantics.

GET /api/stablecoin-summary/{stablecoinId}: supplyUsd fields current, prevDay, prevWeek, prevMonth, change1d, change7d, change30d are number | null. Absent/empty/wholly invalid current peg buckets yield null current and currentUnavailableReason: "supply-buckets-missing"; observed supply, including 0, clears the reason to null. Changes require observed current and historical values; missing current never implies a negative delta. supplyByPegUsd contains only finite buckets ({} if none). Assets absent from the stablecoins publication return 404. GET /api/dex-liquidity and history publish nullable totalVolume24hUsd, totalVolume7dUsd, history volume24h, pool volumeUsd1d and scoreComponents.volumeActivity. Measured volume availability (v6.9) owns 72h admission, complete-only totals, availability-record fields, measured zero, global/legacy rows and the 50% activity/score coverage gate. Each /api/dex-liquidity row also carries optional liquidityScoreUnavailableReason: null when rated, otherwise the machine code of whoever nulled the score — activity-coverage-below-floor, activity-missing, activity-stale, activity-completeness-unknown, no-retained-pools, or invalid-coverage-evidence (publisher quarantine). Rows scored before the field existed publish null; consumers must not infer a cause. See DEX Liquidity Score. DEX price publication. Malformed coverage is quarantined per asset/point, retaining independent measurements. Price admission, nullable fields and the separate 24h clock do not alter liquidity X-Data-Age. GET /api/mint-burn-flows valuation-gated nullable fields: aggregate coins[]: netFlow24hUsd, netFlow7dUsd, netFlow30dUsd, netFlow90dUsd, netFlowDirection24h; chains[].netFlow24hUsd, hourly[].netFlowUsd, gauge.flightToQuality, gauge.flightIntensity; per-coin netFlowUsd, chains[].netFlowUsd. Valuation completeness (v6.23) owns gates, exact/partial/legacy semantics and gauge reweighting. valuation shapes: coin { window24h, baseline, netFlow7d, netFlow30d, netFlow90d, netFlow7dBound?, netFlow30dBound?, netFlow90dBound? } (v6.25 bounds: { kind: "lower" | "upper", valueUsd } or null; a proven one-sided bound on a withheld net); aggregate chain/hourly completeness labels; per-coin totals/chains { completeness, mintCompleteness, burnCompleteness, unpricedMintEventCount, unpricedBurnEventCount }. Absent records are unknown, never complete. GET /api/stablecoin-charts retains invalid/omitted buckets as null, explicit zero as zero; see chart publication.

<!-- GENERATED-START: public-endpoints --> <!-- Generated by scripts/maintenance/generate-api-reference.ts from public/openapi.json and shared/lib/api-endpoints/definitions.ts. --> <!-- Endpoint narratives are authored in scripts/lib/public-api-artifact-catalog.ts and emitted through OpenAPI. Supplemental notes and source-backed examples live in the generator. Do not edit this block by hand. -->

Reference section

Pages Function endpoints

These website-host routes are outside the public Worker API and OpenAPI catalogue. Their caller gate checks an allowlisted UI hostname from Origin, falling back to Referer, not strict same-origin equality; external integrations should use the Worker endpoints above.