{ "openapi": "3.1.0", "info": { "title": "Pharos API", "version": "1.0.0", "description": "Stablecoin analytics API for peg monitoring, liquidity, risk, blacklist events, mint/burn flows, yield, chains, and market-structure data. Protected public routes require X-API-Key. Request email-verified access at https://pharos.watch/api/.", "contact": { "name": "Pharos", "url": "https://pharos.watch/api/", "email": "admin@pharos.watch" }, "license": { "name": "MIT", "url": "https://github.com/TokenBrice/pharos-watch/blob/main/LICENSE" } }, "externalDocs": { "description": "Full Pharos API reference", "url": "https://pharos.watch/about/api/" }, "servers": [ { "url": "https://api.pharos.watch", "description": "Public integration API" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Health", "description": "No-key canary and health probes for API availability checks." }, { "name": "Stablecoins", "description": "Current stablecoin registry, per-asset detail, reserves, summaries, and chart surfaces." }, { "name": "Peg Monitoring", "description": "Peg summaries, depeg incidents, and stress signals for stablecoin peg stability." }, { "name": "Liquidity", "description": "DEX liquidity scores, history, pool quality, and exit-capacity analytics." }, { "name": "Risk", "description": "Safety reports, bluechip ratings, redemption backstops, events, and cross-signal risk surfaces." }, { "name": "Blacklist", "description": "Issuer freeze, blacklist, unblacklist, destroy, and exposure summary data." }, { "name": "Flows", "description": "Mint and burn flow aggregates plus normalized issuance-chain event streams." }, { "name": "Yield", "description": "Yield Intelligence rankings, adapter manifests, and per-stablecoin yield history." }, { "name": "Chains", "description": "Per-chain stablecoin distribution, concentration, quality, and health surfaces." }, { "name": "Market Structure", "description": "Non-USD peg share, alternate peg composition, and public market-structure snapshots." }, { "name": "History", "description": "Historical and archive endpoints intended for slower polling or point-in-time retrieval." }, { "name": "Digest", "description": "Daily and weekly stablecoin market digest snapshots and archive indexes." }, { "name": "Status", "description": "Public operational status timelines and lightweight product telemetry." }, { "name": "Reserves", "description": "Reserve composition and redemption-support context for supported stablecoins." } ], "paths": { "/api/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "description": "No-key health check for the public API host.", "operationId": "health", "security": [], "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stablecoins": { "get": { "tags": [ "Stablecoins" ], "summary": "List stablecoins", "description": "Current stablecoin list with supply, price, peg, chain distribution, and freshness headers.", "operationId": "stablecoins", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stablecoin/{stablecoinId}": { "get": { "tags": [ "Stablecoins" ], "summary": "Stablecoin detail", "description": "Full per-coin analytics dossier for a canonical Pharos stablecoin ID.", "operationId": "stablecoinStablecoinId", "parameters": [ { "name": "stablecoinId", "in": "path", "required": true, "description": "Canonical Pharos stablecoin ID, for example `usdt-tether` or `usdc-circle`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stablecoin-summary/{stablecoinId}": { "get": { "tags": [ "Stablecoins" ], "summary": "Stablecoin summary", "description": "Lightweight per-coin price and aggregate supply snapshot.", "operationId": "stablecoinSummaryStablecoinId", "parameters": [ { "name": "stablecoinId", "in": "path", "required": true, "description": "Canonical Pharos stablecoin ID, for example `usdt-tether` or `usdc-circle`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stablecoin-reserves/{stablecoinId}": { "get": { "tags": [ "Stablecoins", "Reserves" ], "summary": "Stablecoin reserves", "description": "Live or fallback reserve composition for live-reserve-enabled assets.", "operationId": "stablecoinReservesStablecoinId", "parameters": [ { "name": "stablecoinId", "in": "path", "required": true, "description": "Canonical Pharos stablecoin ID, for example `usdt-tether` or `usdc-circle`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stablecoin-charts": { "get": { "tags": [ "Stablecoins", "History" ], "summary": "Stablecoin charts", "description": "Historical total supply chart data.", "operationId": "stablecoinCharts", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/peg-summary": { "get": { "tags": [ "Peg Monitoring" ], "summary": "Peg summary", "description": "Per-coin peg scores plus aggregate peg-monitoring summary.", "operationId": "pegSummary", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/depeg-events": { "get": { "tags": [ "Peg Monitoring" ], "summary": "Depeg events", "description": "Historical and active depeg events, filterable by stablecoin.", "operationId": "depegEvents", "parameters": [ { "name": "stablecoin", "in": "query", "required": false, "description": "Optional canonical Pharos stablecoin ID filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque keyset cursor returned as nextCursor.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "required": false, "description": "When true, returns active depeg events only.", "schema": { "type": "boolean" } }, { "name": "includeTotal", "in": "query", "required": false, "description": "When false, skips the exact total count.", "schema": { "type": "boolean" } }, { "name": "includePending", "in": "query", "required": false, "description": "When true, includes pending incidents awaiting confirmation.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/events": { "get": { "tags": [ "Risk" ], "summary": "Tape events", "description": "Materialized chronological feed of typed events (depeg, freeze, score) backed by the tape_events table. Supports filtering by type, coin, severity floor, and time window, plus keyset pagination.", "operationId": "events", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Repeatable: exact event slug (e.g. depeg.opened) or prefix wildcard (depeg.*).", "schema": { "type": "string" } }, { "name": "class", "in": "query", "required": false, "description": "Shortcut for type=.* (e.g. class=depeg).", "schema": { "type": "string" } }, { "name": "coin", "in": "query", "required": false, "description": "Repeatable canonical stablecoin id filter.", "schema": { "type": "string" } }, { "name": "pegCurrency", "in": "query", "required": false, "description": "Filter to events for a specific peg currency.", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "required": false, "description": "Filter to events on a specific chain.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive free-text search filter (trimmed and lowercased).", "schema": { "type": "string" } }, { "name": "severityFloor", "in": "query", "required": false, "description": "Drop events below this severity.", "schema": { "type": "string", "enum": [ "info", "notice", "warning", "severe", "critical" ] } }, { "name": "since", "in": "query", "required": false, "description": "Lower bound on ts (epoch ms, inclusive).", "schema": { "type": "integer" } }, { "name": "until", "in": "query", "required": false, "description": "Upper bound on ts (epoch ms, inclusive).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque keyset cursor returned as nextCursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 50, max 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "includeTotal", "in": "query", "required": false, "description": "When true, computes the exact total count.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/usds-status": { "get": { "tags": [ "Risk" ], "summary": "USDS freeze status", "description": "Sky/USDS protocol status, including whether the freeze module is currently active.", "operationId": "usdsStatus", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/bluechip-ratings": { "get": { "tags": [ "Risk" ], "summary": "Bluechip ratings", "description": "Safety ratings from bluechip.org for covered stablecoins.", "operationId": "bluechipRatings", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/dex-liquidity": { "get": { "tags": [ "Liquidity" ], "summary": "DEX liquidity", "description": "DEX liquidity scores, top pools, chain/protocol breakdowns, and quality metadata.", "operationId": "dexLiquidity", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/dex-liquidity-history": { "get": { "tags": [ "Liquidity", "History" ], "summary": "DEX liquidity history", "description": "Historical liquidity-score data for a stablecoin.", "operationId": "dexLiquidityHistory", "parameters": [ { "name": "stablecoin", "in": "query", "required": true, "description": "Required canonical Pharos stablecoin ID.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Historical lookback window in days. Defaults to 90.", "schema": { "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/report-cards": { "get": { "tags": [ "Risk" ], "summary": "Report cards", "description": "Safety report-card snapshot across liquidity, resilience, decentralization, dependency, and peg stability.", "operationId": "reportCards", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/depeg-resolver": { "get": { "tags": [ "Risk", "Peg Monitoring" ], "summary": "Depeg Duration Resolver", "description": "Per active confirmed depeg: a mechanistic resolution outlook (terminal vs recoverable) and a stratified empirical duration estimate with per-horizon resolution likelihood.", "operationId": "depegResolver", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/depeg-resolver-review": { "get": { "tags": [ "Risk", "Peg Monitoring" ], "summary": "Depeg Duration Resolver Reviewer", "description": "Review of stored DDR predictions against later depeg-event outcomes, including recovery-likelihood accuracy and observed-minus-predicted recovery duration error.", "operationId": "depegResolverReview", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/redemption-backstops": { "get": { "tags": [ "Risk", "Reserves" ], "summary": "Redemption backstops", "description": "Modeled issuer/protocol redemption routes and effective-exit scoring for configured assets.", "operationId": "redemptionBackstops", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stress-signals": { "get": { "tags": [ "Risk", "Peg Monitoring" ], "summary": "Stress signals", "description": "DEWS-style stress signals for the stablecoin universe or one selected asset.", "operationId": "stressSignals", "parameters": [ { "name": "stablecoin", "in": "query", "required": false, "description": "Optional canonical Pharos stablecoin ID filter.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Historical lookback window in days. Endpoint-specific bounds may apply.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/stability-index": { "get": { "tags": [ "Risk" ], "summary": "Pharos Stability Index", "description": "Latest Pharos Stability Index with optional detail payload and history.", "operationId": "stabilityIndex", "parameters": [ { "name": "detail", "in": "query", "required": false, "description": "When true, includes detailed input components.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/blacklist": { "get": { "tags": [ "Blacklist" ], "summary": "Blacklist events", "description": "Freeze and blacklist events with optional uppercase symbol, chain display-name or chain ID, event type, search, sort, exact-count, and pagination filters. Responses include `chainId` join keys; the `chain` query filter is display-name based.", "operationId": "blacklist", "parameters": [ { "name": "stablecoin", "in": "query", "required": false, "description": "Optional uppercase blacklist-tracker stablecoin symbol filter, for example `USDT` or `USDC`.", "schema": { "type": "string", "enum": [ "USDC", "USDT", "PAXG", "XAUT", "PYUSD", "USD1", "USDG", "RLUSD", "U", "USDTB", "A7A5", "FDUSD", "BRZ", "AUSD", "EURI", "USDQ", "USDO", "USDX", "AID", "TGBP", "MNEE", "EURC", "BUIDL", "USDP", "TUSD", "NUSD", "EURCV", "USDA", "USAT", "AEUR", "XUSD", "XAUM", "JPYC", "FRXUSD", "FIDD" ] } }, { "name": "chain", "in": "query", "required": false, "description": "Optional exact chain display-name filter, for example `Ethereum` or `Tron`. Use response `chainId` fields for programmatic joins.", "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "description": "Optional canonical chain-registry ID filter, for example `ethereum` or `tron`. When both `chain` and `chainId` are supplied, they must identify the same chain.", "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "required": false, "description": "Optional event type filter.", "schema": { "type": "string", "enum": [ "blacklist", "unblacklist", "destroy" ] } }, { "name": "q", "in": "query", "required": false, "description": "Optional case-insensitive affected-address substring search.", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort field. Defaults to `date`.", "schema": { "type": "string", "enum": [ "date", "stablecoin", "chain", "event" ] } }, { "name": "sortDirection", "in": "query", "required": false, "description": "Sort direction. Defaults to `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of events to return. Defaults to 1000; `0` maps to the default.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset. Defaults to 0.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "includeTotal", "in": "query", "required": false, "description": "When false, skips the exact total count.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/blacklist-summary": { "get": { "tags": [ "Blacklist" ], "summary": "Blacklist summary", "description": "Blacklist summary statistics, chart data, chain options, manifest-derived coverage metadata, and freeze-ledger data-quality context. Prefer tracked freeze-ledger fields over legacy active-state fields for public frozen exposure.", "operationId": "blacklistSummary", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/mint-burn-flows": { "get": { "tags": [ "Flows" ], "summary": "Mint and burn flows", "description": "Mint/burn flow aggregates for the selected window.", "operationId": "mintBurnFlows", "parameters": [ { "name": "stablecoin", "in": "query", "required": false, "description": "Optional canonical Pharos stablecoin ID filter.", "schema": { "type": "string" } }, { "name": "hours", "in": "query", "required": false, "description": "Historical lookback window in hours. Defaults to 24.", "schema": { "type": "integer", "minimum": 1, "maximum": 720 } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/mint-burn-events": { "get": { "tags": [ "Flows" ], "summary": "Mint and burn events", "description": "Individual mint/burn events for supported stablecoins.", "operationId": "mintBurnEvents", "parameters": [ { "name": "stablecoin", "in": "query", "required": true, "description": "Required canonical Pharos stablecoin ID.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Optional direction filter.", "schema": { "type": "string", "enum": [ "mint", "burn" ] } }, { "name": "chain", "in": "query", "required": false, "description": "Optional chain ID within the stablecoin's configured issuance scope.", "schema": { "type": "string" } }, { "name": "burnType", "in": "query", "required": false, "description": "Optional burn classification filter.", "schema": { "type": "string", "enum": [ "effective_burn", "bridge_burn", "review_required" ] } }, { "name": "scope", "in": "query", "required": false, "description": "`counted` returns only rows used in economic-flow aggregates. Defaults to `all`.", "schema": { "type": "string", "enum": [ "all", "counted" ] } }, { "name": "minAmount", "in": "query", "required": false, "description": "Minimum USD amount; unpriced rows are excluded when this filter is used.", "schema": { "type": "number", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset. Defaults to 0.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque keyset cursor returned as nextCursor; cannot be combined with a non-zero offset.", "schema": { "type": "string" } }, { "name": "includeTotal", "in": "query", "required": false, "description": "When false, skips the exact total count.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/yield-rankings": { "get": { "tags": [ "Yield" ], "summary": "Yield rankings", "description": "Yield-bearing stablecoin rankings with safety, benchmark-aware context, and optional publication/source-risk metadata fields.", "operationId": "yieldRankings", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YieldRankingsResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/yield-adapter-manifest": { "get": { "tags": [ "Yield" ], "summary": "Yield adapter manifest", "description": "Machine-readable source-list manifest for every yield-bearing asset, including adapter family, exact runtime source key when known, source-key pattern for runtime-resolved or disabled strategies, label, chain/project hints, lifecycle state, and methodology version.", "operationId": "yieldAdapterManifest", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YieldAdapterManifestResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/yield-history": { "get": { "tags": [ "Yield", "History" ], "summary": "Yield history", "description": "Historical yield observations for a stablecoin, with optional publication/source-risk metadata fields.", "operationId": "yieldHistory", "parameters": [ { "name": "stablecoin", "in": "query", "required": true, "description": "Required canonical Pharos stablecoin ID.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Historical lookback window in days. Defaults to 90.", "schema": { "type": "integer", "minimum": 1, "maximum": 365 } }, { "name": "mode", "in": "query", "required": false, "description": "History mode. `best` returns historically selected best-source rows; `source` requires `sourceKey`.", "schema": { "type": "string", "enum": [ "best", "source" ] } }, { "name": "sourceKey", "in": "query", "required": false, "description": "Required with `mode=source`; filters history to a single source key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YieldHistoryResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/chains": { "get": { "tags": [ "Chains" ], "summary": "Chains", "description": "Chain-level stablecoin aggregates with Chain Health Scores.", "operationId": "chains", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/non-usd-share": { "get": { "tags": [ "Market Structure", "History" ], "summary": "Non-USD share", "description": "Historical non-USD peg share series for market-structure views.", "operationId": "nonUsdShare", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Historical lookback window in days. Defaults to 5000; `0` maps to the default.", "schema": { "type": "integer", "minimum": 30, "maximum": 5000 } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/supply-history": { "get": { "tags": [ "History" ], "summary": "Supply history", "description": "Historical supply series for a stablecoin.", "operationId": "supplyHistory", "parameters": [ { "name": "stablecoin", "in": "query", "required": true, "description": "Required canonical Pharos stablecoin ID.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Historical lookback window in days. Defaults to 365.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/safety-score-history": { "get": { "tags": [ "Risk", "History" ], "summary": "Safety score history", "description": "Long-range safety-score history for a stablecoin.", "operationId": "safetyScoreHistory", "parameters": [ { "name": "stablecoin", "in": "query", "required": true, "description": "Required canonical Pharos stablecoin ID.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Historical lookback window in days. Defaults to 365.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/daily-digest": { "get": { "tags": [ "Digest" ], "summary": "Daily digest", "description": "Latest AI-generated stablecoin market digest.", "operationId": "dailyDigest", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/digest-archive": { "get": { "tags": [ "Digest" ], "summary": "Digest archive", "description": "Archive of daily and weekly digests.", "operationId": "digestArchive", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/digest-snapshot": { "get": { "tags": [ "Digest" ], "summary": "Digest snapshot", "description": "Build-time digest context snapshot for a specific digest date.", "operationId": "digestSnapshot", "parameters": [ { "name": "date", "in": "query", "required": true, "description": "Digest date slug, for example `2026-03-16`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/snapshots/index": { "get": { "tags": [ "Digest" ], "summary": "Public snapshot index", "description": "Listing of available daily public snapshots with content hashes and methodology versions.", "operationId": "snapshotsIndex", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/snapshots/{date}.json": { "get": { "tags": [ "Digest", "History" ], "summary": "Public snapshot for a single day", "description": "Full per-day public dataset snapshot (camelCase). Immutable artifact keyed by YYYY-MM-DD; served with public, immutable, max-age=1y cache headers.", "operationId": "snapshotsDateJson", "parameters": [ { "name": "date", "in": "path", "required": true, "description": "ISO 8601 date (YYYY-MM-DD) matching a row in the snapshot index.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/snapshot/{date}/stablecoin/{stablecoinId}": { "get": { "tags": [ "Digest", "Stablecoins", "History" ], "summary": "Public snapshot projection for a single coin", "description": "Per-coin slice of a daily snapshot (camelCase). Immutable artifact keyed by YYYY-MM-DD + stablecoin id; served with public, immutable, max-age=1y cache headers.", "operationId": "snapshotDateStablecoinStablecoinId", "parameters": [ { "name": "date", "in": "path", "required": true, "description": "ISO 8601 date (YYYY-MM-DD) matching a row in the snapshot index.", "schema": { "type": "string" } }, { "name": "stablecoinId", "in": "path", "required": true, "description": "Stablecoin id (lowercase-kebab).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/public-status-history": { "get": { "tags": [ "Status" ], "summary": "Public status history", "description": "Public status timeline for the Pharos system.", "operationId": "publicStatusHistory", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "window", "in": "query", "required": false, "description": "Status history window.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ] } } ], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } }, "/api/telegram-pulse": { "get": { "tags": [ "Status" ], "summary": "Telegram pulse", "description": "Lightweight public telemetry for Telegram alert surfaces.", "operationId": "telegramPulse", "parameters": [], "responses": { "200": { "description": "Successful response. See the public API reference for endpoint-specific payload fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonValue" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid API key" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Service unavailable or cache not populated" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Required for protected public routes on https://api.pharos.watch." } }, "schemas": { "JsonValue": { "description": "Endpoint-specific JSON response. See https://pharos.watch/about/api/ for detailed contracts." }, "YieldRankingsResponse": { "type": "object", "description": "Yield Intelligence rankings payload.", "required": [ "rankings", "riskFreeRate", "scalingFactor", "medianApy", "updatedAt" ], "properties": { "rankings": { "type": "array", "items": { "$ref": "#/components/schemas/YieldRanking" } }, "riskFreeRate": { "type": "number" }, "benchmarks": { "type": "object", "description": "Benchmark registry keyed by currency such as USD, EUR, and CHF.", "additionalProperties": true }, "scalingFactor": { "type": "number" }, "medianApy": { "type": "number" }, "updatedAt": { "type": "number", "description": "Unix seconds when the rankings were last computed." }, "provenance": { "type": [ "object", "null" ], "description": "Snapshot-level source, benchmark, pool, and safety provenance.", "additionalProperties": true }, "warnings": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "publication": { "oneOf": [ { "$ref": "#/components/schemas/YieldPublicationMetadata" }, { "type": "null" } ] }, "methodology": { "type": "object", "description": "Yield methodology envelope when emitted by the rankings publisher.", "additionalProperties": true }, "_meta": { "type": "object", "description": "Cache freshness metadata when present.", "additionalProperties": true } }, "additionalProperties": true }, "YieldRanking": { "type": "object", "description": "Ranked stablecoin yield row.", "required": [ "id", "symbol", "name", "currentApy", "apy7d", "apy30d", "apyBase", "apyReward", "yieldSource", "yieldType", "dataSource", "sourceTvlUsd", "pharosYieldScore", "safetyScore", "safetyGrade", "yieldToRisk", "excessYield", "yieldStability", "apyVariance30d", "apyMin30d", "apyMax30d", "warningSignals", "altSources" ], "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "currentApy": { "type": "number" }, "apy7d": { "type": "number" }, "apy30d": { "type": "number" }, "apyBase": { "type": [ "number", "null" ] }, "apyReward": { "type": [ "number", "null" ] }, "yieldSource": { "type": "string" }, "yieldSourceUrl": { "type": [ "string", "null" ] }, "yieldType": { "type": "string" }, "dataSource": { "type": "string" }, "sourceTvlUsd": { "type": [ "number", "null" ] }, "pharosYieldScore": { "type": [ "number", "null" ] }, "safetyScore": { "type": [ "number", "null" ] }, "safetyGrade": { "type": [ "string", "null" ] }, "yieldToRisk": { "type": [ "number", "null" ] }, "excessYield": { "type": [ "number", "null" ] }, "benchmarkKey": { "type": "string", "enum": [ "USD", "EUR", "CHF" ] }, "benchmarkLabel": { "type": "string" }, "benchmarkCurrency": { "type": "string" }, "benchmarkRate": { "type": "number" }, "benchmarkRecordDate": { "type": [ "string", "null" ] }, "benchmarkIsFallback": { "type": "boolean" }, "benchmarkFallbackMode": { "type": [ "string", "null" ] }, "benchmarkSelectionMode": { "type": "string", "enum": [ "native", "fallback-usd", "manual-override" ] }, "benchmarkIsProxy": { "type": "boolean" }, "yieldStability": { "type": [ "number", "null" ] }, "apyVariance30d": { "type": [ "number", "null" ] }, "apyMin30d": { "type": [ "number", "null" ] }, "apyMax30d": { "type": [ "number", "null" ] }, "warningSignals": { "type": "array", "items": { "type": "string" } }, "altSources": { "type": "array", "items": { "$ref": "#/components/schemas/AltYieldSource" } }, "provenance": { "type": [ "object", "null" ], "description": "Selected-source provenance, benchmark state, and source-switch metadata.", "additionalProperties": true }, "publicationGenerationId": { "type": [ "string", "null" ] }, "publishedRank": { "type": [ "number", "null" ] }, "liveRank": { "type": [ "number", "null" ] }, "sourceRisk": { "oneOf": [ { "$ref": "#/components/schemas/YieldSourceRisk" }, { "type": "null" } ] }, "rankChangeAttribution": { "type": [ "object", "null" ], "description": "Optional rank-change attribution with previous rank/PYS, delta, primary driver, and driver contribution hints.", "additionalProperties": true } }, "additionalProperties": true }, "AltYieldSource": { "type": "object", "description": "Retained non-selected yield source row for the same stablecoin.", "required": [ "sourceKey", "yieldSource", "yieldType", "currentApy", "apy30d", "sourceTvlUsd", "dataSource" ], "properties": { "sourceKey": { "type": "string" }, "yieldSource": { "type": "string" }, "yieldSourceUrl": { "type": [ "string", "null" ] }, "yieldType": { "type": "string" }, "currentApy": { "type": "number" }, "apy30d": { "type": "number" }, "sourceTvlUsd": { "type": [ "number", "null" ] }, "dataSource": { "type": "string" }, "sourceRisk": { "oneOf": [ { "$ref": "#/components/schemas/YieldSourceRisk" }, { "type": "null" } ] } }, "additionalProperties": true }, "YieldSourceRisk": { "type": "object", "description": "Nested source-risk evidence used by PYS v8. Missing or unknown evidence is neutral.", "properties": { "sourceRiskScore": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sourceRiskPenalty": { "type": [ "number", "null" ], "minimum": 1, "description": "PYS v8 source-risk multiplier; runtime clamps populated values to the active range." }, "sourceDepthRatio": { "type": [ "number", "null" ], "minimum": 0 }, "rewardShare": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "sourceAgeSeconds": { "type": [ "integer", "null" ], "minimum": 0 }, "observationCount30d": { "type": [ "integer", "null" ], "minimum": 0 }, "sourceSwitchCount30d": { "type": [ "integer", "null" ], "minimum": 0 }, "deploymentPlace": { "type": [ "string", "null" ], "enum": [ "native-wrapper", "issuer-savings", "lending-market", "strategy-vault", "lp-or-dex", "rwa-fund", "reward-program", "rate-derived", "price-derived", null ] }, "venueProtocol": { "type": [ "string", "null" ] }, "venueChain": { "type": [ "string", "null" ] }, "venueRiskTier": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "unknown", null ], "description": "`unknown` remains neutral and should be treated as missing evidence." }, "investabilityFlags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "YieldPublicationMetadata": { "type": "object", "description": "Generation metadata for published yield payloads.", "properties": { "generationId": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "number", "null" ] }, "cutoffAt": { "type": [ "number", "null" ] }, "schemaVersion": { "type": [ "integer", "null" ], "minimum": 1 }, "status": { "type": [ "string", "null" ], "enum": [ "staged", "published", "failed", null ] } }, "additionalProperties": true }, "YieldAdapterManifestResponse": { "type": "object", "description": "Yield adapter source-list manifest payload.", "required": [ "methodologyVersion", "updatedAt", "entries" ], "properties": { "methodologyVersion": { "type": "string" }, "updatedAt": { "type": "number", "description": "Unix seconds for the methodology snapshot backing the manifest." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/YieldAdapterManifestEntry" } } }, "additionalProperties": true }, "YieldAdapterManifestEntry": { "type": "object", "description": "One yield adapter manifest row.", "required": [ "stablecoinId", "coinSymbol", "family", "sourceKey", "label", "lifecycle", "methodologyVersion", "updatedAt" ], "properties": { "stablecoinId": { "type": "string" }, "coinSymbol": { "type": "string" }, "family": { "type": "string", "enum": [ "onchain", "protocol-api", "defillama", "defillama-auto", "rate-derived", "price-derived", "intentional-gap" ] }, "sourceKey": { "type": [ "string", "null" ], "description": "Exact runtime source key when the strategy publishes a joinable yield_history/rankings source; null for disabled or runtime-resolved strategies." }, "sourceKeyPattern": { "type": [ "string", "null" ], "description": "Human-readable source-key pattern or would-be key for runtime-resolved or disabled strategies." }, "label": { "type": "string" }, "chain": { "type": [ "string", "null" ] }, "project": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "quarantineReason": { "type": [ "string", "null" ] }, "methodologyVersion": { "type": "string" }, "updatedAt": { "type": "number", "description": "Unix seconds for the methodology snapshot backing the manifest entry." } }, "additionalProperties": true }, "YieldHistoryResponse": { "type": "object", "description": "Per-stablecoin yield history payload.", "required": [ "current", "history", "methodology" ], "properties": { "current": { "oneOf": [ { "$ref": "#/components/schemas/YieldHistoryPoint" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/YieldHistoryPoint" } }, "warning": { "type": "string" }, "methodology": { "type": "object", "description": "Yield methodology envelope.", "additionalProperties": true }, "publication": { "oneOf": [ { "$ref": "#/components/schemas/YieldPublicationMetadata" }, { "type": "null" } ] } }, "additionalProperties": true }, "YieldHistoryPoint": { "type": "object", "description": "One historical yield observation.", "required": [ "date", "apy", "apyBase", "apyReward", "exchangeRate", "sourceTvlUsd", "warningSignals" ], "properties": { "date": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "apy": { "type": "number" }, "apyBase": { "type": [ "number", "null" ] }, "apyReward": { "type": [ "number", "null" ] }, "exchangeRate": { "type": [ "number", "null" ] }, "sourceTvlUsd": { "type": [ "number", "null" ] }, "warningSignals": { "type": "array", "items": { "type": "string" } }, "sourceKey": { "type": [ "string", "null" ] }, "yieldSource": { "type": [ "string", "null" ] }, "yieldSourceUrl": { "type": [ "string", "null" ] }, "yieldType": { "type": [ "string", "null" ] }, "dataSource": { "type": [ "string", "null" ] }, "isBest": { "type": "boolean" }, "sourceSwitch": { "type": "boolean" }, "publicationGenerationId": { "type": [ "string", "null" ] }, "sourceRisk": { "oneOf": [ { "$ref": "#/components/schemas/YieldSourceRisk" }, { "type": "null" } ] } }, "additionalProperties": true } } } }