Kalshi Account API

openapi: 3.2.0
info:
  title: Kalshi Trade API Manual Endpoints Account 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: Account
paths:
  /account/limits:
    get:
      operationId: GetAccountApiLimits
      summary: Get Account API Limits
      description: Endpoint to retrieve the authenticated user's Predictions API usage tier and token-bucket limits. Public Predictions tiers include Basic, Advanced, Expert, Premier, Paragon, Prime, and Prestige.
      tags:
      - Account
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      responses:
        '200':
          description: Account API tier limits retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountApiLimitsResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /account/api_usage_level/upgrade:
    post:
      operationId: UpgradeAccountApiUsageLevel
      summary: Upgrade Account API Usage Level
      description: 'Grants a permanent Advanced API usage-level grant. Currently only the Predictions exchange instance is supported. Criteria: at least 1 of the user''s last 100 Predictions orders was created via API. Use Get Account API Limits to inspect the resulting usage tier and grants.'
      x-mint:
        content: '<Note>

          **Rate limit:** 30 tokens per request. See `GET /trade-api/v2/account/endpoint_costs` for current non-default endpoint costs.

          </Note>

          '
      tags:
      - Account
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      responses:
        '201':
          description: Advanced API usage-level grant created or refreshed successfully
        '401':
          description: Unauthorized
        '403':
          description: No API-created order was found in the user's latest 100 Predictions orders
        '429':
          description: Rate limit exceeded. This endpoint costs 30 tokens and uses the Predictions Write bucket.
        '500':
          description: Internal server error
  /account/api_usage_level/volume_progress:
    get:
      operationId: GetAccountApiUsageLevelVolumeProgress
      summary: Get Account API Usage Level Volume Progress
      description: Returns the authenticated user's latest cron-computed trading volume progress toward volume-based API usage tiers for the predictions (event_contract) lane. Volume figures are reported as fixed-point contract counts.
      tags:
      - Account
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      responses:
        '200':
          description: Account API usage level volume progress retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountApiUsageLevelVolumeProgressResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /account/endpoint_costs:
    get:
      operationId: GetAccountEndpointCosts
      summary: List Non-Default Endpoint Costs
      description: Lists API v2 endpoints whose configured token cost differs from the default cost. Endpoints that use the default cost are omitted.
      tags:
      - Account
      responses:
        '200':
          description: Non-default endpoint costs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountEndpointCostsResponse'
        '500':
          description: Internal server error
components:
  schemas:
    GetAccountEndpointCostsResponse:
      type: object
      required:
      - default_cost
      - endpoint_costs
      properties:
        default_cost:
          type: integer
          description: Default token cost applied to endpoints that are not listed in `endpoint_costs`. This is currently 10.
        endpoint_costs:
          type: array
          description: API v2 endpoints whose configured token cost differs from `default_cost`. Endpoints that use the default cost are omitted.
          items:
            $ref: '#/components/schemas/EndpointTokenCost'
    EndpointTokenCost:
      type: object
      required:
      - method
      - path
      - cost
      properties:
        method:
          type: string
          description: HTTP method for the endpoint.
        path:
          type: string
          description: API route path for the endpoint.
        cost:
          type: integer
          description: Configured token cost for an endpoint whose cost differs from the default cost.
    AccountApiUsageLevelVolumeGoal:
      type: object
      required:
      - level
      - earn_volume_goal_fp
      - keep_volume_goal_fp
      properties:
        level:
          type: string
          description: API usage level for this Predictions volume goal.
          example: expert
        earn_volume_goal_fp:
          $ref: '#/components/schemas/FixedPointCount'
        keep_volume_goal_fp:
          $ref: '#/components/schemas/FixedPointCount'
    AccountApiUsageLevelVolumeProgress:
      type: object
      required:
      - computed_ts
      - trailing_30d_volume_fp
      - goals
      properties:
        computed_ts:
          type: integer
          format: int64
          description: Unix timestamp (seconds) when this progress was computed; trailing_30d_volume_fp covers the trailing 30 days ending at this time.
        trailing_30d_volume_fp:
          $ref: '#/components/schemas/FixedPointCount'
        goals:
          type: array
          items:
            $ref: '#/components/schemas/AccountApiUsageLevelVolumeGoal'
    ApiUsageLevelGrant:
      type: object
      required:
      - exchange_instance
      - level
      - source
      properties:
        exchange_instance:
          $ref: '#/components/schemas/ExchangeInstance'
        level:
          type: string
          description: API usage level this grant confers (for example, expert, premier, paragon, prime, or prestige).
          example: prestige
        expires_ts:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp (seconds) when the grant expires. Absent for permanent grants.
        source:
          type: string
          description: 'How the grant was created: "volume" (earned from trading volume) or "manual" (assigned by Kalshi).'
    ExchangeInstance:
      type: string
      enum:
      - event_contract
      - margined
      description: The exchange instance type
    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'
    GetAccountApiLimitsResponse:
      type: object
      required:
      - usage_tier
      - read
      - write
      - grants
      properties:
        usage_tier:
          type: string
          description: User's effective Predictions API usage tier for these limits (for example, basic, advanced, expert, premier, paragon, prime, or prestige).
          example: expert
        read:
          $ref: '#/components/schemas/BucketLimit'
        write:
          $ref: '#/components/schemas/BucketLimit'
        grants:
          type: array
          description: The caller's active API usage level grants across exchange lanes, where each grant applies to its exchange_instance and usage_tier reflects the effective tier for the lane reported by this endpoint.
          items:
            $ref: '#/components/schemas/ApiUsageLevelGrant'
    BucketLimit:
      type: object
      description: 'Token-bucket budget for one rate-limit bucket. Each request deducts

        tokens equal to its endpoint cost; the bucket refills at refill_rate

        tokens per second up to bucket_capacity. A request is allowed if the

        bucket holds enough tokens to cover its cost; otherwise the request

        is rejected with HTTP 429.

        '
      required:
      - refill_rate
      - bucket_capacity
      properties:
        refill_rate:
          type: integer
          description: Tokens added to the bucket per second.
        bucket_capacity:
          type: integer
          description: 'Maximum tokens the bucket can hold. When equal to refill_rate the

            bucket holds one second of budget; larger values represent burst

            headroom that idle clients accumulate and can spend in a single

            pulse (e.g. write buckets at non-Basic tiers hold two seconds of

            budget).

            '
    GetAccountApiUsageLevelVolumeProgressResponse:
      type: object
      required:
      - volume_progress
      properties:
        volume_progress:
          type: array
          description: Latest cron-computed trading volume progress toward volume-based API usage tiers for the predictions (event_contract) lane. Volume-based public tiers are Expert, Premier, Paragon, Prime, and Prestige.
          items:
            $ref: '#/components/schemas/AccountApiUsageLevelVolumeProgress'
  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)