Kalshi API Keys API

openapi: 3.2.0
info:
  title: Kalshi Trade API Manual Endpoints API Keys 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: API Keys
  description: API key management endpoints
paths:
  /api_keys:
    get:
      operationId: GetApiKeys
      summary: Get API Keys
      description: Endpoint for retrieving all API keys associated with the authenticated user. API keys allow programmatic access to the platform without requiring username/password authentication. Each key has a unique identifier and name.
      tags:
      - API Keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      parameters:
      - name: fcm_subtrader_id
        in: query
        required: false
        description: Return only API keys bound to this FCM subtrader. Spelled {your_user_id}_{suffix}; only FCM members hold bound keys. Omit to return every key.
        schema:
          type: string
      responses:
        '200':
          description: List of API keys retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiKeysResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
    post:
      operationId: CreateApiKey
      summary: Create API Key
      description: 'Endpoint for creating a new API key with a user-provided public key. This endpoint allows users with Premier or Market Maker API usage levels to create API keys by providing their own RSA or Ed25519 public key in PEM format. The platform will use this public key to verify signatures on API requests: RSA-PSS with SHA-256 for RSA keys, Ed25519 for Ed25519 keys.'
      tags:
      - API Keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient API usage level, or fcm_subtrader_id from a non-FCM caller
        '409':
          description: Conflict - the bound FCM subtrader is not yet visible in the credential registry; retry after the subtrader create propagates
        '500':
          description: Internal server error
  /api_keys/generate:
    post:
      operationId: GenerateApiKey
      summary: Generate API Key
      description: Endpoint for generating a new API key with an automatically created key pair. This endpoint generates a key pair of the requested key_type (RSA when omitted). The public key is stored on the platform, while the private key is returned to the user and must be stored securely. The private key cannot be retrieved again.
      tags:
      - API Keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateApiKeyRequest'
      responses:
        '201':
          description: API key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateApiKeyResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - fcm_subtrader_id requires an FCM member caller
        '409':
          description: Conflict - the bound FCM subtrader is not yet visible in the credential registry; retry after the subtrader create propagates
        '500':
          description: Internal server error
  /api_keys/{api_key}:
    delete:
      operationId: DeleteApiKey
      summary: Delete API Key
      description: Endpoint for deleting an existing API key. This endpoint permanently deletes an API key. Once deleted, the key can no longer be used for authentication. This action cannot be undone.
      tags:
      - API Keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      parameters:
      - name: api_key
        in: path
        required: true
        description: API key ID to delete
        schema:
          type: string
      responses:
        '204':
          description: API key successfully deleted
        '400':
          description: Bad request - invalid API key ID
        '401':
          description: Unauthorized
        '404':
          description: API key not found
        '500':
          description: Internal server error
