openapi: 3.0.0
info:
  title: Kalshi Trade API Manual Endpoints account multivariate 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: multivariate
  description: Multivariate event collection endpoints
paths:
  /multivariate_event_collections/{collection_ticker}:
    get:
      operationId: GetMultivariateEventCollection
      summary: Get Multivariate Event Collection
      description: ' Endpoint for getting data about a multivariate event collection by its ticker.'
      tags:
      - multivariate
      parameters:
      - name: collection_ticker
        in: path
        required: true
        description: Collection ticker
        schema:
          type: string
      responses:
        '200':
          description: Collection retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMultivariateEventCollectionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: CreateMarketInMultivariateEventCollection
      summary: Create Market In Multivariate Event Collection
      description: Endpoint for creating an individual market in a multivariate event collection. This endpoint must be hit at least once before trading or looking up a market. Users are limited to 5000 creations per week.
      tags:
      - multivariate
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      parameters:
      - name: collection_ticker
        in: path
        required: true
        description: Collection ticker
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMarketInMultivariateEventCollectionRequest'
      responses:
        '200':
          description: Market created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMarketInMultivariateEventCollectionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /multivariate_event_collections:
    get:
      operationId: GetMultivariateEventCollections
      summary: Get Multivariate Event Collections
      description: ' Endpoint for getting data about multivariate event collections.'
      tags:
      - multivariate
      parameters:
      - name: status
        in: query
        description: Only return collections of a certain status. Can be unopened, open, or closed.
        schema:
          type: string
          enum:
          - unopened
          - open
          - closed
      - name: associated_event_ticker
        in: query
        description: Only return collections associated with a particular event ticker.
        schema:
          type: string
      - name: series_ticker
        in: query
        description: Only return collections with a particular series ticker.
        schema:
          type: string
      - name: limit
        in: query
        description: Specify the maximum number of results.
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 200
      - name: cursor
        in: query
        description: The Cursor represents a pointer to the next page of records in the pagination. This optional parameter, when filled, should be filled with the cursor string returned in a previous request to this end-point.
        schema:
          type: string
      responses:
        '200':
          description: Collections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMultivariateEventCollectionsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /multivariate_event_collections/{collection_ticker}/lookup:
    put:
      operationId: LookupTickersForMarketInMultivariateEventCollection
      summary: Lookup Tickers For Market In Multivariate Event Collection
      deprecated: true
      description: 'DEPRECATED: This endpoint predates RFQs and should not be used for new integrations. Endpoint for looking up an individual market in a multivariate event collection. If CreateMarketInMultivariateEventCollection has never been hit with that variable combination before, this will return a 404.'
      x-mint:
        content: '<Warning>

          This endpoint is deprecated and predates RFQs. Do not use it for new integrations.

          </Warning>


          <Note>

          **Rate limit:** 2 tokens per request. Other endpoints use the default cost of 10 tokens per request unless noted on their own page. See [Rate Limits and Tiers](/getting_started/rate_limits).

          </Note>

          '
      tags:
      - multivariate
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      parameters:
      - name: collection_ticker
        in: path
        required: true
        description: Collection ticker
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupTickersForMarketInMultivariateEventCollectionRequest'
      responses:
        '200':
          description: Market looked up successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupTickersForMarketInMultivariateEventCollectionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: GetMultivariateEventCollectionLookupHistory
      summary: Get Multivariate Event Collection Lookup History
      deprecated: true
      description: 'DEPRECATED: This endpoint predates RFQs and should not be used for new integrations. Endpoint for retrieving which markets in an event collection were recently looked up.'
      x-mint:
        content: '<Warning>

          This endpoint is deprecated and predates RFQs. Do not use it for new integrations.

          </Warning>

          '
      tags:
      - multivariate
      parameters:
      - name: collection_ticker
        in: path
        required: true
        description: Collection ticker
        schema:
          type: string
      - name: lookback_seconds
        in: query
        required: true
        description: Number of seconds to look back for lookup history. Must be one of 10, 60, 300, or 3600.
        schema:
          type: integer
          format: int32
          enum:
          - 10
          - 60
          - 300
          - 3600
      responses:
        '200':
          description: Lookup history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMultivariateEventCollectionLookupHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    GetMultivariateEventCollectionResponse:
      type: object
      required:
      - multivariate_contract
      properties:
        multivariate_contract:
          $ref: '#/components/schemas/MultivariateEventCollection'
          description: The multivariate event collection.
    GetMultivariateEventCollectionsResponse:
      type: object
      required:
      - multivariate_contracts
      properties:
        multivariate_contracts:
          type: array
          items:
            $ref: '#/components/schemas/MultivariateEventCollection'
          description: List of multivariate event collections.
        cursor:
          type: string
          description: The Cursor represents a pointer to the next page of records in the pagination. Use the value returned here in the cursor query parameter for this end-point to get the next page containing limit records. An empty value of this field indicates there is no next page.
          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
    CreateMarketInMultivariateEventCollectionResponse:
      type: object
      required:
      - event_ticker
      - market_ticker
      properties:
        event_ticker:
          type: string
          description: Event ticker for the created market.
        market_ticker:
          type: string
          description: Market ticker for the created market.
        market:
          $ref: '#/components/schemas/Market'
          description: Market payload of the created market.
    AssociatedEvent:
      type: object
      required:
      - ticker
      - is_yes_only
      - active_quoters
      properties:
        ticker:
          type: string
          description: The event ticker.
        is_yes_only:
          type: boolean
          description: Whether only the 'yes' side can be used for this event.
        size_max:
          type: integer
          format: int32
          nullable: true
          description: Maximum number of markets from this event (inclusive). Null means no limit.
        size_min:
          type: integer
          format: int32
          nullable: true
          description: Minimum number of markets from this event (inclusive). Null means no limit.
        active_quoters:
          type: array
          items:
            type: string
          description: List of active quoters for this event.
    LookupPoint:
      type: object
      required:
      - event_ticker
      - market_ticker
      - selected_markets
      - last_queried_ts
      properties:
        event_ticker:
          type: string
          description: Event ticker for the lookup point.
        market_ticker:
          type: string
          description: Market ticker for the lookup point.
        selected_markets:
          type: array
          items:
            $ref: '#/components/schemas/TickerPair'
          description: Markets that were selected for this lookup.
        last_queried_ts:
          type: string
          format: date-time
          description: Timestamp when this lookup was last queried.
    LookupTickersForMarketInMultivariateEventCollectionResponse:
      type: object
      required:
      - event_ticker
      - market_ticker
      properties:
        event_ticker:
          type: string
          description: Event ticker for the looked up market.
        market_ticker:
          type: string
          description: Market ticker for the looked up market.
    ExchangeIndex:
      type: integer
      description: 'Identifier for an exchange shard. Defaults to 0 if unspecified. Note: currently only 0 supported.'
      example: 0
    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
    LookupTickersForMarketInMultivariateEventCollectionRequest:
      type: object
      required:
      - selected_markets
      properties:
        selected_markets:
          type: array
          items:
            $ref: '#/components/schemas/TickerPair'
          description: List of selected markets that act as parameters to determine which market is produced.
    TickerPair:
      type: object
      required:
      - market_ticker
      - event_ticker
      - side
      properties:
        market_ticker:
          type: string
          description: Market ticker identifier.
        event_ticker:
          type: string
          description: Event ticker identifier.
        side:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Side of the market (yes or no).
    GetMultivariateEventCollectionLookupHistoryResponse:
      type: object
      required:
      - lookup_points
      properties:
        lookup_points:
          type: array
          items:
            $ref: '#/components/schemas/LookupPoint'
          description: List of recent lookup points in the collection.
    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
          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
          format: date-time
          nullable: true
          description: The recorded datetime when the underlying event occurred, if available
        fee_waiver_expiration_time:
          type: string
          format: date-time
          nullable: true
          x-omitempty: true
          description: Time when this market's fee waiver expires
        early_close_condition:
          type: string
          nullable: true
          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
          format: double
          nullable: true
          x-omitempty: true
          description: Minimum expiration value that leads to a YES settlement
        cap_strike:
          type: number
          format: double
          nullable: true
          x-omitempty: true
          description: Maximum expiration value that leads to a YES settlement
        functional_strike:
          type: string
          nullable: true
          x-omitempty: true
          description: Mapping from expiration values to settlement values
        custom_strike:
          type: object
          nullable: true
          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
          nullable: true
          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
    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'
    MultivariateEventCollection:
      type: object
      required:
      - collection_ticker
      - series_ticker
      - title
      - description
      - open_date
      - close_date
      - associated_events
      - associated_event_tickers
      - is_ordered
      - is_single_market_per_event
      - is_all_yes
      - size_min
      - size_max
      - functional_description
      properties:
        collection_ticker:
          type: string
          description: Unique identifier for the collection.
        series_ticker:
          type: string
          description: Series associated with the collection. Events produced in the collection will be associated with this series.
        title:
          type: string
          description: Title of the collection.
        description:
          type: string
          description: Short description of the collection.
        open_date:
          type: string
          format: date-time
          description: The open date of the collection. Before this time, the collection cannot be interacted with.
        close_date:
          type: string
          format: date-time
          description: The close date of the collection. After this time, the collection cannot be interacted with.
        associated_events:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedEvent'
          description: List of events with their individual configuration.
        associated_event_tickers:
          type: array
          items:
            type: string
          description: '[DEPRECATED - Use associated_events instead] A list of events associated with the collection. Markets in these events can be passed as inputs to the Lookup and Create endpoints.'
        is_ordered:
          type: boolean
          description: Whether the collection is ordered. If true, the order of markets passed into Lookup/Create affects the output. If false, the order does not matter.
        is_single_market_per_event:
          type: boolean
          description: '[DEPRECATED - Use associated_events instead] Whether the collection accepts multiple markets from the same event passed into Lookup/Create.'
        is_all_yes:
          type: boolean
          description: '[DEPRECATED - Use associated_events instead] Whether the collection requires that only the market side of ''yes'' may be used.'
        size_min:
          type: integer
          format: int32
          description: The minimum number of markets that must be passed into Lookup/Create (inclusive).
        size_max:
          type: integer
          format: int32
          description: The maximum number of markets that must be passed into Lookup/Create (inclusive).
        functional_description:
          type: string
          description: A functional description of the collection describing how inputs affect the output.
    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'
    CreateMarketInMultivariateEventCollectionRequest:
      type: object
      required:
      - selected_markets
      properties:
        selected_markets:
          type: array
          items:
            $ref: '#/components/schemas/TickerPair'
          description: List of selected markets that act as parameters to determine which market is created.
        with_market_payload:
          type: boolean
          description: Whether to include the market payload in the response.
    MveSelectedLeg:
      type: object
      properties:
        event_ticker:
          type: string
          description: Unique identifier for the selected event
          x-go-type-skip-optional-pointer: true
        market_ticker:
          type: string
          description: Unique identifier for the selected market
          x-go-type-skip-optional-pointer: true
        side:
          type: string
          description: The side of the selected market
          x-go-type-skip-optional-pointer: true
        yes_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
  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'
    RateLimitError:
      description: Rate limit exceeded. The default cost is 10 tokens per request; endpoints that deviate show a **Rate limit** callout at the top of their own page. See [Rate Limits and Tiers](/getting_started/rate_limits).
      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'
  securitySchemes:
    kalshiAccessKey:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-KEY
      description: Your API key ID
    kalshiAccessSignature:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-SIGNATURE
      description: RSA-PSS signature of the request
    kalshiAccessTimestamp:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-TIMESTAMP
      description: Request timestamp in milliseconds