Kalshi Multivariate API

openapi: 3.2.0
info:
  title: Kalshi Trade API Manual Endpoints Multivariate API
  version: 3.34.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'
components:
  schemas:
    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
          - 'null'
          format: int32
          description: Maximum number of markets from this event (inclusive). Null means no limit.
        size_min:
          type:
          - integer
          - 'null'
          format: int32
          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.
    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
      - open_interest_fp
      - result
      - can_close_early
      - expiration_value
      - rules_primary
      - rules_secondary
      - price_level_structure
      - price_ranges
      - settlement_bounds_type
      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.
        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
        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
        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
        settlement_bounds_type:
          type: string
          enum:
          - default
          - floor
          description: Which settlement bounds apply to this market. default means the market has no settlement bounds
        settlement_floor_dollars:
          $ref: '#/components/schemas/FixedPointDollars'
          x-omitempty: true
          description: The lowest value the YES/LONG side of the contract can settle at in dollars. Only filled when settlement_bounds_type is floor
        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
          x-omitempty: false
    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'
          x-omitempty: true
          description: The settlement value of the YES/LONG side of the contract in dollars. Only filled after determination
    ExchangeIndex:
      type: integer
      description: Identifier for an exchange shard.
      example: 0
    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).
          x-oapi-codegen-extra-tags:
            validate: required,oneof=yes no
    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
    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
    GetMultivariateEventCollectionResponse:
      type: object
      required:
      - multivariate_contract
      properties:
        multivariate_contract:
          $ref: '#/components/schemas/MultivariateEventCollection'
          description: The multivariate event collection.
    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
      - price_level_structure
      - price_ranges
      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.
        exchange_index:
          allOf:
          - $ref: '#/components/schemas/ExchangeIndex'
          description: Exchange index inherited from the collection's series.
          x-go-type-skip-optional-pointer: true
          x-omitempty: false
        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.
        price_level_structure:
          type: string
          description: Price level structure used for new markets created in this collection. Existing markets may differ; use the market's price_level_structure and price_ranges for its current pricing.
        price_ranges:
          type: array
          description: Price bands and tick sizes in fixed-point dollars for new markets created in this collection. Use these ranges to determine valid prices rather than hardcoding the structure name.
          items:
            $ref: '#/components/schemas/PriceRange'
    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.
          x-oapi-codegen-extra-tags:
            validate: required,dive
        with_market_payload:
          type: boolean
          description: Whether to include the market payload in the response.
    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; the minimum granularity is 0.01 contracts.
      example: '10.00'
    FixedPointDollars:
      type: string
      description: Fixed-point US dollar string. Most request fields accept 2-4 decimal places (e.g., "0.56", "0.5600"); responses emit up to 6. Valid quote intervals for a given market are constrained by that market's price level structure.
      example: '0.5600'
    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.
  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'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitError:
      description: Rate limit exceeded. The default cost is 10 tokens per request. Use GET /trade-api/v2/account/endpoint_costs to list non-default endpoint costs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequestError:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    kalshiOauthAccessToken:
      type: http
      scheme: bearer
      description: User OAuth access token with read::compliance_partner, issued to an explicitly authorized partner. Accepted only on current and historical fills and current portfolio positions endpoints; generic read and partner client-credentials tokens do not grant access.
    kalshiAccessKey:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-KEY
      description: Your API key ID
    kalshiAccessSignature:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-SIGNATURE
      description: Base64 signature of the pre-sign text (timestamp + method + path) made with the API key's algorithm - RSA-PSS with SHA-256 for RSA keys, Ed25519 for Ed25519 keys
    kalshiAccessTimestamp:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-TIMESTAMP
      description: Request timestamp in milliseconds
x-provenance:
  method: harvested
  publisher: Kalshi
  source: https://docs.kalshi.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)