Prediction Market API Trading Guide

Overview of Prediction Market APIs

Prediction market APIs enable programmatic access to market data and order management — the same capabilities available through each platform's web interface, but accessible to automated trading systems, custom dashboards, data pipelines, and quantitative models.

The two major APIs serve different ecosystems:

Authentication and Getting API Keys

Kalshi API Authentication

Kalshi authenticates every private request with an asymmetric key pair you generate yourself — no shared secret ever leaves your machine. Per Kalshi's current documentation (verified 24 September 2026):

1. Generate a key pair. Ed25519 is the recommended type (openssl genpkey -algorithm ed25519 -out kalshi.key); RSA-2048 with RSA-PSS/SHA-256 remains supported and is what the official SDKs currently use. Keep the private key secure — it controls order entry.
2. Register the public key. In Profile Settings (kalshi.com/account/profile) → API Keys → "Create New API Key". Kalshi returns a Key ID; the private key stays with you.
3. Sign every request. Three headers: KALSHI-ACCESS-KEY (the Key ID), KALSHI-ACCESS-TIMESTAMP (current time in milliseconds) and KALSHI-ACCESS-SIGNATURE — the base64 signature over the concatenation of timestamp + HTTP method + request path, with the query string stripped before signing (sign /trade-api/v2/portfolio/orders, never …?limit=5).
4. Point at the right host. Production REST is https://api.elections.kalshi.com/trade-api/v2 (the newer external-api.kalshi.com host serves the same API); the demo environment is https://demo-api.kalshi.co/trade-api/v2, where you can test with play money before touching real capital.

import base64, datetime, requests
from cryptography.hazmat.primitives import serialization

with open("kalshi.key", "rb") as f:                      # the private key you generated
    private_key = serialization.load_pem_private_key(f.read(), password=None)

timestamp = str(int(datetime.datetime.now().timestamp() * 1000))
method, path = "GET", "/trade-api/v2/portfolio/balance"   # sign the path WITHOUT any query string
message = (timestamp + method + path).encode("utf-8")
signature = base64.b64encode(private_key.sign(message)).decode("utf-8")   # Ed25519; RSA keys sign with RSA-PSS/SHA-256

headers = {
    "KALSHI-ACCESS-KEY": "YOUR-KEY-ID",
    "KALSHI-ACCESS-TIMESTAMP": timestamp,
    "KALSHI-ACCESS-SIGNATURE": signature,
}
r = requests.get("https://demo-api.kalshi.co" + path, headers=headers)

Or let the official SDKs sign for you: pip install kalshi_python_sync (or kalshi_python_async) and npm install kalshi-typescript, published weekly against Kalshi's OpenAPI specification.

Polymarket API Authentication

Polymarket's global CLOB is Ethereum-native: your wallet is your identity and orders are signed messages the on-chain exchange contract executes. The 2026 unified SDKs hide most of that:

