Kalshi TypeScript Client

Common errors

• Error: Request failed with status code 401

  cause The API request failed due to invalid or missing authentication credentials (API key).
  fix Verify that your `KALSHI_API_KEY` environment variable is correctly set and contains a valid, active API key from your Kalshi account. Ensure it has the necessary permissions for the API endpoint you are trying to access.

• TypeError: Cannot read properties of undefined (reading 'data')

  cause The API response object or its properties are `undefined`, often due to an HTTP error that prevented a successful data payload, or an unexpected response structure.
  fix Wrap your API calls in a `try-catch` block and inspect the `error.response` object for details on the HTTP status code and error message. Ensure your API key is valid and the request parameters are correct.

• Property 'someMethod' does not exist on type 'SomeApi'. Did you mean 'someOtherMethod'?

  cause You are attempting to call a method that does not exist on the API client class, likely due to an outdated client library, a typo, or a breaking change in the Kalshi API.
  fix Check the `kalshi-typescript` documentation (especially the `docs/` folder) for the correct method name and signature. Ensure your `kalshi-typescript` package is up-to-date with the latest version from npm.

Warnings

• breaking As an OpenAPI generated client, breaking changes to the underlying Kalshi API specification can result in changes to method signatures, request/response bodies, or available endpoints within this client library, even without a major version bump of `kalshi-typescript`. Always review the generated client's documentation or diff the new version if you encounter unexpected behavior after an update.
  Fix: Consult the Kalshi API documentation and the generated client's `docs/` folder for updated API endpoint and data model information. Regenerate local client if maintaining a fork.
• gotcha Hardcoding API keys directly in your source code or checking them into version control is a severe security risk. API keys provide access to your account and should be treated as sensitive credentials.
  Fix: Always use environment variables (e.g., `process.env.KALSHI_API_KEY`), a secure configuration management system, or dedicated secret management services to store and retrieve API keys, especially in production environments.
• gotcha The `basePath` configured for the client is crucial. Using an incorrect or outdated base path (e.g., accidentally pointing to a sandbox environment when intending production) will lead to authentication failures or interactions with the wrong Kalshi environment.
  Fix: Ensure the `basePath` in your `Configuration` object matches the target Kalshi API environment (e.g., `https://api.elections.kalshi.com/trade-api/v2` for production). Verify this against the official Kalshi API documentation.

Install

• npm install kalshi-typescript npm
• yarn add kalshi-typescript yarn
• pnpm add kalshi-typescript pnpm

Imports

• Configuration
  wrong:

  const { Configuration } = require('kalshi-typescript');

  correct:

  import { Configuration } from 'kalshi-typescript';

  The primary way to configure the client, including API keys and base path. Supports both ESM and CommonJS.
• ApiKeysApi
  wrong:

  import ApiKeysApi from 'kalshi-typescript';

  correct:

  import { ApiKeysApi } from 'kalshi-typescript';

  Represents the API client for managing API keys. Most API service clients are named exports.
• GetApiKeysResponse
  wrong:

  import { type GetApiKeysResponse } from 'kalshi-typescript';

  correct:

  import { GetApiKeysResponse } from 'kalshi-typescript';

  Imports the TypeScript interface for the response payload of the getApiKeys method. Type imports are automatically resolved.

Quickstart

This quickstart initializes the Kalshi client with an API key and fetches a list of existing API keys, demonstrating basic authentication and API interaction.

import { Configuration, ApiKeysApi } from 'kalshi-typescript';

// Ensure your Kalshi API key is set as an environment variable
// For production, use secure secret management best practices.
const KALSHI_API_KEY = process.env.KALSHI_API_KEY ?? '';

if (!KALSHI_API_KEY) {
  console.error('KALSHI_API_KEY environment variable is not set.');
  process.exit(1);
}

// Initialize the Configuration object with your API key and base path.
const config = new Configuration({
  apiKey: KALSHI_API_KEY,
  basePath: 'https://api.elections.kalshi.com/trade-api/v2' // As specified in the README
});

// Create an instance of the API client you want to use.
const apiKeysApi = new ApiKeysApi(config);

async function listApiKeys() {
  try {
    console.log('Attempting to fetch Kalshi API keys...');
    const response = await apiKeysApi.getApiKeys();
    console.log('Successfully retrieved API keys.');

    if (response.data && response.data.api_keys && response.data.api_keys.length > 0) {
      response.data.api_keys.forEach(key => {
        console.log(`  - Key ID: ${key.api_key_id}, Name: ${key.name}, Created At: ${new Date(key.created_at * 1000).toLocaleString()}`);
      });
    } else {
      console.log('No API keys found for this account.');
    }
  } catch (error: any) {
    console.error('Error fetching API keys:', error.message);
    if (error.response) {
      console.error('Response data:', error.response.data);
      console.error('Response status:', error.response.status);
    }
  }
}

listApiKeys();