@sperax/tool-kalshi

Read and trade on Kalshi, the CFTC-regulated US event exchange.

Kalshi is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-kalshi

Usage

Call it directly

import { kalshiExecutor } from '@sperax/tool-kalshi';

const result = await kalshiExecutor.invoke('listMarkets', {"cursor":"<cursor>","event_ticker":"<event_ticker>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { KalshiManifest, kalshiExecutor } from '@sperax/tool-kalshi';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: KalshiManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await kalshiExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

KalshiManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration — required

This tool needs a backend you control. It will not work on a bare npm install alone.

The upstream API requires a secret key. That key is deliberately not bundled here — shipping it in an npm package would leak it to every consumer. Instead the executor calls a SperaxOS /webapi/* route, which holds the key server-side and injects it. That route is session-authenticated, so the public deployment at https://chat.sperax.io (the default origin) answers 401 to anonymous callers.

To use this tool you need one of:

• a SperaxOS deployment of your own, or
• any HTTP endpoint that implements the same request shape and supplies the key.

Point the package at it before importing the tool — the URL is resolved once, when the module first loads:

SPERAX_API_BASE_URL=https://my-speraxos.example.com

or in code:

import { configureSperaxApi } from '@sperax/agent-tools-core';

configureSperaxApi({ baseUrl: 'https://my-speraxos.example.com' });

// import the tool only after configuring, so the path resolves against your origin
const { kalshiExecutor } = await import('@sperax/tool-kalshi');

Inside a browser that already serves those routes at its own origin, requests stay same-origin and no configuration is needed.

If you want a tool that runs with zero setup, use one of the standalone tools — those call public APIs directly and need no key, no origin, and no backend.

Tool identifier

sperax-kalshi

API reference

listMarkets

List markets on Kalshi. Filter by status (open/closed/settled), event_ticker, or series_ticker. Returns up to limit markets and a cursor for the next page.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | cursor | string | no | Pagination cursor returned by a previous call. | | event_ticker | string | no | Filter markets that belong to a specific event ticker. | | limit | number | no | Page size, 1–1000. Defaults to 100. | | series_ticker | string | no | Filter markets that belong to a series. | | status | open | closed | settled | unopened | no | Market status filter. |

listEvents

List Kalshi events (groups of related markets).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | cursor | string | no | Pagination cursor. | | limit | number | no | Page size, 1–200. | | series_ticker | string | no | Filter by series. | | status | open | closed | settled | unopened | no | Event status filter. | | with_nested_markets | boolean | no | When true, include each event’s markets inline. |

getMarket

Fetch a single Kalshi market by ticker.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | ticker | string | yes | Market ticker (e.g. "PRES-2028-DJT"). |

getOrderbook

Fetch the current orderbook for a Kalshi market. Levels are in cents (1–99).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | depth | number | no | Number of levels per side. Defaults to full book. | | ticker | string | yes | Market ticker. |

placeOrder

Place an order on Kalshi. Prices are integer cents (1–99) for the chosen side. client_order_id provides idempotency.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | action | buy | sell | yes | | | buy_max_cost | number | no | Optional safety cap in cents for market buys. | | client_order_id | string | yes | Idempotency key for this order. | | count | number | yes | Number of contracts (shares). | | expiration_ts | number | no | Unix seconds; required for GTD orders. | | no_price | number | no | Limit price in cents (1–99) when side === "no". | | post_only | boolean | no | Reject if the order would cross the book. | | side | yes | no | yes | | | ticker | string | yes | Market ticker. | | type | limit | market | yes | | | yes_price | number | no | Limit price in cents (1–99) when side === "yes". |

cancelOrder

Cancel a resting Kalshi order by order_id.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | order_id | string | yes | Kalshi order_id returned by placeOrder. |

batchPlaceOrders

Place up to 50 orders in a single signed request. Use this to stay under per-key write rate limits.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | orders | array | yes | Array of placeOrder requests, max 50. |

getPositions

Get the current portfolio positions for the authenticated user.

Takes no parameters.

getFills

List fills (executed trades) for the authenticated user. Filter by ticker, order_id, or time range.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | cursor | string | no | Pagination cursor. | | limit | number | no | Page size, 1–1000. | | max_ts | number | no | Upper bound on created_time (unix seconds). | | min_ts | number | no | Lower bound on created_time (unix seconds). | | order_id | string | no | Restrict to one order. | | ticker | string | no | Restrict to one market. |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-kalshi is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0