Polymarket Kalshi Trading

oddsrail

An MCP server that lets your AI assistant trade on Polymarket (and Kalshi) without handing your keys to anyone.

Point your MCP client at it and your assistant can search markets, read order books, work out what an order would really cost, and place orders. Orders are signed on your own machine. Everything starts in dry-run: Polymarket orders fill against the live order book into a paper account (Kalshi dry-run orders just show what would be sent), so you can watch what your agent does before any money is involved.

We built it after tripping over the Polymarket API ourselves. Rejected orders come back as normal responses with ok: false. Order books arrive sorted worst price first. The "trades" endpoint returns everyone's trades, not just yours. Marketable orders under $1 fail, and that minimum isn't documented. oddsrail handles each one.

That's a real check on a live market. The agent meant to buy NO, built the order on the YES side, and check_order blocked it. Polymarket would have taken it as a normal order.

Before you start. These are tools, and nothing here is financial advice.

You decide every order. Prediction markets are restricted in a lot of places, so

check that you're allowed to trade where you live. oddsrail is an

independent project, not affiliated with or endorsed by Polymarket or Kalshi.

If oddsrail is useful to you, a ⭐ on this repo helps other people find it.

Install

You need Python 3.11 or newer.

pip install oddsrail

Add it to your MCP client as a local (stdio) server: the command is oddsrail, with no arguments. For clients that use JSON config:

{"mcpServers":{"oddsrail":{"command":"oddsrail","args":[]}}}

Have your assistant run server_info first. It shows whether you're in dry-run, which builder code orders will carry, and whether Polymarket is reachable from your network. Then try something like *"search markets about the next Fed rate decision and run the overshoot signal on the favorite"*.

Other ways to install

The plugin and the one-click links start the server with uvx, so they need uv installed. Without uv, pip install oddsrail gives you an oddsrail command you can point any client at.

To run from a clone without installing:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

Then use /abs/path/to/oddsrail/.venv/bin/python with arguments ["-m", "oddsrail.server"] in your client's config.

Setup guides, wallet notes and trading limits are in the documentation.

What's in it

42 tools and four workflow prompts.

• Polymarket data: search_markets, get_market, get_orderbook, price_history, get_positions, resolution_criteria (what resolves YES, who decides, from which sources), closing_soon, and watch_book, which streams live book updates for up to 60 seconds.
• Costs and signals: quote_cost walks the order book for your size and returns the average fill price, slippage, notional and the market's fee schedule where Polymarket publishes one (fees aren't added into the cost). overshoot_signal flags sudden price jumps and shows how far earlier jumps in the same window came back. dispute_risk is a rough 0 to 100 heuristic, with its reasons, for how likely a market's resolution is to be contested. position_size is capped fractional Kelly sizing that refuses bets with negative edge.
• Checking an order: check_order (more below).
• Trading: place_order, cancel_order, open_orders, order_status, my_fills, my_positions, my_balance, and cancel_all_orders as the emergency stop. Prices are probabilities between 0 and 1 and sizes are in shares, so an order's notional is price times size.
• Gasless position management: split_position, merge_positions and redeem_positions go through Polymarket's relayer; redeemable_positions lists what your wallet could redeem or merge right now.
• Paper trading: paper_positions, paper_reset.
• Kalshi: search, market details, order book, recent trades, balance, positions, open orders, placing and cancelling (kalshi_*, nine tools).
• Across venues: find_markets, compare_venues and settlement_audit. A price gap between two venues is not free money; the settlement audit checks whether the two markets actually resolve the same way.
• Attribution and status: builder_stats, attribution_ledger, server_info.

The prompts (find_fade_setup, check_cross_venue_edge, settle_resolved, daily_review) each walk an agent through one job step by step. find_fade_setup, for example, goes signal, book, cost, resolution rules, size, check, then a dry-run order. The skills in skills/ are generated from those prompts, and a test fails if they drift apart.

Checking orders before they go out

check_order compares the order your agent built with a short paraphrase of what was asked for and with the live market. It checks that the market exists and is open, that the wording matches the market and the YES or NO side, that the price makes sense against the book, that the size clears Polymarket's $1 minimum and your limits, that there's liquidity within your price, and that a resolution source is named. You get ok, caution or block, with the evidence for each check. There's no model involved; it's plain Python checks.

It only runs when your agent calls it. place_order doesn't call it for you, so tell your agent to check every order first.

Staying safe

