openapi: 3.0.0
info:
title: Kalshi Trade API Manual Endpoints account events 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: events
description: Event endpoints
paths:
/series/{series_ticker}/events/{ticker}/candlesticks:
get:
operationId: GetMarketCandlesticksByEvent
summary: Get Event Candlesticks
description: ' End-point for returning aggregated data across all markets corresponding to an event.'
tags:
- events
parameters:
- name: ticker
in: path
required: true
description: The event ticker
schema:
type: string
- name: series_ticker
in: path
required: true
description: The series ticker
schema:
type: string
- name: start_ts
in: query
required: true
description: Start timestamp for the range
schema:
type: integer
format: int64
x-oapi-codegen-extra-tags:
validate: required
- name: end_ts
in: query
required: true
description: End timestamp for the range
schema:
type: integer
format: int64
x-oapi-codegen-extra-tags:
validate: required
- name: period_interval
in: query
required: true
description: Specifies the length of each candlestick period, in minutes. Must be one minute, one hour, or one day.
schema:
type: integer
format: int32
enum:
- 1
- 60
- 1440
x-oapi-codegen-extra-tags:
validate: required,oneof=1 60 1440
responses:
'200':
description: Event candlesticks retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventCandlesticksResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'500':
description: Internal server error
/events:
get:
operationId: GetEvents
summary: Get Events
description: 'Get all events. This endpoint excludes multivariate events.
To retrieve multivariate events, use the GET /events/multivariate endpoint.
All events are accessible through this endpoint, even if their associated markets are older than the historical cutoff.
'
tags:
- events
parameters:
- name: limit
in: query
required: false
description: Parameter to specify the number of results per page. Defaults to 200. Maximum value is 200.
schema:
type: integer
minimum: 1
maximum: 200
default: 200
- name: cursor
in: query
required: false
description: Parameter to specify the pagination cursor. Use the cursor value returned from the previous response to get the next page of results. Leave empty for the first page.
schema:
type: string
- name: with_nested_markets
in: query
required: false
description: Parameter to specify if nested markets should be included in the response. When true, each event will include a 'markets' field containing a list of Market objects associated with that event. Historical markets settled before the historical cutoff will not be included.
schema:
type: boolean
default: false
x-go-type-skip-optional-pointer: true
- name: with_milestones
in: query
required: false
description: If true, includes related milestones as a field alongside events.
schema:
type: boolean
default: false
x-go-type-skip-optional-pointer: true
- name: status
in: query
required: false
description: Filter by event status. Possible values are 'unopened', 'open', 'closed', 'settled'. Leave empty to return events with any status.
schema:
type: string
enum:
- unopened
- open
- closed
- settled
- $ref: '#/components/parameters/SeriesTickerQuery'
- name: min_close_ts
in: query
required: false
description: Filter events with at least one market with close timestamp greater than this Unix timestamp (in seconds).
schema:
type: integer
format: int64
- name: min_updated_ts
in: query
required: false
description: Filter events with metadata updated after this Unix timestamp (in seconds). Use this to efficiently poll for changes.
schema:
type: integer
format: int64
responses:
'200':
description: Events retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventsResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'500':
description: Internal server error
/events/multivariate:
get:
operationId: GetMultivariateEvents
summary: Get Multivariate Events
description: Retrieve multivariate (combo) events. These are dynamically created events from multivariate event collections. Supports filtering by series and collection ticker.
tags:
- events
parameters:
- name: limit
in: query
required: false
description: Number of results per page. Defaults to 100. Maximum value is 200.
schema:
type: integer
minimum: 1
maximum: 200
default: 100
- name: cursor
in: query
required: false
description: Pagination cursor. Use the cursor value returned from the previous response to get the next page of results.
schema:
type: string
- $ref: '#/components/parameters/SeriesTickerQuery'
- name: collection_ticker
in: query
required: false
description: Filter events by collection ticker. Returns only multivariate events belonging to the specified collection. Cannot be used together with series_ticker.
schema:
type: string
- name: with_nested_markets
in: query
required: false
description: Parameter to specify if nested markets should be included in the response. When true, each event will include a 'markets' field containing a list of Market objects associated with that event.
schema:
type: boolean
default: false
responses:
'200':
description: Multivariate events retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetMultivariateEventsResponse'
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized
'500':
description: Internal server error
/events/{event_ticker}:
get:
operationId: GetEvent
summary: Get Event
description: 'Endpoint for getting data about an event by its ticker. An event represents a real-world occurrence that can be traded on, such as an election, sports game, or economic indicator release.
Events contain one or more markets where users can place trades on different outcomes.
All events are accessible through this endpoint, even if their associated markets are older than the historical cutoff.
'
tags:
- events
parameters:
- name: event_ticker
in: path
required: true
description: Event ticker
schema:
type: string
- name: with_nested_markets
in: query
required: false
description: If true, markets are included within the event object. If false (default), markets are returned as a separate top-level field in the response. Historical markets settled before the historical cutoff will not be included.
schema:
type: boolean
default: false
x-go-type-skip-optional-pointer: true
responses:
'200':
description: Event retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventResponse'
'400':
description: Bad request
'404':
description: Event not found
'401':
description: Unauthorized
'500':
description: Internal server error
/events/{event_ticker}/metadata:
get:
operationId: GetEventMetadata
summary: Get Event Metadata
description: ' Endpoint for getting metadata about an event by its ticker. Returns only the metadata information for an event.'
tags:
- events
parameters:
- name: event_ticker
in: path
required: true
description: Event ticker
schema:
type: string
responses:
'200':
description: Event metadata retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventMetadataResponse'
'400':
description: Bad request
'404':
description: Event not found
'401':
description: Unauthorized
'500':
description: Internal server error
/series/{series_ticker}/events/{ticker}/forecast_percentile_history:
get:
operationId: GetEventForecastPercentilesHistory
summary: Get Event Forecast Percentile History
description: Endpoint for getting the historical raw and formatted forecast numbers for an event at specific percentiles.
tags:
- events
security:
- kalshiAccessKey: []
kalshiAccessSignature: []
kalshiAccessTimestamp: []
parameters:
- name: ticker
in: path
required: true
description: The event ticker
schema:
type: string
- name: series_ticker
in: path
required: true
description: The series ticker
schema:
type: string
- name: percentiles
in: query
required: true
description: Array of percentile values to retrieve (0-9999, max 10 values)
schema:
type: array
items:
type: integer
format: int32
minimum: 0
maximum: 9999
maxItems: 10
style: form
explode: true
- name: start_ts
in: query
required: true
description: Start timestamp for the range
schema:
type: integer
format: int64
- name: end_ts
in: query
required: true
description: End timestamp for the range
schema:
type: integer
format: int64
- name: period_interval
in: query
required: true
description: Specifies the length of each forecast period, in minutes. 0 for 5-second intervals, or 1, 60, or 1440 for minute-based intervals.
schema:
type: integer
format: int32
enum:
- 0
- 1
- 60
- 1440
responses:
'200':
description: Event forecast percentile history retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventForecastPercentilesHistoryResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'500':
description: Internal server error
components:
schemas:
EventData:
type: object
required:
- event_ticker
- series_ticker
- sub_title
- title
- collateral_return_type
- mutually_exclusive
- available_on_brokers
- product_metadata
properties:
event_ticker:
type: string
description: Unique identifier for this event.
series_ticker:
type: string
description: Unique identifier for the series this event belongs to.
sub_title:
type: string
description: Shortened descriptive title for the event.
title:
type: string
description: Full title of the event.
collateral_return_type:
type: string
description: Specifies how collateral is returned when markets settle (e.g., 'binary' for standard yes/no markets).
mutually_exclusive:
type: boolean
description: If true, only one market in this event can resolve to 'yes'. If false, multiple markets can resolve to 'yes'.
category:
type: string
description: Event category (deprecated, use series-level category instead).
deprecated: true
x-go-type-skip-optional-pointer: true
strike_date:
type: string
format: date-time
nullable: true
x-omitempty: true
description: The specific date this event is based on. Only filled when the event uses a date strike (mutually exclusive with strike_period).
strike_period:
type: string
nullable: true
x-omitempty: true
description: The time period this event covers (e.g., 'week', 'month'). Only filled when the event uses a period strike (mutually exclusive with strike_date).
markets:
type: array
x-omitempty: true
description: Array of markets associated with this event. Only populated when 'with_nested_markets=true' is specified in the request.
items:
$ref: '#/components/schemas/Market'
x-go-type-skip-optional-pointer: true
available_on_brokers:
type: boolean
description: Whether this event is available to trade on brokers.
product_metadata:
type: object
nullable: true
x-omitempty: true
description: Additional metadata for the event.
x-go-type-skip-optional-pointer: true
last_updated_ts:
type: string
format: date-time
description: Timestamp of when this event's metadata was last updated.
fee_type_override:
type: string
nullable: true
x-omitempty: true
description: Fee type override for this event. When present, takes precedence over the series-level fee for this event's markets.
fee_multiplier_override:
type: number
format: double
nullable: true
x-omitempty: true
description: Fee multiplier override for this event. Paired with fee_type_override.
exchange_index:
allOf:
- $ref: '#/components/schemas/ExchangeIndex'
x-go-type-skip-optional-pointer: true
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
GetEventMetadataResponse:
type: object
required:
- image_url
- settlement_sources
- market_details
properties:
image_url:
type: string
description: A path to an image that represents this event.
featured_image_url:
type: string
description: A path to an image that represents the image of the featured market.
market_details:
type: array
description: Metadata for the markets in this event.
items:
$ref: '#/components/schemas/MarketMetadata'
settlement_sources:
type: array
description: A list of settlement sources for this event.
items:
$ref: '#/components/schemas/SettlementSource'
competition:
type: string
nullable: true
x-omitempty: true
description: Event competition.
x-go-type-skip-optional-pointer: true
competition_scope:
type: string
nullable: true
x-omitempty: true
description: Event scope, based on the competition.
x-go-type-skip-optional-pointer: true
GetEventCandlesticksResponse:
type: object
required:
- market_tickers
- market_candlesticks
- adjusted_end_ts
properties:
market_tickers:
type: array
description: Array of market tickers in the event.
items:
type: string
market_candlesticks:
type: array
description: Array of market candlestick arrays, one for each market in the event.
items:
type: array
items:
$ref: '#/components/schemas/MarketCandlestick'
adjusted_end_ts:
type: integer
format: int64
description: Adjusted end timestamp if the requested candlesticks would be larger than maxAggregateCandidates.
GetEventForecastPercentilesHistoryResponse:
type: object
required:
- forecast_history
properties:
forecast_history:
type: array
description: Array of forecast percentile data points over time.
items:
$ref: '#/components/schemas/ForecastPercentilesPoint'
GetEventResponse:
type: object
required:
- event
- markets
properties:
event:
$ref: '#/components/schemas/EventData'
description: Data for the event.
markets:
type: array
description: Data for the markets in this event. This field is deprecated in favour of the "markets" field inside the event. Which will be filled with the same value if you use the query parameter "with_nested_markets=true".
items:
$ref: '#/components/schemas/Market'
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).
Milestone:
type: object
required:
- id
- category
- type
- start_date
- related_event_tickers
- title
- notification_message
- details
- primary_event_tickers
- last_updated_ts
properties:
id:
type: string
description: Unique identifier for the milestone.
category:
type: string
description: Category of the milestone. E.g. Sports, Elections, Esports, Crypto.
example: Sports
type:
type: string
description: Type of the milestone. E.g. football_game, basketball_game, soccer_tournament_multi_leg, baseball_game, hockey_match, golf_tournament, political_race.
example: football_game
start_date:
type: string
format: date-time
description: Start date of the milestone.
end_date:
type: string
format: date-time
nullable: true
description: End date of the milestone, if any.
related_event_tickers:
type: array
items:
type: string
description: List of event tickers related to this milestone.
title:
type: string
description: Title of the milestone.
notification_message:
type: string
description: Notification message for the milestone.
source_id:
type: string
nullable: true
description: Source id of milestone if available.
source_ids:
type: object
additionalProperties:
type: string
description: Source ids of milestone if available.
details:
type: object
additionalProperties: true
description: Additional details about the milestone.
primary_event_tickers:
type: array
items:
type: string
description: List of event tickers directly related to the outcome of this milestone.
last_updated_ts:
type: string
format: date-time
description: Last time this structured target was updated.
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
PercentilePoint:
type: object
required:
- percentile
- raw_numerical_forecast
- numerical_forecast
- formatted_forecast
properties:
percentile:
type: integer
format: int32
description: The percentile value (0-9999).
raw_numerical_forecast:
type: number
description: The raw numerical forecast value.
numerical_forecast:
type: number
description: The processed numerical forecast value.
formatted_forecast:
type: string
description: The human-readable formatted forecast value.
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).
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 number of contracts bought on this market disconsidering netting
notional_value_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: The total value of a single contract at settlement in dollars
previous_yes_bid_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the highest YES buy offer on this market a day ago in dollars
previous_yes_ask_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the lowest YES sell offer on this market a day ago in dollars
previous_price_dollars:
$ref: '#/components/schemas/FixedPointDollars'
description: Price for the last traded YES contract on this market a day ago in dollars
liquidity_dollars:
$ref: '#/components/schemas/FixedPointDollars'
deprecated: true
description: 'DEPRECATED: This field is deprecated and will always return "0.0000".'
settlement_value_dollars:
$ref: '#/components/schemas/FixedPointDollars'
nullable: true
x-omitempty: true
description: The settlement value of the YES/LONG side of the contract in dollars. Only filled after determination
settlement_ts:
type: string
format: date-time
nullable: true
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kalshi/refs/heads/main/openapi/kalshi-events-api-openapi.yml