{"openapi":"3.0.3","info":{"title":"CryptoKeyhole API","version":"1.0.0","description":"On-chain and market analytics for Bitcoin, Ethereum and a growing list of coins, calculated from CryptoKeyhole's own nodes and collectors: every chart's history as exact values, the metric catalogue, the Fear & Greed Index, perpetual futures screens and an MCP server for AI assistants.\n\nWithout a key you read the Free view: the Free charts at daily, weekly, monthly and yearly resolution with full history, plus the free tools' endpoints. A chart above your plan answers a fixed historical sample or a plan lock, never a current reading. With an API key from your account page (Plus and higher plans) you read what your plan includes: Plus adds hourly data, the Plus charts and downloads; Pro adds ten-minute data, every premium chart and full-history downloads; API & Team adds commercial use and unmetered calls. Keys are read-only and go in the Authorization header. Each client (key or address) may make 240 requests a minute; Plus includes 1,000 API calls a day and Pro 100,000 a month.\n\nFree charts and free API data are licensed CC BY 4.0 (credit CryptoKeyhole with a link); their answers, JSON and CSV, carry a Link header with rel=\"license\". Paid-plan data, the samples of paid charts and raw exchange or other third-party data are not covered and carry no such header.\n\nTimes are UTC Unix seconds; a range's start is included and its end is not. Values are exact decimal strings (null where there is no observation, never zero), each with its finality: final, provisional, or partial for the open period, which is updated hourly until it closes.","termsOfService":"https://cryptokeyhole.com/terms/","contact":{"name":"CryptoKeyhole","url":"https://cryptokeyhole.com/data-access/"},"license":{"name":"CC BY 4.0 (free data; paid-plan data under the terms of service)","url":"https://cryptokeyhole.com/methodology/#licence-title"},"x-logo":{"url":"https://cryptokeyhole.com/favicon.svg"}},"externalDocs":{"description":"API keys, plans, Google Sheets, Excel and Python","url":"https://cryptokeyhole.com/data-access/"},"servers":[{"url":"https://cryptokeyhole.com/api/v1"}],"tags":[{"name":"Charts","description":"Chart data, the catalogue and downloads"},{"name":"Indices","description":"The Fear & Greed Index"},{"name":"Markets","description":"Perpetual futures screener and funding carry"},{"name":"Tools","description":"Data behind the free calculators"},{"name":"Platform","description":"Status and the MCP server"}],"paths":{"/status":{"get":{"tags":["Platform"],"operationId":"getStatus","summary":"Platform status","description":"Each data source's processed frontier and freshness, as the site reports them.","security":[{}],"responses":{"200":{"description":"Status document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/assets":{"get":{"tags":["Charts"],"operationId":"listAssets","summary":"Assets","description":"The public assets, Bitcoin first. Every other asset's chart ids start with its prefix (for example eth.).","security":[{}],"responses":{"200":{"description":"The assets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assets"}}}}}}},"/catalog":{"get":{"tags":["Charts"],"operationId":"getCatalog","summary":"Metric catalogue","description":"Every chart of one asset with its id, name, unit, description, method, intervals, coverage and status. A planned chart that has not published carries status held and its reason.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"asset","in":"query","description":"An asset code from /assets. Default BTC, or the asset of the first of ids.","schema":{"type":"string","example":"ETH"}},{"name":"ids","in":"query","description":"Comma-separated chart ids of one asset: only these charts.","schema":{"type":"string","example":"eth.PriceUSD"}},{"name":"view","in":"query","description":"directory: the chart directory's tree instead of the flat list (not with ids).","schema":{"type":"string","enum":["directory"]}}],"responses":{"200":{"description":"The catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/series":{"get":{"tags":["Charts"],"operationId":"getSeries","summary":"Chart series","description":"One chart's observations, one point per period, and for charts with several lines their components. Free charts at 24h, 1w, 1M and 1Y need no key. A chart or interval above the plan answers 200 with state locked and the plan it needs, or a fixed historical sample named by the X-CKH-Preview header. Price-distribution charts (catalogue distribution.type price_histogram) take one UTC day: start at midnight and end exactly one day later.","security":[{},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/metric"},{"$ref":"#/components/parameters/interval"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/end"},{"name":"limit","in":"query","description":"Most points returned (12 to 20,000, default 3,000); a longer range is reduced to it.","schema":{"type":"integer","minimum":12,"maximum":20000,"default":3000}},{"$ref":"#/components/parameters/sma"},{"$ref":"#/components/parameters/smoothing"},{"$ref":"#/components/parameters/publication"}],"responses":{"200":{"description":"The series, or its plan lock","headers":{"X-CKH-Preview":{"description":"Set when the answer is a fixed sample of a chart above the plan: plan, name, from, through (UTC seconds) and sample=1.","schema":{"type":"string"}},"Link":{"description":"Set on a free chart's answer at a free resolution when the data is ours to license: <https://creativecommons.org/licenses/by/4.0/>; rel=\"license\".","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Series"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/formula":{"get":{"tags":["Charts"],"operationId":"getFormula","summary":"Saved formula as a series","description":"A saved formula read like a chart. Anyone can read a formula by the share id of its public link; with your key you can also read your own saved formulas by their id. Every input chart and the interval must be in the requester's plan. Without interval, start and end the formula's saved interval and range apply.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"description":"A share id, or the id of one of your own saved formulas.","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["10m","1h","24h","1w","1M"]}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/end"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":12,"maximum":20000}}],"responses":{"200":{"description":"The formula's series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Series"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/export":{"get":{"tags":["Charts"],"operationId":"exportSeries","summary":"Chart download (Plus and higher)","description":"The chart pages' CSV or JSON download of one chart, with every provenance column, the source, licence and attribution of each series. Included with Plus and higher plans.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/metric"},{"$ref":"#/components/parameters/interval"},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/end"},{"$ref":"#/components/parameters/sma"},{"$ref":"#/components/parameters/smoothing"},{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"],"default":"csv"}},{"$ref":"#/components/parameters/publication"}],"responses":{"200":{"description":"The download, as an attachment","content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/Series"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/fear-and-greed":{"get":{"tags":["Indices"],"operationId":"getFearAndGreed","summary":"Fear & Greed Index","description":"The crypto market's Fear & Greed Index, or one coin's: the latest reading (0 to 100 and exact), its band, the time it is as of and whether its UTC day is still open, today's components with their weights, the readings a day, a week, a month and a year before, and the daily history, newest first. Free, keyless and open to other origins (CORS). Guide: https://cryptokeyhole.com/fear-and-greed-index/api/","security":[{}],"parameters":[{"name":"coin","in":"query","description":"market (the default) or a coin code that has its own index (see /fear-and-greed/coins).","schema":{"type":"string","example":"btc"}},{"name":"limit","in":"query","description":"Days of history, newest first (default 30; 0 for all).","schema":{"type":"integer","minimum":0,"default":30}},{"name":"format","in":"query","description":"csv gives the history rows only.","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The index","headers":{"Link":{"description":"The free data's licence: <https://creativecommons.org/licenses/by/4.0/>; rel=\"license\".","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/fear-and-greed/coins":{"get":{"tags":["Indices"],"operationId":"listFearAndGreedCoins","summary":"Fear & Greed Index of every coin","description":"Today's reading of the market's index and of every coin with its own. Free and keyless (CORS).","security":[{}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Today's readings","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}}}}},"/leverage":{"get":{"tags":["Indices"],"operationId":"getLeverageGauge","summary":"Leverage gauge","description":"How stretched leverage is in a coin, 0 to 100, hourly: open interest against market cap, funding, the futures basis, the long/short account ratio, Hyperliquid's large accounts and the nearest liquidation cluster, each ranked against the coin's own past year. With asset, every viewer gets the current value and band (keyless; CC BY 4.0); Plus and higher plans also get the components (reading, rank, score), the history (history=1h or 24h, with start and end) and, without asset, every coin ranked. page= answers the leverage pages' plan-dependent parts. Method: https://cryptokeyhole.com/crypto-leverage/","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"asset","in":"query","description":"A coin code (BTC, ETH, SOL, ...). Without it: every coin ranked (Plus).","schema":{"type":"string","example":"BTC"}},{"name":"history","in":"query","description":"1h (at most 90 days a request) or 24h: the gauge's history (Plus).","schema":{"type":"string","enum":["1h","24h"]}},{"name":"start","in":"query","description":"UTC seconds (history).","schema":{"type":"integer"}},{"name":"end","in":"query","description":"UTC seconds, exclusive (history).","schema":{"type":"integer"}}],"responses":{"200":{"description":"The gauge","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/tools/closes":{"get":{"tags":["Tools"],"operationId":"getDailyCloses","summary":"Daily closes","description":"One coin's daily USD closes from its first day, as its free price chart shows them: a (the coin), n (days), t0 (the first day, UTC seconds), v (one close or null per UTC day from t0) and now ([time, latest hourly price]). Free and keyless; the DCA and profit calculators use it.","security":[{}],"parameters":[{"name":"asset","in":"query","required":true,"description":"A coin code, for example BTC.","schema":{"type":"string","example":"BTC"}}],"responses":{"200":{"description":"The closes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Closes"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/perps":{"get":{"tags":["Markets"],"operationId":"getPerpsScreener","summary":"Perpetual futures screener","description":"One row per coin across the venues we collect, at the hour. Free (no key): the coins with the highest 24-hour volume, without open-interest, funding, liquidation or long/short values. Plus: every coin and contract with those values, and CSV. Pro: the five-minute view.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"view","in":"query","schema":{"type":"string","enum":["1h","5m"],"default":"1h"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The screener","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"402":{"$ref":"#/components/responses/PlanRequired"}}}},"/screener/fields":{"get":{"tags":["Markets"],"operationId":"getScreenerFields","summary":"Charts the asset screener reads","description":"Every directory slot the asset screener can screen: its id (for where, cols and sort), name, directory path, how many coins have a chart in it and on which plans, and its units.","responses":{"200":{"description":"The slots","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/screener/assets":{"get":{"tags":["Markets"],"operationId":"getAssetScreen","summary":"Asset screener","description":"Every coin screened by the latest readings of its own charts, matched by their place in the directory. where: all(...) or any(...) of conditions slot:measure op number, one nested group deep, at most 12; measure v (the reading), p1, p7, p30, p90 or p365 (the change in percent over that many days), d1 to d365 (the same change in the chart's unit), z (the four-year z-score) or q (the four-year percentile); op <, <=, > or >=. cols: up to 10 slot:measure columns (sp: the shape of the last 90 closed days). Slots come from /screener/fields. A cell above the requester's plan carries only its lock, and a condition on it never matches. Free (no key): the first 10 coins at the daily close. Plus: every coin, the latest hour and CSV. Pro: ten-minute readings and API keys.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"where","in":"query","schema":{"type":"string"},"example":"all(market.Mvrv:v<1,derivatives.FuturesFundingRatePerpetual:v<0)"},{"name":"cols","in":"query","schema":{"type":"string"},"example":"market.PriceUsdClose:v,market.PriceUsdClose:p30,market.Mvrv:v"},{"name":"sort","in":"query","description":"A slot:measure column, or asset for the ticker.","schema":{"type":"string"}},{"name":"dir","in":"query","schema":{"type":"string","enum":["desc","asc"],"default":"desc"}},{"name":"reading","in":"query","schema":{"type":"string","enum":["day","hour","tenmin"],"default":"day"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The screen","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PlanRequired"}}}},"/carry":{"get":{"tags":["Markets"],"operationId":"getCarryScanner","summary":"Funding carry scanner","description":"Funding-rate carry pairs across venues, after fees. Free (no key): the pairs with the highest 24-hour volume, without carry readings. Plus: every pair with net APR, costs, persistence and the backtest, and CSV. Pro: the five-minute view.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"view","in":"query","schema":{"type":"string","enum":["1h","5m"],"default":"1h"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The carry pairs","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"402":{"$ref":"#/components/responses/PlanRequired"}}}},"/carry/pair":{"get":{"tags":["Markets"],"operationId":"getCarryPair","summary":"One carry pair (Plus and higher)","description":"One pair's costs, persistence, backtest and daily settled carry.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"description":"A pair id from /carry.","schema":{"type":"string"}}],"responses":{"200":{"description":"The pair","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/perps/history":{"get":{"tags":["Markets"],"operationId":"getPerpsHistory","summary":"One contract's snapshots (Pro and higher)","security":[{"bearerAuth":[]}],"parameters":[{"name":"contract","in":"query","required":true,"description":"A contract id from /perps.","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["5m","1h"]}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/end"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"The snapshots","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/carry/history":{"get":{"tags":["Markets"],"operationId":"getCarryHistory","summary":"One pair's legs and spread (Pro and higher)","security":[{"bearerAuth":[]}],"parameters":[{"name":"pair","in":"query","required":true,"description":"A pair id from /carry.","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["5m","1h"]}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/end"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"The history","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/carry/funding":{"get":{"tags":["Markets"],"operationId":"getSettledFunding","summary":"One contract's settled funding (Pro and higher)","security":[{"bearerAuth":[]}],"parameters":[{"name":"contract","in":"query","required":true,"description":"A contract id from /perps.","schema":{"type":"string"}},{"$ref":"#/components/parameters/start"},{"$ref":"#/components/parameters/end"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"The settled funding","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/moves/latest":{"get":{"tags":["Markets"],"operationId":"getLatestMove","summary":"The latest sharp price move of a coin, explained","description":"The latest sharp move (a fall or rise within 15 minutes, 1 hour or 4 hours of at least four times the coin's own recent volatility, and at least 1%, 1.5% or 2.5%), found every minute, with what our own data saw during it and a card in plain English. Free (no key): BTC and ETH, built only from readings the free pages show (liquidations by side, open interest and funding, options expiry, ETF flows, transfers of $100M or more, dormant-coin moves of 1,000 BTC or more); the other parts are named in `locked`. Plus: every coin, venue detail, taker flow, the Coinbase premium, Hyperliquid large accounts, hourly exchange flows from our nodes and the base rates (what followed similar moves an hour and a day later). Sizes are exact fractions.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"asset","in":"query","schema":{"type":"string","default":"BTC"},"description":"A coin code (BTC, ETH, SOL, ...) or ALL."},{"name":"direction","in":"query","schema":{"type":"string","enum":["down","up"]}}],"responses":{"200":{"description":"The latest move of each coin asked for","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/PlanRequired"}}}},"/moves":{"get":{"tags":["Markets"],"operationId":"listMoves","summary":"The archive of sharp price moves","description":"Every sharp move of a coin (or ALL) detected between `from` and `to` (Unix seconds), newest first, with its card, what our data saw, the base rates and what followed it an hour and a day later. Coverage: five-minute prices from 2020 for the longest histories, one-minute prices since mid-October 2026. Plus.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"asset","in":"query","schema":{"type":"string","default":"BTC"},"description":"A coin code (BTC, ETH, SOL, ...) or ALL."},{"name":"from","in":"query","schema":{"type":"integer"}},{"name":"to","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}}],"responses":{"200":{"description":"The moves","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/PlanRequired"}}}},"/mcp":{"post":{"tags":["Platform"],"operationId":"mcp","summary":"MCP server for AI assistants","description":"A Model Context Protocol server (JSON-RPC 2.0 over Streamable HTTP): initialize, tools/list and tools/call, with tools to list assets, find charts and read their data. It is read-only and needs no account or key: it serves what the Free plan includes, and a chart on a higher plan answers with the plan that includes it. Send no credentials; a request with an Authorization or X-Api-Key header is refused. Guide: https://cryptokeyhole.com/mcp/","security":[{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string","example":"tools/list"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"The JSON-RPC answer","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"A notification was accepted"},"400":{"description":"An invalid JSON-RPC request, or one sent with credentials","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/billing/usage":{"get":{"tags":["Platform"],"operationId":"getUsage","summary":"API usage and call packs","description":"Calls made with the account's keys today and this month (UTC), the plan's allowance for each and when it resets, calls left in API call packs and when the next pack ends, and the packs on sale. Plus and Pro count calls against a daily or monthly allowance; past it, a call uses a pack (50,000 or 250,000 calls, bought on the account page, each kept 365 days) and without one answers 429. API & Team is unmetered. This request is not counted.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage document","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"},"planName":{"type":"string"},"via":{"type":"string","enum":["key","cookie"]},"apiCalls":{"type":"object","properties":{"today":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer","nullable":true},"resetsAt":{"type":"integer"}}},"month":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer","nullable":true},"resetsAt":{"type":"integer"}}}}},"credits":{"type":"object","properties":{"remaining":{"type":"integer"},"nextExpiry":{"type":"integer","nullable":true}}},"packs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"calls":{"type":"integer"},"amount":{"type":"integer","description":"US cents"},"currency":{"type":"string"},"days":{"type":"integer"}}}}}}}}},"401":{"description":"No API key or session"}}}},"/sql":{"get":{"tags":["Charts"],"operationId":"querySql","summary":"SQL over every chart's daily values","description":"One read-only statement (SELECT, or WITH ... SELECT; SQLite's dialect) over every public chart's daily values: tables series (asset, metric, chart, component, interval, day, t, value, finality), latest, metrics and assets; GET /sql/schema lists them with examples. Pro and API & Team: a key's query counts one API call. At most 100,000 rows (truncated), 30 seconds per statement. Values are 64-bit floats; the series route keeps exact decimals. The database is read again every hour.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"The SQL statement.","schema":{"type":"string","example":"SELECT a.asset, l.value FROM assets a JOIN latest l ON l.metric = a.price ORDER BY l.value DESC"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"maxRows","in":"query","schema":{"type":"integer","minimum":1,"maximum":100000}}],"responses":{"200":{"description":"columns, rows, rowCount, truncated and ms (JSON), or CSV","content":{"application/json":{"schema":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"array","items":{}}},"rowCount":{"type":"integer"},"truncated":{"type":"boolean"},"ms":{"type":"integer"}}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The database is being built or the query service is busy"}}},"post":{"tags":["Charts"],"operationId":"querySqlPost","summary":"SQL over every chart's daily values (long queries)","description":"As GET /sql, with the statement in a JSON body. A signed-in browser session sends its X-CSRF-Token.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"format":{"type":"string","enum":["json","csv"]},"maxRows":{"type":"integer"}}}}}},"responses":{"200":{"description":"As GET /sql"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/sql/schema":{"get":{"tags":["Charts"],"operationId":"getSqlSchema","summary":"SQL tables, columns and examples","description":"The tables and views of the SQL database with their columns, the finality words, example queries and when the data was read. No key needed.","security":[{}],"responses":{"200":{"description":"The schema","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"The database is being built"}}}},"/bulk/metric":{"get":{"tags":["Charts"],"operationId":"getEveryCoin","summary":"One metric for every coin","description":"One chart for every coin that publishes it, in one call: each coin's <prefix>.<name> chart (Bitcoin's ckh.<name>) with its components, as daily values with their finality, from the SQL database. Plus and higher; a coin's chart above the plan is listed under locked. One API call. At most 500,000 rows (truncated).","security":[{"bearerAuth":[]}],"parameters":[{"name":"metric","in":"query","required":true,"description":"A chart name without its coin prefix, or any coin's full chart id.","schema":{"type":"string","example":"PriceUSD"}},{"name":"assets","in":"query","description":"Comma-separated coins (all when absent).","schema":{"type":"string","example":"BTC,ETH"}},{"name":"since","in":"query","description":"First UTC day, YYYY-MM-DD or Unix seconds.","schema":{"type":"string"}},{"name":"until","in":"query","description":"Last UTC day, YYYY-MM-DD or Unix seconds.","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"metric, database (builtAt, kind, fullAt), columns (t, value, finality), series (asset, metric, chart, component, name, unit, interval, plan, url, points), locked, rows, truncated, licence; or CSV (asset, metric, chart, component, day, t, value, finality)","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The database is being built"}}}},"/bulk/venues":{"get":{"tags":["Charts"],"operationId":"getVenueHistory","summary":"Every venue's funding and open interest for a coin","description":"A coin's perpetual funding rate (%, the venue's settled rate averaged over the day, as an 8-hour rate) and open interest (USD, at the day's close) on every venue we hold, one series per measure and venue from its first value, as daily values with their finality, from the SQL database. Open interest uses the venue's own published history where it has one (Bybit, Bitfinex, Kraken, OKX, Gate) and our collection (from 14 October 2026) for the other venues. Pro and API & Team. One API call.","security":[{"bearerAuth":[]}],"parameters":[{"name":"asset","in":"query","required":true,"description":"One coin's ticker.","schema":{"type":"string","example":"BTC"}},{"name":"since","in":"query","description":"First UTC day, YYYY-MM-DD or Unix seconds.","schema":{"type":"string"}},{"name":"until","in":"query","description":"Last UTC day, YYYY-MM-DD or Unix seconds.","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"asset, database (builtAt, kind, fullAt), columns (t, value, finality), series (measure, venue, unit, chart, component, name, interval, plan, url, points), locked, rows, truncated, licence; or CSV (asset, measure, venue, unit, chart, day, t, value, finality)","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The database is being built"}}}},"/bulk/files":{"get":{"tags":["Charts"],"operationId":"listBulkFiles","summary":"The nightly files","description":"The latest nightly files the plan includes: one gzip CSV per coin and the series list (Pro and API & Team) and the whole SQLite database (API & Team), each with bytes, rows, SHA-256 and a download link that works for an hour without a key. One API call.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"builtAt, database, linksExpire, files (name, kind, asset, plan, bytes, rows, sha256, url), locked","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"503":{"description":"The files are being built for the first time"}}}},"/bulk/file/{name}":{"get":{"tags":["Charts"],"operationId":"downloadBulkFile","summary":"One nightly file (a signed link)","description":"A file from GET /bulk/files, by the link it signed (e and s); no key needed. Byte ranges are supported for resumed downloads.","security":[{}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"e","in":"query","required":true,"description":"The link's expiry (Unix seconds)","schema":{"type":"integer"}},{"name":"s","in":"query","required":true,"description":"The link's signature","schema":{"type":"string"}}],"responses":{"200":{"description":"The file","content":{"application/gzip":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"The requested byte range"},"403":{"description":"The link is not valid or has expired"},"404":{"description":"The file was replaced by a newer set"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/vintages":{"get":{"tags":["Charts"],"operationId":"getVintages","summary":"First-published values","description":"Each period's first published value, the reading a backtest would have seen at the time, or with asOf each period's value as it stood then. Every point carries seen, when CryptoKeyhole's recorder first saw that value. History starts when the recorder started (recordedSince) and cannot be recreated for earlier times. API & Team. One API call.","security":[{"bearerAuth":[]}],"parameters":[{"name":"metric","in":"query","required":true,"description":"A recorded chart id; /vintages/charts lists them.","schema":{"type":"string","example":"eth.ExchangeNetflow"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["1h","24h"],"default":"24h"}},{"name":"start","in":"query","description":"First period: YYYY-MM-DD, ISO time or Unix seconds.","schema":{"type":"string"}},{"name":"end","in":"query","description":"End of the window, exclusive: YYYY-MM-DD, ISO time or Unix seconds.","schema":{"type":"string"}},{"name":"asOf","in":"query","description":"Read each period as it stood at this time; without it, each period's first published value.","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"metric, interval, mode (first or asOf), asOf, recordedSince, truncated, points (t, v, finality, seen), about, docs; or CSV","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"description":"No vintages are recorded for this chart and interval"}}}},"/vintages/charts":{"get":{"tags":["Charts"],"operationId":"listVintageCharts","summary":"The charts with first-published values","description":"The recorded charts and intervals, and since when each has been recorded. No key needed.","security":[{}],"responses":{"200":{"description":"charts (metric, interval, recordedSince, vintages), listed, firstRun, lastRun, docs","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/data-webhooks":{"get":{"tags":["Charts"],"operationId":"listDataWebhooks","summary":"Data webhooks and destinations","description":"The account's data webhooks (a chart's new values, or a screen's changes, pushed to one of its webhooks) and its webhook destinations. Pro and API & Team.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"items, destinations, intervals","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"}}},"post":{"tags":["Charts"],"operationId":"addDataWebhook","summary":"Add a data webhook","description":"A chart ({destinationId, metric, interval}) or a screen ({destinationId, screen: {where}, interval}; the screener's conditions). Each new value is sent once as provisional, then final (event data.value); a screen's change in matching coins is one event (data.screen). It starts from the latest value. Checks run every five minutes. Pro holds 50, API & Team 200.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destinationId","interval"],"properties":{"destinationId":{"type":"string"},"metric":{"type":"string"},"screen":{"type":"object","properties":{"where":{"type":"string"}}},"interval":{"type":"string","enum":["10m","1h","24h"]}}}}}},"responses":{"201":{"description":"The new item","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/data-webhooks/delete":{"post":{"tags":["Charts"],"operationId":"deleteDataWebhook","summary":"Delete a data webhook","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/live/stream":{"get":{"tags":["Platform"],"operationId":"liveStream","summary":"Live stream (server-sent events)","description":"Prices (every 0.5 s while they move) and new blocks for everyone. With a Pro or API & Team key, also the data channels: trades ($100K+), liquidations ($10K+), transfers ($1M+), options blocks, funding and mempool. A hello event first; tape events carry an id for Last-Event-ID (20 minutes). Pro holds 2 keyed streams at once, API & Team 10; one API call per stream opened.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"channels","in":"query","description":"Comma-separated channels (GET /live/channels lists them).","schema":{"type":"string","example":"trades,liquidations"}},{"name":"assets","in":"query","description":"Comma-separated coins.","schema":{"type":"string","example":"BTC,ETH"}}],"responses":{"200":{"description":"An event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/live/channels":{"get":{"tags":["Platform"],"operationId":"liveChannels","summary":"Live stream channels","description":"The channels of GET /live/stream with what each sends and its minimum size. No key needed.","security":[{}],"responses":{"200":{"description":"channels","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from your account page (Plus and higher plans): Authorization: Bearer <key>. Keys are read-only."}},"parameters":{"metric":{"name":"metric","in":"query","required":true,"description":"The chart id, as in its address (/charts/eth/?metric=eth.PriceUSD) or the catalogue.","schema":{"type":"string","example":"eth.PriceUSD"}},"interval":{"name":"interval","in":"query","description":"Resolution, as the chart offers it: Free 24h, 1w, 1M and 1Y; Plus also 1h; Pro also 10m.","schema":{"type":"string","enum":["10m","1h","24h","1w","1M","1Y"],"default":"24h"}},"start":{"name":"start","in":"query","description":"UTC Unix seconds, included. Without it the chart's default window applies.","schema":{"type":"integer"}},"end":{"name":"end","in":"query","description":"UTC Unix seconds, not included. Without it the data runs to the latest value.","schema":{"type":"integer"}},"sma":{"name":"sma","in":"query","description":"Smoothing window in observations (0 for none).","schema":{"type":"integer","minimum":0,"default":0}},"smoothing":{"name":"smoothing","in":"query","description":"Smoothing method, as on the charts.","schema":{"type":"string","enum":["sma","ema","median"],"default":"sma"}},"publication":{"name":"publication","in":"query","description":"A retained publication id, for the charts that keep them; omit for current data.","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"The request's parameters are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The API key is invalid or revoked, or was sent to a route keys do not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PlanRequired":{"description":"Included with a higher plan; locked names it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Unknown chart, asset, id or API route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Request limit reached; try again in a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"locked":{"$ref":"#/components/schemas/Locked"}}},"Locked":{"type":"object","description":"What a higher plan would include.","properties":{"feature":{"type":"string","example":"interval"},"requiredPlan":{"type":"string","enum":["plus","pro","team"]},"requiredPlanName":{"type":"string","example":"Plus"},"currentPlan":{"type":"string","example":"free"},"currentPlanName":{"type":"string","example":"Free"},"upgradePath":{"type":"string","example":"/pricing/"},"allowedIntervals":{"type":"array","items":{"type":"string"}}}},"Assets":{"type":"object","properties":{"assets":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"ETH"},"name":{"type":"string","example":"Ethereum"},"route":{"type":"string","example":"eth"},"prefix":{"type":"string","example":"eth.","description":"The asset's chart ids start with it (not for BTC)."}}}}}},"Metric":{"type":"object","properties":{"id":{"type":"string","example":"eth.PriceUSD"},"name":{"type":"string"},"family":{"type":"string"},"unit":{"type":"string","example":"USD/ETH"},"description":{"type":"string"},"method":{"type":"string"},"intervals":{"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"held: planned but not published (see reason)."},"reason":{"type":"string","nullable":true},"historyStart":{"type":"integer","nullable":true,"description":"UTC seconds, the first period."},"historyEnd":{"type":"integer","nullable":true,"description":"UTC seconds, the end of the last period (not included)."}}},"Catalog":{"type":"object","properties":{"asset":{"type":"string"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/Metric"}}}},"Point":{"type":"object","required":["t","v","finality"],"properties":{"t":{"type":"integer","description":"The period's start, UTC seconds."},"v":{"type":"string","nullable":true,"description":"Exact decimal; null where there is no observation."},"finality":{"type":"string","enum":["final","provisional","partial"]}}},"Series":{"type":"object","properties":{"metric":{"$ref":"#/components/schemas/Metric"},"interval":{"type":"string"},"state":{"type":"string","description":"current; delayed (the source is late, with its delay); held (not published); locked (above the plan, see locked)."},"reason":{"type":"string","nullable":true},"points":{"type":"array","items":{"$ref":"#/components/schemas/Point"}},"components":{"type":"array","description":"The lines of a chart with several, each with its points.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"unit":{"type":"string"},"points":{"type":"array","items":{"$ref":"#/components/schemas/Point"}}}}},"historyStart":{"type":"integer","nullable":true},"historyEnd":{"type":"integer","nullable":true},"generatedAt":{"type":"integer"},"sourceObservedAt":{"type":"integer","nullable":true},"locked":{"$ref":"#/components/schemas/Locked"}}},"Closes":{"type":"object","properties":{"a":{"type":"string","example":"BTC"},"n":{"type":"integer"},"t0":{"type":"integer"},"v":{"type":"array","items":{"type":"number","nullable":true}},"now":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}}}