Kalshi events API

openapi: 3.2.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:
    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
          - 'null'
          format: date-time
          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'
          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
          - 'null'
          format: date-time
          x-omitempty: true
          description: Timestamp when the market was settled. Only filled for settled markets
        expiration_value:
          type: string
          description: The value that was considered for the settlement
        occurrence_datetime:
          type:
          - string
          - 'null'
          format: date-time
          description: The recorded datetime when the underlying event occurred, if available
        fee_waiver_expiration_time:
          type:
          - string
          - 'null'
          format: date-time
          x-omitempty: true
          description: Time when this market's fee waiver expires
        early_close_condition:
          type:
          - string
          - 'null'
          x-omitempty: true
          description: The condition under which the market can close early
          x-go-type-skip-optional-pointer: true
        strike_type:
          type: string
          enum:
          - greater
          - greater_or_equal
          - less
          - less_or_equal
          - between
          - functional
          - custom
          - structured
          x-omitempty: true
          description: Strike type defines how the market strike is defined and evaluated
          x-go-type-skip-optional-pointer: true
        floor_strike:
          type:
          - number
          - 'null'
          format: double
          x-omitempty: true
          description: Minimum expiration value that leads to a YES settlement
        cap_strike:
          type:
          - number
          - 'null'
          format: double
          x-omitempty: true
          description: Maximum expiration value that leads to a YES settlement
        functional_strike:
          type:
          - string
          - 'null'
          x-omitempty: true
          description: Mapping from expiration values to settlement values
        custom_strike:
          type:
          - object
          - 'null'
          x-omitempty: true
          description: Expiration value for each target that leads to a YES settlement
        rules_primary:
          type: string
          description: A plain language description of the most important market terms
        rules_secondary:
          type: string
          description: A plain language description of secondary market terms
        mve_collection_ticker:
          type: string
          x-omitempty: true
          description: The ticker of the multivariate event collection
          x-go-type-skip-optional-pointer: true
        mve_selected_legs:
          type: array
          x-omitempty: true
          items:
            $ref: '#/components/schemas/MveSelectedLeg'
          x-go-type-skip-optional-pointer: true
        primary_participant_key:
          type:
          - string
          - 'null'
          x-omitempty: true
        price_level_structure:
          type: string
          description: Price level structure for this market, defining price ranges and tick sizes
        price_ranges:
          type: array
          description: Valid price ranges for orders on this market
          items:
            $ref: '#/components/schemas/PriceRange'
        is_provisional:
          type: boolean
          x-omitempty: true
          description: If true, the market may be removed after determination if there is no activity on it
          x-go-type-skip-optional-pointer: true
        exchange_index:
          allOf:
          - $ref: '#/components/schemas/ExchangeIndex'
          x-go-type-skip-optional-pointer: true
    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'
    GetEventsResponse:
      type: object
      required:
      - events
      - cursor
      properties:
        events:
          type: array
          description: Array of events matching the query criteria.
          items:
            $ref: '#/components/schemas/EventData'
        milestones:
          type: array
          description: Array of milestones related to the events.
          items:
            $ref: '#/components/schemas/Milestone'
        cursor:
          type: string
          description: Pagination cursor for the next page. Empty if there are no more results.
    MarketMetadata:
      type: object
      required:
      - market_ticker
      - image_url
      - color_code
      properties:
        market_ticker:
          type: string
          description: The ticker of the market.
        image_url:
          type: string
          description: A path to an image that represents this market.
        color_code:
          type: string
          description: The color code for the 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).
    FixedPointDollars:
      type: string
      description: US dollar amount as a fixed-point decimal string with up to 6 decimal places of precision. This is the maximum supported precision; valid quote intervals for a given market are constrained by that market's price level structure.
      example: '0.5600'
    ForecastPercentilesPoint:
      type: object
      required:
      - event_ticker
      - end_period_ts
      - period_interval
      - percentile_points
      properties:
        event_ticker:
          type: string
          description: The event ticker this forecast is for.
        end_period_ts:
          type: integer
          format: int64
          description: Unix timestamp for the inclusive end of the forecast period.
        period_interval:
          type: integer
          format: int32
          description: Length of the forecast period in minutes.
        percentile_points:
          type: array
          description: Array of forecast values at different percentiles.
          items:
            $ref: '#/components/schemas/PercentilePoint'
    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.
    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).
    GetMultivariateEventsResponse:
      type: object
      required:
      - events
      - cursor
      properties:
        events:
          type: array
          description: Array of multivariate events matching the query criteria.
          items:
            $ref: '#/components/schemas/EventData'
        cursor:
          type: string
          description: Pagination cursor for the next page. Empty if there are no more results.
    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'
    FixedPointCount:
      type: string
      description: Fixed-point contract count string (2 decimals, e.g., "10.00"; referred to as "fp" in field names). Requests accept 0–2 decimal places (e.g., "10", "10.0", "10.00"); responses always emit 2 decimals. Fractional contract values (e.g., "2.50") are supported on markets with fractional trading enabled; the minimum granularity is 0.01 contracts. Integer contract count fields are legacy and will be deprecated; when both integer and fp fields are provided, they must match.
      example: '10.00'
    PriceDistribution:
      type: object
      properties:
        open_dollars:
          $ref: '#/components/schemas/FixedPointDollars'
          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'
          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'
          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'
          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'
          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'
          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'
          description: Minimum close price of any market during the candlestick period (in dollars).
        max_dollars:
          $ref: '#/components/schemas/FixedPointDollars'
          description: Maximum close price of any market during the candlestick period (in dollars).
    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.
    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:

# --- 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