1. Read without a key. Market data (https://gamma-api.polymarket.com for markets and events, https://clob.polymarket.com for order books, https://data-api.polymarket.com for positions and trade history) and the market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) need no credentials — createPublicClient() in TypeScript, PublicClient() in Python.
2. Trade with a signer. createSecureClient() (@polymarket/client plus viem) or SecureClient.create(private_key=…) (pip install polymarket-client) build a signer from a private key; gasless wallet operations additionally take a Relayer API key created under Settings → API Keys on polymarket.com.
3. Migrating? The older py-clob-client and clob-client libraries are superseded by the unified SDKs; Polymarket publishes a migration guide.

Polymarket US API Authentication

Polymarket US — the CFTC-regulated venue that runs on QCEX rather than on Polygon — has a separate, conventional API at https://api.polymarket.us:

1. Get keys from the developer portal. Once your app account is approved to trade, sign in at polymarket.us/developer with the same method you used in the app and create an API key: you receive a Key ID and a Secret Key.
2. Sign like Kalshi. Three headers — X-PM-Access-Key, X-PM-Timestamp (milliseconds) and X-PM-Signature, an Ed25519 signature over timestamp + method + path made with the Secret Key; timestamps must be within 30 seconds of server time. Public market data needs no key.
3. Or use the SDKs. pip install polymarket-us / npm install polymarket-us take the Key ID and Secret Key and sign for you. Orders go to POST /v1/orders (with preview, cancel, modify and close-position endpoints) and come in two types, limit and market.

Market Data Endpoints

Both APIs provide comprehensive market data access. The core endpoints:

• Markets list. Enumerate all available markets with their contract specifications, status (open/closed/settled), and metadata. Filterable by category, status, and event type.
• Orderbook. The current state of the order book for a specific market — all outstanding bid and ask orders, organized by price level. This shows the current best bid, best ask, spread, and depth at each price level.
• Trades. Historical trade data — every executed trade with timestamp, price, quantity, and side (buy/sell). Essential for backtesting, volume analysis, and detecting market microstructure patterns.
• Market summary / ticker. Aggregated market statistics: last trade price, 24-hour volume, open interest, high/low prices. Useful for dashboard and screening applications.

For real-time data, both platforms offer WebSocket feeds that push orderbook updates and trades as they occur, without the latency and rate-limit overhead of polling REST endpoints. Any serious automated trading system should use WebSocket feeds for market data.

Kalshi-specific data endpoints include market event details (resolution source, settlement date), historical candlestick data, and series metadata for multi-contract markets (e.g., CPI outcome ranges). These are especially useful for economic market analysis.

Polymarket-specific data endpoints include on-chain settlement data, token contract addresses, and condition IDs that map to the underlying smart contract positions. These are necessary for interacting with positions on-chain.

Order Placement

Both APIs support standard order types:

• Limit orders. Specify a price and quantity. The order rests on the book until it is filled by a matching order, you cancel it, or the market closes. Limit orders are maker orders and typically incur lower fees.
• Market orders. Execute immediately at the best available price. Market orders are taker orders and incur higher fees. On thin markets, large market orders may experience slippage — executing at progressively worse prices as they consume liquidity at each price level.

Key parameters for order placement on Kalshi:

• ticker — the market identifier (e.g., "FED-26JUN-T4.50")
• side — "yes" or "no"
• action — "buy" or "sell"
• type — "limit" or "market"
• count — number of contracts
• yes_price or no_price — price in cents (1–99 for limit orders)

Important constraints: orders cannot exceed your available balance (no margin trading on prediction markets). Kalshi enforces a maximum position size per market, which varies by contract. Orders are validated server-side and rejected if they violate any constraint.

On Polymarket, order placement involves creating a signed order object and submitting it to the CLOB API. The order is matched off-chain by Polymarket's operator, but settlement occurs on-chain. This hybrid model provides centralized matching speed with on-chain settlement guarantees.

Position Management and Portfolio Queries

Managing open positions programmatically is essential for automated trading:

• Open positions. Query all your current positions across all markets — contract, side, quantity, average entry price, current market price, and unrealized P&L.
• Order status. Check the status of submitted orders — pending, partially filled, fully filled, or canceled. Implement polling or WebSocket listeners to track order lifecycle events.
• Balance and settlement. Query account balance, pending settlements, and withdrawal availability. On Kalshi, settled contracts are credited to your USD balance immediately. On Polymarket, settlement involves on-chain transactions with associated gas fees.
• Trade history. Download your complete trade history for backtesting, performance analysis, and tax reporting. Kalshi provides CSV export; the API also supports paginated trade history queries.

For portfolio-level risk management, you will typically build your own position tracking system on top of the API. Track exposure by market category, total capital at risk, maximum drawdown limits, and correlation between positions. No prediction market API provides built-in portfolio analytics at the level that professional traders require.

Building a Simple Bot: Monitoring CPI Market Probabilities

A practical starting point for API trading is a monitoring bot — a system that reads market data and alerts you to significant changes, without placing trades automatically. Here is the architecture for a CPI probability monitor:

1. Connect to Kalshi's market data API. Authenticate with your Ed25519 or RSA key pair. Query the markets endpoint with a filter for CPI-related markets to get the list of active CPI contracts.
2. Poll orderbook data at regular intervals. For each CPI outcome range contract, fetch the current best bid and best ask. The midpoint price is your market-implied probability for that range.
3. Build a probability distribution. Aggregate the midpoint prices across all CPI contracts into a single probability distribution. Store each snapshot with a timestamp for historical tracking.
4. Compare to Bloomberg consensus. Manually input the latest Bloomberg consensus estimate. Calculate the divergence between the Kalshi distribution and the consensus. This is the informational signal per the Federal Reserve research.
5. Alert on significant moves. Set thresholds — for example, alert if the probability of an above-consensus CPI print changes by more than 5 percentage points in 24 hours. Send alerts via email, Slack, or SMS.
6. Log and visualize. Store all data in a local database or CSV file. Build simple charts showing how the probability distribution evolves over time as the CPI release date approaches.

This monitoring bot requires no order placement API access — only market data reads. It is a low-risk way to build familiarity with the API, validate the signal quality with your own data, and develop the infrastructure for more sophisticated automated strategies later.

Python is the recommended language for this type of project. The standard stack is: Kalshi's Python SDK for API access, pandas for data manipulation, matplotlib or plotly for visualization, and a simple scheduler (cron or APScheduler) for periodic data collection.

Rate Limits and Best Practices

Both APIs enforce rate limits to prevent abuse and ensure platform stability. Practical guidelines:

• Kalshi REST API: Token buckets, not a flat cap — each request costs tokens (10 by default) and your tier sets the per-second refill budget for reads and writes separately: Basic 200 / 100, Advanced 300 / 300, Expert 600 / 600, Premier 1,200 / 1,200, Paragon 2,400 / 2,400 (about 20 reads and 10 orders a second on Basic). Exceeding your budget returns a 429 status code. Implement exponential backoff with jitter on retries.
• Kalshi WebSocket: Supports multiple market subscriptions per connection. Heartbeat messages maintain the connection. Reconnect logic is essential — WebSocket connections will drop periodically and your system must handle reconnection gracefully.
• Polymarket (global): Limits are tiered under the Builder Program — every new integration starts on the Standard tier and higher tiers raise both API rate limits and daily relayer transaction limits; the docs publish no fixed number, so treat a 429 as the signal and back off.
• Polymarket US: A global limit of 20 requests per second per API key across authenticated endpoints, and 20 per second per IP on the public ones; exceeding it returns 429.
• General best practices:
  • Cache market metadata locally and refresh infrequently (once per hour or less).
  • Use WebSocket feeds for real-time data instead of polling REST endpoints.
  • Batch operations where possible — e.g., cancel all orders in a single request rather than individually.
  • Implement circuit breakers that halt trading if error rates exceed a threshold.
  • Log all API requests and responses for debugging and audit purposes.

Institutional Access: Market Makers, FIX and Private Connectivity

Can a fund trade prediction markets through the API? On Kalshi, yes — the same REST and WebSocket API serves every member, and the exchange layers institutional programmes on top of it:

• Market Maker Program. Designated market makers commit to continuous two-sided quotes and, in exchange for meeting defined quoting and volume requirements, may receive reduced fees and other benefits. Status is granted after a review of financial resources, trading experience and business reputation, and the benefits stay conditional on maintaining liquidity and orderly markets.
• Liquidity Provider Program. Designated Liquidity Providers for a series are chosen through periodic auctions in which applicants state the minimum incentive they would accept; meeting the Incentive Period Requirements earns the Incentive Period Reward.
• FIX API. Order entry over FIX at mm.fix.elections.kalshi.com (port 8228 without retransmission, 8230 with retransmission and RFQ creation), market data at marketdata.fix.elections.kalshi.com, plus gated Drop Copy (8229) and Post Trade (8231) sessions arranged through [email protected].
• Private connectivity. Members on the Premier API tier or above can have AWS PrivateLink endpoints provisioned for the production REST (external-api.kalshi.com) and WebSocket (external-api-ws.kalshi.com) hosts; Prime tier and above can discuss VPC peering for WebSocket traffic.

Polymarket's equivalent is the Builder Program: tiers from Standard upward raise API rate limits and daily relayer transaction limits, subsidise gas, attribute order flow to your builder profile and, for builders routing orders, allow builder fees. Polymarket US documents a single retail API at 20 requests per second per key.

Risk Management for Automated Trading

Automated trading systems require rigorous risk management. Prediction markets have unique risk characteristics:

• Binary outcome risk. Every prediction market position resolves to either $1 or $0. There is no partial loss — you either win or lose the full amount at risk. Position sizing must account for this binary payoff structure.
• Event risk concentration. Many prediction markets resolve on the same date (e.g., multiple CPI contracts resolve simultaneously). If you hold positions across multiple contracts in the same event, your risk is concentrated in a single moment. Calculate correlated exposure across related markets.
• Maximum loss limits. Define a maximum daily and weekly loss limit before starting automated trading. Implement hard stops in your code that halt all trading activity if the limit is breached. Do not rely on manual intervention — automated systems can lose money faster than a human can react.
• Position size limits. Never risk more than a small percentage of your total capital on any single contract. A common rule: no more than 2-5% of trading capital on any single binary outcome.
• Exchange-side kill switches. Kalshi's API lets you place orders inside an order group with a contracts limit (1 to 1,000,000) over a rolling 15-second window: once the group's filled volume exceeds the limit, every resting order in the group is cancelled automatically, and you can fire the same cancel-all manually. Use it as a hard cap your bot cannot talk itself past.
• Regulatory position limits. Position limits live in each exchange's rulebook and contract rules (Kalshi's at kalshi.com/regulatory/rulebook) rather than in an API field — read the rules of any market you intend to size up in.
• API failure handling. Your system must handle API outages, network failures, and unexpected responses gracefully. An open order that you cannot cancel due to an API outage is a risk. Consider using time-in-force parameters (good-til-canceled vs. good-til-date) to limit stale order risk.
• Backtesting vs. live performance. Historical backtesting on prediction market data often overstates real-world performance due to slippage, fees, and the bid-ask spread. Always account for realistic execution costs in backtests. Paper trade for at least 2-4 weeks before deploying capital.

