API
The backend exposes a read-only REST API built with FastAPI. All data is pre-fetched by a background scheduler — endpoints only read from cache and return instantly.
Interactive Docs
FastAPI auto-generates interactive documentation. You can explore all endpoints, inspect request/response schemas, and run live requests from your browser.
Endpoints
GET/api/current
Returns the latest on-chain snapshot fetched by the scheduler (refreshed every 15 minutes). Returns 503 if no snapshot has been fetched yet.
Response: bridged_dai, sdai_total_assets, ssr_apy, amplification_ratio, sdai_apr, fetched_at (ISO-8601).
GET/api/dataset
Returns computed sDAI APR data points for a date range, read from the local cache.
Query params: start (YYYY-MM-DD), end (YYYY-MM-DD), interval (Daily | Weekly).
Response: data_points (array) and latest (most recent point). Each point includes timestamp, bridged_dai, sdai_total_assets, ssr_apy, amplification_ratio, sdai_apr.
Returns 404 if no cached data exists for the requested range.
GET/api/history
Returns raw cached rows for a date range without computing APR fields. Useful for inspecting the underlying on-chain values.
Query params: start (YYYY-MM-DD), end (YYYY-MM-DD).
Response: rows array, each with date, bridged_dai, sdai_total_assets, ssr_apy.
GET/api/available-range
Returns the date bounds of the local cache. Used by the frontend to constrain the date picker and show range warnings.
Response: min_date, max_date (YYYY-MM-DD or null if cache is empty), total_points.
GET/api/yieldoors
Returns the top sDAI and AsDAI holders on Gnosis Network, live from Blockscout. Identifies leveraged positions (AsDAI collateral + USDC.e debt on Aave) and computes net position in DAI terms using the current sDAI vault price.
Query params: limit (integer, 1–100, default 25) — number of top holders to return.
Response: holders (array), sdai_price (DAI per 1 sDAI), fetched_at (ISO-8601). Each holder includes rank, address, sdai_balance, asdai_balance, total_sdai, sdai_value_dai, usdc_debt, net_position_dai, type ("Leveraged" | "Aave" | "Direct").
Returns 503 if Blockscout is unreachable.
GET/api/health
Returns {"status": "ok"}. Used as a container health check.