{ "openapi": "3.1.0", "info": { "title": "vike.io Data API", "description": "The vike.io Data API, in four products: on-chain analytics (wallets, labels, transfers, smart-money flows); Hyperliquid perps analytics with candles from our own node; HL Cohorts, the positioning of Hyperliquid trader cohorts (`/v1/hl-cohorts`); and Polymarket markets with a bulk Parquet archive. Authenticate every request with an `X-API-KEY: vk_...` header or an OAuth 2.1 bearer token; usage is metered per call and subject to an hourly rate limit and a per-minute cap of 200 requests per key (HTTP 429 with a `Retry-After` header over either).", "version": "1.0.0" }, "servers": [ { "url": "https://data.vike.io" } ], "paths": { "/v1/onchain/wallets/compare": { "get": { "tags": [ "onchain" ], "summary": "Wallet Compare", "description": "Are these two wallets related? Returns the counterparties both wallets transacted with and\nthe tokens both touched, within a window.", "operationId": "wallet_compare_v1_onchain_wallets_compare_get", "parameters": [ { "name": "address_a", "in": "query", "required": true, "schema": { "type": "string", "description": "First wallet", "title": "Address A" }, "description": "First wallet" }, { "name": "address_b", "in": "query", "required": true, "schema": { "type": "string", "description": "Second wallet", "title": "Address B" }, "description": "Second wallet" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `90d` | `180d` | `all`. Default `30d`", "default": "", "title": "Window" }, "description": "`24h` | `7d` | `30d` | `90d` | `180d` | `all`. Default `30d`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Max shared items per category. Route default 100; **applied cap 50**", "default": 100, "title": "Limit" }, "description": "Max shared items per category. Route default 100; **applied cap 50**" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/discover": { "get": { "tags": [ "onchain" ], "summary": "Wallet Discover", "description": "Leaderboard of active wallets. Every USD value is in plain dollars. `realized_pnl` and\n`tokens_profitable` are lifetime figures in every window (`realized_pnl_basis: \"lifetime\"`), so\n`sort=pnl` ranks by lifetime PnL whatever `window` is.", "operationId": "wallet_discover_v1_onchain_wallets_discover_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `90d` | `all`. Default `30d`; `base` and `hyperevm` default to `all` and serve the other windows only while those windows were refreshed in the last 2 days, otherwise a 400", "default": "", "title": "Window" }, "description": "`24h` | `7d` | `30d` | `90d` | `all`. Default `30d`; `base` and `hyperevm` default to `all` and serve the other windows only while those windows were refreshed in the last 2 days, otherwise a 400" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`volume` | `inflow` | `outflow` | `net_flow` | `tx_count` | `pnl`. Default `volume`", "default": "", "title": "Sort" }, "description": "`volume` | `inflow` | `outflow` | `net_flow` | `tx_count` | `pnl`. Default `volume`" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "description": "Results per page. Default 10, max 20 — one of the two routes in this namespace whose accepted and applied caps agree, alongside [`/tokens/search`](https://vike.io/docs/data/endpoints/onchain/tokens-search)", "default": 10, "title": "Size" }, "description": "Results per page. Default 10, max 20 — one of the two routes in this namespace whose accepted and applied caps agree, alongside [`/tokens/search`](https://vike.io/docs/data/endpoints/onchain/tokens-search)" }, { "name": "include_hubs", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Boolean, default `false`. Also rank round-trip hubs (flash-loan, MEV and router pass-through wallets: volume of $10B or more, with net flow and realized PnL each within 0.1% of it), which are hidden by default", "default": false, "title": "Include Hubs" }, "description": "Boolean, default `false`. Also rank round-trip hubs (flash-loan, MEV and router pass-through wallets: volume of $10B or more, with net flow and realized PnL each within 0.1% of it), which are hidden by default" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}": { "get": { "tags": [ "onchain" ], "summary": "Wallet Summary", "description": "Aggregate metrics for one wallet — volume, inflow, outflow, net flow, transaction count and\ntokens traded, across the 24h / 7d / 30d / 90d / all windows in a single response. `tokens_traded`\ncounts the distinct tokens moved within each window. `chain` in the response says which chain\nanswered.", "operationId": "wallet_summary_v1_onchain_wallets__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address, 0x-prefixed hex", "title": "Address" }, "description": "Wallet address, 0x-prefixed hex" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Omit for the more recently active of ethereum and bsc; `base` or `hyperevm` is then answered only for a wallet with no priced ethereum/bsc volume", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Omit for the more recently active of ethereum and bsc; `base` or `hyperevm` is then answered only for a wallet with no priced ethereum/bsc volume" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/transactions": { "get": { "tags": [ "onchain" ], "summary": "Wallet Transactions", "description": "The raw transfer list for a wallet: individual transfers, not aggregates. The forensic\nroute.", "operationId": "wallet_transactions_v1_onchain_wallets__address__transactions_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address", "title": "Address" }, "description": "Wallet address" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "description": "`in` | `out`. Omit for both directions", "default": "", "title": "Direction" }, "description": "`in` | `out`. Omit for both directions" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Days back. Default 30, clamped to 365", "default": 0, "title": "Days" }, "description": "Days back. Default 30, clamped to 365" }, { "name": "min_usd", "in": "query", "required": false, "schema": { "type": "number", "description": "Drop transfers below this USD value. Default 0", "default": 0.0, "title": "Min Usd" }, "description": "Drop transfers below this USD value. Default 0" }, { "name": "token_address", "in": "query", "required": false, "schema": { "type": "string", "description": "Restrict to a single token contract", "default": "", "title": "Token Address" }, "description": "Restrict to a single token contract" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Route default 100; **applied cap 500**", "default": 100, "title": "Limit" }, "description": "Route default 100; **applied cap 500**" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/counterparties": { "get": { "tags": [ "onchain" ], "summary": "Wallet Counterparties", "description": "The addresses this wallet transacted with most, by combined transfer volume over a window.", "operationId": "wallet_counterparties_v1_onchain_wallets__address__counterparties_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address", "title": "Address" }, "description": "Wallet address" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `90d` | `180d` | `all`. Default `30d`", "default": "", "title": "Window" }, "description": "`24h` | `7d` | `30d` | `90d` | `180d` | `all`. Default `30d`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Route default 100; **applied cap 50**", "default": 100, "title": "Limit" }, "description": "Route default 100; **applied cap 50**" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/pnl": { "get": { "tags": [ "onchain" ], "summary": "Wallet Pnl History", "description": "A daily net-flow series for the wallet — per-day net inflow USD, a cumulative figure, gross\nvolume and transaction count.", "operationId": "wallet_pnl_history_v1_onchain_wallets__address__pnl_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address", "title": "Address" }, "description": "Wallet address" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Days back. Default 30, clamped to the range 1–365", "default": 0, "title": "Days" }, "description": "Days back. Default 30, clamped to the range 1–365" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/balances": { "get": { "tags": [ "onchain" ], "summary": "Wallet Token Balances", "description": "Current token balances for a wallet on Ethereum, BSC, Base and HyperEVM, read from the chain\nat request time, with a USD value where the token is priced. On base and hyperevm only the\ntokens we map and price carry a symbol, balance and USD value; any other held token is listed\nby address and `balance_raw` only with `min_usd=0`. HyperCore (spot and perp accounts) is not included.", "operationId": "wallet_token_balances_v1_onchain_wallets__address__balances_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address, 0x-prefixed, exactly 42 characters", "title": "Address" }, "description": "Wallet address, 0x-prefixed, exactly 42 characters" }, { "name": "chains", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated. `ethereum`, `bsc`, `base` and `hyperevm`; the aliases `eth`, `mainnet`, `bnb` and `binance` are accepted. Omit for all four. Any other chain is reported in `chain_errors`; a chain whose read failed is listed there too and not in `chains_scanned`.", "default": "", "title": "Chains" }, "description": "Comma-separated. `ethereum`, `bsc`, `base` and `hyperevm`; the aliases `eth`, `mainnet`, `bnb` and `binance` are accepted. Omit for all four. Any other chain is reported in `chain_errors`; a chain whose read failed is listed there too and not in `chains_scanned`." }, { "name": "min_usd", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Hide holdings worth less than this. Omitted resolves to `1` (USD); an explicit `0` filters nothing and lists every holding. ⚠ Any floor above `0` also excludes holdings we cannot price, since an unpriced holding cannot be shown to clear it. The chain's native coin is the exception: it is always listed (when its balance is not zero), priced where a price exists, whatever the floor.", "title": "Min Usd" }, "description": "Hide holdings worth less than this. Omitted resolves to `1` (USD); an explicit `0` filters nothing and lists every holding. ⚠ Any floor above `0` also excludes holdings we cannot price, since an unpriced holding cannot be shown to clear it. The chain's native coin is the exception: it is always listed (when its balance is not zero), priced where a price exists, whatever the floor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/trace": { "get": { "tags": [ "onchain" ], "summary": "Wallet Trace", "description": "Follow the money — expand at each hop to the top counterparties by USD volume, outward,\ninward or both, up to a chosen depth. Every node carries `label`, `wallet_type` and `risk_flag`\n(null when the address is unlabelled).", "operationId": "wallet_trace_v1_onchain_wallets__address__trace_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Root wallet to trace from", "title": "Address" }, "description": "Root wallet to trace from" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "integer", "description": "Hops to follow. Default 2, clamped to 1–5", "default": 0, "title": "Depth" }, "description": "Hops to follow. Default 2, clamped to 1–5" }, { "name": "width", "in": "query", "required": false, "schema": { "type": "integer", "description": "Top N counterparties per hop. Default 5, clamped to 1–10", "default": 0, "title": "Width" }, "description": "Top N counterparties per hop. Default 5, clamped to 1–10" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `90d` | `all`. Default `30d`; anything else is a 400", "default": "", "title": "Window" }, "description": "`24h` | `7d` | `30d` | `90d` | `all`. Default `30d`; anything else is a 400" }, { "name": "min_usd", "in": "query", "required": false, "schema": { "type": "number", "description": "Minimum USD per transfer to follow. Default **10,000**", "default": 0.0, "title": "Min Usd" }, "description": "Minimum USD per transfer to follow. Default **10,000**" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "description": "`out` (where funds went) | `in` (where they came from) | `both`. Default `both`; anything else is a 400", "default": "", "title": "Direction" }, "description": "`out` (where funds went) | `in` (where they came from) | `both`. Default `both`; anything else is a 400" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/ens": { "get": { "tags": [ "onchain" ], "summary": "Wallet Ens", "description": "Reverse ENS lookup — turn an address into vitalik.eth. Returns null where the address has no\nENS name set.", "operationId": "wallet_ens_v1_onchain_wallets__address__ens_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address, 0x-prefixed, exactly 42 characters", "title": "Address" }, "description": "Wallet address, 0x-prefixed, exactly 42 characters" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/first-funder": { "get": { "tags": [ "onchain" ], "summary": "Wallet First Funder", "description": "The earliest inbound transfers of a wallet, as two separate answers: `first_native_in` (the first\nplain send of the chain's coin) and `first_token_in` (the first priced token transfer), each with the\nsender, its label, time, transaction hash, block and amounts. Not proof of who funded the wallet: native\nrows hold top-level sends only, and history starts on a different date per chain (`coverage`).", "operationId": "wallet_first_funder_v1_onchain_wallets__address__first_funder_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address, 0x-prefixed hex", "title": "Address" }, "description": "Wallet address, 0x-prefixed hex" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. Read from that chain's own transfer and label tables", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. Read from that chain's own transfer and label tables" }, { "name": "min_native", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Dust floor for the native coin, in **whole coins** (ETH, BNB or HYPE; `0.01` is 0.01 coin, not wei). Inbound native transfers below it are skipped. Omitted resolves to `0.0001`; an explicit `0` means no floor and returns the very first inbound, probing dust included", "title": "Min Native" }, "description": "Dust floor for the native coin, in **whole coins** (ETH, BNB or HYPE; `0.01` is 0.01 coin, not wei). Inbound native transfers below it are skipped. Omitted resolves to `0.0001`; an explicit `0` means no floor and returns the very first inbound, probing dust included" }, { "name": "min_usd", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Floor for the token side, in USD. Token transfers priced below it, or with no USD price, are skipped. Omitted resolves to `1`; an explicit `0` means no floor and includes unpriced tokens (mostly spam)", "title": "Min Usd" }, "description": "Floor for the token side, in USD. Token transfers priced below it, or with no USD price, are skipped. Omitted resolves to `1`; an explicit `0` means no floor and includes unpriced tokens (mostly spam)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/wallets/{address}/exchange-usage": { "get": { "tags": [ "onchain" ], "summary": "Wallet Exchange Usage", "description": "Which centralised exchanges a wallet sent to and received from over a window: USD sent and received,\ntransfer counts and first and last contact per exchange, plus `pattern: \"sweeps_to_single_cex\"` when at\nleast 90% of the wallet's outgoing USD went to one exchange across at least 3 transfers. The pattern is\nobserved, not a claim that the address is a deposit address, and exchange figures are a lower bound.", "operationId": "wallet_exchange_usage_v1_onchain_wallets__address__exchange_usage_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address, 0x-prefixed hex", "title": "Address" }, "description": "Wallet address, 0x-prefixed hex" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. `hyperevm` has few labels, so a miss there says little", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. `hyperevm` has few labels, so a miss there says little" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`30d` | `90d` | `180d` | `365d` | `all`. Default `365d`. A very active wallet over a long window is a `400` naming this parameter: narrow it", "default": "", "title": "Window" }, "description": "`30d` | `90d` | `180d` | `365d` | `all`. Default `365d`. A very active wallet over a long window is a `400` naming this parameter: narrow it" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/labels/batch": { "post": { "tags": [ "onchain" ], "summary": "Wallet Batch Labels", "description": "Enrich a list of addresses in one call: entity, wallet type, risk flag, 30-day net flow,\n30-day volume and 30-day transaction count, one row per input address in input order. The\n30-day figures are live (the last 30 calendar days, the same window as the wallet summary) and\nare `null` only for an address with no label (`found: false`); a labelled wallet with no\ntransfer in the window reads 0. An address flagged `exploit` is never typed `cex`. A row whose\naddress source `provider_e` knows also carries `provider_e`: a list of that source's labels\n(class, entity, basis, evidence, the Polymarket wallets it is, controls or funded, their volume and\nrealized PnL), on every `chain`, since an address is the same on every EVM chain. It is one more\nsource beside the label: it never changes `entity`, `wallet_type` or `found`.", "operationId": "wallet_batch_labels_v1_onchain_labels_batch_post", "parameters": [ { "name": "addresses", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated addresses. Capped at 100", "title": "Addresses" }, "description": "Comma-separated addresses. Capped at 100" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. Labels and the 30-day flows are read from that chain's own tables. Any other name is a 400", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. Labels and the 30-day flows are read from that chain's own tables. Any other name is a 400" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/labels/{address}/provenance": { "get": { "tags": [ "onchain" ], "summary": "Wallet Label Provenance", "description": "Which source claimed what about this wallet. Degrades to fewer rows\nrather than erroring while one of its label sources is being refreshed. Source `provider_e`\ncovers Polymarket wallets, the addresses that control or funded them, and the addresses that paid\nmany of them (bridges, exchanges, reward payers), with `basis` (`onchain_fact`, or\n`behaviour_inferred` / `behaviour_corroborated` for a guess from behaviour), `evidence`, and for a\nwallet, controller or funder the wallets' count, volume and realized PnL. It never feeds\n`consensus`. `found` is true when any source knows the address, so an address only `provider_e`\nknows answers `found: true` with an all-null `consensus`.", "operationId": "wallet_label_provenance_v1_onchain_labels__address__provenance_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Wallet address, 0x-prefixed hex", "title": "Address" }, "description": "Wallet address, 0x-prefixed hex" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/tokens/search": { "get": { "tags": [ "onchain" ], "summary": "Token Search", "description": "Resolve a symbol or name to the tokens we know about. ``token_address`` is ``0x``-prefixed\nlower-case hex, the spelling every other address in this namespace uses.", "operationId": "token_search_v1_onchain_tokens_search_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "description": "Symbol or name (case-insensitive); an exact symbol ranks first, then symbol prefix, symbol substring, name prefix. A contract address is not matched", "title": "Q" }, "description": "Symbol or name (case-insensitive); an exact symbol ranks first, then symbol prefix, symbol substring, name prefix. A contract address is not matched" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. Any other name is a 400", "default": "ethereum", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`. Any other name is a 400" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "description": "Default 10, max 100", "default": 10, "title": "Limit" }, "description": "Default 10, max 100" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/tokens/screener": { "get": { "tags": [ "onchain" ], "summary": "Token Screener", "description": "Find tokens by activity within a window — rank by volume, net inflow, holder count or smart-\nmoney inflow.", "operationId": "token_screener_v1_onchain_tokens_screener_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `90d`. Default `24h`", "default": "", "title": "Window" }, "description": "`24h` | `7d` | `30d` | `90d`. Default `24h`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`volume` | `net_inflow` | `holders` | `smart_inflow`. Default `volume`. `smart_inflow` is `ethereum` only", "default": "", "title": "Sort" }, "description": "`volume` | `net_inflow` | `holders` | `smart_inflow`. Default `volume`. `smart_inflow` is `ethereum` only" }, { "name": "min_volume_usd", "in": "query", "required": false, "schema": { "type": "number", "description": "Drop tokens below this window volume", "default": 0.0, "title": "Min Volume Usd" }, "description": "Drop tokens below this window volume" }, { "name": "min_holders", "in": "query", "required": false, "schema": { "type": "integer", "description": "Drop tokens below this holder count", "default": 0, "title": "Min Holders" }, "description": "Drop tokens below this holder count" }, { "name": "smart_money_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Boolean. Restrict to smart-money cohort flows. `ethereum` only: any other chain is a 400", "default": false, "title": "Smart Money Only" }, "description": "Boolean. Restrict to smart-money cohort flows. `ethereum` only: any other chain is a 400" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Route default 50; **applied cap 100**", "default": 50, "title": "Limit" }, "description": "Route default 50; **applied cap 100**" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/tokens/{token_address}/transfers": { "get": { "tags": [ "onchain" ], "summary": "Token Transfers", "description": "Who bought and who sold a token over a period — the top net buyers or the top net sellers,\nranked by net USD, with quantities and USD values.", "operationId": "token_transfers_v1_onchain_tokens__token_address__transfers_get", "parameters": [ { "name": "token_address", "in": "path", "required": true, "schema": { "type": "string", "description": "Token contract address, 0x-prefixed", "title": "Token Address" }, "description": "Token contract address, 0x-prefixed" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "description": "`1h` | `24h` | `7d` | `30d`. Default `24h`", "default": "", "title": "Period" }, "description": "`1h` | `24h` | `7d` | `30d`. Default `24h`" }, { "name": "tab", "in": "query", "required": false, "schema": { "type": "string", "description": "`bought` (net buyers: bought more than sold) | `sold` (net sellers). Default `sold`", "default": "", "title": "Tab" }, "description": "`bought` (net buyers: bought more than sold) | `sold` (net sellers). Default `sold`" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm` | `all`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm` | `all`. Default `ethereum`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onchain/tokens/{token_address}/holders": { "get": { "tags": [ "onchain" ], "summary": "Token Holders", "description": "The holder leaderboard for a token: by default ranked by cumulative net inflow USD, or by balance\nwith `sort=balance`.", "operationId": "token_holders_v1_onchain_tokens__token_address__holders_get", "parameters": [ { "name": "token_address", "in": "path", "required": true, "schema": { "type": "string", "description": "Token contract address, 0x-prefixed", "title": "Token Address" }, "description": "Token contract address, 0x-prefixed" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`", "default": "", "title": "Chain" }, "description": "`ethereum` | `bsc` | `base` | `hyperevm`. Default `ethereum`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Route default 50; **applied cap 50**", "default": 50, "title": "Limit" }, "description": "Route default 50; **applied cap 50**" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`flow` | `balance`. Default `flow`: ranked by cumulative net inflow USD (a flow, not a holding). `balance`: ranked by the on-chain `balanceOf` among candidate wallets chosen by net inflow and by volume, highest first; each row then also carries `balance`, `value_usd`, `supply_pct`, `balance_basis`, `balance_approximate` and `candidate_coverage` (how much of the supply the candidates explain). Not available on every chain (a 400 names it); for the native coin the ranking stays `flow` and every row says `balance_basis: unsupported`", "default": "flow", "title": "Sort" }, "description": "`flow` | `balance`. Default `flow`: ranked by cumulative net inflow USD (a flow, not a holding). `balance`: ranked by the on-chain `balanceOf` among candidate wallets chosen by net inflow and by volume, highest first; each row then also carries `balance`, `value_usd`, `supply_pct`, `balance_basis`, `balance_approximate` and `candidate_coverage` (how much of the supply the candidates explain). Not available on every chain (a 400 names it); for the native coin the ranking stays `flow` and every row says `balance_basis: unsupported`" }, { "name": "exclude_exchanges", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Boolean. Drop wallets labelled as an exchange. On `sort=flow` it is applied to the top 200 candidates (at least), so a long list can come back shorter than `limit`", "default": false, "title": "Exclude Exchanges" }, "description": "Boolean. Drop wallets labelled as an exchange. On `sort=flow` it is applied to the top 200 candidates (at least), so a long list can come back shorter than `limit`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/traders": { "get": { "tags": [ "hyperliquid" ], "summary": "Top Traders", "description": "Top HL perp traders by the requested metric over the window.\n\nKept on the tool implementation rather than moved to the new engine: MCP and\nthe AI chat call the same code, and a second ranking that disagreed with the\none the assistant quotes would be worse than a near-duplicate route.\n``/leaderboard`` is the richer, cursor-paged version.", "operationId": "top_traders_v1_hyperliquid_traders_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Effective default `30d`", "default": "", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Effective default `30d`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`pnl` | `roi` | `win_rate` | `volume` | `trade_count` | `drawdown` | `account_value` | `long_pnl` | `short_pnl`. Default `pnl`", "default": "", "title": "Sort" }, "description": "`pnl` | `roi` | `win_rate` | `volume` | `trade_count` | `drawdown` | `account_value` | `long_pnl` | `short_pnl`. Default `pnl`" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "min_trades", "in": "query", "required": false, "schema": { "type": "integer", "description": "Minimum closed trades. Floored at 3: omitting it or passing 0, 1 or 2 gives 3", "default": 0, "title": "Min Trades" }, "description": "Minimum closed trades. Floored at 3: omitting it or passing 0, 1 or 2 gives 3" }, { "name": "min_win_rate", "in": "query", "required": false, "schema": { "type": "number", "description": "**Percent, 0–100**, not a fraction", "default": 0.0, "title": "Min Win Rate" }, "description": "**Percent, 0–100**, not a fraction" }, { "name": "min_volume", "in": "query", "required": false, "schema": { "type": "number", "description": "Minimum total volume", "default": 0.0, "title": "Min Volume" }, "description": "Minimum total volume" }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "description": "Number of traders, 1–100", "default": 20, "title": "Size" }, "description": "Number of traders, 1–100" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/positions/match": { "get": { "tags": [ "hyperliquid" ], "summary": "Position Match", "description": "Find open positions matching a symbol/side/leverage/entry profile — the\n'who else is in this trade' query.", "operationId": "position_match_v1_hyperliquid_positions_match_get", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. HL ticker as listed, e.g. `BTC`, `kPEPE`, `xyz:TSLA`; case-insensitive for those spellings", "default": "", "title": "Symbol" }, "description": "HL ticker as listed, e.g. `BTC`, `kPEPE`, `xyz:TSLA`; case-insensitive for those spellings" }, { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "description": "`long` | `short`", "title": "Side" }, "description": "`long` | `short`" }, { "name": "leverage", "in": "query", "required": true, "schema": { "type": "number", "description": "Numeric, 0 or more. Matched within ±0.5 absolute. `0` finds cross-margin positions with no leverage recorded", "title": "Leverage" }, "description": "Numeric, 0 or more. Matched within ±0.5 absolute. `0` finds cross-margin positions with no leverage recorded" }, { "name": "entry_price", "in": "query", "required": true, "schema": { "type": "number", "description": "Numeric, positive", "title": "Entry Price" }, "description": "Numeric, positive" }, { "name": "mark_price", "in": "query", "required": false, "schema": { "type": "number", "description": "Tie-break among equally close entries (matches are ranked by entry-price distance first). **Defaults to `entry_price`** when omitted", "default": 0.0, "title": "Mark Price" }, "description": "Tie-break among equally close entries (matches are ranked by entry-price distance first). **Defaults to `entry_price`** when omitted" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Number of matches, 1–500", "default": 50, "title": "Limit" }, "description": "Number of matches, 1–500" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/positions": { "get": { "tags": [ "hyperliquid" ], "summary": "List Positions", "description": "Position rows, current or historical.\n\n``open_only=true`` reads the latest-state table. Passing ``start``/``end``\nswitches to the historical snapshot table, which is 8.7 billion rows — bound\nit by ``symbol`` or ``wallet``, or expect it to be slow.\n\n**Rows come in key order, not by size.** The cursor pages on the table's\nprimary key, so current positions are ordered by ``wallet``, ``symbol``,\n``direction`` and historical ones by ``symbol``, ``snapshot_ts``,\n``wallet`` (``resolution=1h`` with ``wallet``: by ``snapshot_ts``, then\n``symbol``): ``limit=10`` is the first ten wallets in address order, never\nthe ten biggest positions. For the biggest, pass ``sort=size`` (below), or\nread ``/v1/hl-cohorts/symbols/{symbol}/size-breakdown`` (positioning by\nposition-size bucket), ``/positions/symbols`` (open interest per symbol) or\n``/v1/hl-cohorts/symbols/{symbol}/cohort-metrics`` (by cohort).\n\n**``sort=size``** returns the ``limit`` biggest current positions of one\n``symbol``, ordered by ``size_usd`` descending, then ``wallet``, then\n``direction``, from the same latest-state read as the default. It is a\ntop-N, not a page: ``symbol`` is required, ``limit`` is at most 500, there\nis no ``cursor`` (``nextCursor`` is always null), and ``start``/``end`` are\nrefused; each violation is a ``400`` with a one-line reason. Every row\nadditionally carries ``account_value``: the wallet's NATIVE perp account\nvalue in USD at the newest snapshot (the same figure as ``equity.account_value``\non ``/wallets/{address}``, so it leaves out a builder DEX's separate\naccount), or null when it is unknown (a repaired value, or no row in the\nnewest snapshot). It is never 0 for unknown. No per-position cumulative\nfunding is served, because no per-position source exists that avoids\nscanning the funding table.\n\nEvery row declares its pnl-label provenance: ``pnl_cohort_basis``\n(``point_in_time`` | ``current``, the same vocabulary ``labelBasis`` uses\nelsewhere) and ``pnl_cohort_as_of`` (the ISO hour the label was computed\nat, or null). Historical rows carry the point-in-time label from the\nhourly label table — not today's dictionary standing — with the current\nunlabelled tail (the newest hour or two) falling back to the dictionary\nand saying so per row; the envelope's ``label_computed`` block states the\nmode's source once. A historical ``pnl``/``pnl_abs`` cohort filter is\nanswered from the same label table and therefore requires ``symbol`` or\n``wallet`` alongside it.\n\nA historical row's own label counts fills up to the end of its hour\n(``label_computed.lookahead`` is true). For a backtest read ``label_causal``\ninstead: an object with the same keys (``pnl_cohort``, ``pnl_abs_cohort``,\n``pnl_cohort_as_of``, ``pnl_cohort_basis``) computed at the PREVIOUS hour, so it\nholds no later fill. It is null where that hour has no label for the wallet and\nis absent on current rows. The row's own label values are unchanged.", "operationId": "list_positions_v1_hyperliquid_positions_get", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker, e.g. `BTC`", "default": "", "title": "Symbol" }, "description": "HL ticker, e.g. `BTC`" }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "description": "One wallet", "default": "", "title": "Wallet" }, "description": "One wallet" }, { "name": "cohort", "in": "query", "required": false, "schema": { "type": "string", "description": "One label on `axis`", "default": "", "title": "Cohort" }, "description": "One label on `axis`" }, { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. Default `size`", "default": "size", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs`. Default `size`" }, { "name": "open_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Boolean, default `true`. Latest open positions only", "default": true, "title": "Open Only" }, "description": "Boolean, default `true`. Latest open positions only" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Setting either switches to history. Not before 2026-05-01", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Setting either switches to history. Not before 2026-05-01" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Setting either switches to history", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Setting either switches to history" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000 (500 with `sort=size`)", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000 (500 with `sort=size`)" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor. Refused with `sort=size`", "default": "", "title": "Cursor" }, "description": "Keyset cursor. Refused with `sort=size`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` = the biggest positions of one `symbol` first. Default: key order. Current mode only; needs `symbol`; `limit` at most 500; no `cursor`", "default": "", "title": "Sort" }, "description": "`size` = the biggest positions of one `symbol` first. Default: key order. Current mode only; needs `symbol`; `limit` at most 500; no `cursor`" }, { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string", "description": "History only (needs `start`). `5m` = every snapshot, ~5 minutes apart. `1h` = the last snapshot of each hour, ~12x fewer rows. Default: `1h` when `wallet` is given (served from a wallet-sorted copy), `5m` otherwise. A `5m` read of one wallet is limited to 48 hours per request.", "default": "", "title": "Resolution" }, "description": "History only (needs `start`). `5m` = every snapshot, ~5 minutes apart. `1h` = the last snapshot of each hour, ~12x fewer rows. Default: `1h` when `wallet` is given (served from a wallet-sorted copy), `5m` otherwise. A `5m` read of one wallet is limited to 48 hours per request." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/positions/symbols": { "get": { "tags": [ "hyperliquid" ], "summary": "Oi Snapshot", "description": "Market-wide open interest per coin at the latest snapshot, with the\nvenue's own OI alongside our aggregate so the two can be reconciled.", "operationId": "oi_snapshot_v1_hyperliquid_positions_symbols_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/hyperliquid/orders": { "get": { "tags": [ "hyperliquid" ], "summary": "Open Orders", "description": "The orders resting at one instant: every order in a 5-minute snapshot, or a rebuild from the sightings around it\nwhen no complete 5-minute snapshot exists.\n\nReturns `snapshotTs`, `source` (`l4_5m` | `state_12m`), `orders`, `nextCursor`. The 5-minute snapshots start at\n2026-10-23 21:45 UTC; before that, and after a stalled feed's last snapshot, the answer is rebuilt from the\n12-minute checkpoints. A rebuilt answer for a past `at` lists only the orders seen before the instant and again after\nit, so short-lived orders can be missing, and its `snapshotTs` is the `at` floored to 5 minutes; an `at` inside an\noutage of either feed is answered the same way. Rows in key order (dex, symbol, side, oid); the cursor pins the\nsnapshot.", "operationId": "open_orders_v1_hyperliquid_orders_get", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL perp ticker, e.g. `BTC` or `xyz:TSLA`. `symbol` and/or `wallet` is required", "default": "", "title": "Symbol" }, "description": "HL perp ticker, e.g. `BTC` or `xyz:TSLA`. `symbol` and/or `wallet` is required" }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "description": "One wallet. `symbol` and/or `wallet` is required", "default": "", "title": "Wallet" }, "description": "One wallet. `symbol` and/or `wallet` is required" }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC, floored to 5 minutes. Default: the newest snapshot. Not before 2026-07-29, not in the future", "default": "", "title": "At" }, "description": "ISO-8601 UTC, floored to 5 minutes. Default: the newest snapshot. Not before 2026-07-29, not in the future" }, { "name": "oid", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "One order id", "default": 0, "title": "Oid" }, "description": "One order id" }, { "name": "order_type", "in": "query", "required": false, "schema": { "type": "string", "description": "`Limit` | `Stop Market` | `Stop Limit` | `Take Profit Market` | `Take Profit Limit` | `Trailing Stop Market`", "default": "", "title": "Order Type" }, "description": "`Limit` | `Stop Market` | `Stop Limit` | `Take Profit Market` | `Take Profit Limit` | `Trailing Stop Market`" }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Placed at or after", "default": "", "title": "Created From" }, "description": "ISO-8601 UTC. Placed at or after" }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Placed at or before", "default": "", "title": "Created To" }, "description": "ISO-8601 UTC. Placed at or before" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Default 100, max 1000", "default": 100, "title": "Limit" }, "description": "Default 100, max 1000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/orders": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Orders", "description": "What became of one wallet's orders in a window: each order seen resting in it or filled in it, with its\nfills in the window and a `status`. Newest placement first; `notes` says what a snapshot cannot tell.", "operationId": "wallet_orders_v1_hyperliquid_wallets__address__orders_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: 7 days before `to`", "default": "", "title": "From" }, "description": "ISO-8601 UTC. Default: 7 days before `to`" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: the newest order snapshot. At most 30 days after `from`", "default": "", "title": "To" }, "description": "ISO-8601 UTC. Default: the newest order snapshot. At most 30 days after `from`" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL perp ticker", "default": "", "title": "Symbol" }, "description": "HL perp ticker" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "`open` | `filled` | `partially_filled` | `canceled_or_expired`", "default": "", "title": "Status" }, "description": "`open` | `filled` | `partially_filled` | `canceled_or_expired`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Default 100, max 1000", "default": 100, "title": "Limit" }, "description": "Default 100, max 1000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/symbols/{symbol}/order-clusters": { "get": { "tags": [ "hyperliquid" ], "summary": "Order Clusters", "description": "One symbol's standing orders within `range_pct` of the mid of the best resting bid and ask, bucketed by price:\nbid / ask by limit price, tp / sl by trigger price.\n\nTrailing stops are not bucketed. For an `at` with no complete 5-minute snapshot at that instant (before\n2026-10-23 21:45 UTC, or inside an outage) the book is rebuilt from the sightings on both sides of it: short-lived\norders can be missing and `reference_price` then reflects the long-lived orders only. A call without `at` is\nnever rebuilt: it is the newest snapshot, or the newest checkpoint while the 5-minute feed is stalled. For a past\n`at`, sizes can be later, smaller remaining sizes.", "operationId": "order_clusters_v1_hyperliquid_symbols__symbol__order_clusters_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL perp ticker", "title": "Symbol" }, "description": "HL perp ticker" }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC, floored to 5 minutes. Default: the newest snapshot", "default": "", "title": "At" }, "description": "ISO-8601 UTC, floored to 5 minutes. Default: the newest snapshot" }, { "name": "step_bps", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Bucket width in basis points of the reference price. Default 10", "default": 10, "title": "Step Bps" }, "description": "Bucket width in basis points of the reference price. Default 10" }, { "name": "range_pct", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Half-width of the price range, percent. Default 10", "default": 10, "title": "Range Pct" }, "description": "Half-width of the price range, percent. Default 10" }, { "name": "cohort_axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. Default `size`", "default": "", "title": "Cohort Axis" }, "description": "`size` | `pnl` | `pnl_abs`. Default `size`" }, { "name": "cohort", "in": "query", "required": false, "schema": { "type": "string", "description": "One label on `cohort_axis`, by CURRENT labels: refused with `at`", "default": "", "title": "Cohort" }, "description": "One label on `cohort_axis`, by CURRENT labels: refused with `at`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/leaderboard": { "get": { "tags": [ "hyperliquid" ], "summary": "Leaderboard", "description": "Trader leaderboard carrying the full risk-metric set.\n\nDrawdown, Calmar, recovery factor, profit factor, expectancy and streaks sit\nbeside PnL: a wallet up 300% through a 70% drawdown is not the same find as\none up 300% without, and a PnL-only board cannot tell them apart.\n\n``calmar_ratio`` and ``recovery_factor`` divide by CURRENT account value, so they are null\nunder $1 of it, and ``sort=calmar``, ``recovery_factor`` or ``roi`` skips those wallets (an\nemptied account used to lead with a ratio in the billions). ``profit_factor`` is capped at 999:\n999 means no losing trade closed, or only a negligible one, not a measured ratio.", "operationId": "leaderboard_v1_hyperliquid_leaderboard_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `30d`. The trades CLOSED in the current UTC day and the 1, 7, 30 or 365 days before it, so PnL, trade counts, win rates and tags are what was realized in the window", "default": "30d", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `30d`. The trades CLOSED in the current UTC day and the 1, 7, 30 or 365 days before it, so PnL, trade counts, win rates and tags are what was realized in the window" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "One of `pnl`, `realized_pnl`, `roi`, `volume`, `trades`, `win_rate`, `long_win_rate`, `short_win_rate`, `account_value`, `profit_factor`, `expectancy`, `calmar`, `recovery_factor`, `max_drawdown`, `current_drawdown`, `avg_leverage`, `avg_duration`, `fees`, `win_streak`, `loss_streak`. Default `pnl`. An unknown key is a `400`, not a default", "default": "pnl", "title": "Sort" }, "description": "One of `pnl`, `realized_pnl`, `roi`, `volume`, `trades`, `win_rate`, `long_win_rate`, `short_win_rate`, `account_value`, `profit_factor`, `expectancy`, `calmar`, `recovery_factor`, `max_drawdown`, `current_drawdown`, `avg_leverage`, `avg_duration`, `fees`, `win_streak`, `loss_streak`. Default `pnl`. An unknown key is a `400`, not a default" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "cohort", "in": "query", "required": false, "schema": { "type": "string", "description": "One label on `axis`", "default": "", "title": "Cohort" }, "description": "One label on `axis`" }, { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. Default `size`", "default": "size", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs`. Default `size`" }, { "name": "min_trades", "in": "query", "required": false, "schema": { "type": "integer", "description": "Minimum closed trades in the window. Default 3, the floor `/traders` applies; pass `0` for no floor", "default": 3, "title": "Min Trades" }, "description": "Minimum closed trades in the window. Default 3, the floor `/traders` applies; pass `0` for no floor" }, { "name": "min_win_rate", "in": "query", "required": false, "schema": { "type": "number", "description": "Minimum win rate", "default": 0.0, "title": "Min Win Rate" }, "description": "Minimum win rate" }, { "name": "min_volume", "in": "query", "required": false, "schema": { "type": "number", "description": "Minimum total volume", "default": 0.0, "title": "Min Volume" }, "description": "Minimum total volume" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 25, max 500", "default": 25, "title": "Limit" }, "description": "Default 25, max 500" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/leaderboard/flow-adjusted": { "get": { "tags": [ "hyperliquid" ], "summary": "Leaderboard Flow Adjusted", "description": "Leaderboard ranked on trading PnL, with external flow reported beside it.\n\nAn account-value delta is not a trading result: a wallet that deposits $1M\nand loses $50k reads as +$950k on any equity-delta ranking. This ranks on\n**fills-derived realized PnL**, which excludes deposits by construction, and\nreturns the deposits, withdrawals and the daily attribution figures in the\nsame row so a caller can see what was excluded rather than trust that\nsomething was.\n\nEach row carries ``flow_unbalanced``. It is true when the wallet had a\n``send`` in the window, which is when the *attributed* block beside the rank\nis unreliable — ``ledger_events`` records ``send`` one-sided, so an outflow\nis seen while the matching inflow is not. The rank itself does not depend on\nattribution and is unaffected. The flag is reported, never used to filter:\nactive traders move money constantly, and excluding them would empty the\nboard rather than clean it.", "operationId": "leaderboard_flow_adjusted_v1_hyperliquid_leaderboard_flow_adjusted_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `30d`. The trades CLOSED in the current UTC day and the 1, 7, 30 or 365 days before it, so PnL, trade counts, win rates and tags are what was realized in the window", "default": "30d", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `30d`. The trades CLOSED in the current UTC day and the 1, 7, 30 or 365 days before it, so PnL, trade counts, win rates and tags are what was realized in the window" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 25, max 500", "default": 25, "title": "Limit" }, "description": "Default 25, max 500" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" }, { "name": "min_trades", "in": "query", "required": false, "schema": { "type": "integer", "description": "Minimum closed trades in the window. Default 3; `0` keeps any wallet with at least one", "default": 3, "title": "Min Trades" }, "description": "Minimum closed trades in the window. Default 3; `0` keeps any wallet with at least one" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Summary", "description": "One wallet: equity, cohorts, risk metrics, lifetime external flow.\n\n``openedWithin`` bounds the **open-positions block only** — the equity,\nlifetime and metrics blocks are wallet-level totals with nothing per-position\nto filter, and bounding them would return a number that looks bounded and is\nnot. Positions with no known open time are excluded from every bounded\nbucket, matching what ``/v1/hl-cohorts/segments`` and ``/v1/hl-cohorts/heatmap`` do, so cohort\ncomparisons stay like-for-like.\n\n``open_positions.perp_bias`` = (long - short) / ``equity.account_value`` and\n``open_positions.equity_exposure`` = (long + short) / ``equity.account_value``, native perp\naccount only: positions on the main dex over the native perp account value; builder-DEX\npositions are not included. Unbounded ratios, null with no main-dex position or no positive\nequity.\n\nA wallet we hold nothing for (no equity snapshot, open position, trade, fill\nor ledger event) is a ``400`` naming it, not a block of zeros.", "operationId": "wallet_summary_v1_hyperliquid_wallets__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `all`", "default": "all", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `all`" }, { "name": "openedWithin", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `all`. Default `all`", "default": "all", "title": "Openedwithin" }, "description": "`24h` | `7d` | `30d` | `all`. Default `all`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/trades": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Trades", "description": "Closed round-trip trades for one wallet.", "operationId": "wallet_trades_v1_hyperliquid_wallets__address__trades_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker, e.g. `BTC`. Omit for all", "default": "", "title": "Symbol" }, "description": "HL ticker, e.g. `BTC`. Omit for all" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/trades/summary": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Trades Summary", "description": "Trade statistics for one wallet, overall and **per coin**.\n\nMedians as well as means: one $4M outlier drags the mean trade size far from\nanything the wallet typically does, and the mean is where most leaderboards\nstop.\n\nA wallet with no trade at all is a ``400`` naming it, not zeros. A wallet\nthat has traded and was quiet in the requested ``window`` gets the zeros,\nwhich are true.", "operationId": "wallet_trades_summary_v1_hyperliquid_wallets__address__trades_summary_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `all`", "default": "all", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `all`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/fills": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Fills", "description": "Raw fills for one wallet.", "operationId": "wallet_fills_v1_hyperliquid_wallets__address__fills_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker", "default": "", "title": "Symbol" }, "description": "HL ticker" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "description": "`buy` | `sell`", "default": "", "title": "Side" }, "description": "`buy` | `sell`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/funding": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Funding", "description": "Funding paid and received by one wallet.", "operationId": "wallet_funding_v1_hyperliquid_wallets__address__funding_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker", "default": "", "title": "Symbol" }, "description": "HL ticker" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/ledger": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Ledger", "description": "Deposits, withdrawals, transfers and vault events for one wallet.", "operationId": "wallet_ledger_v1_hyperliquid_wallets__address__ledger_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "description": "One of `accountClassTransfer`, `borrowLend`, `deposit`, `internalTransfer`, `rewardsClaim`, `send`, `spotTransfer`, `subAccountTransfer`, `vaultCreate`, `vaultDeposit`, `vaultDistribution`, `vaultLeaderCommission`, `vaultWithdraw`, `withdraw`. Validated against this fixed set", "default": "", "title": "Event Type" }, "description": "One of `accountClassTransfer`, `borrowLend`, `deposit`, `internalTransfer`, `rewardsClaim`, `send`, `spotTransfer`, `subAccountTransfer`, `vaultCreate`, `vaultDeposit`, `vaultDistribution`, `vaultLeaderCommission`, `vaultWithdraw`, `withdraw`. Validated against this fixed set" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/twaps": { "get": { "tags": [ "hyperliquid" ], "summary": "Twaps", "description": "TWAP orders across wallets, one row per status line, newest first.\n\nA line is a status CHANGE (`activated`, `waitingForTrigger`, then `finished`, `terminated` or `stopped`),\nnot a slice fill: `executed_size` and `executed_notional_usd` are the cumulative totals when the line was\nwritten. Rejected placements (`error`) are hidden unless `status=error`. Rows sharing a `ts` keep a stable\norder, so a cursor never skips or repeats one.", "operationId": "twaps_v1_hyperliquid_twaps_get", "parameters": [ { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "description": "One wallet, `0x` plus 40 hex, any case", "default": "", "title": "Wallet" }, "description": "One wallet, `0x` plus 40 hex, any case" }, { "name": "twap_id", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9007199254740991, "minimum": 0, "description": "One TWAP id: every status line of that TWAP", "default": 0, "title": "Twap Id" }, "description": "One TWAP id: every status line of that TWAP" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker, e.g. `BTC` or `xyz:AAPL`", "default": "", "title": "Symbol" }, "description": "HL ticker, e.g. `BTC` or `xyz:AAPL`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "One of `activated`, `waitingForTrigger`, `finished`, `terminated`, `stopped`, `error`. Default: every status except `error`, a rejected placement rather than an order; `status=error` shows those rows", "default": "", "title": "Status" }, "description": "One of `activated`, `waitingForTrigger`, `finished`, `terminated`, `stopped`, `error`. Default: every status except `error`, a rejected placement rather than an order; `status=error` shows those rows" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: the 24 hours before `end` (before now when `end` is empty), unless `wallet` or `twap_id` is given. Resuming an `order=asc` cursor starts from the cursor instead; a `desc` cursor keeps the 24-hour floor", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Default: the 24 hours before `end` (before now when `end` is empty), unless `wallet` or `twap_id` is given. Resuming an `order=asc` cursor starts from the cursor instead; a `desc` cursor keeps the 24-hour floor" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: now. A window wider than 31 days is a `400` unless `wallet` or `twap_id` is given", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Default: now. A window wider than 31 days is a `400` unless `wallet` or `twap_id` is given" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call with no `start` or `wallet` or `twap_id`, a cursor at the lower bound of the default window (`null` when one of them already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page that comes back short carries no cursor. Anything else is a `400`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call with no `start` or `wallet` or `twap_id`, a cursor at the lower bound of the default window (`null` when one of them already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page that comes back short carries no cursor. Anything else is a `400`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. Without `wallet` or `twap_id`, an `asc` cursor more than 31 days before `end` (before now when `end` is empty) is a `400` too: restart with `start`. `/twaps?wallet=` and the per-wallet TWAP route are one feed: with the same parameters their cursors are interchangeable", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. Without `wallet` or `twap_id`, an `asc` cursor more than 31 days before `end` (before now when `end` is empty) is a `400` too: restart with `start`. `/twaps?wallet=` and the per-wallet TWAP route are one feed: with the same parameters their cursors are interchangeable" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/twaps": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Twaps", "description": "One wallet's TWAP orders: `/twaps` with the wallet pinned, wrapped as `wallet`, `items`, `nextCursor`.", "operationId": "wallet_twaps_v1_hyperliquid_wallets__address__twaps_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "twap_id", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9007199254740991, "minimum": 0, "description": "One TWAP id: every status line of that TWAP", "default": 0, "title": "Twap Id" }, "description": "One TWAP id: every status line of that TWAP" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker, e.g. `BTC` or `xyz:AAPL`", "default": "", "title": "Symbol" }, "description": "HL ticker, e.g. `BTC` or `xyz:AAPL`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "One of `activated`, `waitingForTrigger`, `finished`, `terminated`, `stopped`, `error`. Default: every status except `error`, a rejected placement rather than an order; `status=error` shows those rows", "default": "", "title": "Status" }, "description": "One of `activated`, `waitingForTrigger`, `finished`, `terminated`, `stopped`, `error`. Default: every status except `error`, a rejected placement rather than an order; `status=error` shows those rows" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: no lower bound", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Default: no lower bound" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: now. The window has no 31-day cap", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Default: now. The window has no 31-day cap" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call `null` (the wallet already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page that comes back short carries no cursor. Anything else is a `400`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call `null` (the wallet already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page that comes back short carries no cursor. Anything else is a `400`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. It is also valid on `/twaps?wallet=` with the same parameters", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. It is also valid on `/twaps?wallet=` with the same parameters" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/ledger": { "get": { "tags": [ "hyperliquid" ], "summary": "Ledger Feed", "description": "Deposits, withdrawals, transfers and vault events across wallets, newest first.\n\nThe cross-wallet twin of `/wallets/{address}/ledger`, with `wallet` on every row. A transfer between two\nwallets is one row per affected wallet with the same `hash`.", "operationId": "ledger_feed_v1_hyperliquid_ledger_get", "parameters": [ { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "description": "One wallet, `0x` plus 40 hex, any case", "default": "", "title": "Wallet" }, "description": "One wallet, `0x` plus 40 hex, any case" }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "description": "One of `accountClassTransfer`, `borrowLend`, `deposit`, `internalTransfer`, `rewardsClaim`, `send`, `spotTransfer`, `subAccountTransfer`, `vaultCreate`, `vaultDeposit`, `vaultDistribution`, `vaultLeaderCommission`, `vaultWithdraw`, `withdraw`. Validated against this fixed set", "default": "", "title": "Event Type" }, "description": "One of `accountClassTransfer`, `borrowLend`, `deposit`, `internalTransfer`, `rewardsClaim`, `send`, `spotTransfer`, `subAccountTransfer`, `vaultCreate`, `vaultDeposit`, `vaultDistribution`, `vaultLeaderCommission`, `vaultWithdraw`, `withdraw`. Validated against this fixed set" }, { "name": "min_usd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "description": "Minimum absolute `amount_usd`, 0 or more. Default `0`: no floor", "default": 0.0, "title": "Min Usd" }, "description": "Minimum absolute `amount_usd`, 0 or more. Default `0`: no floor" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: the 24 hours before `end` (before now when `end` is empty), unless `wallet` is given. Resuming an `order=asc` cursor starts from the cursor instead; a `desc` cursor keeps the 24-hour floor", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Default: the 24 hours before `end` (before now when `end` is empty), unless `wallet` is given. Resuming an `order=asc` cursor starts from the cursor instead; a `desc` cursor keeps the 24-hour floor" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: now. A window wider than 31 days is a `400` unless `wallet` is given", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Default: now. A window wider than 31 days is a `400` unless `wallet` is given" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call with no `start` or `wallet`, a cursor at the lower bound of the default window (`null` when one of them already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page the read finds short carries no cursor, but duplicate rows are dropped from a page after it is read, so a page with fewer than `limit` rows can still carry one: stop on an empty page. Anything else is a `400`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call with no `start` or `wallet`, a cursor at the lower bound of the default window (`null` when one of them already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page the read finds short carries no cursor, but duplicate rows are dropped from a page after it is read, so a page with fewer than `limit` rows can still carry one: stop on an empty page. Anything else is a `400`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. Without `wallet`, an `asc` cursor more than 31 days before `end` (before now when `end` is empty) is a `400` too: restart with `start`", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. Without `wallet`, an `asc` cursor more than 31 days before `end` (before now when `end` is empty) is a `400` too: restart with `start`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/leverage-changes": { "get": { "tags": [ "hyperliquid" ], "summary": "Leverage Changes", "description": "Positions whose leverage or margin mode differs between two consecutive complete position snapshots,\nnewest first.\n\nOne row per wallet and symbol, with the previous and the new value of leverage, margin mode, side, size and\nentry price. `ts` is when the later snapshot was written, not when the venue changed the setting. Snapshots\nare stamped every 5 minutes, but the positions behind them are captured about every 12 minutes, so changes\narrive in batches.", "operationId": "leverage_changes_v1_hyperliquid_leverage_changes_get", "parameters": [ { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "description": "One wallet, `0x` plus 40 hex, any case", "default": "", "title": "Wallet" }, "description": "One wallet, `0x` plus 40 hex, any case" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker, e.g. `BTC` or `xyz:TSLA`", "default": "", "title": "Symbol" }, "description": "HL ticker, e.g. `BTC` or `xyz:TSLA`" }, { "name": "change", "in": "query", "required": false, "schema": { "type": "string", "description": "`up` (leverage rose) | `down` (leverage fell) | `mode` (only the margin mode, `cross` or `isolated`, changed). Validated against this fixed set", "default": "", "title": "Change" }, "description": "`up` (leverage rose) | `down` (leverage fell) | `mode` (only the margin mode, `cross` or `isolated`, changed). Validated against this fixed set" }, { "name": "min_leverage", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "description": "Minimum new `leverage`, 0 or more. Default `0`: no floor", "default": 0.0, "title": "Min Leverage" }, "description": "Minimum new `leverage`, 0 or more. Default `0`: no floor" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: the 24 hours before `end` (before now when `end` is empty), unless `wallet` is given. Resuming an `order=asc` cursor starts from the cursor instead; a `desc` cursor keeps the 24-hour floor", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Default: the 24 hours before `end` (before now when `end` is empty), unless `wallet` is given. Resuming an `order=asc` cursor starts from the cursor instead; a `desc` cursor keeps the 24-hour floor" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Default: now. A window wider than 31 days is a `400` unless `wallet` is given", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Default: now. A window wider than 31 days is a `400` unless `wallet` is given" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call with no `start` or `wallet`, a cursor at the lower bound of the default window (`null` when one of them already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page that comes back short carries no cursor. Anything else is a `400`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`, newest first. `order=asc` returns the oldest events first and is the mode for following a feed: pass each `nextCursor` back verbatim. It orders by key, so a row the writer inserts late with an older key is not seen by a poller already past it: re-read a small overlap. An `asc` page with rows always carries a cursor; an empty one returns the cursor you sent, or on a first call with no `start` or `wallet`, a cursor at the lower bound of the default window (`null` when one of them already pins the place). So stop on an empty page, not on a `null` cursor. A `desc` page that comes back short carries no cursor. Anything else is a `400`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. Without `wallet`, an `asc` cursor more than 31 days before `end` (before now when `end` is empty) is a `400` too: restart with `start`", "default": "", "title": "Cursor" }, "description": "`nextCursor` from the previous page, verbatim. It pins the call that returned it: the feed, `order`, every filter and the `start` and `end` you sent. Changing or dropping any of them, `start` included, is a `400`. Without `wallet`, an `asc` cursor more than 31 days before `end` (before now when `end` is empty) is a `400` too: restart with `start`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/liquidations": { "get": { "tags": [ "hyperliquid" ], "summary": "Liquidations", "description": "Liquidation events, newest first: exact, from the node's fills since 2026-08-03; older rows inferred from position snapshots.\n\nSince 2026-08-03 a row is the liquidated account's own fill, as the venue marked it: ``liq_ts``\nis the fill's millisecond time, ``size_token`` and ``size_usd`` the size it closed (fills of one\nliquidation in the same millisecond summed) and ``mark_price`` the mark price the venue\nliquidated at. An older row is a position worth over $100 whose mark was within 5% of its\nliquidation price in one snapshot (taken about every 5 minutes) and that is gone from the next:\n``liq_ts`` is the time of that snapshot, size and mark are the last values seen, a position\nclosed by hand that close to its liquidation price is counted and a partial liquidation is not.\n\nEach row's ``pnl_cohort`` is point-in-time — the label as it stood at the\nliquidation's own hour — where the hourly label table covers it, and the\nquery-time dictionary label where it cannot; ``pnl_cohort_basis`` says\nwhich per row, and the envelope's ``label_computed`` declares the\nprovenance and the two windows with no point-in-time label (rows before\n2026-04-07, and the newest hours the label job has not yet published).", "operationId": "liquidations_v1_hyperliquid_liquidations_get", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker", "default": "", "title": "Symbol" }, "description": "HL ticker" }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "description": "One wallet", "default": "", "title": "Wallet" }, "description": "One wallet" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "description": "`long` | `short`", "default": "", "title": "Direction" }, "description": "`long` | `short`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/symbols/{symbol}/liquidation-heatmap": { "get": { "tags": [ "hyperliquid" ], "summary": "Liquidation Heatmap", "description": "Where liquidations would cluster if price moved — every open position's\nown liquidation price, binned and weighted by notional.", "operationId": "liquidation_heatmap_v1_hyperliquid_symbols__symbol__liquidation_heatmap_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL ticker", "title": "Symbol" }, "description": "HL ticker" }, { "name": "bins", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 5, "description": "Number of price bins. Default 50, min 5, max 500", "default": 50, "title": "Bins" }, "description": "Number of price bins. Default 50, min 5, max 500" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/liquidations/risk": { "get": { "tags": [ "hyperliquid" ], "summary": "Liquidation Risk", "description": "Share of each coin's open interest sitting close to liquidation.", "operationId": "liquidation_risk_v1_hyperliquid_liquidations_risk_get", "parameters": [ { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. Default `size`", "default": "size", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs`. Default `size`" }, { "name": "cohort", "in": "query", "required": false, "schema": { "type": "string", "description": "One label on that axis", "default": "", "title": "Cohort" }, "description": "One label on that axis" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 100, max 500", "default": 100, "title": "Limit" }, "description": "Default 100, max 500" }, { "name": "min_value_usd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "description": "Smallest total open notional (USD) a coin needs to be ranked. Default 0 (no floor): the ranking is by `percent_risk`, so small markets with a few thousand dollars of interest lead it; raise this to keep only markets big enough for a cascade to matter.", "default": 0.0, "title": "Min Value Usd" }, "description": "Smallest total open notional (USD) a coin needs to be ranked. Default 0 (no floor): the ranking is by `percent_risk`, so small markets with a few thousand dollars of interest lead it; raise this to keep only markets big enough for a cascade to matter." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/stats": { "get": { "tags": [ "hyperliquid" ], "summary": "Stats", "description": "Ecosystem time series: perp equity, open interest, position counts.", "operationId": "stats_v1_hyperliquid_stats_get", "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 500, max 5000", "default": 500, "title": "Limit" }, "description": "Default 500, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/stats/volume": { "get": { "tags": [ "hyperliquid" ], "summary": "Stats Volume", "description": "Hourly perp volume, whole venue or one coin.\n\n``volume`` is the traded notional counted once per trade (one side), the figure the candles\nreport; until 2026-10-25 it counted both sides of every trade and was exactly twice that.\nThe venue total (no ``symbol``) is perp volume, builder-dex perps included, and leaves out spot\nand outcome markets; naming one of those as ``symbol`` still returns it. ``n_fills`` counts fill\nrecords, two per trade (one for each side).", "operationId": "stats_volume_v1_hyperliquid_stats_volume_get", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker. Omit for the whole venue", "default": "", "title": "Symbol" }, "description": "HL ticker. Omit for the whole venue" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 500, max 5000", "default": 500, "title": "Limit" }, "description": "Default 500, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/hype/holders": { "get": { "tags": [ "hyperliquid" ], "summary": "Hype Holders", "description": "HYPE holder leaderboard — spot balance plus staked, per wallet.\n\n``pnl_cohort`` is resolved at query time and the envelope declares it\n(``label_basis='current'`` + ``label_computed``). Correct here, not a\nfallback: the leaderboard has no time axis — every row is last-known\nstate, so a current label has no earlier row to contaminate. The caveat\nruns the other way: balances are last-known, so a stale balance can sit\nbeside a fresh label. ``account_value`` is the wallet's perp account value and is ``null``\nfor a holder with no perp account on record (it used to read ``0.0``, the same as an account\nthat really holds nothing).", "operationId": "hype_holders_v1_hyperliquid_hype_holders_get", "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 100, max 500", "default": 100, "title": "Limit" }, "description": "Default 100, max 500" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/builders": { "get": { "tags": [ "hyperliquid" ], "summary": "Builder Leaderboard", "description": "Builder leaderboard — fee revenue, routed volume, unique traders, fills.\n\n``sort=fee`` ranks the builder's own cut, not the trader's total cost; the\ntwo orderings differ materially because take rates range from ~0.2 bps to\n~3.4 bps across the top of the board.\n\n``fee_usd`` and ``volume_usd`` cover every builder fill on record, older history included;\n``trader_fee_usd`` covers only the newer, dollar-paid fills, so ``fee_usd / trader_fee_usd`` is not\na take rate (it can pass 100%). Use ``fee_usd_node / trader_fee_usd``: ``fee_usd_node`` is the\nbuilder's revenue over exactly the fills ``trader_fee_usd`` covers.\n\nEvery row carries ``active_days`` for the window. The history is still being\nfilled in, so a long window can currently cover\nfewer days than it names — ``active_days`` beside the resolved\n``window.start`` / ``window.end`` is how a client tells a quiet builder from\nan unfilled window instead of guessing.\n\n``market_share_pct`` is the row's routed notional over **all** Hyperliquid\nfill notional, measured over ``market_share_window_start`` → ``window.end``\n— which can start LATER than ``window.start``. Venue-wide volume exists only\nfrom the node's own retained fills, while the builder history reaches months\nfurther back via Hyperliquid's published CSVs, and that gap is permanent\nrather than a backlog. The share is therefore taken over the overlap; a\nnumber covering less than the requested window says so instead of quietly\nmeaning something else.\n\n**Auditing it:** divide ``share_volume_usd`` (the clamped numerator, shipped\nper row) by ``venue_volume_usd`` (top level). Do NOT use ``volume_usd`` —\nthat is the row's full unclamped notional for the requested window, so on\n``window=all`` it can exceed the numerator by more than 2x.\n\n``first_seen_lifetime`` is NOT window-scoped (``first_seen`` is) —\nit is the builder's genuine first fill, which is the only one of the two that\nanswers \"how established is this front-end\". Every ``*_pct`` here is\npercentage points, 0-100.", "operationId": "builder_leaderboard_v1_hyperliquid_builders_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `30d`", "default": "30d", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `30d`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`fee` | `volume` | `users` | `fills`. Default `fee`", "default": "fee", "title": "Sort" }, "description": "`fee` | `volume` | `users` | `fills`. Default `fee`" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 50, max 500", "default": 50, "title": "Limit" }, "description": "Default 50, max 500" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/builders/stats": { "get": { "tags": [ "hyperliquid" ], "summary": "Builder Ecosystem Stats", "description": "Builder-code economics for the whole venue — the summary-card surface.\n\nAnswers what no per-builder route can: how many builders are active, how many\ndistinct traders route through one, what share of all Hyperliquid fill\nnotional carries a builder code, and how that moved day by day.\n``lifetime.fee_usd`` is all-time and unwindowed. No fixed figure or start\ndate is quoted here: builder history is imported from Hyperliquid's\npublished per-builder fee CSVs, which reach back to the launch of builder\ncodes, so both move as that import proceeds. Read ``lifetime.first_seen``\nfor the actual coverage start. (This line previously read \"$21.7M since\n2026-04-05\" and was 40% low and eight months late within a day.)\n\n**Declared before ``/builders/{builder}``** because Starlette matches in\ndeclaration order and compiles ``{builder}`` to ``[^/]+``: the other way\nround, this path returns a 400 for a builder literally named \"stats\".", "operationId": "builder_ecosystem_stats_v1_hyperliquid_builders_stats_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `30d`", "default": "30d", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `30d`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/builders/{builder}": { "get": { "tags": [ "hyperliquid" ], "summary": "Builder Profile", "description": "One builder: window totals plus per-asset and per-dex breakdowns.\n\n``fee_rate_bps`` is the realized effective rate (fee / volume); the venue's\nconfigured per-order rate is not in the data. ``fee_rate_bps_p50`` is the\nmedian across fills that actually paid a builder fee, which is the closest\nobservable thing to an advertised rate — 21% of rows pay the builder nothing\nand drag the mean.\n\n``user_volume_distribution`` is the concentration answer: users split into\nvolume deciles, so \"19k users\" and \"one whale plus a tail\" stop looking the\nsame. ``profitable_users`` is a per-**wallet** test (``sum(closed_pnl) > 0``),\nnot a per-fill one — a wallet that won once and lost once is one loser.\n``lifetime`` is unwindowed and is what makes a 30-day window interpretable.", "operationId": "builder_profile_v1_hyperliquid_builders__builder__get", "parameters": [ { "name": "builder", "in": "path", "required": true, "schema": { "type": "string", "description": "Builder address", "title": "Builder" }, "description": "Builder address" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `30d`", "default": "30d", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `30d`" }, { "name": "breakdown_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Rows per breakdown. Default 100, max 1000", "default": 100, "title": "Breakdown Limit" }, "description": "Rows per breakdown. Default 100, max 1000" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/builders/{builder}/users": { "get": { "tags": [ "hyperliquid" ], "summary": "Builder Users", "description": "The wallets routing through one builder, ranked.\n\n``sort=pnl`` ranks ``sum(closed_pnl)`` — the **traders'** realized result,\nnot the builder's. It is signed, and a builder whose users lose money is a\ndifferent business from one whose users win.", "operationId": "builder_users_v1_hyperliquid_builders__builder__users_get", "parameters": [ { "name": "builder", "in": "path", "required": true, "schema": { "type": "string", "description": "Builder address", "title": "Builder" }, "description": "Builder address" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `30d`", "default": "30d", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `30d`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`volume` | `fees` | `pnl`. Default `volume`", "default": "volume", "title": "Sort" }, "description": "`volume` | `fees` | `pnl`. Default `volume`" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Default 100, max 1000", "default": 100, "title": "Limit" }, "description": "Default 100, max 1000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/builders/{builder}/fills": { "get": { "tags": [ "hyperliquid" ], "summary": "Builder Fills", "description": "Raw builder-routed fills, newest first.\n\n``fee`` ships raw beside its own ``fee_token`` here, unlike every aggregate\nin this namespace: 0.95% of fills pay in a non-dollar token, so summing this\ncolumn client-side without grouping by ``fee_token`` produces nonsense.\n``fee_usd`` (the builder's slice) is dollars on every row.", "operationId": "builder_fills_v1_hyperliquid_builders__builder__fills_get", "parameters": [ { "name": "builder", "in": "path", "required": true, "schema": { "type": "string", "description": "Builder address", "title": "Builder" }, "description": "Builder address" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "description": "HL ticker", "default": "", "title": "Symbol" }, "description": "HL ticker" }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "description": "`buy` | `sell`", "default": "", "title": "Side" }, "description": "`buy` | `sell`" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 100, max 5000", "default": 100, "title": "Limit" }, "description": "Default 100, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/builders/{builder}/series": { "get": { "tags": [ "hyperliquid" ], "summary": "Builder Series", "description": "Fee, volume, users and fills per bucket for one builder, newest first.\n\n``users`` is a distinct count per bucket and is **not** additive — summing the\ndaily column double-counts anyone who traded on two days. A period total\ncomes from ``/builders/{builder}`` over that period.", "operationId": "builder_series_v1_hyperliquid_builders__builder__series_get", "parameters": [ { "name": "builder", "in": "path", "required": true, "schema": { "type": "string", "description": "Builder address", "title": "Builder" }, "description": "Builder address" }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "description": "`1h` | `1d`. Default `1d`", "default": "1d", "title": "Bucket" }, "description": "`1h` | `1d`. Default `1d`" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2000, "description": "Default 500, max 2000", "default": 500, "title": "Limit" }, "description": "Default 500, max 2000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/wallets/{address}/builders": { "get": { "tags": [ "hyperliquid" ], "summary": "Wallet Builders", "description": "Reverse lookup — which builders this wallet's flow is routed through.\n\n``share_of_volume`` is the share of the wallet's **builder-routed** volume.\nFills placed without a builder code never reach this table, so it is not a\nshare of the wallet's total trading.", "operationId": "wallet_builders_v1_hyperliquid_wallets__address__builders_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet", "title": "Address" }, "description": "The wallet" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `7d` | `30d` | `all`. Default `all`", "default": "all", "title": "Window" }, "description": "`1d` | `7d` | `30d` | `all`. Default `all`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 50, max 500", "default": 50, "title": "Limit" }, "description": "Default 50, max 500" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault List", "description": "Every Hyperliquid vault, one row per vault family: current TVL, APR, the window's PnL, return, net\nflow, volume and fills, and the risk columns.\n\nHLP and its sub-vaults are ONE row (``child_vaults`` lists them), every dollar counted once. A window ends\non the newest recorded day and reaches back 7, 30, 90 or 365 days; ``all`` is all recorded history.\nWindows are whole UTC days, from the close of the ``start`` day to the newest reading, so a figure can\ndiffer from the venue's own rolling week or month by up to one day's movement; ``tvl_usd`` is within a few\npercent of the venue's own figure. The top-level ``window`` states the resolved bounds, and each row its own ``start`` and ``partial``: a vault\nyounger than the window starts later. A family is measured from the first day inside the window on which\nall its open vaults are recorded (its ``start``; ``partial`` true when that is later than the window's),\nevery vault over that same span; if one of them has no record that day, ``pnl_usd``, ``return_pct`` and\n``apr_pct`` are null. A family's flows are the deposits into and withdrawals from its parent only: a\nsub-vault's own deposits and withdrawals are the parent moving money between its vaults, and ``pnl_usd``\nnets them out. A closed sub-vault holds nothing and never holds a family's figures back.\n\n``pnl_usd`` is the equity change minus net deposits, null until a day after ``start`` is recorded (as\n``return_pct`` is). ``return_pct`` is the chained share-price return in percentage points over the days\nwith a measurable share-price step; days without one are skipped, and ``coverage`` (a fraction) says how\nmuch of the window was measured. It is null below 95% coverage, and null when a rebuilt day before\n2026-10-27 holds a share-price jump of more than 2x either way that is not one of a pair (a jump and an\nequally large reversal on the next day, with no other such jump beside them, are both skipped). ``apr_pct`` annualises the vault's own 30-day return and is\nnull for a vault, or a family, not recorded for all 30 days. ``net_flow_usd`` counts withdrawals\nand distributions as outflow. ``leverage`` is gross open notional over equity, ``leader_share_pct`` the\nleader's own share and ``top5_share_pct`` the five largest depositors' share, in percentage points, from\nthe newest hourly reading (null for a vault not read in the last day, e.g. a closed one).", "operationId": "vault_list_v1_hyperliquid_vaults_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `30d`", "default": "30d", "title": "Window" }, "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `30d`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`tvl` | `apr` | `pnl` | `return` | `net_flow` | `volume` | `age` | `leverage` | `top5_share`. Default `tvl`", "default": "tvl", "title": "Sort" }, "description": "`tvl` | `apr` | `pnl` | `return` | `net_flow` | `volume` | `age` | `leverage` | `top5_share`. Default `tvl`" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "`open` | `closed` | `all`. Default `open`", "default": "open", "title": "Status" }, "description": "`open` | `closed` | `all`. Default `open`" }, { "name": "deposits", "in": "query", "required": false, "schema": { "type": "string", "description": "`any` | `open` | `closed`: whether the vault accepts deposits. Default `any`", "default": "any", "title": "Deposits" }, "description": "`any` | `open` | `closed`: whether the vault accepts deposits. Default `any`" }, { "name": "min_tvl", "in": "query", "required": false, "schema": { "type": "number", "description": "Minimum current TVL in USD. Default 0", "default": 0.0, "title": "Min Tvl" }, "description": "Minimum current TVL in USD. Default 0" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Search, 2 to 64 characters: a case-insensitive part of the vault name, or an address prefix when it starts with `0x` (a sub-vault's address finds its family). Matched literally: `%` and `_` are not wildcards", "default": "", "title": "Q" }, "description": "Search, 2 to 64 characters: a case-insensitive part of the vault name, or an address prefix when it starts with `0x` (a sub-vault's address finds its family). Matched literally: `%` and `_` are not wildcards" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Default 50, max 500", "default": 50, "title": "Limit" }, "description": "Default 50, max 500" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults/stats": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault Stats", "description": "Vault platform totals: TVL with every vault family counted once, flows over the window, vaults\ncreated per month.\n\n``user_vault_tvl_usd`` is the TVL outside the HLP family and ``hlp_net_flow_usd`` HLP's own net flow.\n``withdrawals_usd`` includes distributions (a vault paying its depositors out), as ``net_flow_usd`` does.\nHLP moving money between its own sub-vaults is not a flow. ``vaults`` and ``open_vaults`` count vault\nfamilies. With no recorded history the money totals and\n``window`` are null.", "operationId": "vault_stats_v1_hyperliquid_vaults_stats_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `30d`", "default": "30d", "title": "Window" }, "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `30d`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults/flows": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault Flows Feed", "description": "Deposits into and withdrawals from every vault, newest first, from the depositor's side.\n\nEach row names the ``depositor``, the ``vault`` and ``direction`` (``in`` | ``out``; ``amount_usd`` is\nunsigned). ``pnl_rank`` is the depositor's rank in the top 1,000 of\n``/v1/hyperliquid/leaderboard?window=all``, else null. ``vault`` is null on rows recorded before\n2026-10-25 06:31 UTC.", "operationId": "vault_flows_feed_v1_hyperliquid_vaults_flows_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `7d`", "default": "7d", "title": "Window" }, "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `7d`" }, { "name": "min_usd", "in": "query", "required": false, "schema": { "type": "number", "description": "Smallest flow in USD. Default 10000", "default": 10000.0, "title": "Min Usd" }, "description": "Smallest flow in USD. Default 10000" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "`all` | `deposit` | `withdraw` | `distribution` | `commission`. Default `all`", "default": "all", "title": "Type" }, "description": "`all` | `deposit` | `withdraw` | `distribution` | `commission`. Default `all`" }, { "name": "smart_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only depositors in the top 1,000 of `/v1/hyperliquid/leaderboard?window=all`. Default false", "default": false, "title": "Smart Only" }, "description": "Only depositors in the top 1,000 of `/v1/hyperliquid/leaderboard?window=all`. Default false" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Default 100, max 1000", "default": 100, "title": "Limit" }, "description": "Default 100, max 1000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults/{vault}": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault Profile", "description": "One vault: registry fields, current TVL, APR, leverage, depositor concentration and all five windows.\n\n``windows`` holds ``7d``, ``30d``, ``90d``, ``365d`` and ``all``, each with ``start``, ``end``,\n``partial``, ``pnl_usd``, ``return_pct``, ``net_flow_usd``, ``volume_usd``, ``fills`` and ``coverage`` as\non ``/vaults``. ``leverage`` is open notional over equity; ``leader_share_pct`` and ``top5_share_pct`` are\nthe leader's and the five largest depositors' shares in percentage points; ``active_depositors`` counts\ndepositors holding at least $1. A parent vault's figures include its sub-vaults (``child_vaults``). With\nno recorded history ``windows``, ``tvl_usd`` and ``apr_pct`` are null; an unknown address is a 404.\n\nThe vault's fills, trades and positions are served by ``/v1/hyperliquid/wallets/{address}/…`` with the\nvault's address.", "operationId": "vault_profile_v1_hyperliquid_vaults__vault__get", "parameters": [ { "name": "vault", "in": "path", "required": true, "schema": { "type": "string", "description": "Vault address", "title": "Vault" }, "description": "Vault address" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults/{vault}/depositors": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault Depositors", "description": "A vault's current depositors, largest share first.\n\n``share_pct`` is the depositor's share of the vault in percentage points and ``equity_usd`` its value at\n``as_of``; a parent vault's depositors own shares of the parent and its sub-vaults together, so the\ntop-level ``equity_usd`` is theirs combined. ``pnl_usd`` is that value minus the cost basis of the depositor's current position (unrealised,\nas the venue reports it), ``all_time_pnl_usd`` that value minus everything the depositor ever put in net\nof what it took out. ``entered_at`` is the depositor's entry into the vault and ``lockup_until`` the end\nof the lockup after its last deposit (null when the vault has no lockup). ``pnl_rank`` is the depositor's\nrank in the top 1,000 of ``/v1/hyperliquid/leaderboard?window=all``, else null. The list is complete:\nevery depositor holding at least ``min_equity_usd``, not only the largest 100; a wallet that has left the\nvault is never listed.", "operationId": "vault_depositors_v1_hyperliquid_vaults__vault__depositors_get", "parameters": [ { "name": "vault", "in": "path", "required": true, "schema": { "type": "string", "description": "Vault address", "title": "Vault" }, "description": "Vault address" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "`share` | `pnl` | `all_time_pnl` | `entered`. Default `share`", "default": "share", "title": "Sort" }, "description": "`share` | `pnl` | `all_time_pnl` | `entered`. Default `share`" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "`asc` | `desc`. Default `desc`", "default": "desc", "title": "Order" }, "description": "`asc` | `desc`. Default `desc`" }, { "name": "smart_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only depositors in the top 1,000 of `/v1/hyperliquid/leaderboard?window=all`. Default false", "default": false, "title": "Smart Only" }, "description": "Only depositors in the top 1,000 of `/v1/hyperliquid/leaderboard?window=all`. Default false" }, { "name": "min_equity_usd", "in": "query", "required": false, "schema": { "type": "number", "description": "Smallest depositor equity in USD, at least 1. Default 1", "default": 1.0, "title": "Min Equity Usd" }, "description": "Smallest depositor equity in USD, at least 1. Default 1" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Default 100, max 1000", "default": 100, "title": "Limit" }, "description": "Default 100, max 1000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults/{vault}/flows": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault Flows", "description": "One vault's own deposits, withdrawals, distributions and leader commissions, newest first.\n\n``counterparty`` is the depositor on deposits and withdrawals (on a deposit it is read from the\ndepositor's own row of the same event; null when that row is missing or ambiguous).\n``amount_usd`` is unsigned and ``direction`` is ``in`` or ``out``. On a parent vault (HLP), the parent\nmoving money into or out of its own sub-vaults is not a row.", "operationId": "vault_flows_v1_hyperliquid_vaults__vault__flows_get", "parameters": [ { "name": "vault", "in": "path", "required": true, "schema": { "type": "string", "description": "Vault address", "title": "Vault" }, "description": "Vault address" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `30d`", "default": "30d", "title": "Window" }, "description": "`7d` | `30d` | `90d` | `365d` | `all`, whole UTC days ending on the newest recorded day. Default `30d`" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "`all` | `deposit` | `withdraw` | `distribution` | `commission`. Default `all`", "default": "all", "title": "Type" }, "description": "`all` | `deposit` | `withdraw` | `distribution` | `commission`. Default `all`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Default 100, max 1000", "default": 100, "title": "Limit" }, "description": "Default 100, max 1000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/vaults/{vault}/series": { "get": { "tags": [ "hyperliquid" ], "summary": "Vault Series", "description": "Equity, share price, net flow and PnL of one vault per hour or day, oldest first.\n\n``nav`` is the chained share price, 1.0 at the first point of the first page; a missing step ends the\nchain (``nav`` null from there), it is never read as 1.0. ``pnl_usd`` is the equity change minus the\npoint's net flow. The cursor carries the previous point, so ``nav`` and ``pnl_usd`` continue across pages.\nA parent vault's (HLP's) series is its family's: ``equity_usd`` sums the parent and the sub-vaults read at\nthat hour, or for a day at the parent's last reading of it (a closed one while it existed, a new one from its\nfirst reading), and\n``net_flow_usd`` is the parent's\ndepositors' deposits and withdrawals, so money moved between the parent and its sub-vaults is not PnL.", "operationId": "vault_series_v1_hyperliquid_vaults__vault__series_get", "parameters": [ { "name": "vault", "in": "path", "required": true, "schema": { "type": "string", "description": "Vault address", "title": "Vault" }, "description": "Vault address" }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "description": "`1d` | `1h`. Default `1d`", "default": "1d", "title": "Bucket" }, "description": "`1d` | `1h`. Default `1d`" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "Start" }, "description": "ISO-8601 UTC bounds" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC bounds", "default": "", "title": "End" }, "description": "ISO-8601 UTC bounds" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 500, max 5000", "default": 500, "title": "Limit" }, "description": "Default 500, max 5000" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/ohlcv": { "get": { "tags": [ "hyperliquid" ], "summary": "Ohlcv", "description": "Hyperliquid candles, derived from executed fills.", "operationId": "ohlcv_v1_hyperliquid_ohlcv_get", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. Perp ticker (`BTC`), spot token (`HYPE`) or raw index (`@107`)", "default": "", "title": "Symbol" }, "description": "Perp ticker (`BTC`), spot token (`HYPE`) or raw index (`@107`)" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "description": "`1m` | `5m` | `15m` | `30m` | `1h` | `4h` | `1d`, or `Nt` for N-trade bars. Default `1h`", "default": "1h", "title": "Interval" }, "description": "`1m` | `5m` | `15m` | `30m` | `1h` | `4h` | `1d`, or `Nt` for N-trade bars. Default `1h`" }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "description": "`perp` | `spot`. Default `perp`", "default": "perp", "title": "Market" }, "description": "`perp` | `spot`. Default `perp`" }, { "name": "dex", "in": "query", "required": false, "schema": { "type": "string", "description": "HL core or a HIP-3 perp DEX, e.g. `XYZ`. Default `HL`. Builder DEXs are added over time, so do not hard-code a list", "default": "HL", "title": "Dex" }, "description": "HL core or a HIP-3 perp DEX, e.g. `XYZ`. Default `HL`. Builder DEXs are added over time, so do not hard-code a list" }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC or epoch ms, inclusive", "title": "Start" }, "description": "ISO-8601 UTC or epoch ms, inclusive" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC or epoch ms, exclusive", "title": "End" }, "description": "ISO-8601 UTC or epoch ms, exclusive" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 500, clamped to 5000", "default": 500, "title": "Limit" }, "description": "Default 500, clamped to 5000" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/ohlcv/latest": { "get": { "tags": [ "hyperliquid" ], "summary": "Ohlcv Latest", "description": "The newest 1-minute candle of every symbol that traded in the last hour, in one request.", "operationId": "ohlcv_latest_v1_hyperliquid_ohlcv_latest_get", "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "description": "`perp` | `spot`. Default `perp`", "default": "perp", "title": "Market" }, "description": "`perp` | `spot`. Default `perp`" }, { "name": "dex", "in": "query", "required": false, "schema": { "type": "string", "description": "HL core or a HIP-3 perp DEX, e.g. `XYZ`. Omit for every DEX; each row names its own", "default": "", "title": "Dex" }, "description": "HL core or a HIP-3 perp DEX, e.g. `XYZ`. Omit for every DEX; each row names its own" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "description": "Only `1m`, the default. Any other value is a `400`", "default": "1m", "title": "Interval" }, "description": "Only `1m`, the default. Any other value is a `400`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/symbols/hourly": { "get": { "tags": [ "hyperliquid" ], "summary": "Assets Hourly", "description": "Hourly close + open interest + funding rate + premium, many assets at once.\n\nRows are arrays in ``columns`` order, not objects — a 120-day 10-asset\nwindow is 28,800 of them.", "operationId": "assets_hourly_v1_hyperliquid_symbols_hourly_get", "parameters": [ { "name": "symbols", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated perp tickers, e.g. `BTC,ETH,SOL`. Max 64", "title": "Symbols" }, "description": "Comma-separated perp tickers, e.g. `BTC,ETH,SOL`. Max 64" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Window length back from `end`. Default 120, range 1–400", "default": 120, "title": "Days" }, "description": "Window length back from `end`. Default 120, range 1–400" }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC or epoch s/ms, inclusive. **Overrides `days`**", "title": "Start" }, "description": "ISO-8601 UTC or epoch s/ms, inclusive. **Overrides `days`**" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC or epoch s/ms, exclusive. Defaults to now", "title": "End" }, "description": "ISO-8601 UTC or epoch s/ms, exclusive. Defaults to now" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/ohlcv/export": { "get": { "tags": [ "hyperliquid" ], "summary": "Ohlcv Export", "description": "Stream a window as NDJSON. Billed 2 credits up front, because the response\nis a stream and its row count is unknown when the usage is recorded.", "operationId": "ohlcv_export_v1_hyperliquid_ohlcv_export_get", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv)", "default": "", "title": "Symbol" }, "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv)" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv). Default `1h`", "default": "1h", "title": "Interval" }, "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv). Default `1h`" }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv). Default `perp`", "default": "perp", "title": "Market" }, "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv). Default `perp`" }, { "name": "dex", "in": "query", "required": false, "schema": { "type": "string", "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv). Default `HL`", "default": "HL", "title": "Dex" }, "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv). Default `HL`" }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv)", "title": "Start" }, "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv)" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv)", "title": "End" }, "description": "As on [`/ohlcv`](https://vike.io/docs/data/endpoints/hyperliquid/ohlcv)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Defaults to the maximum, 5000", "default": 5000, "title": "Limit" }, "description": "Defaults to the maximum, 5000" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hyperliquid/archive/datasets": { "get": { "tags": [ "hyperliquid" ], "summary": "Archive file index", "description": "Index of the Hyperliquid Parquet file archive: which UTC days exist and what is in each file.\n\nOne Parquet file per UTC day for `fills` (every fill) and `positions` (every 5-minute snapshot of\nevery open position), from 2026-05-01. `dates` is newest first, each\n`{\"date\": \"YYYY-MM-DD\", \"streams\": {\"fills\": {\"rows\", \"bytes\"}, \"positions\": {\"rows\", \"bytes\",\n\"snapshots\"}}}`; `snapshots` is how many distinct 5-minute snapshots that day holds. `schema` lists\nevery column of both datasets with its type and meaning. A day appears once it is complete\n(yesterday's files are published in the early UTC morning).\n\n`latest.positions` is ONE file with the current open positions of every asset, replaced every\n5 minutes (`snapshot_ts`, `generated_at`, `rows`, `bytes`, `assets`, `note`).\n\nNo daily or `latest` file has a direct URL and the folder cannot be listed: `url_endpoint`\n(`/v1/hyperliquid/archive/url`) answers with a 7-day link for exactly one file. The one exception is the\nfree samples: `samples_base` is their public folder, and its files (`manifest.json` names them) are read with a\nplain `GET` or `HEAD` and no API key.", "operationId": "archive_datasets_v1_hyperliquid_archive_datasets_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/hyperliquid/archive/url": { "get": { "tags": [ "hyperliquid" ], "summary": "Download link for one archive file", "description": "A download link to ONE archive file, valid 7 days.\n\n`{\"url\", \"expires_at\", \"expires_in\", \"dataset\", \"date\", \"bytes\", \"rows\"}`. The `url` is a presigned\nCloudflare R2 link (host `.r2.cloudflarestorage.com`): it needs no API key (the link is the\ncredential), names exactly this file, and works for `expires_in` seconds (604800, 7 days) for any number\nof requests, so a reader that fetches byte ranges over HTTP (DuckDB, pyarrow) can use it directly. Once it\nexpires, R2 answers `403`: ask again. The call costs one credit and one request of the hourly budget like\nany route; the download itself spends none, and there is no download quota.", "operationId": "archive_url_v1_hyperliquid_archive_url_get", "parameters": [ { "name": "dataset", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. `fills` or `positions`. Anything else returns `400` naming both.", "default": "", "title": "Dataset" }, "description": "`fills` or `positions`. Anything else returns `400` naming both." }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. `YYYY-MM-DD` of a published UTC day, or `latest` (`positions` only: the file of the current open positions, replaced every 5 minutes). A day that is not published returns `400` naming the range that is.", "default": "", "title": "Date" }, "description": "`YYYY-MM-DD` of a published UTC day, or `latest` (`positions` only: the file of the current open positions, replaced every 5 minutes). A day that is not published returns `400` naming the range that is." }, { "name": "redirect", "in": "query", "required": false, "schema": { "type": "string", "description": "`1` or `true` answers `302` with the link in `Location`; the JSON body is still sent, so a client that does not follow redirects keeps the answer.", "default": "", "title": "Redirect" }, "description": "`1` or `true` answers `302` with the link in `Location`; the JSON body is still sent, so a client that does not follow redirects keeps the answer." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/cohorts": { "get": { "tags": [ "hl-cohorts" ], "summary": "List Cohorts", "description": "The canonical cohort ladders — label sets only, in axis order.\n\n``{\"size\": [...12], \"pnl\": [...12, \"unknown\"], \"pnl_abs\": [...8, \"unknown\"],\n\"tier\": [...10]}`` — the same sets the axes group by and the cohort filters\nvalidate against, so this endpoint cannot disagree with either: a label is\nserved by its axis if and only if it is in this response, and\n``?cohort=`` accepts exactly these strings (or their\n/segments slugs). ``unknown`` rides the two PnL sets because it is a real,\nqueryable bucket there (``pnl``: wallets under 10 closed trades;\n``pnl_abs``: wallets with no realized record at all), not a rung of the\nladder. ``tier`` is the per-position ladder that ``/segments`` publishes\nas ``trade_size``.\n\n``/segments`` remains the detailed catalogue (bounds, slugs, ranks,\n``groupable``); this is the flat taxonomy for a client that just needs the\nexact spellings.", "operationId": "list_cohorts_v1_hl_cohorts_cohorts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/hl-cohorts/segments": { "get": { "tags": [ "hl-cohorts" ], "summary": "List Segments", "description": "The cohort catalogue: every bucket on every axis, with its boundaries.\n\nSelf-describing on purpose. A client that hard-codes bucket names learned\nfrom an absolute-$ ladder elsewhere will mis-map ours, which is a percentile\nladder over realized PnL; this endpoint is how it finds that out.\n\nEach row carries ``groupable``: true for the three per-wallet ladders, false\nfor ``trade_size``, which is a per-position property and is not accepted as\n``?axis=`` by /heatmap or /segments/{cohort}/summary. Filter on it rather\nthan assuming every published axis is a valid grouping key.", "operationId": "list_segments_v1_hl_cohorts_segments_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/hl-cohorts/segments/{cohort}/summary": { "get": { "tags": [ "hl-cohorts" ], "summary": "Segment Summary", "description": "Aggregate positioning for one cohort at the latest snapshot.\n\n``perp_bias`` = (long - short) / equity and ``equity_exposure`` = (long + short) / equity,\nnative perp account only: positions on the main dex over the native perp account value of the\nwallets holding them, each wallet counted once; builder-DEX positions are not included, and\nwallets without a known positive native equity are left out of perp_bias, equity_exposure and\nthe numerator of ``equity_covered_share`` (main-dex notional of the counted wallets / main-dex\nnotional of the whole cohort). Unbounded ratios (above 1 = more than 1x of equity), null when\nthat equity <= 0. That equity is not ``total_equity``, so ``perp_bias`` x ``total_equity`` is\nnot ``total_long_usd - total_short_usd``. Under ``openedWithin`` long/short are the qualifying\npositions and the equity the whole native account of every wallet holding one.\n``exposure_ratio`` stays notional / margin used.", "operationId": "segment_summary_v1_hl_cohorts_segments__cohort__summary_get", "parameters": [ { "name": "cohort", "in": "path", "required": true, "schema": { "type": "string", "description": "A label or slug from [`/cohorts`](https://vike.io/docs/data/endpoints/hl-cohorts/cohorts) / [`/segments`](https://vike.io/docs/data/endpoints/hl-cohorts/segments)", "title": "Cohort" }, "description": "A label or slug from [`/cohorts`](https://vike.io/docs/data/endpoints/hl-cohorts/cohorts) / [`/segments`](https://vike.io/docs/data/endpoints/hl-cohorts/segments)" }, { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. Default `size`. Per-wallet ladders only — `trade_size` is per-position and is rejected here; see the `groupable` field on `/segments`.", "default": "size", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs`. Default `size`. Per-wallet ladders only — `trade_size` is per-position and is rejected here; see the `groupable` field on `/segments`." }, { "name": "openedWithin", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `all`. Default `all`", "default": "all", "title": "Openedwithin" }, "description": "`24h` | `7d` | `30d` | `all`. Default `all`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/segments/{cohort}/history": { "get": { "tags": [ "hl-cohorts" ], "summary": "Segment History", "description": "One cohort's long / short / bias per hour, summed over every symbol. Ratios in [-1, +1]. A 404 names the\naxis only. `axis=size` groups positions by the size cohort stored on each position; `axis=pnl` by the\nrealized-PnL cohort frozen at that hour (hourly from 2026-08-06, daily before it; see `label_computed`).\nPer hour: `long_usd` and `short_usd` in USD, `bias` = (long - short) / (long + short), null when both are 0,\nand `position_count`, which counts open positions ((wallet, symbol) pairs), not wallets. Newest first, settled\nhours only. `include=leverage` adds the three equity ratios described on that parameter.", "operationId": "segment_history_v1_hl_cohorts_segments__cohort__history_get", "parameters": [ { "name": "cohort", "in": "path", "required": true, "schema": { "type": "string", "description": "A label or slug of `axis`, from `/cohorts` / `/segments`", "title": "Cohort" }, "description": "A label or slug of `axis`, from `/cohorts` / `/segments`" }, { "name": "axis", "in": "query", "required": true, "schema": { "type": "string", "description": "`size` | `pnl`: this endpoint serves history for these two only. Required.", "title": "Axis" }, "description": "`size` | `pnl`: this endpoint serves history for these two only. Required." }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Oldest edge. Omit it for the `hours` newest hours.", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Oldest edge. Omit it for the `hours` newest hours." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Newest edge; with no `start`, the window is the `hours` newest hours at or before it.", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Newest edge; with no `start`, the window is the `hours` newest hours at or before it." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 8760, "description": "Window length in hours when `start` is omitted. Default 168, max 8760.", "default": 168, "title": "Hours" }, "description": "Window length in hours when `start` is omitted. Default 168, max 8760." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Max rows, newest first, default and max 5000; `has_more` says there are older ones (page back with `end` = the oldest `ts` minus 1 second; `end` is inclusive).", "default": 5000, "title": "Limit" }, "description": "Max rows, newest first, default and max 5000; `has_more` says there are older ones (page back with `end` = the oldest `ts` minus 1 second; `end` is inclusive)." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma list; only `leverage`, default none (nothing extra is read). Adds to every row `perp_bias` = (long - short) / equity, `equity_exposure` = (long + short) / equity and `equity_covered_share` = main-dex notional of the counted wallets / main-dex notional of the whole cohort: unbounded ratios (above 1 = more than 1x of equity), native perp account only (main-dex positions of wallets with a known positive native equity, each wallet once; builder-DEX positions are not included). An hour with no stored row, and any hour before `leverage.data_from` (2026-08-11), is null on all three (never 0). `perp_bias` and `equity_exposure` are also null when no counted wallet has a positive equity; `equity_covered_share` is null when the cohort holds no main-dex notional and a real 0 when it holds some but no wallet is counted. Hours rebuilt from fills rather than read from snapshots are null. An unknown token is a 400.", "default": "", "title": "Include" }, "description": "Comma list; only `leverage`, default none (nothing extra is read). Adds to every row `perp_bias` = (long - short) / equity, `equity_exposure` = (long + short) / equity and `equity_covered_share` = main-dex notional of the counted wallets / main-dex notional of the whole cohort: unbounded ratios (above 1 = more than 1x of equity), native perp account only (main-dex positions of wallets with a known positive native equity, each wallet once; builder-DEX positions are not included). An hour with no stored row, and any hour before `leverage.data_from` (2026-08-11), is null on all three (never 0). `perp_bias` and `equity_exposure` are also null when no counted wallet has a positive equity; `equity_covered_share` is null when the cohort holds no main-dex notional and a real 0 when it holds some but no wallet is counted. Hours rebuilt from fills rather than read from snapshots are null. An unknown token is a 400." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/heatmap": { "get": { "tags": [ "hl-cohorts" ], "summary": "Heatmap", "description": "Coin x cohort positioning matrix — the whole board in one call.", "operationId": "heatmap_v1_hl_cohorts_heatmap_get", "parameters": [ { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. Default `size`. Per-wallet ladders only — `trade_size` is per-position and is rejected here; see the `groupable` field on `/segments`.", "default": "size", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs`. Default `size`. Per-wallet ladders only — `trade_size` is per-position and is rejected here; see the `groupable` field on `/segments`." }, { "name": "openedWithin", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `all`. Default `all`", "default": "all", "title": "Openedwithin" }, "description": "`24h` | `7d` | `30d` | `all`. Default `all`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/symbols/{symbol}/metrics": { "get": { "tags": [ "hl-cohorts" ], "summary": "Coin Metrics", "description": "Hourly open-interest / position-count / bias series for one coin,\noptionally sliced to a single cohort.\n\nHourly by construction: the 5-minute snapshot table summed into hour buckets\nover-counts open interest ~12x, which is what forced the previous cohort\naggregate to be rebuilt.\n\nEvery row carries ``provisional``. It is True on at most one row — the\nnewest, covering the hour still in progress — because the hourly rollup\nlands 60-120 minutes late and a \"current positioning\" read would otherwise\nbe silently that stale. Its ``ts`` is a snapshot instant rather than an hour\nboundary and it changes on every poll; drop it when persisting a series.\nPresent only on the first page of a window reaching the present.", "operationId": "coin_metrics_v1_hl_cohorts_symbols__symbol__metrics_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL ticker", "title": "Symbol" }, "description": "HL ticker" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Oldest edge of the window. Omit it and the window is the `limit` newest hourly rows at or before `end`.", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Oldest edge of the window. Omit it and the window is the `limit` newest hourly rows at or before `end`." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Newest edge. With no `start`: the `limit` newest hourly rows at or before `end`, the same rows as `start = end - limit hours`. A row counts when its hour starts at or before `end`, so an `end` exactly on the hour includes that hour. An `end` at or after the newest data (a future one included) is the same as no `end`; one older than all data returns no rows.", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Newest edge. With no `start`: the `limit` newest hourly rows at or before `end`, the same rows as `start = end - limit hours`. A row counts when its hour starts at or before `end`, so an `end` exactly on the hour includes that hour. An `end` at or after the newest data (a future one included) is the same as no `end`; one older than all data returns no rows." }, { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs`. **Omit for all cohorts combined**", "default": "", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs`. **Omit for all cohorts combined**" }, { "name": "cohort", "in": "query", "required": false, "schema": { "type": "string", "description": "One label on that axis", "default": "", "title": "Cohort" }, "description": "One label on that axis" }, { "name": "openedWithin", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `all`. Default `all`. Rolling per bucket, not relative to now — each hour counts positions opened in the window before THAT hour.", "default": "all", "title": "Openedwithin" }, "description": "`24h` | `7d` | `30d` | `all`. Default `all`. Rolling per bucket, not relative to now — each hour counts positions opened in the window before THAT hour." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Default 500, max 5000. One row per hour, so also the window length in hours when `start` is omitted", "default": 500, "title": "Limit" }, "description": "Default 500, max 5000. One row per hour, so also the window length in hours when `start` is omitted" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Keyset cursor", "default": "", "title": "Cursor" }, "description": "Keyset cursor" }, { "name": "labelBasis", "in": "query", "required": false, "schema": { "type": "string", "description": "`current` only. This endpoint resolves the cohort label from the wallet dictionary at QUERY time, so on the pnl ladders it can only serve `current`, and it REFUSES `point_in_time` by name instead of ignoring it. Every response declares `label_basis` and, for a pnl axis, `label_computed.lookahead`.", "default": "", "title": "Labelbasis" }, "description": "`current` only. This endpoint resolves the cohort label from the wallet dictionary at QUERY time, so on the pnl ladders it can only serve `current`, and it REFUSES `point_in_time` by name instead of ignoring it. Every response declares `label_basis` and, for a pnl axis, `label_computed.lookahead`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/symbols/{symbol}/indices": { "get": { "tags": [ "hl-cohorts" ], "summary": "Symbol Indices", "description": "Smart Money Index, Whale-vs-Shrimp Index, whale / smart bias: the website's numbers as RATIOS\nin [-1, +1] (the site multiplies by 100). `latest` is the newest 5-minute snapshot (its pnl rungs graded\nby today's PnL grading, `latest.label_basis: current`), `series` the settled hourly rows, newest first.\n`smi` = long share of the 3x smart / 2x smart / smart wallets minus long share of the rekt / 2x rekt / 3x rekt\nwallets; `wsi` = long share of the 4x whale .. whale wallets minus long share of the 2x shrimp / shrimp\nwallets; `whale_bias` and `smart_bias` (`latest` only) = (long - short) / (long + short) over those whale /\nsmart wallets. A value is null, never 0, when a cohort holds no positions.", "operationId": "symbol_indices_v1_hl_cohorts_symbols__symbol__indices_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL ticker", "title": "Symbol" }, "description": "HL ticker" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Oldest edge. Omit it for the `hours` newest hours.", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Oldest edge. Omit it for the `hours` newest hours." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Newest edge; with no `start`, the window is the `hours` newest hours at or before it.", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Newest edge; with no `start`, the window is the `hours` newest hours at or before it." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 8760, "description": "Window length in hours when `start` is omitted. Default 168, max 8760.", "default": 168, "title": "Hours" }, "description": "Window length in hours when `start` is omitted. Default 168, max 8760." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "description": "Max series rows, newest first, default and max 5000; `has_more` says there are older ones (page back with `end` = the oldest `ts` minus 1 second; `end` is inclusive).", "default": 5000, "title": "Limit" }, "description": "Max series rows, newest first, default and max 5000; `has_more` says there are older ones (page back with `end` = the oldest `ts` minus 1 second; `end` is inclusive)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/symbols/{symbol}/large-fills": { "get": { "tags": [ "hl-cohorts" ], "summary": "Symbol Large Fills", "description": "The asset page's Whale Activity feed: a symbol's large fills, newest first. The feed keeps only the\nnewest 200 fills over $50k per symbol of the last 24 hours, so on a busy symbol that is minutes, not a day:\n`covered_from` is how far back the answer reaches, `truncated` says that cap may have cut older fills inside\nthe window, `has_more` that `limit` cut rows. Each row has `ts`, `wallet`, `direction` (`buy` | `sell`),\n`size_token`, `size_usd`, `price`, `order_type` (`market` = crossed the book, `limit` = rested), `size_cohort`\n(the wallet's size rung on its latest snapshot) and `pnl_cohort` (graded at the fill's own hour where that hour\nis labelled, else today; `pnl_cohort_basis` says which). Liquidations are not flagged.", "operationId": "symbol_large_fills_v1_hl_cohorts_symbols__symbol__large_fills_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL ticker", "title": "Symbol" }, "description": "HL ticker" }, { "name": "min_usd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 50000, "description": "Smallest fill in USD. Default and MINIMUM 50000: the feed behind this route holds nothing smaller.", "default": 50000, "title": "Min Usd" }, "description": "Smallest fill in USD. Default and MINIMUM 50000: the feed behind this route holds nothing smaller." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 24, "minimum": 1, "description": "How far back, in hours. Default and max 24: the feed holds a day.", "default": 24, "title": "Hours" }, "description": "How far back, in hours. Default and max 24: the feed holds a day." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Max rows, newest first. Default 200 (all the feed holds per symbol), max 1000; `has_more` says a lower `limit` cut rows.", "default": 200, "title": "Limit" }, "description": "Max rows, newest first. Default 200 (all the feed holds per symbol), max 1000; `has_more` says a lower `limit` cut rows." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/symbols/{symbol}/cohort-metrics": { "get": { "tags": [ "hl-cohorts" ], "summary": "Coin Cohort Metrics", "description": "The full cohort matrix for one coin — every bucket on an axis, hourly.\n\n`/symbols/{symbol}/metrics` returns one row per hour, either all cohorts summed\nor a single cohort. Rebuilding the matrix from it costs one request per\ncohort (12 for `size`, 13 for `pnl`); this returns all of them in one.\n\n`axis=tier` is the PER-POSITION ladder — each position row's own notional\nbucket, DERIVED from the row's `size_usd`: the canonical ten dollar-range\nbuckets, largest first, the website's spellings verbatim (`>$2.5m`,\n`$1m-$2.5m`, `$500k-$1m`, `$250k-$500k`, `$100k-$250k`, `$50k-$100k`,\n`$25k-$50k`, `$10k-$25k`, `$1k-$10k`, `<$1k` — /cohorts and /segments\npublish the ladder with bounds). Rows have the same shape as `axis=size`,\nthe bucket in the `cohort` field. It is a grouping only here: this\nendpoint aggregates position rows, so each row sits in exactly one bucket,\nwhile the per-wallet endpoints (/heatmap, /segments/{cohort}/summary) keep\nrejecting it — a wallet straddles buckets. (The retired\nmicro/small/medium/large/mega vocabulary is gone; sending one of those as\na cohort filter anywhere returns a 400 naming this ladder.)\n\nPaginated by HOUR, not by row — a row limit would cut a bucket in half and\nreturn an hour whose cohorts do not sum to its total. `hours` bounds the\nbuckets; every cohort in a returned bucket comes with it.\n\nNo provisional row: this is bulk history, and a partial hour inside a matrix\nthat will be differenced or z-scored produces a fake move at the right edge.\nUse `/symbols/{symbol}/metrics` for the current value.\n\n`include=volume,median_pnl` adds two per-cohort columns to the rows of the newest\nbucket, `volume_24h_usd` and `median_realized_pnl_usd` (`size` and `pnl` only; see the\nparameter). They are computed at request time, so they describe the book now, not\nthe bucket's hour.\n\n⚠️ **`labelBasis` matters for research.** By default the `pnl` cohort is\nresolved from the dictionary AT QUERY TIME, so a historical row carries\nTODAY's grading — correct for \"who is smart right now\", **lookahead for a\nbacktest**, because a wallet under the 10-closed-trade floor back then may\nbe graded now. Pass `labelBasis=point_in_time` to get each row's label as it\nwas that hour. Hours from 2026-08-07 on carry every field\n(`unavailable_fields` is empty). A window that reaches an earlier hour is\nserved as one aggregate for all of its hours, and its `position_count`,\n`position_count_long`, `total_unrealized_pnl`, `total_position_size` and\n`total_position_size_long` are null (listed in `unavailable_fields`); so are\nthose five fields under `grading=unrealized` and `grading=realized-pit`.\nPoint-in-time matrices are stored aggregates and refuse `openedWithin` (400).\n\n`axis=size` is always point-in-time (a stored column), `axis=tier` is\nalways point-in-time (a pure function of the stored `size_usd`),\n`axis=pnl_unrealized` is always point-in-time (the HOURLY rollup stores it,\nsee below) and `axis=pnl_abs` is always current (no frozen source exists);\nall four reject a conflicting `labelBasis` rather than silently ignoring\nit. Every row and the envelope carry `label_basis` so the answer is\nself-describing.\n\n⚠️ **`grading` selects WHICH PnL grading; `label_computed` says WHEN it\nwas computed.** The two are independent and the response carries both, on\nthe envelope and on every row. A grading name is neutral by design —\n`realized` does not say whether the label is today's or the hour's — so\nthe endpoint refuses to let the name travel alone.\n\n* `grading=realized` (default on `axis=pnl`) — the percentile ladder over\n cumulative realized PnL. With the default `labelBasis` this is resolved\n at QUERY time, so every historical hour carries TODAY's grading:\n `label_computed.lookahead` is **true** and says so. With\n `labelBasis=point_in_time` it is the frozen ladder, and `label_computed`\n names the 2026-08-06 seam — before it the labels come from the\n 2026-08-17 point-in-time rebuild (daily resolution), from it they come\n from the row's own `pnl_cohort_realized` (hourly). Both halves are honest;\n a series crossing the seam changes label RESOLUTION, which a turnover\n count will read as a regime change that is an artefact.\n* `grading=realized-pit` — the same ladder graded point-in-time across the\n WHOLE window (day D on the cumulative as of the end of D-1), which is\n what makes it the control for a study crossing that seam. A frozen\n research artefact: nothing has written to it since 2026-08-16 19:00 UTC,\n so a window reaching the present comes back short rather than wrong.\n* `grading=unrealized` — \"currently onside\": hour H's rank over the\n wallet's last snapshot strictly before H. `axis=pnl_unrealized` is the\n legacy spelling of exactly this and keeps working; both reach one branch.\n\n`grading` is refused on `size`, `tier` and `pnl_abs`, which rank no PnL,\nand `realized-pit`/`unrealized` refuse `labelBasis=current` rather than\nsilently overriding it.\n\n⚠️ **`freshness` is how a REALTIME caller checks it is not trading a stale\nbook.** On any window that reaches the present the envelope carries\n`{newest_ts, behind_hours, settled_lag_ceiling_hours, stale}`. `stale` is\nthe pre-computed verdict, so a consumer does not have to re-derive the\nrollup's cadence — the rollup writes hour H at H+1:00–H+1:30, so a bucket\nup to two hours old is healthy and the ceiling sits an hour above that.\n\nIt exists because prose was not enough. `grading=realized-pit` reads a\nFROZEN research artefact; ask it for an explicit recent window and it\nanswers honestly with zero rows, but ask it the way a poller does\n(`?grading=realized-pit&hours=1`, no `start`) and it returns its own newest\nbucket — **identical in shape to a current one**, and days old. That gap\nis not a constant: the table's last write is 2026-08-16 19:00 UTC and\nnothing has written since, so it GROWS by 24 hours a day. Read the age off\n`freshness.behind_hours` rather than from any number written in prose.\n\nFor live trading use `grading=realized` with `labelBasis=point_in_time`:\nhonest labels, and one hour behind the clock rather than days.\n\nA window that ends in the PAST gets no `freshness` — \"the newest bar is\nfour months old\" answers a question a historical query did not ask, and\nwould make every backtest fetch look broken.\n\n**`axis=pnl_unrealized` grades positioning, not skill.** Each wallet is\nranked by the unrealized PnL of its open positions as a share of account\nvalue — \"currently onside\" — over its last snapshot STRICTLY BEFORE hour\nH, and that rank labels hour H. The grading turns over ~44% of wallets per\nday (the realized ladder: ~2.4%), which is the point: it is a different\naxis, not a re-spelling. Twelve rungs, no `unknown` (eligibility is a\npositive-equity snapshot, not a trade count), the same five null fields as\na point-in-time pnl window that reaches before 2026-08-07, coverage from 2026-04-04 with a known three-day hole\n(2026-06-28..30, graded off days whose equity feed was down).", "operationId": "coin_cohort_metrics_v1_hl_cohorts_symbols__symbol__cohort_metrics_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL ticker", "title": "Symbol" }, "description": "HL ticker" }, { "name": "axis", "in": "query", "required": false, "schema": { "type": "string", "description": "`size` | `pnl` | `pnl_abs` | `tier` | `pnl_unrealized`. Default `size`. `trade_size` (the name `/segments` gives the ladder) is accepted as an alias of `tier`; the response still says `axis: tier`", "default": "size", "title": "Axis" }, "description": "`size` | `pnl` | `pnl_abs` | `tier` | `pnl_unrealized`. Default `size`. `trade_size` (the name `/segments` gives the ladder) is accepted as an alias of `tier`; the response still says `axis: tier`" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Oldest edge of the window. Omit it and the window is the `hours` newest hourly buckets at or before `end`.", "default": "", "title": "Start" }, "description": "ISO-8601 UTC. Oldest edge of the window. Omit it and the window is the `hours` newest hourly buckets at or before `end`." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO-8601 UTC. Newest edge. With no `start`: the `hours` newest hourly buckets at or before `end`, the same buckets as `start = end - hours`. A bucket counts when its hour starts at or before `end`, so an `end` exactly on the hour includes that hour's bucket. An `end` at or after the newest data (a future one included) is the same as no `end`; one older than all data returns an empty series.", "default": "", "title": "End" }, "description": "ISO-8601 UTC. Newest edge. With no `start`: the `hours` newest hourly buckets at or before `end`, the same buckets as `start = end - hours`. A bucket counts when its hour starts at or before `end`, so an `end` exactly on the hour includes that hour's bucket. An `end` at or after the newest data (a future one included) is the same as no `end`; one older than all data returns an empty series." }, { "name": "openedWithin", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h` | `7d` | `30d` | `all`. Default `all`. Refused (400) with `axis=pnl` and `labelBasis=point_in_time`, with `grading=unrealized` or `realized-pit` and with `axis=pnl_unrealized`: those matrices are stored aggregates with position age summed away. Use `axis=size`, `tier`, `pnl_abs` or `pnl` with the default basis.", "default": "all", "title": "Openedwithin" }, "description": "`24h` | `7d` | `30d` | `all`. Default `all`. Refused (400) with `axis=pnl` and `labelBasis=point_in_time`, with `grading=unrealized` or `realized-pit` and with `axis=pnl_unrealized`: those matrices are stored aggregates with position age summed away. Use `axis=size`, `tier`, `pnl_abs` or `pnl` with the default basis." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 8760, "description": "Number of hourly buckets. Default 168, max 8760. Sizes the window when `start` is omitted; with `start`, it caps how many buckets come back (newest first).", "default": 168, "title": "Hours" }, "description": "Number of hourly buckets. Default 168, max 8760. Sizes the window when `start` is omitted; with `start`, it caps how many buckets come back (newest first)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor over **hours**", "default": "", "title": "Cursor" }, "description": "Cursor over **hours**" }, { "name": "grading", "in": "query", "required": false, "schema": { "type": "string", "description": "`realized` | `realized-pit` | `unrealized`. Which PnL grading labels each wallet, for the axes that carry one (`axis=pnl`, `axis=pnl_unrealized`). Default `realized` on `axis=pnl`; refused on `size`, `tier`, `pnl_abs`. Every response declares in `label_computed` WHEN the label was computed — the grading name alone cannot say it.", "default": "", "title": "Grading" }, "description": "`realized` | `realized-pit` | `unrealized`. Which PnL grading labels each wallet, for the axes that carry one (`axis=pnl`, `axis=pnl_unrealized`). Default `realized` on `axis=pnl`; refused on `size`, `tier`, `pnl_abs`. Every response declares in `label_computed` WHEN the label was computed — the grading name alone cannot say it." }, { "name": "labelBasis", "in": "query", "required": false, "schema": { "type": "string", "description": "`current` | `point_in_time`. Default depends on the axis: `size`, `tier` and `pnl_unrealized` are always `point_in_time`, `pnl_abs` always `current`. `point_in_time` (`axis=pnl`) returns each row's cohort label AS IT WAS that hour. Hours from 2026-08-07 carry every field; a window with an earlier hour is served as one aggregate whose five position fields are null (listed in `unavailable_fields`). Use it for backtests. Refused (400) with `openedWithin`.", "default": "", "title": "Labelbasis" }, "description": "`current` | `point_in_time`. Default depends on the axis: `size`, `tier` and `pnl_unrealized` are always `point_in_time`, `pnl_abs` always `current`. `point_in_time` (`axis=pnl`) returns each row's cohort label AS IT WAS that hour. Hours from 2026-08-07 carry every field; a window with an earlier hour is served as one aggregate whose five position fields are null (listed in `unavailable_fields`). Use it for backtests. Refused (400) with `openedWithin`." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma list of `volume` and `median_pnl`; default none (nothing extra is read). Adds to every row of the NEWEST bucket `volume_24h_usd` (USD the cohort's wallets filled in this symbol over the last 24 hours; on `axis=size` only wallets holding the symbol now count; null when they filled nothing or the cohort is empty) and/or `median_realized_pnl_usd` (median cumulative realized PnL, USD, over the DISTINCT wallets holding the symbol now; null when none does). The median is a sampled quantile: exact up to 8,192 wallets in a cohort, an estimate above it. The asset page's pnl-axis \"Med Lifetime\" counts positions rather than wallets, so it can differ slightly. Both are CURRENT figures (request time, newest 5-minute snapshot), not the bucket hour's, and null on `unknown`. `axis=size` and `axis=pnl` with `grading=realized` only; refused (400) on any other axis or grading, with `openedWithin`, with `cursor` and with an `end` in the past.", "default": "", "title": "Include" }, "description": "Comma list of `volume` and `median_pnl`; default none (nothing extra is read). Adds to every row of the NEWEST bucket `volume_24h_usd` (USD the cohort's wallets filled in this symbol over the last 24 hours; on `axis=size` only wallets holding the symbol now count; null when they filled nothing or the cohort is empty) and/or `median_realized_pnl_usd` (median cumulative realized PnL, USD, over the DISTINCT wallets holding the symbol now; null when none does). The median is a sampled quantile: exact up to 8,192 wallets in a cohort, an estimate above it. The asset page's pnl-axis \"Med Lifetime\" counts positions rather than wallets, so it can differ slightly. Both are CURRENT figures (request time, newest 5-minute snapshot), not the bucket hour's, and null on `unknown`. `axis=size` and `axis=pnl` with `grading=realized` only; refused (400) on any other axis or grading, with `openedWithin`, with `cursor` and with an `end` in the past." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hl-cohorts/symbols/{symbol}/size-breakdown": { "get": { "tags": [ "hl-cohorts" ], "summary": "Coin Size Breakdown", "description": "Positioning split by canonical position-size bucket for one coin.\n\nTen dollar-range buckets (largest first), derived from each row's\n`size_usd` — the same ladder, spellings and bounds as `axis=tier` on\n/symbols/{symbol}/cohort-metrics and the /cohorts catalogue. Empty buckets\ncome back zero-filled so the table shape is stable.", "operationId": "coin_size_breakdown_v1_hl_cohorts_symbols__symbol__size_breakdown_get", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "description": "HL ticker", "title": "Symbol" }, "description": "HL ticker" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/markets": { "get": { "tags": [ "polymarket" ], "summary": "List Polymarket markets", "description": "Search/filter recorded markets. Returns a BARE ARRAY, newest ``end_date``\nfirst; page with ``limit`` and ``offset``.\n\n``active`` and ``closed`` are derived rather than stored: a market is closed\nwhen its on-chain resolution exists or Polymarket's own ``closed`` flag says\nso. ``?active=false`` therefore returns the closed markets, and a settled\n5-minute market reports itself settled.\n\n⚠ ``?active=`` is also the SLOW path — ~1.00 s against ~46 ms for an\nunfiltered page, because a filter on a derived flag has to derive it for\nevery market before it can limit.", "operationId": "markets_v1_polymarket_markets_get", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring match on the market slug.", "default": "", "title": "Query" }, "description": "Case-insensitive substring match on the market slug." }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "`true` = only active, `false` = only inactive, omit = all.", "default": "", "title": "Active" }, "description": "`true` = only active, `false` = only inactive, omit = all." }, { "name": "closed", "in": "query", "required": false, "schema": { "type": "string", "description": "The complement of `active`: `true` (or `1`) = only closed.", "default": "", "title": "Closed" }, "description": "The complement of `active`: `true` (or `1`) = only closed." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Max rows. Default `50`, **hard cap 100** — a larger value is silently clamped, not rejected.", "default": "", "title": "Limit" }, "description": "Max rows. Default `50`, **hard cap 100** — a larger value is silently clamped, not rejected." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string", "description": "Rows to skip, an integer from 0 to 10000. Default 0. Page with `limit` and `offset`; with an offset, rows with the same `end_date` order by `condition_id`, so pages do not repeat or skip a market. Above 10000 is a `400`.", "default": "", "title": "Offset" }, "description": "Rows to skip, an integer from 0 to 10000. Default 0. Page with `limit` and `offset`; with an offset, rows with the same `end_date` order by `condition_id`, so pages do not repeat or skip a market. Above 10000 is a `400`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/markets/{condition_id}": { "get": { "tags": [ "polymarket" ], "summary": "One market", "description": "One market by ``condition_id``, as an ARRAY of 0 or 1 rows.\n\nA market outside the recorded universe is answered from Polymarket's full\nmarket catalog: ``source`` says which list answered (``recorded`` or\n``catalog``), and a catalog row has ``tick_size`` and ``neg_risk`` = ``null``.\n``active``/``closed`` are derived the same way for both.\n\n⚠ An unknown id is ``200 []``, never a 404. ⚠ A TOKEN id in this position\nreturns ``[]`` too: the route cannot look up by token (the MCP tool can).", "operationId": "market_detail_v1_polymarket_markets__condition_id__get", "parameters": [ { "name": "condition_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The `0x`-prefixed market condition id.", "title": "Condition Id" }, "description": "The `0x`-prefixed market condition id." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/markets/{condition_id}/trades": { "get": { "tags": [ "polymarket" ], "summary": "One market's trades, with wallets (paged)", "description": "One market's trades **newest first**, with the wallet behind each: who traded, which side, how\nmuch and at what price. History runs from 2026-01-01 to a few minutes ago.\n\nEnvelope ``{trades, has_more, next_cursor}``; ``next_cursor`` is a string only while ``has_more`` is\ntrue and ``null`` otherwise. Walk a market's whole history by following ``next_cursor``; bound it\nwith ``from_ms`` / ``to_ms``, a half-open ``[from_ms, to_ms)`` window. Rows are ordered by time and\nthen by a fixed tie-break, so a page boundary inside one block neither repeats nor skips a row.\n\nEach row: ``ts`` (epoch ms, the block's time, whole seconds), ``tx_hash``, ``log_index``,\n``block_number``, ``proxy_wallet``, ``name`` and ``pseudonym`` (Polymarket's display labels, empty\nwhen unset), ``side`` (`BUY` or `SELL`), ``role`` (`maker` or `taker`), ``outcome``,\n``outcome_index``, ``token_id``, ``size`` (shares) and ``price`` (0 to 1).\n\n⚠ ``proxy_wallet`` is the Polymarket proxy wallet that placed the order, not necessarily the\nperson's own address. ⚠ ``side`` is per token: a buy of one outcome and a sell of the other can be\nthe same bet.\n\n⚠ **One row is one ORDER's fill, not one match.** A match is several rows: the resting `maker`\norders that were hit, and one `taker` row for the aggressor, whose size is the sum of theirs. Adding\n``size * price`` over both roles counts the match twice, and the two roles price a complementary-token\nmatch differently (over 15 minutes of one market: $11,060 summed over `maker` rows, $17,066 over\n`taker` rows). Pick one role and stay with it; never add both.\n\n⚠ **A few percent of fills are not rows.** Fills one wallet made on one token inside a single\ntransaction can be merged into one row, so a count here can sit under the on-chain fill count\n(-3.2% of fills and -2.3% of USD over 58 markets checked on 2026-10-17).", "operationId": "market_trades_v1_polymarket_markets__condition_id__trades_get", "parameters": [ { "name": "condition_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The `0x`-prefixed market condition id (`0x` and 64 hex digits). An unknown or malformed id is `200` with an empty `trades`, never a `404`.", "title": "Condition Id" }, "description": "The `0x`-prefixed market condition id (`0x` and 64 hex digits). An unknown or malformed id is `200` with an empty `trades`, never a `404`." }, { "name": "from_ms", "in": "query", "required": false, "schema": { "type": "string", "description": "Trade time, epoch ms, **inclusive**. Default: from the first trade.", "default": "", "title": "From Ms" }, "description": "Trade time, epoch ms, **inclusive**. Default: from the first trade." }, { "name": "to_ms", "in": "query", "required": false, "schema": { "type": "string", "description": "Trade time, epoch ms, **exclusive**. Must be greater than `from_ms`. Default: no upper bound.", "default": "", "title": "To Ms" }, "description": "Trade time, epoch ms, **exclusive**. Must be greater than `from_ms`. Default: no upper bound." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Resume strictly after the last row of a previous page: pass its `next_cursor` back unchanged.", "default": "", "title": "Cursor" }, "description": "Resume strictly after the last row of a previous page: pass its `next_cursor` back unchanged." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Rows per page. Default `1000`, hard cap `10000`. A page of 1,000 typically takes 0.5 to 2 seconds and a full 10,000 up to about 10 seconds when the service is busy; each page counts as one request, so ask for full pages.", "default": "", "title": "Limit" }, "description": "Rows per page. Default `1000`, hard cap `10000`. A page of 1,000 typically takes 0.5 to 2 seconds and a full 10,000 up to about 10 seconds when the service is busy; each page counts as one request, so ask for full pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/market_stats": { "get": { "tags": [ "polymarket" ], "summary": "One token's tape summary", "description": "Event counts, trade volume and first/last timestamps for one token.\n\n⚠ ALWAYS exactly one row. An unknown token returns one row of ZEROS, not\n``[]``.", "operationId": "market_stats_v1_polymarket_market_stats_get", "parameters": [ { "name": "token_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. The outcome token. Omitting it returns `400 {\"error\":\"market_stats requires token_id\"}`.", "default": "", "title": "Token Id" }, "description": "The outcome token. Omitting it returns `400 {\"error\":\"market_stats requires token_id\"}`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/ohlcv": { "get": { "tags": [ "polymarket" ], "summary": "Polymarket candles", "description": "Bars at a fixed interval, OLDEST first. With `to` and no `from`, `limit` keeps the newest\nbars up to `to`; the rows still come back oldest first.\n\n⚠ ``from``/``to`` here are epoch-ms INTEGERS and ``to`` is INCLUSIVE — unlike\n``/v1/polymarket/events``, whose window is half-open, and unlike\n``/v1/polymarket/archive/datasets``, where the same two names are\n``YYYY-MM-DD`` STRINGS. A date-shaped value here does not parse as an\ninteger and is therefore IGNORED, answering the request unfiltered.\n\n⚠ The two required args are checked in order — ``token_id`` first, then\n``interval`` — so ``?interval=1h`` alone reports the missing token, not the\nother way round.", "operationId": "ohlcv_v1_polymarket_ohlcv_get", "parameters": [ { "name": "token_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. The outcome token.", "default": "", "title": "Token Id" }, "description": "The outcome token." }, { "name": "interval", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. One of `1m`, `5m`, `1h`, `1d`. Anything else returns `400` naming the four accepted values.", "default": "", "title": "Interval" }, "description": "One of `1m`, `5m`, `1h`, `1d`. Anything else returns `400` naming the four accepted values." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "Epoch MILLISECONDS, INCLUSIVE lower bound.", "default": "", "title": "From" }, "description": "Epoch MILLISECONDS, INCLUSIVE lower bound." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "Epoch MILLISECONDS, INCLUSIVE upper bound.", "default": "", "title": "To" }, "description": "Epoch MILLISECONDS, INCLUSIVE upper bound." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Max bars. Default `500`, hard cap `1000`. With `to` and no `from`, the `limit` bars nearest `to` (so `to=X&limit=1` is the last bar at or before X); otherwise the oldest bars of the window.", "default": "", "title": "Limit" }, "description": "Max bars. Default `500`, hard cap `1000`. With `to` and no `from`, the `limit` bars nearest `to` (so `to=X&limit=1` is the last bar at or before X); otherwise the oldest bars of the window." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/orderbook": { "get": { "tags": [ "polymarket" ], "summary": "Order-book snapshot", "description": "The nearest ``book`` snapshot at or before ``ts``, flattened to levels.\n\n``as_of_ts`` repeats on every row and is the snapshot ACTUALLY used, not the\n``ts`` requested. Asks precede bids (``side`` sorts alphabetically), each\nascending by level, in one array.\n\n⚠ A book can be one-sided, so ``depth=5`` returning five rows rather than\nten is correct. ⚠ And this endpoint can currently return every level\nSEVERAL TIMES.", "operationId": "orderbook_v1_polymarket_orderbook_get", "parameters": [ { "name": "token_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. The outcome token.", "default": "", "title": "Token Id" }, "description": "The outcome token." }, { "name": "ts", "in": "query", "required": false, "schema": { "type": "string", "description": "As-of epoch ms. The nearest snapshot at-or-before it is used; omit for the latest.", "default": "", "title": "Ts" }, "description": "As-of epoch ms. The nearest snapshot at-or-before it is used; omit for the latest." }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "string", "description": "Levels per side. Default `25`, hard cap `25`.", "default": "", "title": "Depth" }, "description": "Levels per side. Default `25`, hard cap `25`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/settlements/bulk": { "get": { "tags": [ "polymarket" ], "summary": "On-chain settlements (paged)", "description": "On-chain settlements, oldest resolution first, ordered ``(resolved_ts_ms, condition_id)``.\n\nEnvelope ``{settlements, has_more, next_cursor}``; ``next_cursor`` is a string only while\n``has_more`` is true and ``null`` otherwise. Each row is exactly what\n[`/settlements/{condition_id}`](https://vike.io/docs/data/endpoints/polymarket/settlements-condition-id)\nreturns for that market. Walk every settled 5-minute BTC market with\n``?slug_prefix=btc-updown-5m-&limit=5000`` and follow ``next_cursor``: 5,000 markets per request\ninstead of one.\n\nPages are rebuilt every 5 minutes: a market that has just resolved on-chain can take up to about\n5 minutes to appear here, and a row with ``market_known`` false gets its market fields at the first\nrebuild after the market is added. `/settlements/{condition_id}` is always current.", "operationId": "settlements_bulk_v1_polymarket_settlements_bulk_get", "parameters": [ { "name": "from_ms", "in": "query", "required": false, "schema": { "type": "string", "description": "Resolution time, epoch ms, **inclusive**. Default: from the first resolution.", "default": "", "title": "From Ms" }, "description": "Resolution time, epoch ms, **inclusive**. Default: from the first resolution." }, { "name": "to_ms", "in": "query", "required": false, "schema": { "type": "string", "description": "Resolution time, epoch ms, **exclusive**. Must be greater than `from_ms`. Default: no upper bound.", "default": "", "title": "To Ms" }, "description": "Resolution time, epoch ms, **exclusive**. Must be greater than `from_ms`. Default: no upper bound." }, { "name": "slug_prefix", "in": "query", "required": false, "schema": { "type": "string", "description": "Only markets whose slug starts with this, e.g. `btc-updown-5m-`. Lowercase letters, digits and `-`, up to 100 characters; anything else is a `400`. A market with no known slug never matches.", "default": "", "title": "Slug Prefix" }, "description": "Only markets whose slug starts with this, e.g. `btc-updown-5m-`. Lowercase letters, digits and `-`, up to 100 characters; anything else is a `400`. A market with no known slug never matches." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Resume strictly after this `resolved_ts_ms:condition_id`, taken from a previous page's `next_cursor`.", "default": "", "title": "Cursor" }, "description": "Resume strictly after this `resolved_ts_ms:condition_id`, taken from a previous page's `next_cursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Rows per page. Default and hard cap `5000`. A full page typically takes 1 to 3 seconds and each page counts as one request, so ask for full pages.", "default": "", "title": "Limit" }, "description": "Rows per page. Default and hard cap `5000`. A full page typically takes 1 to 3 seconds and each page counts as one request, so ask for full pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/settlements/{condition_id}": { "get": { "tags": [ "polymarket" ], "summary": "On-chain settlement", "description": "The ON-CHAIN resolution row for one market, as an array of 0 or 1 rows.\n\n⚠ ``[]`` means \"the chain resolved nothing\", NOT \"open\". ~2,134 markets are\nclosed by Polymarket with no on-chain resolution (cancellations, UMA voids), so\nan empty settlement is not \"still trading\" — which is why ``active``/``closed``\non ``/markets`` read BOTH sources rather than this one alone.\n\n``market_known`` is false for a resolved market with no market-list row: its\n``slug``, ``token_ids``, ``outcomes``, ``question``, ``winning_token_id`` and\n``winning_outcome`` are then empty, while the on-chain fields are still exact.", "operationId": "settlement_v1_polymarket_settlements__condition_id__get", "parameters": [ { "name": "condition_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The `0x`-prefixed market condition id. As with [`/markets/{condition_id}`](https://vike.io/docs/data/endpoints/polymarket/markets-condition-id), a `token_id` here returns `[]`.", "title": "Condition Id" }, "description": "The `0x`-prefixed market condition id. As with [`/markets/{condition_id}`](https://vike.io/docs/data/endpoints/polymarket/markets-condition-id), a `token_id` here returns `[]`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/wallets/{address}": { "get": { "tags": [ "polymarket" ], "summary": "One trader's profile", "description": "A Polymarket wallet's profile: lifetime volume and trade counts, realized P&L and hit rate\nover ``window`` (by RESOLUTION time), markets, recent trades, open positions and an equity\ncurve. A wallet with no recorded trades answers ``400 {\"error\": ...}``, not zeros.\n\nThe headline ``realized_pnl_usd``, ``resolved_markets`` and ``hit_rate`` count only markets\nalready settled in Polymarket's own daily resolution records, so a market that settled on chain\nin the last day can show ``realized_pnl`` in ``markets[]`` (which also reads the on-chain\nsettlement) before the headline counts it. The headline ``hit_rate`` is volume-weighted;\n``category_breakdown[].hit_rate`` is a plain count (``wins`` / ``resolved``), and\n``category_breakdown[].hit_rate_volume_weighted`` is the headline's definition per category.\nEach ``open_positions`` row carries its ``token_id``.\n\nThe wallets that trade the same markets (``correlated``) are not in this response: that scan is\nfar heavier than the rest of the profile, so it is its own endpoint,\n``GET /v1/polymarket/wallets/{address}/correlated``. The key is absent, not an empty list, and\nevery successful response says so in an ``X-Vike-Hint`` header.", "operationId": "wallet_v1_polymarket_wallets__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet's `0x`-prefixed proxy-wallet address (40 hex digits). Anything else is a `400`.", "title": "Address" }, "description": "The wallet's `0x`-prefixed proxy-wallet address (40 hex digits). Anything else is a `400`." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h`, `7d`, `30d` or `all`. Default `all`. Any other value is a `400`. See *What the window moves* for which fields it changes.", "default": "", "title": "Window" }, "description": "`24h`, `7d`, `30d` or `all`. Default `all`. Any other value is a `400`. See *What the window moves* for which fields it changes." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/wallets/{address}/correlated": { "get": { "tags": [ "polymarket" ], "summary": "Wallets that trade the same markets", "description": "The other wallets that trade the same markets as ``address``, as a BARE ARRAY of up to 8 rows: most\nshared markets first, then the largest overlap volume. Each row has ``proxy_wallet``, ``pseudonym``,\n``display_name``, ``shared_markets``, ``overlap_volume_usd``, ``overlap_trades`` and ``last_seen``.\n\nA wallet is listed when it shares at least 3 markets and at least $500 of volume with ``address``. Only\nthe address's 1,000 largest markets by its own volume are compared, so a market-making bot is matched on\nits biggest markets, not all of them. An answer is cached for up to 3 minutes.\n\nThis block used to be the ``correlated`` key of ``GET /v1/polymarket/wallets/{address}``, which no longer\ncarries it: the scan is the heaviest read of the profile, so a client that does not want it never waits\nfor it. ``[]`` means no wallet qualifies, and is also the answer for an address with no recorded trades\n(the profile answers that with a `400`). The MCP and AI-chat tool ``polymarket_wallet`` still returns\nthe block inline.", "operationId": "wallet_correlated_v1_polymarket_wallets__address__correlated_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet's `0x`-prefixed proxy-wallet address (40 hex digits). Anything else is a `400`.", "title": "Address" }, "description": "The wallet's `0x`-prefixed proxy-wallet address (40 hex digits). Anything else is a `400`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/smart_money": { "get": { "tags": [ "polymarket" ], "summary": "Smart-money signals", "description": "``flows``: markets with the largest net inflow from the smart-money cohort over the\nwindow. ``mispricings``: markets where that cohort bought meaningfully below the current mid.\nThe cohort is wallets with $1k+ realized PnL over 5+ resolved markets and $5k+ volume.\nA ``flows`` row's ``buy_inflow``, ``sell_outflow`` and ``net_inflow`` add both outcomes, so buying\nUp and buying Down both read as inflow; ``outcomes`` splits them per outcome, and a market's\ndirection is the difference between its outcomes' ``net_inflow``.", "operationId": "smart_money_v1_polymarket_smart_money_get", "parameters": [ { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "description": "`flows` (default) — markets with the largest net cohort inflow in the window. `mispricings` — markets where the cohort bought meaningfully below the current mid. Any other value is a `400`.", "default": "", "title": "Mode" }, "description": "`flows` (default) — markets with the largest net cohort inflow in the window. `mispricings` — markets where the cohort bought meaningfully below the current mid. Any other value is a `400`." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "string", "description": "Lookback window in hours, an integer from 1 to 720. Default 24. Anything else is a `400`.", "default": "", "title": "Hours" }, "description": "Lookback window in hours, an integer from 1 to 720. Default 24. Anything else is a `400`." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Restrict to one market category (at most 64 characters). Default: all. An unknown category returns `[]`, not an error.", "default": "", "title": "Category" }, "description": "Restrict to one market category (at most 64 characters). Default: all. An unknown category returns `[]`, not an error." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Maximum rows, a positive integer. Default 10; values above 20 are capped at 20.", "default": "", "title": "Limit" }, "description": "Maximum rows, a positive integer. Default 10; values above 20 are capped at 20." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/leaderboard": { "get": { "tags": [ "polymarket" ], "summary": "Wallet leaderboard", "description": "The wallet leaderboard: Polymarket wallets ranked by realized P&L, hit rate, volume or trade\ncount, as an ARRAY of rows (an empty array means no wallet passes the filters). The same board\nvike.io/polymarket shows, read from the hourly leaderboard table, not the tape.\n\n``hit_rate`` is a FRACTION (0.62 = 62%), volume-weighted, and ``null`` where undefined, never 0;\n``hit_rate_ci`` is the +/- half-width of its 95% Wilson interval, also a fraction. ``tags`` are\n``whale``, ``bot``, ``hot`` and ``cold``. ``first_seen`` is the first trade in the recorded tape\n(it starts 2026-01-01), so it does not show a wallet is new.", "operationId": "leaderboard_v1_polymarket_leaderboard_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "`all` (default), `Crypto`, `Sports`, `Politics`, `Pop-Culture` or `Tech`. Every figure is recomputed on that category's markets only. Any other value is a `400`.", "default": "", "title": "Category" }, "description": "`all` (default), `Crypto`, `Sports`, `Politics`, `Pop-Culture` or `Tech`. Every figure is recomputed on that category's markets only. Any other value is a `400`." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "`24h`, `7d`, `30d` or `all`. Default `all`. The period behind `trades_window`, `volume_window_usd` and `realized_pnl_window_usd` (P&L of the markets that RESOLVED inside it), and what the `*_window` sorts rank on; with no `sort`, `24h` / `7d` / `30d` rank on `realized_pnl_window_usd`. `24h`, `7d` and `30d` are rebuilt hourly and a market's resolution time can be corrected later, so they can be revised; `all` is not affected. Any other value is a `400`.", "default": "", "title": "Window" }, "description": "`24h`, `7d`, `30d` or `all`. Default `all`. The period behind `trades_window`, `volume_window_usd` and `realized_pnl_window_usd` (P&L of the markets that RESOLVED inside it), and what the `*_window` sorts rank on; with no `sort`, `24h` / `7d` / `30d` rank on `realized_pnl_window_usd`. `24h`, `7d` and `30d` are rebuilt hourly and a market's resolution time can be corrected later, so they can be revised; `all` is not affected. Any other value is a `400`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Default `realized_pnl_window` when `window` is `24h`, `7d` or `30d`, `realized_pnl` when it is `all`. `realized_pnl` (lifetime USD, largest first, whatever the window), `realized_pnl_asc` (biggest losers first), `realized_pnl_window` and `realized_pnl_window_asc` (P&L inside `window`), `hit_rate` (highest first, nulls last; the top is often wallets that buy near-certain outcomes just under $1, a 100% rate on a sliver of P&L, so set `realized_pnl_usd` against `volume_all_usd` before reading it as skill), `resolved` (most resolved markets), `volume_24h` and `trades_24h` (USD volume and trade count inside `window`; the names are historical), `volume_all`, `trades_all`, `markets` (lifetime), `last_seen` (most recent first). Ties break on the wallet address; `hit_rate` ties break on the most resolved markets first, then the largest lifetime volume, then the address. Any other value is a `400`.", "default": "", "title": "Sort" }, "description": "Default `realized_pnl_window` when `window` is `24h`, `7d` or `30d`, `realized_pnl` when it is `all`. `realized_pnl` (lifetime USD, largest first, whatever the window), `realized_pnl_asc` (biggest losers first), `realized_pnl_window` and `realized_pnl_window_asc` (P&L inside `window`), `hit_rate` (highest first, nulls last; the top is often wallets that buy near-certain outcomes just under $1, a 100% rate on a sliver of P&L, so set `realized_pnl_usd` against `volume_all_usd` before reading it as skill), `resolved` (most resolved markets), `volume_24h` and `trades_24h` (USD volume and trade count inside `window`; the names are historical), `volume_all`, `trades_all`, `markets` (lifetime), `last_seen` (most recent first). Ties break on the wallet address; `hit_rate` ties break on the most resolved markets first, then the largest lifetime volume, then the address. Any other value is a `400`." }, { "name": "min_resolved", "in": "query", "required": false, "schema": { "type": "string", "description": "Minimum resolved markets, a count from 0 to 4294967295. Default `20`, so a `hit_rate` rests on a real sample; `0` includes wallets too thin for one.", "default": "", "title": "Min Resolved" }, "description": "Minimum resolved markets, a count from 0 to 4294967295. Default `20`, so a `hit_rate` rests on a real sample; `0` includes wallets too thin for one." }, { "name": "min_volume_usd", "in": "query", "required": false, "schema": { "type": "string", "description": "Minimum lifetime volume in USD (buys plus sells), a finite number of 0 or more. Default `0`.", "default": "", "title": "Min Volume Usd" }, "description": "Minimum lifetime volume in USD (buys plus sells), a finite number of 0 or more. Default `0`." }, { "name": "min_avg_usd", "in": "query", "required": false, "schema": { "type": "string", "description": "Minimum average trade size in USD, a finite number of 0 or more. Default `0`. `20` leaves out every wallet tagged `bot`.", "default": "", "title": "Min Avg Usd" }, "description": "Minimum average trade size in USD, a finite number of 0 or more. Default `0`. `20` leaves out every wallet tagged `bot`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Rows per page, a positive integer. Default 20; values above 50 are capped at 50.", "default": "", "title": "Limit" }, "description": "Rows per page, a positive integer. Default 20; values above 50 are capped at 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string", "description": "Rows to skip, an integer from 0 to 1000. Default 0. The board is rebuilt hourly, so a page fetched after a rebuild can repeat or skip a wallet. Above 1000 is a `400`: narrow with `category` or a `min_*` filter instead.", "default": "", "title": "Offset" }, "description": "Rows to skip, an integer from 0 to 1000. Default 0. The board is rebuilt hourly, so a page fetched after a rebuild can repeat or skip a wallet. Above 1000 is a `400`: narrow with `category` or a `min_*` filter instead." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/events": { "get": { "tags": [ "polymarket" ], "summary": "Raw event tape (paged)", "description": "The raw per-market event tape, ordered ``(local_ts, seq, token_id)``.\n\n⚠ **One of two routes whose body is an envelope** (the other is\n``/settlements/bulk``): ``{events, has_more, next_cursor}``. ``bids``/``asks``\nare strings carrying embedded JSON, and ``is_snapshot`` is a number, 0 or 1.\n\nBounded in every dimension on purpose: both window bounds required, the\nwindow itself capped at 24h, ``token_ids`` capped at 100, ``limit`` capped\nat 50,000. ``next_cursor`` is a string only while ``has_more`` is true and\n``null`` otherwise.", "operationId": "events_v1_polymarket_events_get", "parameters": [ { "name": "token_id", "in": "query", "required": false, "schema": { "type": "string", "description": "A single token — sugar for a one-element `token_ids`.", "default": "", "title": "Token Id" }, "description": "A single token — sugar for a one-element `token_ids`." }, { "name": "token_ids", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated token ids, **max 100 per request**. Wins over `token_id` if both are given.", "default": "", "title": "Token Ids" }, "description": "Comma-separated token ids, **max 100 per request**. Wins over `token_id` if both are given." }, { "name": "from_ms", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. Window start, epoch ms, **inclusive**.", "default": "", "title": "From Ms" }, "description": "Window start, epoch ms, **inclusive**." }, { "name": "to_ms", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. Window end, epoch ms, **exclusive**. Must be greater than `from_ms`.", "default": "", "title": "To Ms" }, "description": "Window end, epoch ms, **exclusive**. Must be greater than `from_ms`." }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to one of `book`, `price_change`, `trade`, `tick_size_change`, `status`.", "default": "", "title": "Event Type" }, "description": "Filter to one of `book`, `price_change`, `trade`, `tick_size_change`, `status`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Resume from a previous page's `next_cursor`, passed back unchanged. It is `local_ts:seq:token_id`, with a `~n` suffix when the page ended between two rows that share one `local_ts:seq:token_id` (two prints of a token in the same millisecond); no row is skipped or repeated.", "default": "", "title": "Cursor" }, "description": "Resume from a previous page's `next_cursor`, passed back unchanged. It is `local_ts:seq:token_id`, with a `~n` suffix when the page ended between two rows that share one `local_ts:seq:token_id` (two prints of a token in the same millisecond); no row is skipped or repeated." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Max rows per page. Default `5000`, hard cap `50000`.", "default": "", "title": "Limit" }, "description": "Max rows per page. Default `5000`, hard cap `50000`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/archive/datasets": { "get": { "tags": [ "polymarket" ], "summary": "Archive file index", "description": "Every known archive Parquet file, filtered and paged, in MANIFEST ORDER.\n\n``{\"datasets\": [...], \"limit\": n, \"offset\": n, \"total\": n}`` — ``total`` is\nthe filtered count BEFORE paging, and ``limit``/``offset`` echo the\nEFFECTIVE values.\n\n⚠ TWO row shapes on one endpoint. A ``family`` row carries ``asset`` and\n``tenor``; a ``flat`` row OMITS both keys entirely rather than emitting\n``null``. Supplying either filter therefore excludes every flat row by\nconstruction.\n\n⚠ ``from``/``to`` are DATE STRINGS here and epoch-ms integers on\n``/v1/polymarket/ohlcv``. Same names, different endpoints, different types.", "operationId": "archive_datasets_v1_polymarket_archive_datasets_get", "parameters": [ { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "description": "Matches **family-layout rows only**, e.g. `btc`. Supplying it excludes every flat row.", "default": "", "title": "Asset" }, "description": "Matches **family-layout rows only**, e.g. `btc`. Supplying it excludes every flat row." }, { "name": "tenor", "in": "query", "required": false, "schema": { "type": "string", "description": "Matches **family-layout rows only**, e.g. `5m`.", "default": "", "title": "Tenor" }, "description": "Matches **family-layout rows only**, e.g. `5m`." }, { "name": "stream", "in": "query", "required": false, "schema": { "type": "string", "description": "One of `book_events`, `trades`, `l1_quotes`.", "default": "", "title": "Stream" }, "description": "One of `book_events`, `trades`, `l1_quotes`." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "`YYYY-MM-DD`, inclusive lower date bound.", "default": "", "title": "From" }, "description": "`YYYY-MM-DD`, inclusive lower date bound." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "`YYYY-MM-DD`, inclusive upper date bound.", "default": "", "title": "To" }, "description": "`YYYY-MM-DD`, inclusive upper date bound." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "description": "Max rows. Default `200`, hard cap `1000`.", "default": "", "title": "Limit" }, "description": "Max rows. Default `200`, hard cap `1000`." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string", "description": "Skip this many matching rows. Default `0`.", "default": "", "title": "Offset" }, "description": "Skip this many matching rows. Default `0`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/polymarket/archive/url": { "get": { "tags": [ "polymarket" ], "summary": "Resolve one archive file", "description": "Resolve exactly ONE dataset to a temporary download link.\n\nReturns a single dataset OBJECT — not an array, not an envelope. The only\nroute in this family with that shape, the only one that can answer 302, and\nthe only one that sets a header.\n\n``url`` is a presigned link to that one file, valid for ``expires_in``\nseconds (7 days) until ``expires_at``; it needs no API key, so do not share\nit. A file your account may not download is a **403**.\n\n⚠ ``?redirect=1`` returns **302** with a ``Location`` header AND the full\nJSON body, so a client that does not follow redirects still gets the answer.\n\n⚠ \"No such dataset\" is a **400**, not a 404: the manifest was read and the\ncombination simply has no file. A 404 would claim the route does not exist.\n\n⚠ Both ``asset`` and ``tenor``, or neither. Exactly one is rejected as\nambiguous rather than guessed at.", "operationId": "archive_url_v1_polymarket_archive_url_get", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. `YYYY-MM-DD`. Omitting it returns `400 {\"error\":\"archive/url requires date\"}`.", "default": "", "title": "Date" }, "description": "`YYYY-MM-DD`. Omitting it returns `400 {\"error\":\"archive/url requires date\"}`." }, { "name": "stream", "in": "query", "required": true, "schema": { "type": "string", "description": "Required. One of `book_events`, `trades`, `l1_quotes`.", "default": "", "title": "Stream" }, "description": "One of `book_events`, `trades`, `l1_quotes`." }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "description": "Supply **both** `asset` and `tenor` to resolve the family layout, or **neither** to resolve the flat layout.", "default": "", "title": "Asset" }, "description": "Supply **both** `asset` and `tenor` to resolve the family layout, or **neither** to resolve the flat layout." }, { "name": "tenor", "in": "query", "required": false, "schema": { "type": "string", "description": "With asset, selects the family layout.", "default": "", "title": "Tenor" }, "description": "With asset, selects the family layout." }, { "name": "redirect", "in": "query", "required": false, "schema": { "type": "string", "description": "`true` (or `1`) returns `302` with the file in `Location`; the JSON body is still sent, so a client that does not follow redirects keeps the answer.", "default": "", "title": "Redirect" }, "description": "`true` (or `1`) returns `302` with the file in `Location`; the JSON body is still sent, so a client that does not follow redirects keeps the answer." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "OAuth2Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "vk_oat_...", "description": "OAuth 2.1 access token: `Authorization: Bearer vk_oat_...`. Issued by vike.io — discovery at `https://vike.io/.well-known/oauth-authorization-server`. Tried first; an invalid bearer falls through to the API-key header, so a request may carry either or both." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Long-lived API key: `X-API-KEY: vk_...`. Create and revoke keys at https://vike.io/account?tab=api-keys. Every call is metered against the key and subject to an hourly rate limit and, on `/v1`, a per-minute cap of 200 requests; a trip is HTTP 429 with a `Retry-After` header." } } }, "security": [ { "OAuth2Bearer": [] }, { "ApiKeyHeader": [] } ], "x-vike-limits": { "credits_per_call": 1, "credit_overrides": { "GET /v1/hyperliquid/ohlcv/export": 2 }, "hourly_limit": 20000, "minute_limit": 200 } }