components:
  schemas:
    ApiKeyScope:
      type: string
      enum:
      - read
      - write
      - read::block_trade_accept
      - read::portfolio_balance
      - write::trade
      - write::transfer
      - write::fcm_risk
      - write::block_trade_accept
      x-enum-varnames:
      - ApiKeyScopeRead
      - ApiKeyScopeWrite
      - ApiKeyScopeReadBlockTradeAccept
      - ApiKeyScopeReadPortfolioBalance
      - ApiKeyScopeWriteTrade
      - ApiKeyScopeWriteTransfer
      - ApiKeyScopeWriteFCMRisk
      - ApiKeyScopeWriteBlockTradeAccept
      description: Scope granted to an API key. Parent scopes grant broad access; for example, `read` grants all read endpoints and `write` grants all write endpoints. Child scopes such as `read::block_trade_accept`, `read::portfolio_balance`, `write::trade`, `write::transfer`, `write::fcm_risk` (FCM subtrader creation, trading blocks, daily premium caps, and margin caps), and `write::block_trade_accept` grant only their specific endpoint group and can be granted without the parent scope.
    CreateApiKeyRequest:
      type: object
      required:
      - name
      - public_key
      properties:
        name:
          type: string
          description: Name for the API key. This helps identify the key's purpose
        public_key:
          type: string
          description: RSA or Ed25519 public key in PEM format (`-----BEGIN PUBLIC KEY-----`). This will be used to verify signatures on API requests - RSA-PSS with SHA-256 for RSA keys, Ed25519 for Ed25519 keys
        scopes:
          type: array
          description: List of scopes to grant to the API key. If the broad `write` parent scope is included, `read` must also be included. Child scopes may be granted without the broad parent scope. Defaults to full access (`read`, `write`) if not provided.
          items:
            $ref: '#/components/schemas/ApiKeyScope'
        subaccount:
          type: integer
          minimum: 0
          maximum: 63
          description: If set, restricts the API key to a single sub-account (0-63) that you own. A restricted key may only read and trade on that sub-account; it cannot act on other sub-accounts, transfer funds between sub-accounts, or create sub-accounts. Omit to leave the key unrestricted. Mutually exclusive with fcm_subtrader_id.
        fcm_subtrader_id:
          type: string
          description: FCM members only. If set, binds the API key to a single FCM subtrader that you own, spelled {your_user_id}_{suffix} with a suffix of 1-16 case-sensitive ASCII alphanumeric characters. The subtrader must already exist. A bound key is the institution's trading credential for that subtrader - FIX order-entry and market-data sessions, plus margin WebSocket sessions scoped to the subtrader's own data - and is denied on every REST endpoint, including key management. Mutually exclusive with subaccount.
    GenerateApiKeyResponse:
      type: object
      required:
      - api_key_id
      - private_key
      properties:
        api_key_id:
          type: string
          description: Unique identifier for the newly generated API key
        key_type:
          $ref: '#/components/schemas/ApiKeyType'
        private_key:
          type: string
          description: Private key in PEM format - PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`) for `rsa`, PKCS#8 (`-----BEGIN PRIVATE KEY-----`) for `ed25519`. This must be stored securely and cannot be retrieved again after this response
        warning:
          type:
          - string
          - 'null'
          description: Present only when the minted key is bound to an FCM subtrader that is missing a per-subtrader risk control - the initial-margin cap (margin lane) or the event-contract daily cap. The mint still succeeds; the warning names each missing control - an event-contract subtrader without a daily cap has its event-contract orders rejected until one is set, while a margin subtrader without an initial-margin cap is bounded only by firm-level risk limits.
    GenerateApiKeyRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name for the API key. This helps identify the key's purpose
        key_type:
          $ref: '#/components/schemas/ApiKeyType'
        scopes:
          type: array
          description: List of scopes to grant to the API key. If the broad `write` parent scope is included, `read` must also be included. Child scopes may be granted without the broad parent scope. Defaults to full access (`read`, `write`) if not provided.
          items:
            $ref: '#/components/schemas/ApiKeyScope'
        subaccount:
          type: integer
          minimum: 0
          maximum: 63
          description: If set, restricts the API key to a single sub-account (0-63) that you own. A restricted key may only read and trade on that sub-account; it cannot act on other sub-accounts, transfer funds between sub-accounts, or create sub-accounts. Omit to leave the key unrestricted. Mutually exclusive with fcm_subtrader_id.
        fcm_subtrader_id:
          type: string
          description: FCM members only. If set, binds the API key to a single FCM subtrader that you own, spelled {your_user_id}_{suffix} with a suffix of 1-16 case-sensitive ASCII alphanumeric characters. The subtrader must already exist. A bound key is the institution's trading credential for that subtrader - FIX order-entry and market-data sessions, plus margin WebSocket sessions scoped to the subtrader's own data - and is denied on every REST endpoint, including key management. Mutually exclusive with subaccount.
    ApiKeyType:
      type: string
      enum:
      - rsa
      - ed25519
      x-enum-varnames:
      - ApiKeyTypeRsa
      - ApiKeyTypeEd25519
      description: Signature algorithm of an API key pair. `rsa` - 2048-bit RSA; requests are signed with RSA-PSS SHA-256. `ed25519` - Ed25519 (RFC 8032) signatures over the same pre-sign text, with lower client-side signing cost. Defaults to `rsa` when omitted from a generate request, for compatibility with existing clients.
    GetApiKeysResponse:
      type: object
      required:
      - api_keys
      properties:
        api_keys:
          type: array
          description: List of all API keys associated with the user
          items:
            $ref: '#/components/schemas/ApiKey'
        api_key_region_expiration_ts:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp (seconds) when the account's location attestation for API key requests expires; a past value means the attestation has lapsed. Absent when the account has never attested.
    ApiKey:
      type: object
      required:
      - api_key_id
      - name
      - scopes
      properties:
        api_key_id:
          type: string
          description: Unique identifier for the API key
        name:
          type: string
          description: User-provided name for the API key
        scopes:
          type: array
          description: List of scopes granted to this API key.
          items:
            $ref: '#/components/schemas/ApiKeyScope'
        subaccount:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 63
          description: If set, the API key is restricted to this single sub-account and may only read and trade on it. Absent/null means the key is unrestricted.
        fcm_subtrader_id:
          type:
          - string
          - 'null'
          description: If set, the API key is bound to this single FCM subtrader ({fcm_user_id}_{suffix}) and is usable only as that institution's trading credential - FIX sessions and subtrader-scoped margin WebSocket sessions; every REST endpoint is denied. Absent/null means the key carries no subtrader binding.
    CreateApiKeyResponse:
      type: object
      required:
      - api_key_id
      properties:
        api_key_id:
          type: string
          description: Unique identifier for the newly created API key
        warning:
          type:
          - string
          - 'null'
          description: Present only when the minted key is bound to an FCM subtrader that is missing a per-subtrader risk control - the initial-margin cap (margin lane) or the event-contract daily cap. The mint still succeeds; the warning names each missing control - an event-contract subtrader without a daily cap has its event-contract orders rejected until one is set, while a margin subtrader without an initial-margin cap is bounded only by firm-level risk limits.
  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)