Tax Implications of High-Frequency Prediction Market Trading

Automated trading generates a high volume of taxable events. Key considerations:

• Kalshi tax documents. Kalshi does not issue a 1099 for event-contract profits. It provides a monthly profit-and-loss statement (Account → Tax Info) and issues Form 1099-INT for interest and Form 1099-MISC for credits and rewards above IRS thresholds. Each contract settlement is a taxable event. High-frequency traders may have hundreds or thousands of taxable events per year. Maintain detailed trade logs from the API for tax preparation.
• Section 1256 potential. If Section 1256 applies to CFTC-regulated contracts (Kalshi), gains are taxed 60% long-term capital gains / 40% short-term, regardless of holding period. This would be favorable for short-term traders. Whether it applies is unsettled: no platform has been verified to treat or report its event contracts as Section 1256 contracts, and the IRS has not issued definitive guidance on prediction market contracts. Consult a tax professional who is familiar with CFTC-regulated instruments.
• Wash sale considerations. If you trade the same contract frequently (buying and selling within 30-day windows), wash sale rules may apply, disallowing certain losses. The interaction between prediction market contracts and wash sale rules is not fully settled in tax law.
• Polymarket tax complexity. Trading on Polymarket’s international (CLOB) app involves USDC (a cryptocurrency), which may trigger separate capital gains events on the underlying crypto asset in addition to gains or losses on the prediction market contracts themselves. This double taxation layer adds complexity. Polymarket US accounts are held in US dollars, so this layer does not arise there.
• Record-keeping. Automated trading systems should log every order, fill, and settlement with timestamps, prices, and quantities. Export this data regularly. API-sourced trade logs are generally more reliable than exchange-provided reports for tax purposes, because they capture your complete order history including canceled and partially filled orders.

Getting Started

To begin building with prediction market APIs:

1. Open a Kalshi account and generate an Ed25519 (or RSA-2048) key pair. Register the public key under Profile Settings → API Keys and note your Key ID.
2. Install an official SDK (pip install kalshi_python_sync or kalshi_python_async; npm install kalshi-typescript) and authenticate against the demo host with a simple balance query before touching production.
3. Query market data — list active CPI markets, fetch an orderbook, and retrieve recent trades. Verify that data matches what you see on the Kalshi web interface.
4. Add Polymarket if you need it — pip install polymarket-client / npm install @polymarket/client for the global CLOB, or polymarket-us for the CFTC-regulated US venue.
5. Build a monitoring bot (as described above) before attempting any order placement.
6. Paper trade by logging theoretical orders without submitting them to the API. Compare your theoretical P&L to actual market outcomes over 2-4 weeks.
7. Start small. When you begin live trading, use the minimum position size ($1 contracts) until you have verified that your order placement, position tracking, and risk management systems work correctly in production.