Kalshi market API
The market API from Kalshi — 9 operation(s) for market.
The market API from Kalshi — 9 operation(s) for market.
openapi: 3.0.0
info:
title: Kalshi Trade API Manual Endpoints account market API
version: 3.19.0
description: Manually defined OpenAPI spec for endpoints being migrated to spec-first approach
servers:
- url: https://external-api.kalshi.com/trade-api/v2
description: Production Trade API server
- url: https://api.elections.kalshi.com/trade-api/v2
description: Production shared API server, also supported
- url: https://external-api.demo.kalshi.co/trade-api/v2
description: Demo Trade API server
- url: https://demo-api.kalshi.co/trade-api/v2
description: Demo shared API server, also supported
tags:
- name: market
paths:
/series/{series_ticker}/markets/{ticker}/candlesticks:
get:
operationId: GetMarketCandlesticks
summary: Get Market Candlesticks
description: 'Time period length of each candlestick in minutes. Valid values: 1 (1 minute), 60 (1 hour), 1440 (1 day).
Candlesticks for markets that settled before the historical cutoff are only available via `GET /historical/markets/{ticker}/candlesticks`. See [Historical Data](https://docs.kalshi.com/getting_started/historical_data) for details.
'
tags:
- market
parameters:
- name: series_ticker
in: path
required: true
description: Series ticker - the series that contains the target market
schema:
type: string
- name: ticker
in: path
required: true
description: Market ticker - unique identifier for the specific market
schema:
type: string
- name: start_ts
in: query
required: true
description: Start timestamp (Unix timestamp). Candlesticks will include those ending on or after this time.
schema:
type: integer
format: int64
- name: end_ts
in: query
required: true
description: End timestamp (Unix timestamp). Candlesticks will include those ending on or before this time.
schema:
type: integer
format: int64
- name: period_interval
in: query
required: true
description: Time period length of each candlestick in minutes. Valid values are 1 (1 minute), 60 (1 hour), or 1440 (1 day).
schema:
type: integer
enum:
- 1
- 60
- 1440
x-oapi-codegen-extra-tags:
validate: required,oneof=1 60 1440
- name: include_latest_before_start
in: query
required: false
description: 'If true, prepends the latest candlestick available before the start_ts. This synthetic candlestick is created by:
1. Finding the most recent real candlestick before start_ts
2. Projecting it forward to the first period boundary (calculated as the next period interval after start_ts)
3. Setting all OHLC prices to null, and `previous_price` to the close price from the real candlestick
'
schema:
type: boolean
default: false
responses:
'200':
description: Candlesticks retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketCandlesticksResponse'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal server error
/markets/trades:
get:
operationId: GetTrades
summary: Get Trades
description: 'Endpoint for getting all trades for all markets. A trade represents a completed transaction between two users on a specific market. Each trade includes the market ticker, price, quantity, and timestamp information. This endpoint returns a paginated response. Use the ''limit'' parameter to control page size (1-1000, defaults to 100). The response includes a ''cursor'' field - pass this value in the ''cursor'' parameter of your next request to get the next page. An empty cursor indicates no more pages are available.
'
tags:
- market
parameters:
- $ref: '#/components/parameters/MarketLimitQuery'
- $ref: '#/components/parameters/CursorQuery'
- $ref: '#/components/parameters/TickerQuery'
- $ref: '#/components/parameters/MinTsQuery'
- $ref: '#/components/parameters/MaxTsQuery'
responses:
'200':
description: Trades retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetTradesResponse'
'400':
description: Bad request
'500':
description: Internal server error
/markets/{ticker}/orderbook:
get:
operationId: GetMarketOrderbook
summary: Get Market Orderbook
description: ' Endpoint for getting the current order book for a specific market. The order book shows all active bid orders for both yes and no sides of a binary market. It returns yes bids and no bids only (no asks are returned). This is because in binary markets, a bid for yes at price X is equivalent to an ask for no at price (100-X). For example, a yes bid at 7¢ is the same as a no ask at 93¢, with identical contract sizes. Each side shows price levels with their corresponding quantities and order counts, organized from best to worst prices.'
tags:
- market
security:
- kalshiAccessKey: []
kalshiAccessSignature: []
kalshiAccessTimestamp: []
parameters:
- $ref: '#/components/parameters/TickerPath'
- name: depth
in: query
description: Depth of the orderbook to retrieve (0 or negative means all levels, 1-100 for specific depth)
required: false
schema:
type: integer
minimum: 0
maximum: 100
default: 0
x-oapi-codegen-extra-tags:
validate: omitempty,min=0,max=100
responses:
'200':
description: Orderbook retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketOrderbookResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
/markets/orderbooks:
get:
operationId: GetMarketOrderbooks
summary: Get Multiple Market Orderbooks
description: Endpoint for getting the current order books for multiple markets in a single request. The order book shows all active bid orders for both yes and no sides of a binary market. It returns yes bids and no bids only (no asks are returned). This is because in binary markets, a bid for yes at price X is equivalent to an ask for no at price (100-X). For example, a yes bid at 7¢ is the same as a no ask at 93¢, with identical contract sizes. Each side shows price levels with their corresponding quantities and order counts, organized from best to worst prices. Returns one orderbook per requested market ticker.
tags:
- market
security:
- kalshiAccessKey: []
kalshiAccessSignature: []
kalshiAccessTimestamp: []
parameters:
- name: tickers
in: query
required: true
description: List of market tickers to fetch orderbooks for
schema:
type: array
items:
type: string
maxLength: 200
minItems: 1
maxItems: 100
style: form
explode: true
x-oapi-codegen-extra-tags:
validate: required,min=1,max=100,dive,max=200
responses:
'200':
description: Orderbooks retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketOrderbooksResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/InternalServerError'
/series/{series_ticker}:
get:
operationId: GetSeries
summary: Get Series
description: ' Endpoint for getting data about a specific series by its ticker. A series represents a template for recurring events that follow the same format and rules (e.g., "Monthly Jobs Report", "Weekly Initial Jobless Claims", "Daily Weather in NYC"). Series define the structure, settlement sources, and metadata that will be applied to each recurring event instance within that series.'
tags:
- market
parameters:
- name: series_ticker
in: path
required: true
schema:
type: string
description: The ticker of the series to retrieve
- name: include_volume
in: query
required: false
schema:
type: boolean
default: false
x-go-type-skip-optional-pointer: true
description: If true, includes the total volume traded across all events in this series.
responses:
'200':
description: Series retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetSeriesResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/InternalServerError'
/series:
get:
operationId: GetSeriesList
summary: Get Series List
description: ' Endpoint for getting data about multiple series with specified filters. A series represents a template for recurring events that follow the same format and rules (e.g., "Monthly Jobs Report", "Weekly Initial Jobless Claims", "Daily Weather in NYC"). This endpoint allows you to browse and discover available series templates by category.'
tags:
- market
parameters:
- name: category
in: query
required: false
schema:
type: string
x-go-type-skip-optional-pointer: true
- name: tags
in: query
required: false
schema:
type: string
x-go-type-skip-optional-pointer: true
- name: include_product_metadata
in: query
required: false
schema:
type: boolean
default: false
x-go-type-skip-optional-pointer: true
- name: include_volume
in: query
required: false
schema:
type: boolean
default: false
x-go-type-skip-optional-pointer: true
description: If true, includes the total volume traded across all events in each series.
- name: min_updated_ts
in: query
required: false
description: Filter series with metadata updated after this Unix timestamp (in seconds). Use this to efficiently poll for changes.
schema:
type: integer
format: int64
responses:
'200':
description: Series list retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetSeriesListResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/InternalServerError'
/markets:
get:
operationId: GetMarkets
summary: Get Markets
description: "Filter by market status. Possible values: `unopened`, `open`, `closed`, `settled`. Leave empty to return markets with any status.\n - Only one `status` filter may be supplied at a time.\n - Timestamp filters will be mutually exclusive from other timestamp filters and certain status filters.\n\n | Compatible Timestamp Filters | Additional Status Filters| Extra Notes |\n |------------------------------|--------------------------|-------------|\n | min_created_ts, max_created_ts | `unopened`, `open`, *empty* | |\n | min_close_ts, max_close_ts | `closed`, *empty* | |\n | min_settled_ts, max_settled_ts | `settled`, *empty* | |\n | min_updated_ts | *empty* | Incompatible with all filters besides `mve_filter=exclude` |\n\n Markets that settled before the historical cutoff are only available via `GET /historical/markets`. See [Historical Data](https://docs.kalshi.com/getting_started/historical_data) for details.\n"
tags:
- market
parameters:
- $ref: '#/components/parameters/MarketLimitQuery'
- $ref: '#/components/parameters/CursorQuery'
- $ref: '#/components/parameters/SingleEventTickerQuery'
- $ref: '#/components/parameters/SeriesTickerQuery'
- $ref: '#/components/parameters/MinCreatedTsQuery'
- $ref: '#/components/parameters/MaxCreatedTsQuery'
- $ref: '#/components/parameters/MinUpdatedTsQuery'
- $ref: '#/components/parameters/MaxCloseTsQuery'
- $ref: '#/components/parameters/MinCloseTsQuery'
- $ref: '#/components/parameters/MinSettledTsQuery'
- $ref: '#/components/parameters/MaxSettledTsQuery'
- $ref: '#/components/parameters/MarketStatusQuery'
- $ref: '#/components/parameters/TickersQuery'
- $ref: '#/components/parameters/MveFilterQuery'
responses:
'200':
description: Markets retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketsResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'500':
description: Internal server error
/markets/{ticker}:
get:
operationId: GetMarket
summary: Get Market
description: ' Endpoint for getting data about a specific market by its ticker. A market represents a specific binary outcome within an event that users can trade on (e.g., "Will candidate X win?"). Markets have yes/no positions, current prices, volume, and settlement rules.'
tags:
- market
parameters:
- $ref: '#/components/parameters/TickerPath'
responses:
'200':
description: Market retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketResponse'
'401':
description: Unauthorized
'404':
description: Not found
'500':
description: Internal server error
/markets/candlesticks:
get:
operationId: BatchGetMarketCandlesticks
summary: Batch Get Market Candlesticks
description: 'Endpoint for retrieving candlestick data for multiple markets.
- Accepts up to 100 market tickers per request
- Returns up to 10,000 candlesticks total across all markets
- Returns candlesticks grouped by market_id
- Optionally includes a synthetic initial candlestick for price continuity (see `include_latest_before_start` parameter)
'
tags:
- market
parameters:
- name: market_tickers
in: query
required: true
description: Comma-separated list of market tickers (maximum 100)
schema:
type: string
- name: start_ts
in: query
required: true
description: Start timestamp in Unix seconds
schema:
type: integer
format: int64
- name: end_ts
in: query
required: true
description: End timestamp in Unix seconds
schema:
type: integer
format: int64
- name: period_interval
in: query
required: true
description: Candlestick period interval in minutes
schema:
type: integer
format: int32
minimum: 1
- name: include_latest_before_start
in: query
required: false
description: 'If true, prepends the latest candlestick available before the start_ts. This synthetic candlestick is created by:
1. Finding the most recent real candlestick before start_ts
2. Projecting it forward to the first period boundary (calculated as the next period interval after start_ts)
3. Setting all OHLC prices to null, and `previous_price` to the close price from the real candlestick
'
schema:
type: boolean
default: false
responses:
'200':
description: Market candlesticks retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGetMarketCandlesticksResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'500':
description: Internal server error
components:
responses:
UnauthorizedError:
description: Unauthorized - authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFoundError:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequestError:
description: Bad request - invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
MarketCandlesticksResponse:
type: object
required:
- market_ticker
- candlesticks
properties:
market_ticker:
type: string
description: Market ticker string (e.g., 'INXD-24JAN01').
candlesticks:
type: array
description: Array of candlestick data points for the market. Includes an initial data point at the start timestamp when available.
items:
$ref: '#/components/schemas/MarketCandlestick'
GetMarketCandlesticksResponse:
type: object
required:
- ticker
- candlesticks
properties:
ticker:
type: string
description: Unique identifier for the market.
candlesticks:
type: array
description: Array of candlestick data points for the specified time range.
items:
$ref: '#/components/schemas/MarketCandlestick'
PriceRange:
type: object
required:
- start
- end
- step
properties:
start:
type: string
description: Starting price for this range in dollars
end:
type: string
description: Ending price for this range in dollars
step:
type: string
description: Price step/tick size for this range in dollars
Trade:
type: object
required:
- trade_id
- ticker
- count_fp
- yes_price_dollars
- no_price_dollars
- taker_side
- taker_outcome_side
- taker_book_side
- created_time
properties:
trade_id:
type: string
description: Unique identifier for this trade
ticker:
type: string
description: Unique identifier for the market
count_fp:
$ref: '#/components/schemas/FixedPointCount'
description: String representation of the number of contracts bought or sold in this trade
yes_price_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Yes price for this trade in dollars
no_price_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: No price for this trade in dollars
taker_side:
type: string
enum:
- 'yes'
- 'no'
x-enum-varnames:
- TradeTakerSideYes
- TradeTakerSideNo
deprecated: true
description: 'Deprecated. Use `taker_outcome_side` (or `taker_book_side`) instead. See [Order direction](/getting_started/order_direction). This field will not be removed before May 14, 2026.
'
taker_outcome_side:
type: string
enum:
- 'yes'
- 'no'
x-enum-varnames:
- TradeTakerOutcomeSideYes
- TradeTakerOutcomeSideNo
description: 'The outcome side the taker is positioned for. buy-yes and sell-no produce ''yes''; buy-no and sell-yes produce ''no''.
`taker_outcome_side` describes directional exposure only; it does not change the trade''s price. A trade at price `p` with `taker_outcome_side=no` is matched against the maker at the same price `p` with the opposite direction — both parties trade at the same price.
`taker_outcome_side` and `taker_book_side` will become the canonical way to determine trade direction. The legacy `taker_side` field will be deprecated in a future release — please migrate to these new fields.
'
taker_book_side:
$ref: '#/components/schemas/BookSide'
description: 'Same directional bit as taker_outcome_side in book vocabulary. ''bid'' is equivalent to taker_outcome_side ''yes''; ''ask'' is equivalent to taker_outcome_side ''no''.
`taker_outcome_side` and `taker_book_side` will become the canonical way to determine trade direction. The legacy `taker_side` field will be deprecated in a future release — please migrate to these new fields.
'
created_time:
type: string
format: date-time
description: Timestamp when this trade was executed
GetMarketsResponse:
type: object
required:
- markets
- cursor
properties:
markets:
type: array
items:
$ref: '#/components/schemas/Market'
cursor:
type: string
MarketCandlestick:
type: object
required:
- end_period_ts
- yes_bid
- yes_ask
- price
- volume_fp
- open_interest_fp
properties:
end_period_ts:
type: integer
format: int64
description: Unix timestamp for the inclusive end of the candlestick period.
yes_bid:
$ref: '#/components/schemas/BidAskDistribution'
description: Open, high, low, close (OHLC) data for YES buy offers on the market during the candlestick period.
yes_ask:
$ref: '#/components/schemas/BidAskDistribution'
description: Open, high, low, close (OHLC) data for YES sell offers on the market during the candlestick period.
price:
$ref: '#/components/schemas/PriceDistribution'
description: Open, high, low, close (OHLC) and more data for trade YES contract prices on the market during the candlestick period.
volume_fp:
$ref: '#/components/schemas/FixedPointCount'
description: String representation of the number of contracts bought on the market during the candlestick period.
open_interest_fp:
$ref: '#/components/schemas/FixedPointCount'
description: String representation of the number of contracts bought on the market by end of the candlestick period (end_period_ts).
BidAskDistribution:
type: object
required:
- open_dollars
- low_dollars
- high_dollars
- close_dollars
properties:
open_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Offer price on the market at the start of the candlestick period (in dollars).
low_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Lowest offer price on the market during the candlestick period (in dollars).
high_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Highest offer price on the market during the candlestick period (in dollars).
close_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Offer price on the market at the end of the candlestick period (in dollars).
ExchangeIndex:
type: integer
description: 'Identifier for an exchange shard. Defaults to 0 if unspecified. Note: currently only 0 supported.'
example: 0
MarketOrderbookFp:
type: object
required:
- ticker
- orderbook_fp
properties:
ticker:
type: string
orderbook_fp:
$ref: '#/components/schemas/OrderbookCountFp'
ErrorResponse:
type: object
properties:
code:
type: string
description: Error code
message:
type: string
description: Human-readable error message
details:
type: string
description: Additional details about the error, if available
service:
type: string
description: The name of the service that generated the error
PriceDistribution:
type: object
properties:
open_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: First traded YES contract price on the market during the candlestick period (in dollars). May be null if there was no trade during the period.
low_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Lowest traded YES contract price on the market during the candlestick period (in dollars). May be null if there was no trade during the period.
high_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Highest traded YES contract price on the market during the candlestick period (in dollars). May be null if there was no trade during the period.
close_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Last traded YES contract price on the market during the candlestick period (in dollars). May be null if there was no trade during the period.
mean_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Mean traded YES contract price on the market during the candlestick period (in dollars). May be null if there was no trade during the period.
previous_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Last traded YES contract price on the market before the candlestick period (in dollars). May be null if there were no trades before the period.
min_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Minimum close price of any market during the candlestick period (in dollars).
max_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
description: Maximum close price of any market during the candlestick period (in dollars).
GetTradesResponse:
type: object
required:
- trades
- cursor
properties:
trades:
type: array
items:
$ref: '#/components/schemas/Trade'
cursor:
type: string
Market:
type: object
required:
- ticker
- event_ticker
- market_type
- yes_sub_title
- no_sub_title
- created_time
- updated_time
- open_time
- close_time
- latest_expiration_time
- settlement_timer_seconds
- status
- notional_value_dollars
- yes_bid_dollars
- yes_ask_dollars
- no_bid_dollars
- no_ask_dollars
- yes_bid_size_fp
- yes_ask_size_fp
- last_price_dollars
- previous_yes_bid_dollars
- previous_yes_ask_dollars
- previous_price_dollars
- volume_fp
- volume_24h_fp
- liquidity_dollars
- open_interest_fp
- result
- can_close_early
- fractional_trading_enabled
- expiration_value
- rules_primary
- rules_secondary
- price_level_structure
- price_ranges
properties:
ticker:
type: string
event_ticker:
type: string
market_type:
type: string
enum:
- binary
- scalar
description: Identifies the type of market
title:
type: string
deprecated: true
x-go-type-skip-optional-pointer: true
subtitle:
type: string
deprecated: true
x-go-type-skip-optional-pointer: true
yes_sub_title:
type: string
description: Shortened title for the yes side of this market
no_sub_title:
type: string
description: Shortened title for the no side of this market
created_time:
type: string
format: date-time
updated_time:
type: string
format: date-time
description: Time of the last non-trading metadata update.
open_time:
type: string
format: date-time
close_time:
type: string
format: date-time
expected_expiration_time:
type: string
format: date-time
nullable: true
x-omitempty: true
description: Time when this market is expected to expire
expiration_time:
type: string
format: date-time
deprecated: true
x-go-type-skip-optional-pointer: true
latest_expiration_time:
type: string
format: date-time
description: Latest possible time for this market to expire
settlement_timer_seconds:
type: integer
description: The amount of time after determination that the market settles
status:
type: string
enum:
- initialized
- inactive
- active
- closed
- determined
- disputed
- amended
- finalized
description: The current status of the market in its lifecycle.
response_price_units:
type: string
enum:
- usd_cent
deprecated: true
description: 'DEPRECATED: Use price_level_structure and price_ranges instead.'
x-go-type-skip-optional-pointer: true
yes_bid_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the highest YES buy offer on this market in dollars
yes_bid_size_fp:
$ref: '#/components/schemas/FixedPointCount'
description: Total contract size of orders to buy YES at the best bid price (fixed-point count string).
yes_ask_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the lowest YES sell offer on this market in dollars
yes_ask_size_fp:
$ref: '#/components/schemas/FixedPointCount'
description: Total contract size of orders to sell YES at the best ask price (fixed-point count string).
no_bid_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the highest NO buy offer on this market in dollars
no_ask_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the lowest NO sell offer on this market in dollars
last_price_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the last traded YES contract on this market in dollars
volume_fp:
$ref: '#/components/schemas/FixedPointCount'
description: String representation of the market volume in contracts
volume_24h_fp:
$ref: '#/components/schemas/FixedPointCount'
description: String representation of the 24h market volume in contracts
result:
type: string
enum:
- 'yes'
- 'no'
- scalar
- ''
can_close_early:
type: boolean
fractional_trading_enabled:
type: boolean
deprecated: true
description: Deprecated. This flag is always `true` and carries no information. Will be removed after a pre-announcement with the removal date.
open_interest_fp:
$ref: '#/components/schemas/FixedPointCount'
description: String representation of the num
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kalshi/refs/heads/main/openapi/kalshi-market-api-openapi.yml