{"openapi":"3.1.1","info":{"title":"Castle Labs Data API","version":"1.0.0","summary":"Read-only JSON API over Castle Labs' live crypto datasets, refreshed daily.","description":"No key or sign-up. GET only, CORS open, responses cached for five minutes. Cite Castle Labs with a link to the dataset page, and credit the sources listed when you reuse a figure. The same datasets are available to AI agents through the MCP server at https://castlelabs.io/mcp.","contact":{"name":"Castle Labs","url":"https://castlelabs.io/contact"}},"externalDocs":{"description":"Setup guide and examples","url":"https://castlelabs.io/research/data/api"},"servers":[{"url":"https://castlelabs.io/api/v1"}],"paths":{"/datasets":{"get":{"operationId":"listDatasets","summary":"List datasets","description":"Every dataset the API serves, with its tables, row counts, columns, sources and citation.","responses":{"200":{"description":"Dataset list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetList"}}}}}}},"/datasets/{slug}":{"get":{"operationId":"getDataset","summary":"Describe one dataset","parameters":[{"name":"slug","in":"path","required":true,"description":"Dataset slug, as listed by /datasets.","schema":{"type":"string","enum":["perp-dex-rankings","l2-economics","hyperliquid","tokenized-stocks","institutional-vaults","stablecoin-yields","eth-staking-yield","stablecoins","tokenized-treasuries","onchain-commodities","pre-ipo-markets"]}}],"responses":{"200":{"description":"Dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dataset"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/datasets/{slug}/{table}":{"get":{"operationId":"getRows","summary":"Read rows from a table","description":"Filter, sort, project and page through one table. String comparisons ignore case.","parameters":[{"name":"slug","in":"path","required":true,"description":"Dataset slug, as listed by /datasets.","schema":{"type":"string","enum":["perp-dex-rankings","l2-economics","hyperliquid","tokenized-stocks","institutional-vaults","stablecoin-yields","eth-staking-yield","stablecoins","tokenized-treasuries","onchain-commodities","pre-ipo-markets"]}},{"name":"table","in":"path","required":true,"description":"Table id, as listed for the dataset.","schema":{"type":"string","enum":["hip3-deployers","depth","chains","hip3-volume-by-deployer","hip3-share-of-volume","hip3-crude-oil-volume","stock-perps","morpho-vaults","morpho-curators","rates","tokens","queue","savings","funds","markets","daily-volume","other-dexes"]}},{"name":"where","in":"query","description":"Filter as column:op:value; repeat for more (all must match, at most 10). Operators: eq, ne, gt, gte, lt, lte, contains, in. in takes a comma-separated list.","schema":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]+:(eq|ne|gt|gte|lt|lte|contains|in):.*$"}},"style":"form","explode":true,"example":["oiUsd:gt:1000000"]},{"name":"sort","in":"query","description":"Column to sort by; prefix with - for descending.","schema":{"type":"string"},"example":"-oiUsd"},{"name":"fields","in":"query","description":"Comma-separated columns to return. Nested columns use dots.","schema":{"type":"string"},"example":"ticker,oiUsd,dayVolume"},{"name":"limit","in":"query","description":"Rows to return; larger values are capped at 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","description":"Rows to skip, for paging with nextOffset.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rows"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/search":{"get":{"operationId":"search","summary":"Search every table","description":"Rows whose text mentions the query, plus datasets whose name or description matches.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100},"example":"hyperliquid"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/openapi.json":{"get":{"operationId":"openapi","summary":"This document","responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["name","url"]},"Attribution":{"type":"object","description":"How to cite the data: Castle Labs with the page link, plus the upstream sources.","properties":{"cite":{"type":"string"},"page":{"type":"string","format":"uri"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"terms":{"type":"string"}},"required":["cite","page","sources","terms"]},"Table":{"type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"rows":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}},"columnInfo":{"type":"object","additionalProperties":{"type":"string"}},"updatedAt":{"type":["string","null"],"format":"date-time"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"url":{"type":"string"},"note":{"type":"string"}},"required":["id","description","rows","columns","sources","url"]},"Dataset":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"page":{"type":"string","format":"uri"},"url":{"type":"string"},"updatedAt":{"type":["string","null"],"format":"date-time"},"complete":{"type":"boolean","description":"False when some of the page's tables are not served by the API."},"tables":{"type":"array","items":{"$ref":"#/components/schemas/Table"}},"attribution":{"$ref":"#/components/schemas/Attribution"},"note":{"type":"string"}},"required":["slug","name","page","tables","attribution"]},"DatasetList":{"type":"object","properties":{"version":{"type":"string"},"count":{"type":"integer"},"datasets":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"}},"pageOnly":{"type":"array","description":"Live datasets available on castlelabs.io pages but not through the API.","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"page":{"type":"string","format":"uri"}}}},"terms":{"type":"string"}},"required":["count","datasets"]},"Rows":{"type":"object","properties":{"dataset":{"type":"string"},"table":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"page":{"type":"string","format":"uri"},"updatedAt":{"type":["string","null"],"format":"date-time"},"query":{"type":"object"},"total":{"type":"integer","description":"Rows matching the filters, before limit and offset."},"returned":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"columns":{"type":"array","items":{"type":"string"}},"columnInfo":{"type":"object","additionalProperties":{"type":"string"}},"rows":{"type":"array","items":{"type":"object"}},"attribution":{"$ref":"#/components/schemas/Attribution"},"note":{"type":"string"},"otherTables":{"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean"}},"required":["dataset","table","total","returned","rows","attribution"]},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"returned":{"type":"integer"},"datasets":{"type":"array","items":{"type":"object"}},"pageOnly":{"type":"array","description":"Matching datasets that are on castlelabs.io pages only, because their source terms bar re-serving them through the API","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"page":{"type":"string"},"note":{"type":"string"}}}},"rows":{"type":"array","items":{"type":"object","properties":{"dataset":{"type":"string"},"table":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}},"row":{"type":"object"}}}},"attribution":{"type":"array","items":{"$ref":"#/components/schemas/Attribution"}},"terms":{"type":"string"}},"required":["query","total","rows","attribution"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"}},"required":["status","code","message"]},"docs":{"type":"string","format":"uri"}},"required":["error"]}},"responses":{"BadRequest":{"description":"Invalid filter, column, sort or limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Unknown dataset or table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}