Kalshi — Tool Reference
Query Kalshi prediction market prices, orderbooks, trades, and event data
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# get_event_details read
Get a Kalshi event and all its child markets.
Full description
Get all child markets for a Kalshi event. Events group related markets (e.g., all Bitcoin price brackets for a date). Returns the event metadata plus all nested markets.
| Parameter | Type | Required | Description |
|---|---|---|---|
event_ticker | string | Yes | Event ticker from search results (e.g., 'KXBTC-26MAR14') |
Parameter schema (JSON)
{
"description": "Parameters for get_event_details tool.",
"properties": {
"event_ticker": {
"description": "Event ticker from search results (e.g., 'KXBTC-26MAR14')",
"title": "Event Ticker",
"type": "string"
}
},
"required": [
"event_ticker"
],
"title": "GetEventDetailsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"MarketSummary": {
"description": "Individual market within an event.",
"properties": {
"ticker": {
"description": "Human-readable market ticker (e.g., 'KXBTC-26MAR14-B100000')",
"title": "Ticker",
"type": "string"
},
"title": {
"default": "",
"description": "Market title/question",
"title": "Title",
"type": "string"
},
"subtitle": {
"default": "",
"description": "Market subtitle with additional context",
"title": "Subtitle",
"type": "string"
},
"yes_price": {
"default": 0,
"description": "Current Yes price (0.0-1.0 probability)",
"title": "Yes Price",
"type": "number"
},
"no_price": {
"default": 0,
"description": "Current No price (0.0-1.0 probability)",
"title": "No Price",
"type": "number"
},
"status": {
"default": "",
"description": "Market status: 'open', 'closed', 'settled'",
"title": "Status",
"type": "string"
},
"result": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Settlement result: 'yes', 'no', or null if unsettled",
"title": "Result"
},
"volume": {
"default": 0,
"description": "Total contracts traded",
"title": "Volume",
"type": "number"
},
"volume_24h": {
"default": 0,
"description": "Contracts traded in last 24 hours",
"title": "Volume 24H",
"type": "number"
},
"open_interest": {
"default": 0,
"description": "Currently open contracts",
"title": "Open Interest",
"type": "number"
},
"last_price": {
"default": 0,
"description": "Last traded price (0.0-1.0)",
"title": "Last Price",
"type": "number"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series ticker (needed for candlestick history)",
"title": "Series Ticker"
},
"event_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Parent event ticker",
"title": "Event Ticker"
}
},
"required": [
"ticker"
],
"title": "MarketSummary",
"type": "object"
}
},
"description": "Result of get_event_details tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"event_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event ticker",
"title": "Event Ticker"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event title",
"title": "Title"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event category",
"title": "Category"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series ticker",
"title": "Series Ticker"
},
"mutually_exclusive": {
"default": false,
"description": "Whether child markets are mutually exclusive",
"title": "Mutually Exclusive",
"type": "boolean"
},
"markets": {
"description": "All child markets for this event",
"items": {
"$ref": "#/$defs/MarketSummary"
},
"title": "Markets",
"type": "array"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetEventDetailsResult",
"type": "object"
} # get_market_details read
Read detailed metadata for a Kalshi market, including rules, strikes, settlement, and timing.
Full description
Get detailed information for a specific Kalshi market. Returns extended market metadata including rules, strike prices, settlement info, and timing details. Use the ticker from get_event_details results.
| Parameter | Type | Required | Description |
|---|---|---|---|
ticker | string | Yes | Market ticker (e.g., 'KXBTC-26MAR14-B100000') from search results |
Parameter schema (JSON)
{
"description": "Parameters for get_market_details tool.",
"properties": {
"ticker": {
"description": "Market ticker (e.g., 'KXBTC-26MAR14-B100000') from search results",
"title": "Ticker",
"type": "string"
}
},
"required": [
"ticker"
],
"title": "GetMarketDetailsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_market_details tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market ticker",
"title": "Ticker"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market title/question",
"title": "Title"
},
"subtitle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market subtitle",
"title": "Subtitle"
},
"yes_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Current Yes price (0.0-1.0)",
"title": "Yes Price"
},
"no_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Current No price (0.0-1.0)",
"title": "No Price"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market status",
"title": "Status"
},
"result": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Settlement result",
"title": "Result"
},
"created_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the market was listed (ISO 8601)",
"title": "Created Time"
},
"updated_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When market metadata was last updated (ISO 8601)",
"title": "Updated Time"
},
"open_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market open time (ISO 8601)",
"title": "Open Time"
},
"close_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market close time (ISO 8601)",
"title": "Close Time"
},
"expiration_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Expiration time (ISO 8601)",
"title": "Expiration Time"
},
"settlement_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Settlement value if settled",
"title": "Settlement Value"
},
"rules_primary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Primary rules for market resolution",
"title": "Rules Primary"
},
"volume": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Total contracts traded",
"title": "Volume"
},
"open_interest": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Currently open contracts",
"title": "Open Interest"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series ticker (for candlestick history)",
"title": "Series Ticker"
},
"event_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Parent event ticker",
"title": "Event Ticker"
},
"strike_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Strike type (e.g., 'greater', 'between')",
"title": "Strike Type"
},
"floor_strike": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Lower strike price",
"title": "Floor Strike"
},
"cap_strike": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Upper strike price",
"title": "Cap Strike"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetMarketDetailsResult",
"type": "object"
} # get_market_history read
Read OHLC candlestick history for a market and return timestamped price candles over a time range.
Full description
Get OHLC candlestick price history for a market. Requires both the market ticker and its series_ticker (available from search_events or get_event_details results). Returns candlestick data sorted ascending by timestamp. The Kalshi /candlesticks endpoint enforces a hard 5000-candlestick max per request. This tool auto-paginates backwards in sub-windows up to MAX_HISTORY_POINTS_PER_CALL (2000) candles or MAX_HISTORY_PAGES (15) API calls, whichever comes first. When a cap is hit, `truncated=True` and `continue_from` holds the earliest returned Unix timestamp — re-invoke with `end_ts = continue_from - 1` to fetch older data. Parameters: - period_interval: Candle size in minutes — 1 (1-min), 60 (1-hour), 1440 (1-day) - start_ts / end_ts: Optional Unix-seconds window. When start_ts is set, overrides the default window. ISO 8601 date strings are accepted as well, e.g. "2026-05-01" or "2026-05-01T00:00:00Z". end_ts defaults to now. Default windows scale with fidelity: 1 day (minute), 30 days (hourly), 1 year (daily). - skip_empty / exclude_zero_volume: When true, drop zero-volume candles. Useful for thin markets where long flatline runs add noise.
| Parameter | Type | Required | Description |
|---|---|---|---|
ticker | string | Yes | Market ticker from search results |
series_ticker | string | Yes | Series ticker from search or event results (required for candlestick endpoint) |
period_interval | integer | No | Candle period in minutes: 1 (1-min), 60 (1-hour), 1440 (1-day) Default: 60 |
start_ts | integer | string | null | No | Optional start timestamp as Unix seconds or ISO 8601 string (for example '2026-05-01' or '2026-05-01T00:00:00Z'). When omitted, defaults to a fidelity-scaled window (1 day for minute, 30 days for hourly, 1 year for daily). |
end_ts | integer | string | null | No | Optional end timestamp as Unix seconds or ISO 8601 string. Defaults to now when start_ts is set. Pass `continue_from - 1` from a truncated result to page backwards. |
skip_empty | boolean | No | When true, drop zero-volume candles from the result. Useful for thin markets where long runs of no-trade flatline candles add noise. Default: false |
exclude_zero_volume | boolean | null | No | Alias for skip_empty. When true, drop candles whose volume is 0. |
Parameter schema (JSON)
{
"description": "Parameters for get_market_history tool.",
"properties": {
"ticker": {
"description": "Market ticker from search results",
"title": "Ticker",
"type": "string"
},
"series_ticker": {
"description": "Series ticker from search or event results (required for candlestick endpoint)",
"title": "Series Ticker",
"type": "string"
},
"period_interval": {
"default": 60,
"description": "Candle period in minutes: 1 (1-min), 60 (1-hour), 1440 (1-day)",
"title": "Period Interval",
"type": "integer"
},
"start_ts": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional start timestamp as Unix seconds or ISO 8601 string (for example '2026-05-01' or '2026-05-01T00:00:00Z'). When omitted, defaults to a fidelity-scaled window (1 day for minute, 30 days for hourly, 1 year for daily).",
"title": "Start Ts"
},
"end_ts": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional end timestamp as Unix seconds or ISO 8601 string. Defaults to now when start_ts is set. Pass `continue_from - 1` from a truncated result to page backwards.",
"title": "End Ts"
},
"skip_empty": {
"default": false,
"description": "When true, drop zero-volume candles from the result. Useful for thin markets where long runs of no-trade flatline candles add noise.",
"title": "Skip Empty",
"type": "boolean"
},
"exclude_zero_volume": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Alias for skip_empty. When true, drop candles whose volume is 0.",
"title": "Exclude Zero Volume"
}
},
"required": [
"ticker",
"series_ticker"
],
"title": "GetMarketHistoryParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"CandleStick": {
"description": "OHLC candlestick data point.",
"properties": {
"timestamp": {
"description": "Candle end period timestamp (Unix seconds)",
"title": "Timestamp",
"type": "string"
},
"open": {
"description": "Opening price (0.0-1.0)",
"title": "Open",
"type": "number"
},
"high": {
"description": "Highest price (0.0-1.0)",
"title": "High",
"type": "number"
},
"low": {
"description": "Lowest price (0.0-1.0)",
"title": "Low",
"type": "number"
},
"close": {
"description": "Closing price (0.0-1.0)",
"title": "Close",
"type": "number"
},
"volume": {
"default": 0,
"description": "Contracts traded in this candle",
"title": "Volume",
"type": "number"
},
"session_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Session date (YYYY-MM-DD, America/New_York) this candle represents. Populated only for daily candles (period_interval=1440); null for minute and hourly candles.",
"title": "Session Date"
}
},
"required": [
"timestamp",
"open",
"high",
"low",
"close"
],
"title": "CandleStick",
"type": "object"
}
},
"description": "Result of get_market_history tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"candles": {
"description": "OHLC candlestick data, sorted ascending by timestamp",
"items": {
"$ref": "#/$defs/CandleStick"
},
"title": "Candles",
"type": "array"
},
"count": {
"default": 0,
"description": "Number of candles returned",
"title": "Count",
"type": "integer"
},
"truncated": {
"default": false,
"description": "True when the result was capped by MAX_HISTORY_POINTS_PER_CALL or MAX_HISTORY_PAGES. More data may be available earlier than `continue_from`.",
"title": "Truncated",
"type": "boolean"
},
"continue_from": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "When truncated=True, the earliest Unix timestamp fetched from the API (pre-filter). Re-invoke with end_ts = continue_from - 1 to page further back. NOTE: when skip_empty=True, the candle at this timestamp may have been filtered out and will not appear in `candles` — the value still anchors pagination to the raw window.",
"title": "Continue From"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional human-readable note (e.g., how to continue when truncated).",
"title": "Note"
},
"market_open_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market open/listing date when available (YYYY-MM-DD).",
"title": "Market Open Date"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetMarketHistoryResult",
"type": "object"
} # get_movers read
List top Kalshi volume movers over 1h/24h or price movers over 1h/24h/7d.
Full description
Return top Kalshi markets ranked by volume or price change. For kind="volume", ranks by relative volume over the selected window using the market-data API's baseline comparison. Volume movers currently support 1h and 24h windows. For kind="price", ranks by price percentage change over the same window; price movers support 1h, 24h, and 7d. Defaults to open markets only; pass status="" to include closed/settled markets. Use query for keyword/topic filtering, and list_mover_categories to discover valid category names for category/categories filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | "volume" | "price" | No | Rank by relative volume ('volume') or price move ('price'). Default: "volume" |
window | "1h" | "24h" | "7d" | No | Window to rank movers over. Use 24h for one day. Default: "1h" |
direction | "up" | "down" | "both" | No | For price: up/down/both price changes. For volume: up returns highest relative volume; down returns lowest; both ranks by absolute relative volume. Default: "up" |
category | string | null | No | Optional single market category filter. Prefer categories for multiple values. |
categories | array<string> | null | No | Optional set of market categories to include, e.g. ['Politics', 'Elections']. Empty means no include filter. |
exclude_categories | array<string> | null | No | Market categories to exclude. Defaults to ['Sports'] because sports markets are short-lived and often dominate movers noise. Pass [] to include sports. |
query | string | null | No | Optional keyword/topic filter applied before ranking. Matches market title or description, e.g. 'Fed' or 'election'. |
min_volume_24h | number | No | Minimum 24h volume filter used to suppress thin markets. Default: 500 |
limit | integer | No | Max movers to return (1..200). Default: 20 |
status | string | null | No | Filter to a single market-data status value. Defaults to 'active'. Pass an empty string to include all statuses. Default: "active" |
Parameter schema (JSON)
{
"description": "Parameters for get_movers tool.",
"properties": {
"kind": {
"default": "volume",
"description": "Rank by relative volume ('volume') or price move ('price').",
"enum": [
"volume",
"price"
],
"title": "Kind",
"type": "string"
},
"window": {
"default": "1h",
"description": "Window to rank movers over. Use 24h for one day.",
"enum": [
"1h",
"24h",
"7d"
],
"title": "Window",
"type": "string"
},
"direction": {
"default": "up",
"description": "For price: up/down/both price changes. For volume: up returns highest relative volume; down returns lowest; both ranks by absolute relative volume.",
"enum": [
"up",
"down",
"both"
],
"title": "Direction",
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional single market category filter. Prefer categories for multiple values.",
"title": "Category"
},
"categories": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional set of market categories to include, e.g. ['Politics', 'Elections']. Empty means no include filter.",
"title": "Categories"
},
"exclude_categories": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Market categories to exclude. Defaults to ['Sports'] because sports markets are short-lived and often dominate movers noise. Pass [] to include sports.",
"title": "Exclude Categories"
},
"query": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional keyword/topic filter applied before ranking. Matches market title or description, e.g. 'Fed' or 'election'.",
"title": "Query"
},
"min_volume_24h": {
"default": 500,
"description": "Minimum 24h volume filter used to suppress thin markets.",
"minimum": 0,
"title": "Min Volume 24H",
"type": "number"
},
"limit": {
"default": 20,
"description": "Max movers to return (1..200).",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "active",
"description": "Filter to a single market-data status value. Defaults to 'active'. Pass an empty string to include all statuses.",
"title": "Status"
}
},
"title": "GetMoversParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"MoverInfo": {
"description": "One market's volume or price change over the requested window.",
"properties": {
"venue": {
"title": "Venue",
"type": "string"
},
"market_id": {
"description": "Kalshi market ticker",
"title": "Market Id",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Status"
},
"samples": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Samples"
},
"open": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Open"
},
"close": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Close"
},
"price_abs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Price Abs"
},
"price_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Price Pct"
},
"window_vol": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Window Vol"
},
"baseline_per_window": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Baseline Per Window"
},
"rvol": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Rvol"
}
},
"required": [
"venue",
"market_id"
],
"title": "MoverInfo",
"type": "object"
}
},
"description": "Result of get_movers tool.",
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"kind": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Kind"
},
"window": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Window"
},
"direction": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Direction"
},
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Limit"
},
"baseline_window": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Baseline Window"
},
"baseline_complete": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Baseline Complete"
},
"warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Warning"
},
"movers": {
"items": {
"$ref": "#/$defs/MoverInfo"
},
"title": "Movers",
"type": "array"
},
"count": {
"default": 0,
"title": "Count",
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetMoversResult",
"type": "object"
} # get_orderbook read
Read the current market orderbook and return bid/ask depth with summary stats for up to 10 levels per side.
Full description
Get the current orderbook (bid/ask depth) for a market. Use the ticker from get_event_details results. Returns current bids, asks, and summary statistics. Results limited to 10 levels per side. NOTE: Kalshi only returns YES bids and NO bids. YES asks are derived from NO bids (ask_price = 1.0 - no_bid_price) for a unified view. Response includes: - summary: Quick stats (best_bid, best_ask, spread, midpoint, total liquidity) - bids: Top 10 YES bid levels sorted by price (highest first) - asks: Top 10 YES ask levels sorted by price (lowest first)
| Parameter | Type | Required | Description |
|---|---|---|---|
ticker | string | Yes | Market ticker from search results |
Parameter schema (JSON)
{
"description": "Parameters for get_orderbook tool.",
"properties": {
"ticker": {
"description": "Market ticker from search results",
"title": "Ticker",
"type": "string"
}
},
"required": [
"ticker"
],
"title": "GetOrderbookParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"OrderbookLevel": {
"description": "Single level in the orderbook.",
"properties": {
"price": {
"description": "Price level (0.0-1.0 probability)",
"title": "Price",
"type": "number"
},
"size": {
"description": "Number of contracts at this price level",
"title": "Size",
"type": "number"
}
},
"required": [
"price",
"size"
],
"title": "OrderbookLevel",
"type": "object"
},
"OrderbookSummary": {
"description": "Summary statistics for the orderbook.",
"properties": {
"best_bid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Highest bid price",
"title": "Best Bid"
},
"best_ask": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Lowest ask price",
"title": "Best Ask"
},
"spread": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Bid-ask spread (best_ask - best_bid)",
"title": "Spread"
},
"midpoint": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Midpoint price ((best_bid + best_ask) / 2)",
"title": "Midpoint"
},
"total_bid_liquidity": {
"default": 0,
"description": "Total contracts across all bid levels",
"title": "Total Bid Liquidity",
"type": "number"
},
"total_ask_liquidity": {
"default": 0,
"description": "Total contracts across all ask levels",
"title": "Total Ask Liquidity",
"type": "number"
},
"liquidity_units": {
"default": "contracts",
"description": "Units for total_bid_liquidity and total_ask_liquidity. Always 'contracts' — one contract settles for $1.",
"title": "Liquidity Units",
"type": "string"
}
},
"title": "OrderbookSummary",
"type": "object"
}
},
"description": "Result of get_orderbook tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"summary": {
"anyOf": [
{
"$ref": "#/$defs/OrderbookSummary"
},
{
"type": "null"
}
],
"default": null,
"description": "Summary statistics for quick reference"
},
"bids": {
"description": "Buy orders (bids), limited to top 10 levels",
"items": {
"$ref": "#/$defs/OrderbookLevel"
},
"title": "Bids",
"type": "array"
},
"asks": {
"description": "Sell orders (asks), limited to top 10 levels",
"items": {
"$ref": "#/$defs/OrderbookLevel"
},
"title": "Asks",
"type": "array"
},
"derived_asks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True when asks are present and derived from NO bids (yes_ask = 1.0 - no_bid_price). None on error or empty book.",
"title": "Derived Asks"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetOrderbookResult",
"type": "object"
} # get_recent_trades read
Read recent trades for a market and return paginated trade records with price, size, and taker side.
Full description
Get recent trades for a market. Returns a feed of recent trade records including price, size, and taker side. Supports pagination via cursor.
| Parameter | Type | Required | Description |
|---|---|---|---|
ticker | string | Yes | Market ticker from search results |
limit | integer | No | Maximum number of trades to return Default: 20 |
cursor | string | null | No | Pagination cursor from previous response |
Parameter schema (JSON)
{
"description": "Parameters for get_recent_trades tool.",
"properties": {
"ticker": {
"description": "Market ticker from search results",
"title": "Ticker",
"type": "string"
},
"limit": {
"default": 20,
"description": "Maximum number of trades to return",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from previous response",
"title": "Cursor"
}
},
"required": [
"ticker"
],
"title": "GetRecentTradesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"TradeSummary": {
"description": "Single trade record.",
"properties": {
"trade_id": {
"description": "Unique trade identifier",
"title": "Trade Id",
"type": "string"
},
"ticker": {
"description": "Market ticker",
"title": "Ticker",
"type": "string"
},
"price": {
"description": "Trade price (0.0-1.0)",
"title": "Price",
"type": "number"
},
"count": {
"default": 0,
"description": "Number of contracts",
"title": "Count",
"type": "integer"
},
"taker_side": {
"default": "",
"description": "Taker side: 'yes' or 'no'",
"title": "Taker Side",
"type": "string"
},
"created_time": {
"default": "",
"description": "Trade timestamp (ISO 8601)",
"title": "Created Time",
"type": "string"
}
},
"required": [
"trade_id",
"ticker",
"price"
],
"title": "TradeSummary",
"type": "object"
}
},
"description": "Result of get_recent_trades tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"trades": {
"description": "Recent trade records",
"items": {
"$ref": "#/$defs/TradeSummary"
},
"title": "Trades",
"type": "array"
},
"count": {
"default": 0,
"description": "Number of trades returned",
"title": "Count",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor for next page",
"title": "Cursor"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetRecentTradesResult",
"type": "object"
} # get_series read
Get metadata about a Kalshi series (a recurring event group).
Full description
Get information about a Kalshi series (recurring event group). Series represent repeating events (e.g., daily Bitcoin price markets). Returns series metadata including settlement sources and frequency.
| Parameter | Type | Required | Description |
|---|---|---|---|
series_ticker | string | Yes | Series ticker (e.g., 'KXBTC') from search or event results |
Parameter schema (JSON)
{
"description": "Parameters for get_series tool.",
"properties": {
"series_ticker": {
"description": "Series ticker (e.g., 'KXBTC') from search or event results",
"title": "Series Ticker",
"type": "string"
}
},
"required": [
"series_ticker"
],
"title": "GetSeriesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_series tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series ticker",
"title": "Series Ticker"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series title",
"title": "Title"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series category",
"title": "Category"
},
"frequency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "How often new events are created",
"title": "Frequency"
},
"settlement_sources": {
"description": "Data sources used for settlement",
"items": {
"type": "string"
},
"title": "Settlement Sources",
"type": "array"
},
"tags": {
"description": "Series tags",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "GetSeriesResult",
"type": "object"
} # get_user_permissions read
Check the user's Kalshi permissions and return the current access scopes.
Full description
Check user's Kalshi permissions. Phase 1 is read-only with no authentication required. Always returns success with empty scopes.
No parameters.
Parameter schema (JSON)
{
"description": "Parameters for get_user_permissions tool (no-auth stub).",
"properties": {},
"title": "GetUserPermissionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result of get_user_permissions tool.",
"properties": {
"success": {
"default": true,
"description": "Always true for no-auth toolkit",
"title": "Success",
"type": "boolean"
},
"scopes": {
"description": "Granted scopes (empty for no-auth)",
"items": {
"type": "string"
},
"title": "Scopes",
"type": "array"
}
},
"title": "GetUserPermissionsResult",
"type": "object"
} # list_categories read
List all available Kalshi event categories with event counts and volume.
Full description
List all available Kalshi event categories with event counts and volume. Returns categories sorted by total volume. Use category names with search_events(category=...) to filter by category.
No parameters.
Parameter schema (JSON)
{
"description": "Parameters for list_categories tool.",
"properties": {},
"title": "ListCategoriesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"CategorySummary": {
"description": "Summary of a single category.",
"properties": {
"category": {
"description": "Category name",
"title": "Category",
"type": "string"
},
"event_count": {
"default": 0,
"description": "Number of events with active markets",
"title": "Event Count",
"type": "integer"
},
"total_volume": {
"default": 0,
"description": "Total volume across all events",
"title": "Total Volume",
"type": "number"
}
},
"required": [
"category"
],
"title": "CategorySummary",
"type": "object"
}
},
"description": "Result of list_categories tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"categories": {
"description": "Categories sorted by total volume",
"items": {
"$ref": "#/$defs/CategorySummary"
},
"title": "Categories",
"type": "array"
},
"count": {
"default": 0,
"description": "Number of categories",
"title": "Count",
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "ListCategoriesResult",
"type": "object"
} # list_mover_categories read
List Kalshi categories available for get_movers filters.
Full description
List Kalshi market-data categories available for get_movers filters. Use these category names with get_movers(category=...) or get_movers(categories=[...]). This is distinct from list_categories, which is based on the Kalshi event cache.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | null | No | Filter to a single market-data status value. Defaults to 'active'. Pass an empty string to include all statuses. Default: "active" |
Parameter schema (JSON)
{
"description": "Parameters for list_mover_categories tool.",
"properties": {
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "active",
"description": "Filter to a single market-data status value. Defaults to 'active'. Pass an empty string to include all statuses.",
"title": "Status"
}
},
"title": "ListMoverCategoriesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"MoverCategorySummary": {
"description": "Category available for market-data mover filters.",
"properties": {
"category": {
"description": "Category name to pass to get_movers",
"title": "Category",
"type": "string"
},
"market_count": {
"default": 0,
"description": "Number of market metadata rows in this category",
"title": "Market Count",
"type": "integer"
}
},
"required": [
"category"
],
"title": "MoverCategorySummary",
"type": "object"
}
},
"description": "Result of list_mover_categories tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"categories": {
"description": "Mover categories sorted by market count",
"items": {
"$ref": "#/$defs/MoverCategorySummary"
},
"title": "Categories",
"type": "array"
},
"count": {
"default": 0,
"description": "Number of categories",
"title": "Count",
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "ListMoverCategoriesResult",
"type": "object"
} # search_events read
Search Kalshi prediction market events using keywords.
Full description
Search for Kalshi prediction market events using keywords.
Searches a cached index of ~4,000 open events using fuzzy text matching.
Returns events ranked by relevance and volume — no markets included.
Use get_event_details(event_ticker) to see an event's markets with live pricing.
WORKFLOW:
1. search_events("bitcoin") -> find events by topic
2. get_event_details(event_ticker) -> see markets with live prices
3. get_orderbook(ticker) or get_recent_trades(ticker) -> deep dive
Categories: Economics, Sports, Crypto, Elections, Politics, Entertainment,
Climate and Weather, Financials, Companies, Health, Science and Technology,
World, Transportation, Social, Mentions | Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Keywords to search for in event titles and subtitles. Uses fuzzy matching — typos and partial matches are handled. Truncated to 20 terms if longer. |
category | string | null | No | Filter by category (e.g., 'Economics', 'Sports', 'Crypto', 'Elections', 'Politics', 'Entertainment', 'Climate and Weather', 'Financials', 'Companies') |
series_ticker | string | null | No | Filter by series ticker (e.g., 'INX' for S&P 500, 'FED' for Fed funds rate, 'CPI' for CPI, 'KXBTC' for Bitcoin community markets) |
status | string | null | No | Filter by event status. Defaults to 'open' for active events. Default: "open" |
min_volume | number | null | No | Minimum total volume filter. Use to exclude zero-volume events. |
sort | "relevance" | "volume" | "open_interest" | "volume_24h" | null | No | Sort results by: 'relevance' (default), 'volume', 'open_interest', or 'volume_24h' |
ascending | boolean | No | Sort direction. Default false (highest first). Default: false |
offset | integer | No | Pagination offset. Use with limit to page through results. Default: 0 |
limit | integer | No | Maximum number of events to return Default: 20 |
Parameter schema (JSON)
{
"description": "Parameters for search_events tool.",
"properties": {
"query": {
"description": "Keywords to search for in event titles and subtitles. Uses fuzzy matching — typos and partial matches are handled. Truncated to 20 terms if longer.",
"title": "Query",
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by category (e.g., 'Economics', 'Sports', 'Crypto', 'Elections', 'Politics', 'Entertainment', 'Climate and Weather', 'Financials', 'Companies')",
"title": "Category"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by series ticker (e.g., 'INX' for S&P 500, 'FED' for Fed funds rate, 'CPI' for CPI, 'KXBTC' for Bitcoin community markets)",
"title": "Series Ticker"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "open",
"description": "Filter by event status. Defaults to 'open' for active events.",
"title": "Status"
},
"min_volume": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum total volume filter. Use to exclude zero-volume events.",
"title": "Min Volume"
},
"sort": {
"anyOf": [
{
"enum": [
"relevance",
"volume",
"open_interest",
"volume_24h"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort results by: 'relevance' (default), 'volume', 'open_interest', or 'volume_24h'",
"title": "Sort"
},
"ascending": {
"default": false,
"description": "Sort direction. Default false (highest first).",
"title": "Ascending",
"type": "boolean"
},
"offset": {
"default": 0,
"description": "Pagination offset. Use with limit to page through results.",
"minimum": 0,
"title": "Offset",
"type": "integer"
},
"limit": {
"default": 20,
"description": "Maximum number of events to return",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"query"
],
"title": "SearchEventsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"EventSearchResult": {
"description": "Event result from search_events — lightweight, no nested markets.",
"properties": {
"event_ticker": {
"description": "Event ticker (use with get_event_details for markets)",
"title": "Event Ticker",
"type": "string"
},
"title": {
"default": "",
"description": "Event title/question",
"title": "Title",
"type": "string"
},
"sub_title": {
"default": "",
"description": "Event subtitle with additional context",
"title": "Sub Title",
"type": "string"
},
"category": {
"default": "",
"description": "Event category",
"title": "Category",
"type": "string"
},
"series_ticker": {
"default": "",
"description": "Parent series ticker",
"title": "Series Ticker",
"type": "string"
},
"volume": {
"default": 0,
"description": "Total volume across all markets (cached)",
"title": "Volume",
"type": "number"
},
"volume_24h": {
"default": 0,
"description": "Volume in last 24 hours (cached)",
"title": "Volume 24H",
"type": "number"
},
"open_interest": {
"default": 0,
"description": "Total open interest (cached)",
"title": "Open Interest",
"type": "number"
},
"market_count": {
"default": 0,
"description": "Number of markets in this event",
"title": "Market Count",
"type": "integer"
}
},
"required": [
"event_ticker"
],
"title": "EventSearchResult",
"type": "object"
}
},
"description": "Result of search_events tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"events": {
"description": "Matching events sorted by relevance and volume",
"items": {
"$ref": "#/$defs/EventSearchResult"
},
"title": "Events",
"type": "array"
},
"count": {
"default": 0,
"description": "Number of events returned",
"title": "Count",
"type": "integer"
},
"total_count": {
"default": 0,
"description": "Total matching events before pagination",
"title": "Total Count",
"type": "integer"
},
"has_more": {
"default": false,
"description": "Whether more results exist beyond this page",
"title": "Has More",
"type": "boolean"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "SearchEventsResult",
"type": "object"
} # search_markets read
Search Kalshi markets by name, ticker, event, or candidate and return tickers for follow-up tools.
Full description
Search for Kalshi markets by ticker, candidate/name text, event title, or market description. This is the direct market-level resolver for workflows where an event search is too broad. Results include ticker and series_ticker so callers can chain directly into get_market_history, get_orderbook, or get_recent_trades.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Keywords, candidate name, event title, or ticker to search across Kalshi markets. Examples: 'Tucker Carlson', '2028 president', 'KXPRESPERSON-28-TCAR'. |
category | string | null | No | Optional event category filter, e.g. 'Elections' or 'Economics'. |
series_ticker | string | null | No | Optional series ticker filter, e.g. 'KXPRESPERSON'. |
status | string | null | No | Filter market status. Defaults to active live markets. Pass empty string for no status filter. 'open' also matches active markets. Default: "active" |
min_volume | number | null | No | Minimum total market volume. |
limit | integer | No | Maximum markets to return. Default: 10 |
event_limit | integer | No | Maximum matching events to expand while searching markets. Default: 25 |
Parameter schema (JSON)
{
"description": "Parameters for search_markets tool.",
"properties": {
"query": {
"description": "Keywords, candidate name, event title, or ticker to search across Kalshi markets. Examples: 'Tucker Carlson', '2028 president', 'KXPRESPERSON-28-TCAR'.",
"minLength": 1,
"title": "Query",
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional event category filter, e.g. 'Elections' or 'Economics'.",
"title": "Category"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional series ticker filter, e.g. 'KXPRESPERSON'.",
"title": "Series Ticker"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "active",
"description": "Filter market status. Defaults to active live markets. Pass empty string for no status filter. 'open' also matches active markets.",
"title": "Status"
},
"min_volume": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum total market volume.",
"title": "Min Volume"
},
"limit": {
"default": 10,
"description": "Maximum markets to return.",
"maximum": 50,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"event_limit": {
"default": 25,
"description": "Maximum matching events to expand while searching markets.",
"maximum": 50,
"minimum": 1,
"title": "Event Limit",
"type": "integer"
}
},
"required": [
"query"
],
"title": "SearchMarketsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"MarketSearchResult": {
"description": "Single market result from search_markets.",
"properties": {
"ticker": {
"description": "Kalshi market ticker",
"title": "Ticker",
"type": "string"
},
"title": {
"default": "",
"description": "Market title/question",
"title": "Title",
"type": "string"
},
"subtitle": {
"default": "",
"description": "Market subtitle",
"title": "Subtitle",
"type": "string"
},
"event_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Parent event ticker",
"title": "Event Ticker"
},
"event_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Parent event title",
"title": "Event Title"
},
"series_ticker": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Series ticker for history",
"title": "Series Ticker"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event category",
"title": "Category"
},
"yes_price": {
"default": 0,
"description": "Current Yes price",
"title": "Yes Price",
"type": "number"
},
"no_price": {
"default": 0,
"description": "Current No price",
"title": "No Price",
"type": "number"
},
"last_price": {
"default": 0,
"description": "Last traded price",
"title": "Last Price",
"type": "number"
},
"volume": {
"default": 0,
"description": "Total contracts traded",
"title": "Volume",
"type": "number"
},
"volume_24h": {
"default": 0,
"description": "Contracts traded in last 24 hours",
"title": "Volume 24H",
"type": "number"
},
"open_interest": {
"default": 0,
"description": "Currently open contracts",
"title": "Open Interest",
"type": "number"
},
"status": {
"default": "",
"description": "Market status",
"title": "Status",
"type": "string"
},
"market_open_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Market open/listing date when available (YYYY-MM-DD)",
"title": "Market Open Date"
}
},
"required": [
"ticker"
],
"title": "MarketSearchResult",
"type": "object"
}
},
"description": "Result of search_markets tool.",
"properties": {
"success": {
"description": "Whether the operation succeeded",
"title": "Success",
"type": "boolean"
},
"markets": {
"description": "Matching markets sorted by relevance and volume",
"items": {
"$ref": "#/$defs/MarketSearchResult"
},
"title": "Markets",
"type": "array"
},
"count": {
"default": 0,
"description": "Number of markets returned",
"title": "Count",
"type": "integer"
},
"searched_events": {
"default": 0,
"description": "Number of matching events expanded during search",
"title": "Searched Events",
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Error message if operation failed",
"title": "Error"
}
},
"required": [
"success"
],
"title": "SearchMarketsResult",
"type": "object"
}