{ "openapi": "3.1.0", "info": { "title": "Hylo Public API", "version": "1", "description": "> **⚠️ Work in progress.** This API is not fully stable yet: paths and response shapes may still change without notice or versioning. Pin nothing critical to it until this notice is removed.\n\nRead-only Hylo protocol data: wallet PnL, revenue, daily digest, event feed, state history, prices. Amounts are exact decimal strings (never floats); timestamps ISO-8601 UTC; optional keys omitted, not null; markets are SOL, cbBTC, HYPE (USDC is the swap counter-asset). CORS-open; Cache-Control per route." }, "servers": [ { "url": "https://api.hylo.so", "description": "Production" }, { "url": "/", "description": "This host" } ], "paths": { "/v1/status": { "get": { "summary": "Data freshness", "operationId": "getStatus", "responses": { "200": { "description": "Freshness markers; any field may be null on an empty database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Meta"] } }, "/v1/protocol/fees": { "get": { "summary": "Protocol revenue", "operationId": "getFeesDaily", "parameters": [ { "$ref": "#/components/parameters/days" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" } ], "responses": { "200": { "description": "`period` aggregates cover exactly `since`..`until`; `allTime` spans the whole history. Raw `fee` is in the fee token's units; `usd` are historically priced (a lower bound on early days with no price data). Cache-Control: public, max-age=300.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeesDaily" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Protocol"] } }, "/v1/protocol/digest": { "get": { "summary": "Daily digest", "operationId": "getDaily", "parameters": [ { "$ref": "#/components/parameters/days" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" } ], "responses": { "200": { "description": "One entry per date that has data; absent dates are not zero-filled. A market appears only on days it had activity. Cache-Control: public, max-age=300.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Daily" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Protocol"], "description": "Per-day, per-market protocol activity. New fields may appear without notice." } }, "/v1/protocol/activity": { "get": { "summary": "Event feed", "operationId": "getActivity", "description": "On-chain events unioned with balance-derived PnL settlements (`source: derived`; no signature appears in both). Cursor-paginated, newest first. `signature=` returns one transaction's events (no cursor).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size; values outside 1..200 are clamped." }, { "name": "before", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from the previous page's `cursor`. Omit for the newest page. Malformed → 400." }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated `eventType` filter, e.g. `SwapExoToUsdc,SettleRebalancePnl`. Blank = no filter." }, { "name": "program", "in": "query", "schema": { "type": "string", "enum": ["exchange", "stability-pool"] }, "description": "Blank = no filter." }, { "name": "signature", "in": "query", "schema": { "type": "string" }, "description": "Per-tx mode: all events of this transaction signature." } ], "responses": { "200": { "description": "Cache-Control: public, max-age=10.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Activity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Protocol"] } }, "/v1/wallet/{address}/pnl": { "get": { "summary": "Wallet PnL", "operationId": "getPnl", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Wallet public key (base58)." }, { "name": "tokens", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated token symbols to include (default: all supported)." }, { "name": "lots", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include open/closed lot detail." } ], "responses": { "200": { "description": "Per-token PnL with totals; `warnings` lists partial-data conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pnl" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Wallet"] } }, "/v1/wallet/{address}/pnl/history": { "get": { "summary": "Wallet PnL history", "operationId": "getPnlHistory", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "schema": { "type": "string", "default": "1d" }, "description": "Bucket size, e.g. `1h`, `1d`." }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365 }, "description": "Trailing window; default depends on granularity." } ], "responses": { "200": { "description": "Bucketed series.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PnlHistory" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Wallet"] } }, "/v1/validator/revenue": { "get": { "summary": "Validator revenue", "operationId": "getValidatorRevenue", "description": "Daily validator revenue in SOL. Inflation and Jito rewards settle once per epoch (~2 days). No USD (no price source).", "parameters": [ { "$ref": "#/components/parameters/days" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" } ], "responses": { "200": { "description": "Cache-Control: public, max-age=300.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatorRevenue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Validator"] } }, "/v1/protocol/state": { "get": { "summary": "State history", "operationId": "getProtocolState", "description": "Bucketed state history: per-market CR, leverage, NAVs, supplies, TVL; USDC peg; earn pool. Sparse — absent buckets/markets/fields are omitted, never zero-filled. Pre-2026-07-31 buckets carry at most CR/leverage/supplies/collateral price and no usdcPeg. Market virtual-supply counters (+ USDC peg) sum to the real hyUSD supply.", "parameters": [ { "$ref": "#/components/parameters/granularity" }, { "$ref": "#/components/parameters/daysGrain" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" } ], "responses": { "200": { "description": "Cache-Control: public, max-age=300.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolState" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Protocol"] } }, "/v1/protocol/prices": { "get": { "summary": "Token prices", "operationId": "getProtocolPrices", "description": "Bucketed USD price series per token (hyUSD/xSOL back to 2025-04; others from launch). `sol` only on LSTs. With `ohlc=true` each point is a candle: `open`/`high`/`low` plus `usd` = close, merged from the recorder's 5-minute candles (`open` is the first 5-minute open in the bucket, `high`/`low` the extremes) — so intra-5-minute wicks are not visible at any grain.", "parameters": [ { "$ref": "#/components/parameters/granularity" }, { "$ref": "#/components/parameters/daysGrain" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "name": "token", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated token labels (case-insensitive): BTC, HYPE, HYUSD, HyloSOL, JitoSOL, SOL, eHYUSD, xBTC, xHYPE, xSOL. Omit for all. Unknown label → 400." }, { "name": "ohlc", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Serve OHLC candles instead of last-value points. `true` / `1`." } ], "responses": { "200": { "description": "Cache-Control: public, max-age=300.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolPrices" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": ["Protocol"] } } }, "components": { "parameters": { "days": { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 120 }, "description": "Trailing window ending today (inclusive). Ignored when `from` is given." }, "daysGrain": { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 7 }, "description": "Trailing window ending today (inclusive). Ignored when `from` is given. Must fit the granularity's window cap." }, "from": { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive range start (YYYY-MM-DD). Overrides `days`." }, "to": { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive range end; default today. Range capped at 1000 days; `from` > `to` → 400." }, "granularity": { "name": "granularity", "in": "query", "schema": { "type": "string", "enum": ["5m", "1h", "1d"], "default": "1d" }, "description": "Bucket size (last value in bucket). Max window: 7d at 5m, 90d at 1h, 1000d at 1d." } }, "responses": { "BadRequest": { "description": "Invalid parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" } }, "required": ["success", "error"] } } } } }, "schemas": { "Decimal": { "type": "string", "description": "Exact decimal as a plain string (e.g. \"12.75\", \"0.0000001\"). Never a float." }, "Date": { "type": "string", "format": "date", "example": "2026-08-19" }, "Market": { "type": "string", "enum": ["SOL", "cbBTC", "HYPE"] }, "Pair": { "type": "object", "required": ["amount", "usd"], "properties": { "amount": { "$ref": "#/components/schemas/Decimal" }, "usd": { "$ref": "#/components/schemas/Decimal" } } }, "TokenPair": { "type": "object", "required": ["token", "amount", "usd"], "properties": { "token": { "type": "string", "description": "Unit of `amount`." }, "amount": { "$ref": "#/components/schemas/Decimal" }, "usd": { "$ref": "#/components/schemas/Decimal" } } }, "FeePair": { "type": "object", "required": ["fee", "usd"], "properties": { "fee": { "$ref": "#/components/schemas/Decimal" }, "usd": { "$ref": "#/components/schemas/Decimal" } } }, "Status": { "type": "object", "required": [ "lastIndexedSignature", "latestEventTime", "latestRollupDate" ], "properties": { "lastIndexedSignature": { "type": ["string", "null"] }, "latestEventTime": { "type": ["string", "null"], "format": "date-time" }, "latestRollupDate": { "type": ["string", "null"], "format": "date" } } }, "FeesDaily": { "type": "object", "required": [ "since", "until", "totals", "byToken", "byOperation", "daily" ], "properties": { "since": { "$ref": "#/components/schemas/Date" }, "until": { "$ref": "#/components/schemas/Date" }, "totals": { "type": "object", "required": ["allTimeUsd", "periodUsd"], "properties": { "allTimeUsd": { "$ref": "#/components/schemas/Decimal" }, "periodUsd": { "$ref": "#/components/schemas/Decimal" } } }, "byToken": { "type": "array", "items": { "type": "object", "required": ["token", "allTime", "period"], "properties": { "token": { "type": "string" }, "allTime": { "$ref": "#/components/schemas/FeePair" }, "period": { "$ref": "#/components/schemas/FeePair" } } } }, "byOperation": { "type": "array", "items": { "type": "object", "required": ["operation", "token", "allTime", "period"], "properties": { "operation": { "type": "string" }, "token": { "type": "string" }, "market": { "$ref": "#/components/schemas/Market", "description": "Omitted for protocol-level rows." }, "allTime": { "$ref": "#/components/schemas/FeePair" }, "period": { "$ref": "#/components/schemas/FeePair" } } } }, "daily": { "type": "array", "items": { "type": "object", "required": ["date", "byToken", "byOperation"], "properties": { "date": { "$ref": "#/components/schemas/Date" }, "byToken": { "type": "array", "items": { "type": "object", "required": ["token", "fee", "usd"], "properties": { "token": { "type": "string" }, "fee": { "$ref": "#/components/schemas/Decimal" }, "usd": { "$ref": "#/components/schemas/Decimal" } } } }, "byOperation": { "type": "array", "items": { "type": "object", "required": ["operation", "token", "fee", "usd"], "properties": { "operation": { "type": "string" }, "token": { "type": "string" }, "market": { "$ref": "#/components/schemas/Market" }, "fee": { "$ref": "#/components/schemas/Decimal" }, "usd": { "$ref": "#/components/schemas/Decimal" } } } } } } } } }, "Daily": { "type": "object", "required": ["since", "until", "daily"], "properties": { "since": { "$ref": "#/components/schemas/Date" }, "until": { "$ref": "#/components/schemas/Date" }, "daily": { "type": "array", "items": { "type": "object", "required": ["date", "eventCount", "hyusd", "ehyusd", "markets"], "properties": { "date": { "$ref": "#/components/schemas/Date" }, "eventCount": { "type": "integer" }, "hyusd": { "type": "object", "required": ["minted", "redeemed"], "properties": { "minted": { "$ref": "#/components/schemas/Pair" }, "redeemed": { "$ref": "#/components/schemas/Pair" } } }, "ehyusd": { "type": "object", "description": "Earn-pool deposits/withdrawals in eHYUSD units; `usd` is the stablecoin side.", "required": ["minted", "redeemed"], "properties": { "minted": { "$ref": "#/components/schemas/Pair" }, "redeemed": { "$ref": "#/components/schemas/Pair" } } }, "markets": { "type": "array", "items": { "type": "object", "required": [ "market", "levercoin", "levercoinMinted", "levercoinRedeemed", "collaterals" ], "properties": { "market": { "$ref": "#/components/schemas/Market" }, "levercoin": { "type": "string", "enum": ["xSOL", "xBTC", "xHYPE"] }, "levercoinMinted": { "$ref": "#/components/schemas/Pair" }, "levercoinRedeemed": { "$ref": "#/components/schemas/Pair" }, "yieldToPool": { "$ref": "#/components/schemas/TokenPair", "description": "hyUSD minted to the earn pool, net of protocol fees (add the matching Harvest* row on /v1/protocol/fees for gross). Omitted when none that day." }, "pnlSettled": { "$ref": "#/components/schemas/TokenPair", "description": "Signed net rebalance-PnL settlement against the earn pool (positive = minted to pool). Omitted when none that day." }, "collaterals": { "type": "array", "items": { "type": "object", "required": [ "token", "mint", "vaultInflow", "vaultOutflow" ], "properties": { "token": { "type": "string" }, "mint": { "type": "string" }, "vaultInflow": { "$ref": "#/components/schemas/Pair" }, "vaultOutflow": { "$ref": "#/components/schemas/Pair" } } } } } } }, "usdcVault": { "type": "object", "required": ["inflow", "outflow"], "properties": { "inflow": { "$ref": "#/components/schemas/Pair" }, "outflow": { "$ref": "#/components/schemas/Pair" } }, "description": "Omitted when no USDC vault activity that day." } } } } } }, "Activity": { "type": "object", "required": ["events"], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "cursor": { "type": ["string", "null"], "description": "Pass as `before` for the next page; null when history is exhausted. Absent in per-tx mode." } } }, "ActivityEvent": { "type": "object", "required": [ "signature", "eventName", "eventType", "program", "blockTime", "slot", "eventIndex", "source", "eventData" ], "properties": { "signature": { "type": "string" }, "eventName": { "type": "string", "description": "Raw on-chain event name, e.g. `SwapExoToUsdcEvent`." }, "eventType": { "type": "string", "description": "Canonical type, e.g. `SwapExoToUsdc`." }, "program": { "type": "string", "enum": ["exchange", "stability-pool"] }, "blockTime": { "type": "string", "format": "date-time" }, "slot": { "type": "integer" }, "eventIndex": { "type": "integer" }, "source": { "type": "string", "enum": ["event", "derived"], "description": "`derived` = balance-derived PnL settlement, not chain-attested." }, "eventData": { "type": "object", "additionalProperties": true, "description": "Verbatim decoded payload; snake_case IDL keys, decimals as strings." } } }, "Pnl": { "type": "object", "required": ["wallet", "asOf", "tokens", "totals", "warnings"], "properties": { "wallet": { "type": "string" }, "asOf": { "type": "object", "properties": { "slot": { "type": "integer" }, "time": { "type": "string" }, "checkpointDay": { "type": ["string", "null"], "description": "Newest checkpoint day any token resumed from; null when every pair was replayed from inception." } } }, "tokens": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "symbol": { "type": "string" }, "mint": { "type": "string" }, "denomination": { "type": "string", "enum": ["usd", "sol"] }, "holdings": { "$ref": "#/components/schemas/Decimal" }, "costBasis": { "$ref": "#/components/schemas/Decimal" }, "realized": { "$ref": "#/components/schemas/Decimal" }, "unrealized": { "$ref": "#/components/schemas/Decimal" }, "total": { "$ref": "#/components/schemas/Decimal" }, "txCount": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } } } } }, "totals": { "type": "object", "properties": { "realized": { "$ref": "#/components/schemas/Decimal" }, "unrealized": { "$ref": "#/components/schemas/Decimal" }, "total": { "$ref": "#/components/schemas/Decimal" } } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "PnlHistory": { "type": "object", "required": ["wallet", "granularity", "series", "warnings"], "properties": { "wallet": { "type": "string" }, "granularity": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "time": { "type": "string" }, "realized": { "$ref": "#/components/schemas/Decimal" }, "unrealized": { "$ref": "#/components/schemas/Decimal" }, "total": { "$ref": "#/components/schemas/Decimal" }, "positionValue": { "$ref": "#/components/schemas/Decimal" }, "epoch": { "type": ["integer", "null"] }, "byToken": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "ValidatorRevenue": { "type": "object", "required": ["since", "until", "totals", "daily"], "properties": { "since": { "$ref": "#/components/schemas/Date" }, "until": { "$ref": "#/components/schemas/Date" }, "totals": { "type": "object", "required": ["periodSol", "allTimeSol"], "properties": { "periodSol": { "$ref": "#/components/schemas/Sol" }, "allTimeSol": { "$ref": "#/components/schemas/Sol" } } }, "daily": { "type": "array", "items": { "type": "object", "required": [ "date", "total", "blocksProduced", "leaderSlotsAssigned", "epochsSettled", "final" ], "properties": { "date": { "$ref": "#/components/schemas/Date" }, "inflationCommission": { "$ref": "#/components/schemas/Sol", "description": "Omitted until the epoch's inflation rewards settle." }, "jitoTips": { "$ref": "#/components/schemas/Sol", "description": "Omitted until the epoch's Jito tips settle." }, "blockRewards": { "$ref": "#/components/schemas/Sol", "description": "Block fees from produced leader slots (accrues daily)." }, "total": { "$ref": "#/components/schemas/Sol", "description": "Sum of the settled parts." }, "blocksProduced": { "type": "integer" }, "leaderSlotsAssigned": { "type": "integer" }, "epochsSettled": { "type": "array", "items": { "type": "integer" } }, "final": { "type": "boolean", "description": "Block rewards final AND at least one epoch part settled; false means the day can still grow." } } } } } }, "Sol": { "type": "string", "description": "SOL amount as a decimal string. Never a float." }, "ProtocolState": { "type": "object", "required": ["since", "until", "granularity", "series"], "properties": { "since": { "$ref": "#/components/schemas/Date" }, "until": { "$ref": "#/components/schemas/Date" }, "granularity": { "type": "string", "enum": ["5m", "1h", "1d"] }, "series": { "type": "array", "items": { "type": "object", "required": ["ts", "markets"], "properties": { "ts": { "type": "string", "format": "date-time" }, "markets": { "type": "array", "items": { "type": "object", "required": ["market"], "properties": { "market": { "type": "string", "enum": ["SOL", "cbBTC", "HYPE"] }, "collateralRatio": { "$ref": "#/components/schemas/Decimal" }, "levercoinLeverage": { "$ref": "#/components/schemas/Decimal", "description": "Effective leverage CR/(CR−1); omitted at CR ≤ 1." }, "stablecoinNav": { "$ref": "#/components/schemas/Decimal", "description": "Redeem NAV." }, "levercoinNav": { "$ref": "#/components/schemas/Decimal", "description": "Redeem NAV." }, "virtualStablecoinSupply": { "$ref": "#/components/schemas/Decimal", "description": "hyUSD supply attributed to this market." }, "levercoinSupply": { "$ref": "#/components/schemas/Decimal" }, "totalCollateral": { "$ref": "#/components/schemas/Decimal", "description": "In collateral units (SOL / cbBTC / HYPE)." }, "collateralPriceUsd": { "$ref": "#/components/schemas/Decimal", "description": "Oracle lower bound." }, "tvlUsd": { "$ref": "#/components/schemas/Decimal" } } } }, "usdcPeg": { "type": "object", "properties": { "vaultReserves": { "$ref": "#/components/schemas/Decimal", "description": "USDC held against the peg." }, "virtualStablecoinSupply": { "$ref": "#/components/schemas/Decimal", "description": "hyUSD minted against USDC." } } }, "earnPool": { "type": "object", "properties": { "hyusdPoolBalance": { "$ref": "#/components/schemas/Decimal" }, "ehyusdSupply": { "$ref": "#/components/schemas/Decimal" }, "ehyusdNav": { "$ref": "#/components/schemas/Decimal", "description": "Pool hyUSD × hyUSD NAV ÷ eHYUSD supply." } } } } } } } }, "ProtocolPrices": { "type": "object", "required": ["since", "until", "granularity", "tokens"], "properties": { "since": { "$ref": "#/components/schemas/Date" }, "until": { "$ref": "#/components/schemas/Date" }, "granularity": { "type": "string", "enum": ["5m", "1h", "1d"] }, "tokens": { "type": "array", "items": { "type": "object", "required": ["token", "series"], "properties": { "token": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "required": ["ts", "usd"], "properties": { "ts": { "type": "string", "format": "date-time" }, "usd": { "$ref": "#/components/schemas/Decimal", "description": "Last price in the bucket; the close when `ohlc=true`." }, "sol": { "$ref": "#/components/schemas/Decimal", "description": "LSTs only." }, "open": { "$ref": "#/components/schemas/Decimal", "description": "First price in the bucket. `ohlc=true` only." }, "high": { "$ref": "#/components/schemas/Decimal", "description": "Highest price in the bucket. `ohlc=true` only." }, "low": { "$ref": "#/components/schemas/Decimal", "description": "Lowest price in the bucket. `ohlc=true` only." } } } } } } } } } } }, "tags": [ { "name": "Protocol", "description": "Chain-wide protocol data." }, { "name": "Validator", "description": "Hylo validator revenue." }, { "name": "Wallet", "description": "Per-wallet PnL." }, { "name": "Meta", "description": "Data freshness." } ] }