openapi: 3.0.0
info:
  title: Kalshi Trade API Manual Endpoints account incentive-programs 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: incentive-programs
  description: Incentive program endpoints
paths:
  /incentive_programs:
    get:
      operationId: GetIncentivePrograms
      summary: Get Incentives
      description: ' List incentives with optional filters. Incentives are rewards programs for trading activity on specific markets.'
      tags:
      - incentive-programs
      parameters:
      - name: status
        in: query
        required: false
        description: Status filter. Can be "all", "active", "upcoming", "closed", or "paid_out". Default is "all".
        schema:
          type: string
          enum:
          - all
          - active
          - upcoming
          - closed
          - paid_out
      - name: type
        in: query
        required: false
        description: Type filter. Can be "all", "liquidity", or "volume". Default is "all".
        schema:
          type: string
          enum:
          - all
          - liquidity
          - volume
      - name: incentive_description
        in: query
        required: false
        description: Filter by exact incentive description.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Number of results per page. Defaults to 100. Maximum value is 10000.
        schema:
          type: integer
          minimum: 1
          maximum: 10000
      - name: cursor
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      responses:
        '200':
          description: Incentive programs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIncentiveProgramsResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    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
    IncentiveProgram:
      type: object
      required:
      - id
      - market_id
      - market_ticker
      - incentive_type
      - incentive_description
      - start_date
      - end_date
      - period_reward
      - paid_out
      properties:
        id:
          type: string
          description: Unique identifier for the incentive program
        market_id:
          type: string
          description: The unique identifier of the market associated with this incentive program
        market_ticker:
          type: string
          description: The ticker symbol of the market associated with this incentive program
        incentive_type:
          type: string
          enum:
          - liquidity
          - volume
          description: Type of incentive program
        incentive_description:
          type: string
          description: Plain text description of the incentive program
        start_date:
          type: string
          format: date-time
          description: Start date of the incentive program
        end_date:
          type: string
          format: date-time
          description: End date of the incentive program
        period_reward:
          type: integer
          format: int64
          description: Total reward for the period in centi-cents
        paid_out:
          type: boolean
          description: Whether the incentive has been paid out
        discount_factor_bps:
          type: integer
          format: int32
          nullable: true
          description: Discount factor in basis points (optional)
        target_size_fp:
          $ref: '#/components/schemas/FixedPointCount'
          nullable: true
          description: String representation of the target size for the incentive program (optional)
    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'
    GetIncentiveProgramsResponse:
      type: object
      required:
      - incentive_programs
      properties:
        incentive_programs:
          type: array
          items:
            $ref: '#/components/schemas/IncentiveProgram'
        next_cursor:
          type: string
          description: Cursor for pagination to get the next page of results
  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