Hyperliquid Market Data — OHLCV, Funding Rates & Positioning (Tessera)

Every field the query tools accept, each with its meaning, unit and whether it can be missing. Open — no key needed. Call this before query_cross_section, screen_universe or query_series. Percentile, z-score and the top_pct/bottom_pct conditions rank within the markets your plan can see, so they need a wide slice.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "fields": {
      "description": "Every field the query tools accept.",
      "items": {
        "$ref": "#/$defs/FieldDoc"
      },
      "type": "array"
    },
    "generated_at": {
      "description": "When this vocabulary was produced.",
      "type": "string"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "generated_at",
    "fields",
    "notes"
  ],
  "$defs": {
    "FieldDoc": {
      "description": "One addressable field's documentation.\n\nServed verbatim by the MCP plane's `list_fields`; the schema derive is what\nkeeps the tool's advertised output shape and the served JSON the same thing.",
      "properties": {
        "kind": {
          "description": "`stored` (a column in the daily source) or `factor` (computed at query\ntime over a trailing window, or from the end-day row).",
          "type": "string"
        },
        "meaning": {
          "description": "Plain-English meaning, authored in the semantic layer.",
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "nullable": {
          "description": "Whether the value can be absent for a market on a day.",
          "type": "boolean"
        },
        "type": {
          "description": "The stored column's type (`float64`, `uint32`, `date32`, …); absent for\nquery-time factors, which are always floats.",
          "nullable": true,
          "type": "string"
        },
        "unit": {
          "description": "The unit the values actually carry (`usd_notional`, `base_units`,\n`ratio`, `fraction`, `count`, `date`, …). A stored column name is never a\nsynonym for its unit — the OI a caller sees is USD notional where the\ncolumn is named for the notion.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "meaning",
        "unit",
        "nullable",
        "kind"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "FieldsResult"
}

Rank markets by how far their funding has diverged from a benchmark (default ETH) over a trailing window. metric=rate compares mean daily funding; metric=cum_funding_spread compares funding accumulated over the window. Returns the most diverged in each direction. Markets with no funding reading are excluded from both lists. Descriptive only.

{
  "type": "object",
  "properties": {
    "benchmark": {
      "default": null,
      "description": "The market whose funding is the yardstick. Defaults to ETH.",
      "nullable": true,
      "type": "string"
    },
    "coins": {
      "default": null,
      "description": "Restrict to these markets.",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "type": "array"
    },
    "metric": {
      "default": null,
      "description": "`rate` (the default) ranks each market's mean daily funding minus the\nbenchmark's; `cum_funding_spread` ranks funding accumulated over the\nwindow, high minus low, minus the benchmark's.",
      "nullable": true,
      "type": "string"
    },
    "scope": {
      "default": null,
      "description": "`crypto` (the default), `hip3`, or `all`.",
      "nullable": true,
      "type": "string"
    },
    "top_n": {
      "default": null,
      "description": "Markets per ranked list, 1..50. Defaults to 10.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    },
    "window_days": {
      "default": null,
      "description": "Length of the trailing window in days, 1..365. Defaults to 7.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DivergenceArgs"
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "type": "string"
    },
    "benchmark": {
      "type": "string"
    },
    "benchmark_value": {
      "description": "The benchmark's own value for the metric.",
      "format": "double",
      "type": "number"
    },
    "coin_count": {
      "description": "How many markets had a funding reading in the window; markets without\none are excluded from both lists and from this count.",
      "format": "int64",
      "type": "integer"
    },
    "metric": {
      "type": "string"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "scope": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "top_negative": {
      "description": "The largest divergences toward the benchmark's opposite, most extreme\nfirst.",
      "items": {
        "$ref": "#/$defs/DivergenceRow"
      },
      "type": "array"
    },
    "top_positive": {
      "description": "The largest divergences away from the benchmark, most extreme first.",
      "items": {
        "$ref": "#/$defs/DivergenceRow"
      },
      "type": "array"
    },
    "truncated": {
      "type": "boolean"
    },
    "window_days": {
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "source",
    "as_of",
    "scope",
    "coin_count",
    "metric",
    "benchmark",
    "window_days",
    "benchmark_value",
    "top_positive",
    "top_negative",
    "truncated",
    "notes"
  ],
  "$defs": {
    "DivergenceRow": {
      "description": "One market's funding divergence from the benchmark.",
      "properties": {
        "coin": {
          "type": "string"
        },
        "divergence": {
          "description": "`value` minus the benchmark's.",
          "format": "double",
          "type": "number"
        },
        "value": {
          "description": "This market's value for the requested metric over the window.",
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "coin",
        "value",
        "divergence"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DivergenceResult"
}

The coverage picture: the last complete day, how many markets are in the universe for a scope, how much history sits behind them, and how densely it is populated. A compact SUMMARY by default — pass top_n (1..50) only if you need the per-market day counts.

{
  "type": "object",
  "properties": {
    "day": {
      "default": null,
      "description": "The day to describe, `YYYY-MM-DD` or `latest`.",
      "nullable": true,
      "type": "string"
    },
    "scope": {
      "default": null,
      "description": "`crypto` (the default), `hip3`, or `all`.",
      "nullable": true,
      "type": "string"
    },
    "top_n": {
      "default": null,
      "description": "Per-market detail is off by default; passing a value (1..50) returns\nthat many markets, listed by name, alongside the summary.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "UniverseArgs"
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "description": "The day the per-population counts describe.",
      "type": "string"
    },
    "coin_count_crypto": {
      "description": "Markets without a deployer prefix on the described day, whatever scope\nwas asked for.",
      "format": "int64",
      "type": "integer"
    },
    "coin_count_hip3": {
      "description": "Markets with a deployer prefix on the described day.",
      "format": "int64",
      "type": "integer"
    },
    "coin_count_total": {
      "description": "Distinct markets in scope over the whole range.",
      "format": "int64",
      "type": "integer"
    },
    "coins": {
      "description": "Per-market detail, only when requested. Markets are listed by name.",
      "items": {
        "$ref": "#/$defs/UniverseCoin"
      },
      "nullable": true,
      "type": "array"
    },
    "coverage_from_manifest": {
      "description": "True when the day range came from the published coverage manifest,\nfalse when it had to be read from the data itself.",
      "type": "boolean"
    },
    "day_count": {
      "description": "Distinct days in the range.",
      "format": "int64",
      "type": "integer"
    },
    "max_complete_day": {
      "description": "The newest complete day — the day `latest` resolves to.",
      "type": "string"
    },
    "min_day": {
      "description": "The oldest day the counts below cover: the published range start, or the\ncaller's history floor when the plan clips it (the response says so in\n`notes`).",
      "type": "string"
    },
    "months_covered": {
      "format": "int64",
      "type": "integer"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "row_count": {
      "description": "Rows in scope over the whole range.",
      "format": "int64",
      "type": "integer"
    },
    "rows_per_market_day": {
      "description": "`row_count` divided by (days × markets) — how densely the range is\npopulated. Below 1.0 means some markets are missing some days.",
      "format": "double",
      "type": "number"
    },
    "scope": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "truncated": {
      "description": "True when more markets exist than the detail list returned.",
      "type": "boolean"
    }
  },
  "required": [
    "source",
    "as_of",
    "scope",
    "min_day",
    "max_complete_day",
    "day_count",
    "months_covered",
    "coin_count_total",
    "coin_count_crypto",
    "coin_count_hip3",
    "row_count",
    "rows_per_market_day",
    "coverage_from_manifest",
    "truncated",
    "notes"
  ],
  "$defs": {
    "UniverseCoin": {
      "description": "One market's coverage within the described range.",
      "properties": {
        "coin": {
          "type": "string"
        },
        "days": {
          "description": "How many days of the range this market appears on.",
          "format": "int64",
          "type": "integer"
        }
      },
      "required": [
        "coin",
        "days"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "UniverseResult"
}

Screen the whole market on ONE completed day with several conditions ANDed together. Conditions use op >, <, >=, <=, between, top_pct or bottom_pct; top_pct/bottom_pct are deciles of the markets you can see. Answers 'top-decile funding with bottom-decile open-interest change' and 'open interest rising faster than volume'. A market that does not report a field never satisfies a condition on it.

{
  "type": "object",
  "properties": {
    "coins": {
      "default": null,
      "description": "Restrict to these markets.",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "type": "array"
    },
    "columns": {
      "default": null,
      "description": "Fields to return per market, from `list_fields`.",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "type": "array"
    },
    "conditions": {
      "description": "Conditions, all of which must hold. A market that does not report a\nfield never satisfies a condition on it.",
      "items": {
        "$ref": "#/$defs/ConditionArg"
      },
      "type": "array"
    },
    "day": {
      "default": null,
      "description": "The day to screen, `YYYY-MM-DD` or `latest`.",
      "nullable": true,
      "type": "string"
    },
    "descending": {
      "default": null,
      "description": "Rank largest first (the default).",
      "nullable": true,
      "type": "boolean"
    },
    "max_results": {
      "default": null,
      "description": "How many markets to return, 1..50. Defaults to 25.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    },
    "min_usd_volume_7d_avg": {
      "default": null,
      "description": "Drop markets below this average daily traded notional over the window.",
      "format": "double",
      "nullable": true,
      "type": "number"
    },
    "order_by": {
      "default": null,
      "description": "The field to rank the matches by. Defaults to the day's traded notional.",
      "nullable": true,
      "type": "string"
    },
    "scope": {
      "default": null,
      "description": "`crypto` (the default), `hip3`, or `all`.",
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "conditions"
  ],
  "$defs": {
    "ConditionArg": {
      "description": "One condition of a screen.",
      "properties": {
        "column": {
          "description": "The field to test, from `list_fields`.",
          "type": "string"
        },
        "op": {
          "description": "One of `>`, `<`, `>=`, `<=`, `between`, `top_pct`, `bottom_pct`.\n`top_pct`/`bottom_pct` keep the best/worst `value` percent of the\nmarkets you can see by that field.",
          "type": "string"
        },
        "value": {
          "description": "The threshold. For `top_pct`/`bottom_pct` this is a percentage, e.g. 10\nfor the top decile.",
          "format": "double",
          "type": "number"
        },
        "value2": {
          "default": null,
          "description": "Required for `between`: the upper bound, inclusive.",
          "format": "double",
          "nullable": true,
          "type": "number"
        }
      },
      "required": [
        "column",
        "op",
        "value"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ScreenArgs"
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "type": "string"
    },
    "coin_count": {
      "description": "The number of markets in your visible slice on that day — the\ndenominator the percentage conditions and the floor were measured\nagainst.",
      "format": "int64",
      "type": "integer"
    },
    "matched_count": {
      "description": "How many markets met every condition.",
      "format": "int64",
      "type": "integer"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "row_count": {
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "rows": {
      "items": true,
      "type": "array"
    },
    "scope": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "truncated": {
      "type": "boolean"
    }
  },
  "required": [
    "source",
    "as_of",
    "scope",
    "coin_count",
    "matched_count",
    "row_count",
    "truncated",
    "rows",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ScreenResult"
}

List the downloadable datasets: one-line summary, the plan required, and the month range available. Open — no key needed. Then use describe_dataset for one dataset's columns, or list_fields for the fields the query tools accept.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "datasets": {
      "items": {
        "$ref": "#/$defs/CatalogEntry"
      },
      "type": "array"
    },
    "generated_at": {
      "description": "When this catalog was produced.",
      "type": "string"
    },
    "your_tier": {
      "description": "The caller's own plan (`free`, `pro` or `anonymous`).",
      "type": "string"
    }
  },
  "required": [
    "your_tier",
    "generated_at",
    "datasets"
  ],
  "$defs": {
    "CatalogEntry": {
      "description": "One dataset in the public catalog.",
      "properties": {
        "cadence": {
          "type": "string"
        },
        "category": {
          "type": "string"
        },
        "column_count": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "months": {
          "description": "The published month range, `[earliest, latest]`. Absent when the catalog\nlists no months for it.",
          "items": {
            "type": "string"
          },
          "nullable": true,
          "type": "array"
        },
        "name": {
          "type": "string"
        },
        "summary": {
          "type": "string"
        },
        "tier": {
          "description": "`free` or `pro` — the plan required to read this dataset's data.",
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "title",
        "category",
        "cadence",
        "summary",
        "tier",
        "column_count"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DatasetsResult"
}

Rank the whole market on ONE completed day: pick columns, an order_by field and top_n. Answers 'top markets by funding / open interest / returns on the latest day' and 'what percentile is BTC on open interest'. day defaults to the last complete day; scope defaults to crypto (HIP-3 markets track an underlying that closes, so their flow is not comparable); stat=percentile|zscore ranks within your visible markets; window_days recomputes the trailing-window fields; min_usd_volume_7d_avg keeps dust out of the ranking. Field names come from list_fields — never guess them, they are snake_case compound names; for a cut ('top decile by X') use screen_universe.

{
  "type": "object",
  "properties": {
    "coins": {
      "default": null,
      "description": "Restrict to these markets. A market outside your plan's coverage is\nignored rather than widening the answer.",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "type": "array"
    },
    "columns": {
      "default": null,
      "description": "Fields to return per market, from `list_fields`. `coin` is always\nincluded. Defaults to price, traded notional and the day's return.",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "type": "array"
    },
    "day": {
      "default": null,
      "description": "The day to rank, `YYYY-MM-DD`, or `latest` (the default: the most recent\ncomplete day).",
      "nullable": true,
      "type": "string"
    },
    "descending": {
      "default": null,
      "description": "Rank largest first (the default). Set false for the smallest.",
      "nullable": true,
      "type": "boolean"
    },
    "min_usd_volume_7d_avg": {
      "default": null,
      "description": "Drop markets whose average daily traded notional over the window is\nbelow this value, so dust cannot top a ranking.",
      "format": "double",
      "nullable": true,
      "type": "number"
    },
    "order_by": {
      "default": null,
      "description": "The field to rank by. Need not appear in `columns`. Defaults to the\nday's traded notional.",
      "nullable": true,
      "type": "string"
    },
    "scope": {
      "default": null,
      "description": "`crypto` (the default), `hip3`, or `all`. Restricted markets track an\nunderlying that closes, so their flow is not comparable on a weekend.",
      "nullable": true,
      "type": "string"
    },
    "stat": {
      "default": null,
      "description": "`raw` (the default), `percentile`, or `zscore`. Percentile and z-score\nare ranked **within the markets your plan can see**, so they need a\nslice of at least four markets.",
      "nullable": true,
      "type": "string"
    },
    "top_n": {
      "default": null,
      "description": "How many markets to return, 1..50. Defaults to 20.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    },
    "window_days": {
      "default": null,
      "description": "Recompute the trailing-window fields over this many days, 1..365\n(default 7). The response always states the window it used.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CrossSectionArgs"
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "description": "The UTC day the answer describes.",
      "type": "string"
    },
    "coin_count": {
      "description": "The number of markets in your visible slice on that day — the\ndenominator every statistic and floor below is measured against.",
      "format": "int64",
      "type": "integer"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "ranked_count": {
      "description": "How many markets had a value for the ranked field and passed the floor.",
      "format": "int64",
      "type": "integer"
    },
    "row_count": {
      "description": "How many markets are in `rows`.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "rows": {
      "items": true,
      "type": "array"
    },
    "scope": {
      "description": "The market population the ranking ran over.",
      "type": "string"
    },
    "source": {
      "description": "`tessera_daily` — the answer is from completed days, not the live market.",
      "type": "string"
    },
    "stat": {
      "description": "The ranking treatment actually applied: `raw`, `percentile` or\n`zscore`.",
      "type": "string"
    },
    "truncated": {
      "description": "True when `ranked_count` exceeds `row_count`.",
      "type": "boolean"
    }
  },
  "required": [
    "source",
    "as_of",
    "scope",
    "coin_count",
    "ranked_count",
    "row_count",
    "truncated",
    "stat",
    "rows",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CrossSectionResult"
}

The daily series for one market or a few (max 10): one row per market per day over a trailing window, oldest first. Answers 'is this move backed by real flow' and 'how has positioning built up'. ending_day defaults to the last complete day. The whole answer is capped, so markets times window_days must stay inside the row cap; the response states the window it used.

{
  "type": "object",
  "properties": {
    "coins": {
      "description": "The markets to return, 1..10.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "columns": {
      "default": null,
      "description": "Fields to return per row, from `list_fields`. `day` and `coin` are\nalways included.",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "type": "array"
    },
    "ending_day": {
      "default": null,
      "description": "The last day to include, `YYYY-MM-DD` or `latest`.",
      "nullable": true,
      "type": "string"
    },
    "scope": {
      "default": null,
      "description": "`crypto` (the default), `hip3`, or `all`.",
      "nullable": true,
      "type": "string"
    },
    "window_days": {
      "default": null,
      "description": "Length of the trailing window in days, 1..365. Defaults to 7.",
      "format": "uint",
      "minimum": 0,
      "nullable": true,
      "type": "integer"
    }
  },
  "required": [
    "coins"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SeriesArgs"
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "description": "The last day in the series.",
      "type": "string"
    },
    "coin_count": {
      "description": "The markets the series covers.",
      "format": "int64",
      "type": "integer"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "row_count": {
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "rows": {
      "items": true,
      "type": "array"
    },
    "scope": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "truncated": {
      "type": "boolean"
    },
    "window_days": {
      "description": "The window the trailing fields were computed over.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "source",
    "as_of",
    "scope",
    "window_days",
    "coin_count",
    "row_count",
    "truncated",
    "rows",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SeriesResult"
}

What is happening right now: mark price, current hourly funding, open interest, 24-hour traded notional and premium for up to 25 markets, taken straight from the venue's public API and stamped with the moment it was read. Use this for 'now' questions; the daily tools answer completed days only.

{
  "type": "object",
  "properties": {
    "coins": {
      "description": "The markets to snapshot, 1..25.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "coins"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "LiveMarketArgs"
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "description": "When the snapshot was taken, UTC.",
      "type": "string"
    },
    "coin_count": {
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "rows": {
      "items": {
        "$ref": "#/$defs/LiveMarketRow"
      },
      "type": "array"
    },
    "source": {
      "description": "`hyperliquid_rest` — this is the live market, not the completed-day data.",
      "type": "string"
    }
  },
  "required": [
    "source",
    "as_of",
    "coin_count",
    "rows",
    "notes"
  ],
  "$defs": {
    "LiveMarketRow": {
      "description": "Snapshot of one market, as of the upstream fetch.",
      "properties": {
        "coin": {
          "type": "string"
        },
        "day_volume_usd": {
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "funding_rate": {
          "description": "Current hourly funding rate.",
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "mark_px": {
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "mid_px": {
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "oi_usd": {
          "description": "`open_interest * mark_px` when both are present.",
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "open_interest": {
          "description": "Open interest in base units, as reported upstream.",
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "oracle_px": {
          "format": "double",
          "nullable": true,
          "type": "number"
        },
        "premium": {
          "format": "double",
          "nullable": true,
          "type": "number"
        }
      },
      "required": [
        "coin"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "LiveMarketResult"
}

The full dictionary for ONE downloadable dataset: description plus every column's type, nullability and plain-English meaning. Pass a name from list_datasets. Open — no key needed. For the fields the query tools accept, use list_fields.

{
  "type": "object",
  "properties": {
    "asset": {
      "description": "Dataset name, as returned by `list_datasets`.",
      "type": "string"
    }
  },
  "required": [
    "asset"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Which dataset's dictionary to return.",
  "title": "DatasetArg"
}

{
  "type": "object",
  "properties": {
    "cadence": {
      "description": "How frequently the data is sampled, e.g. \"1-minute bars\".",
      "type": "string"
    },
    "category": {
      "description": "Presentation category, e.g. `raw-tiles` or `forecast-layer`.",
      "type": "string"
    },
    "column_count": {
      "description": "Number of documented columns.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "column_groups": {
      "description": "Columns, grouped for presentation, in schema order.",
      "items": {
        "$ref": "#/$defs/ColumnGroup"
      },
      "type": "array"
    },
    "description": {
      "description": "Longer prose — the dictionary page header.",
      "type": "string"
    },
    "direct_answer": {
      "default": "",
      "description": "40-60 word keyword-first lead answer — the definitional \"what is this\"\nblurb, and the strongest AI-citation extraction target. Defaulted for\nforward/backward compatibility with snapshots predating the field.",
      "type": "string"
    },
    "keywords": {
      "default": [],
      "description": "Per-dataset discovery keywords (schema.org keywords on the web).",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "name": {
      "description": "Dataset name, exactly as `list_datasets` reports it.",
      "type": "string"
    },
    "note": {
      "description": "Optional \"how to use this\" callout.",
      "nullable": true,
      "type": "string"
    },
    "seo_title": {
      "default": "",
      "description": "Keyword-first SEO title tag (web `<title>`). Defaulted so older snapshots\nwithout the field still deserialize.",
      "type": "string"
    },
    "summary": {
      "description": "One-line intuitive summary — the catalog card.",
      "type": "string"
    },
    "temporal": {
      "$ref": "#/$defs/Temporal",
      "default": {
        "convention": "",
        "grain": "",
        "label": "",
        "timestamp_field": ""
      },
      "description": "Machine-readable timestamp/interval contract: what the label marks and\nhow to join without leaking the future. Defaulted so snapshots predating\nthe field still deserialize."
    },
    "tier": {
      "description": "Display tier: `free` or `pro`. Re-derived from `policy.rs` on read, so it\nalways matches actual entitlement regardless of the on-disk value.",
      "type": "string"
    },
    "title": {
      "description": "Human-friendly title, e.g. \"Order-flow OHLCV (1-minute)\".",
      "type": "string"
    },
    "use_case": {
      "default": "",
      "description": "One-line \"what you'd use it for\" (buyer-intent) copy.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "title",
    "category",
    "cadence",
    "summary",
    "description",
    "tier",
    "column_count",
    "column_groups"
  ],
  "$defs": {
    "ColumnDoc": {
      "description": "One column's dictionary entry: the engineering facts (type/nullability/how\nit's computed) plus the plain-English `meaning` (what it is and why you'd care).",
      "properties": {
        "description": {
          "description": "Technical description — *how* the column is computed. May be absent.",
          "nullable": true,
          "type": "string"
        },
        "meaning": {
          "description": "Plain-English meaning — *what* the column is and why it's useful.",
          "type": "string"
        },
        "name": {
          "description": "Column name.",
          "type": "string"
        },
        "nullable": {
          "description": "Whether the column may be null.",
          "type": "boolean"
        },
        "type": {
          "description": "Arrow type string, e.g. `float64`, `timestamp[us]`.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "type",
        "nullable",
        "meaning"
      ],
      "type": "object"
    },
    "ColumnGroup": {
      "description": "A labelled section of columns within a dataset.",
      "properties": {
        "columns": {
          "items": {
            "$ref": "#/$defs/ColumnDoc"
          },
          "type": "array"
        },
        "label": {
          "description": "Section heading, or `null` for a single unlabelled group.",
          "nullable": true,
          "type": "string"
        },
        "meaning": {
          "description": "Group-level plain-English meaning, used for large column families (e.g.\nthe residualized factor backbone) where a per-column line adds no value.",
          "nullable": true,
          "type": "string"
        },
        "window": {
          "default": null,
          "description": "Temporal window of this group's fields relative to the timestamp label:\none of `point_in_time`, `backward`, `forward`, `contemporaneous`,\n`static`. Null when the dataset-level `temporal.convention` covers them.",
          "nullable": true,
          "type": "string"
        }
      },
      "required": [
        "columns"
      ],
      "type": "object"
    },
    "Temporal": {
      "description": "The dataset's temporal contract — what the timestamp column marks and the\nlook-ahead-safety rules for joining. Mirror of the resolver's `temporal`\nblock (`semantic/__init__.py`).",
      "properties": {
        "convention": {
          "description": "One-paragraph plain-English join / look-ahead contract.",
          "type": "string"
        },
        "grain": {
          "description": "Observation width, e.g. `1m`, `1h`, `1d`, `1mo`.",
          "type": "string"
        },
        "label": {
          "description": "What the label marks: one of `interval_start`, `interval_end`,\n`snapshot`, `forecast_target`.",
          "type": "string"
        },
        "timestamp_field": {
          "description": "Which column carries the label, e.g. `time`, `day`, `month_start`.",
          "type": "string"
        }
      },
      "required": [
        "grain",
        "timestamp_field",
        "label",
        "convention"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "One dataset's catalog entry + full data dictionary.",
  "title": "DatasetDoc"
}