Kalshi Exchange API

openapi: 3.2.0
info:
  title: Kalshi Trade API Manual Endpoints Exchange 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: Exchange
  description: Exchange status and information endpoints
paths:
  /exchange/status:
    get:
      operationId: GetExchangeStatus
      summary: Get Exchange Status
      description: Endpoint for getting the exchange status.
      tags:
      - Exchange
      responses:
        '200':
          description: Exchange status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeStatus'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeStatus'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeStatus'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeStatus'
  /series/fee_changes:
    get:
      operationId: GetSeriesFeeChanges
      summary: Get Series Fee Changes
      tags:
      - Exchange
      parameters:
      - name: series_ticker
        in: query
        required: false
        schema:
          type: string
        x-go-type-skip-optional-pointer: true
      - name: show_historical
        in: query
        required: false
        schema:
          type: boolean
          default: false
        x-go-type-skip-optional-pointer: true
      responses:
        '200':
          description: Series fee changes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSeriesFeeChangesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/schedule:
    get:
      operationId: GetExchangeSchedule
      summary: Get Exchange Schedule
      description: Endpoint for getting the exchange schedule.
      tags:
      - Exchange
      responses:
        '200':
          description: Exchange schedule retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExchangeScheduleResponse'
        '500':
          description: Internal server error
  /exchange/user_data_timestamp:
    get:
      operationId: GetUserDataTimestamp
      summary: Get User Data Timestamp
      description: 'There is typically a short delay before exchange events are reflected in the API endpoints. Whenever possible, combine API responses to PUT/POST/DELETE requests with WebSocket data to obtain the most accurate view of the exchange state. This endpoint provides an approximate indication of when the data from the following endpoints was last validated: GetBalance, GetOrder(s), GetFills, GetPositions'
      tags:
      - Exchange
      responses:
        '200':
          description: User data timestamp retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserDataTimestampResponse'
        '500':
          description: Internal server error
components:
  schemas:
    DailySchedule:
      type: object
      required:
      - open_time
      - close_time
      properties:
        open_time:
          type: string
          description: Opening time in ET (Eastern Time) format HH:MM.
        close_time:
          type: string
          description: Closing time in ET (Eastern Time) format HH:MM.
    ExchangeIndexStatus:
      type: object
      required:
      - exchange_index
      - description
      - exchange_active
      - trading_active
      - intra_exchange_transfers_active
      properties:
        exchange_index:
          $ref: '#/components/schemas/ExchangeIndex'
        description:
          type: string
          description: Description of this exchange shard.
        exchange_active:
          type: boolean
          description: False if this exchange index is no longer taking any state changes at all. True unless under maintenance.
        trading_active:
          type: boolean
          description: True if trading is currently permitted on this exchange index. False outside exchange hours or during pauses.
        intra_exchange_transfers_active:
          type: boolean
          description: True if intra-exchange transfers are currently permitted on this exchange index. False when transfers are temporarily blocked.
    WeeklySchedule:
      type: object
      required:
      - start_time
      - end_time
      - monday
      - tuesday
      - wednesday
      - thursday
      - friday
      - saturday
      - sunday
      properties:
        start_time:
          type: string
          format: date-time
          description: Start date and time for when this weekly schedule is effective.
        end_time:
          type: string
          format: date-time
          description: End date and time for when this weekly schedule is no longer effective.
        monday:
          type: array
          description: Trading hours for Monday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
        tuesday:
          type: array
          description: Trading hours for Tuesday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
        wednesday:
          type: array
          description: Trading hours for Wednesday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
        thursday:
          type: array
          description: Trading hours for Thursday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
        friday:
          type: array
          description: Trading hours for Friday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
        saturday:
          type: array
          description: Trading hours for Saturday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
        sunday:
          type: array
          description: Trading hours for Sunday. May contain multiple sessions.
          items:
            $ref: '#/components/schemas/DailySchedule'
    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
    ExchangeIndex:
      type: integer
      description: Identifier for an exchange shard.
      example: 0
    MaintenanceWindow:
      type: object
      required:
      - start_datetime
      - end_datetime
      properties:
        start_datetime:
          type: string
          format: date-time
          description: Start date and time of the maintenance window.
        end_datetime:
          type: string
          format: date-time
          description: End date and time of the maintenance window.
    Schedule:
      type: object
      required:
      - standard_hours
      - maintenance_windows
      properties:
        standard_hours:
          type: array
          description: The standard operating hours of the exchange. All times are expressed in ET. Outside of these times trading will be unavailable.
          items:
            $ref: '#/components/schemas/WeeklySchedule'
        maintenance_windows:
          type: array
          description: Scheduled maintenance windows, during which the exchange may be unavailable.
          items:
            $ref: '#/components/schemas/MaintenanceWindow'
    FeeType:
      type: string
      enum:
      - quadratic
      - quadratic_with_maker_fees
      - quadratic_with_combo_maker_fees
      - flat
      x-enum-varnames:
      - FeeTypeQuadratic
      - FeeTypeQuadraticWithMakerFees
      - FeeTypeQuadraticWithComboMakerFees
      - FeeTypeFlat
      description: Fee type for a series or scheduled fee override.
    GetUserDataTimestampResponse:
      type: object
      required:
      - as_of_time
      properties:
        as_of_time:
          type: string
          format: date-time
          description: Timestamp when user data was last updated.
    GetExchangeScheduleResponse:
      type: object
      required:
      - schedule
      properties:
        schedule:
          $ref: '#/components/schemas/Schedule'
    SeriesFeeChange:
      type: object
      required:
      - id
      - series_ticker
      - fee_type
      - fee_multiplier
      - scheduled_ts
      properties:
        id:
          type: string
          description: Unique identifier for this fee change
        series_ticker:
          type: string
          description: Series ticker this fee change applies to
        fee_type:
          allOf:
          - $ref: '#/components/schemas/FeeType'
          description: New fee type for the series
        fee_multiplier:
          type: number
          format: double
          description: New fee multiplier for the series
        scheduled_ts:
          type: string
          format: date-time
          description: Timestamp when this fee change is scheduled to take effect
    GetSeriesFeeChangesResponse:
      type: object
      required:
      - series_fee_change_arr
      properties:
        series_fee_change_arr:
          type: array
          items:
            $ref: '#/components/schemas/SeriesFeeChange'
    ExchangeStatus:
      type: object
      required:
      - exchange_active
      - trading_active
      properties:
        exchange_active:
          type: boolean
          description: False if the core Kalshi exchange is no longer taking any state changes at all. This includes but is not limited to trading, new users, and transfers. True unless we are under maintenance.
        trading_active:
          type: boolean
          description: True if we are currently permitting trading on the exchange. This is true during trading hours and false outside exchange hours. Kalshi reserves the right to pause at any time in case issues are detected.
        intra_exchange_transfers_active:
          type: boolean
          description: True if intra-exchange transfers are currently permitted. False when transfers are temporarily blocked.
        exchange_estimated_resume_time:
          type:
          - string
          - 'null'
          format: date-time
          description: Estimated downtime for the current exchange maintenance window. However, this is not guaranteed and can be extended.
        exchange_index_statuses:
          type: array
          description: Status of each exchange index. The top-level fields above reflect the default exchange index (0). Absent when the per-index breakdown is unavailable.
          items:
            $ref: '#/components/schemas/ExchangeIndexStatus'
  responses:
    InternalServerError:
      description: Internal server error
      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)