• Dry-run is the default. Only ODDSRAIL_DRY_RUN=0 (or false, or no) turns on live trading. Any other value keeps you in dry-run.
• Paper orders persist. In dry-run, Polymarket orders fill against the live book into a local paper ledger (~/.oddsrail/paper.json, starting at $1,000). Whatever doesn't fill rests and can fill later if the market crosses it. Paper fills ignore queue position, latency, market impact and fees, so treat paper results as a best case.
• Limits no tool can change. You set them as environment variables (see Configuration). The per-order cap and the allowed markets apply in dry-run too; the session cap and the open-order cap count live orders only. They're checked before anything is sent, and a refusal says exactly which rule stopped the order:

  {"accepted": false, "blocked_by": "guardrail", "rule": "max_order_notional",

"limit": 25.0, "requested": 99.5, "note": "refused by an operator-set guardrail ... Nothing was sent."}

The session budget resets when the server restarts. server_info shows your limits and how much of the session budget is used.

• Clients can ask before trading. Every tool that places or cancels orders or moves funds is marked destructive in its MCP annotations, so clients that support it can ask you to approve each call.

Going live

Set POLYMARKET_PRIVATE_KEY (and POLYMARKET_WALLET_ADDRESS if your account uses a proxy or deposit wallet), set ODDSRAIL_DRY_RUN=0 and restart. The key stays on your machine; Polymarket gets signed orders and API credentials derived from the key, never the key itself.

For gasless split, merge and redeem, create your own relayer key at polymarket.com (Settings, Relayer API keys) and set POLYMARKET_RELAYER_API_KEY and POLYMARKET_RELAYER_API_KEY_ADDRESS. Without both, those tools send nothing; they never fall back to paying gas from your wallet. Polymarket allows 100 relayer requests a day for unverified builders and 10,000 for verified ones.

A 1 USDC split and merge through the relayer on 2026-09-02 is written up in the live verification notes. redeem_positions hasn't been exercised live yet, because the test account hasn't held a resolved winning position.

Fees and builder codes

oddsrail is free, and it adds nothing to your trades. By default your orders carry our builder code (0xa576c5ce…, registered at 0 bps for both makers and takers), so Polymarket attributes the volume to the project without charging you anything for it. Orders sent from this server earn the project a share of Polymarket's weekly builder rewards, which Polymarket pays from its own program. Separately, oddsrail.app's links to Polymarket and its Perps authorizations carry our referral code, which pays the project a share of Polymarket's own fee without changing yours. There's no paid tier.

You can use your own code instead. Get one at polymarket.com (Settings, Builders), where you set your own fee rates (takers up to 100 bps and makers up to 50 bps, on top of platform fees, paid to your builder wallet), and set ODDSRAIL_BUILDER_CODE. The code goes into the order before it's signed, so attribution is on-chain. server_info shows which code is in use and builder_stats lets you check the attribution. The oddsrail builder profile was verified in Polymarket's builder program on 2026-09-02.

The hosted version

If you'd rather not install anything, add https://mcp.oddsrail.app/mcp as a remote MCP server in a client that supports OAuth, and sign in with your email (you get a one-time link). Example prompts and troubleshooting are in the hosted connector docs.

The connector is paper trading only. Each account gets a $1,000 paper bankroll that fills against the live Polymarket book. Its tools use no wallet keys and never send a real order, and Kalshi isn't available there. It has 22 of the 42 tools; oddsrail/hosted.py shows exactly which are removed and why:

• Market data: search_markets, find_markets, get_market, get_orderbook, price_history, watch_book, closing_soon, resolution_criteria, get_positions
• Costs and signals: overshoot_signal, dispute_risk, quote_cost, position_size
• Paper trading: check_order, place_order, cancel_order, paper_positions, paper_reset
• A public paper arena: arena_register, arena_unregister, arena_status
• Status: server_info

Your account holds your email address, the sign-in records for the client you connected, your paper ledger and, only if you set them up, an arena entry or a hosted paper agent. The details are in the privacy policy.

The website at oddsrail.app also runs hosted agents and a leaderboard. Real-money hosted agents are a small pilot for allowlisted wallets, use a session key for a Deposit Wallet, and don't go through these tools. Signing in to the website with a wallet lists it on the public leaderboard under a shortened address; the privacy policy explains how to be removed. The hosted service and the website are developed in a separate private repository. This repository is the MCP server.

Where it works

Two different things can stop an order, and they look different.

Polymarket's own restrictions apply to orders, not connections. Market data loads normally and then orders get rejected. A few places are blocked co