MCP Kalshi

Package: @iqai/mcp-kalshi
Purpose: Interacting with Kalshi prediction markets for trading and market analysis.

Usage with ADK TypeScript

import {McpKalshi} from "@iqai/adk";

const toolset = McpKalshi({
  env: {
    KALSHI_API_KEY: process.env.KALSHI_API_KEY,
    KALSHI_PRIVATE_KEY_PATH: process.env.KALSHI_PRIVATE_KEY_PATH,
  },
})

const tools = await toolset.getTools()

import {McpToolset} from "@iqai/adk";

const toolset = new McpToolset({
  name: "Kalshi MCP Client",
  description: "Client for Kalshi prediction markets",
  transport: {
    mode: "stdio",
    command: "pnpm",
    args: ["dlx", "@iqai/mcp-kalshi"],
    env: {
      KALSHI_API_KEY: process.env.KALSHI_API_KEY,
      KALSHI_PRIVATE_KEY_PATH: process.env.KALSHI_PRIVATE_KEY_PATH,
      PATH: process.env.PATH || "",
    },
  },
})

const tools = await toolset.getTools()

{
  "mcpServers": {
    "kalshi-mcp-server": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-kalshi"],
      "env": {
        "KALSHI_API_KEY": "your_kalshi_api_key",
        "KALSHI_PRIVATE_KEY_PATH": "/path/to/your/private_key.pem"
      }
    }
  }
}

Available Tools

GET_MARKETS

limit:numbercursor:stringeventTicker:stringseriesTicker:stringstatus:stringtickers:string

Description

List and discover prediction markets on Kalshi. Markets represent binary outcomes users can trade on. Returns paginated results with market details including ticker, title, prices, and volume.

GET_MARKET

ticker:string

Description

Get detailed information about a specific prediction market by its ticker, including current prices, volume, open interest, and settlement rules.

GET_MARKET_ORDERBOOK

ticker:stringdepth:number

Description

Get the current orderbook for a market showing bid prices and quantities for both Yes and No sides.

GET_TRADES

ticker:stringlimit:numbercursor:stringminTs:numbermaxTs:number

Description

Get recent public trades across all markets or for a specific market. Each trade shows price, quantity, and timestamp.

GET_SERIES

seriesTicker:string

Description

Get information about a series, which is a template for recurring events (e.g., monthly jobs reports, daily weather).

GET_BALANCE

No parameters

Description

Get the current account balance and portfolio value. Values are returned in dollars.

GET_POSITIONS

ticker:stringeventTicker:stringlimit:numbercursor:stringcountFilter:string

Description

Get your current portfolio positions showing market exposure, cost basis, and P&L for each position.

GET_FILLS

ticker:stringorderId:stringlimit:numbercursor:stringminTs:numbermaxTs:number

Description

Get your trade fill history. A fill occurs when your order is matched with another trader.

GET_SETTLEMENTS

ticker:stringeventTicker:stringlimit:numbercursor:stringminTs:numbermaxTs:number

Description

Get your settlement history showing resolved markets and their payouts.

GET_ORDERS

ticker:stringeventTicker:stringstatus:stringlimit:numbercursor:string

Description

Get your orders with optional filtering by market, status, or time range.

GET_ORDER

orderId:string

Description

Get detailed information about a specific order by its ID.

CREATE_ORDER

ticker:stringside:stringaction:stringcount:numbertype:stringyesPrice:numbernoPrice:numbertimeInForce:stringpostOnly:booleanreduceOnly:boolean

Description

Create a new order to buy or sell contracts in a prediction market. Use limit orders with a price, or market orders for immediate execution.

CANCEL_ORDER

orderId:string

Description

Cancel an existing open order by its ID.

BATCH_CANCEL_ORDERS

ids:array

Description

Cancel multiple orders at once (up to 20 orders per batch).

DECREASE_ORDER

orderId:stringreduceBy:number

Description

Decrease the quantity of an existing order. This is the only way to reduce order size without fully canceling.

Environment Variables

Security

Private keys are used for trading operations. Handle with care and never commit them to version control.

KALSHI_API_KEY: Required. Your Kalshi API key ID.
KALSHI_PRIVATE_KEY_PATH: Path to your RSA private key PEM file.
KALSHI_PRIVATE_KEY_PEM: RSA private key as PEM string (alternative to path).

Authentication

Provide either KALSHI_PRIVATE_KEY_PATH or KALSHI_PRIVATE_KEY_PEM, not both.

Usage Examples

Here's a complete example of using MCP Kalshi with an ADK agent:

import { McpKalshi, AgentBuilder } from "@iqai/adk";
import dotenv from "dotenv";

dotenv.config();

async function main() {
  // Initialize Kalshi MCP toolset
  const toolset = McpKalshi({
    env: {
      KALSHI_API_KEY: process.env.KALSHI_API_KEY,
      KALSHI_PRIVATE_KEY_PATH: process.env.KALSHI_PRIVATE_KEY_PATH,
    },
    debug: false,
    retryOptions: {
      maxRetries: 3,
      initialDelay: 500,
    },
  });

  // Get available tools
  const kalshiTools = await toolset.getTools();

  // Create agent with Kalshi tools
  const { runner } = await AgentBuilder.create("kalshi_agent")
    .withModel("gemini-2.5-flash")
    .withDescription("An agent that interacts with Kalshi prediction markets")
    .withTools(...kalshiTools)
    .build();

  try {
    // Example queries
    const response = await runner.ask("Show me available markets on Kalshi");
    console.log(response);
  } finally {
    // Clean up resources
    await toolset.close();
  }
}

main().catch(console.error);

Getting Your Credentials

API Key

Sign up at Kalshi
Navigate to your account settings
Generate an API key

Private Key

Generate an RSA private key for API authentication. You can provide it either as a file path (KALSHI_PRIVATE_KEY_PATH) or as a PEM string (KALSHI_PRIVATE_KEY_PEM).

Important

Never share your private key or commit it to version control. Always use environment variables or secure secret management systems.

Best Practices

Security: Store API keys and private keys in environment variables, never hardcode them
Resource Cleanup: Always call await toolset.close() when done to properly close connections
Error Handling: Implement proper error handling for trading operations
Rate Limits: Be aware of Kalshi API rate limits and implement appropriate retry logic

Error Handling

Error Scenarios

The server handles various error scenarios gracefully.

🚨 Missing credentials: Ensure KALSHI_API_KEY and a private key are set 💸 Insufficient balance: Ensure your account has sufficient funds for trading 🔄 Invalid market identifiers: Verify market IDs are correct 🌐 Network issues: Check your internet connection and Kalshi API status

Resources

Kalshi - Kalshi prediction market platform
Model Context Protocol - MCP specification and standards

MCP Kalshi

On this page