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".

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.

Related MCP server: telekash-mcp-server

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 completely; many more are close-only, meaning you can close positions but not open new ones. That list includes the United States, the United Kingdom, France, Germany and Australia, among others. In sanctioned places you can't even close positions, and a few countries (Ireland, Japan, the Netherlands, and Malta for sports) are close-only on Polymarket's website but not through the API. The list changes without notice, so check Polymarket's list rather than relying on this README.

Network filters block the connection itself. Turkish ISPs block polymarket.com, for example, even though Polymarket doesn't restrict Turkey. You'll see DNS failures, TLS errors or an ISP page where data should be. oddsrail tells your agent which of the two it ran into.

oddsrail doesn't support Polymarket US (polymarket.us). That's a separate, CFTC-regulated exchange with its own API, keys and SDK.

server_info reports Polymarket's verdict for your IP address, but that's a network probe, not a compliance check. Polymarket's terms ask you to confirm you're not a US person, not in a restricted jurisdiction and not using a VPN to get around restrictions. That's between you and Polymarket; if it matters for you, get legal advice.

Privacy and network access

The local server has no telemetry or analytics and never contacts oddsrail.app or any other server we run. It only talks to the venues and blockchain hosts below, and only when a tool needs them. Each of them sees your IP address.

server_info also sends one unauthenticated reachability check each to gamma-api, clob, data-api and external-api.kalshi.com (plus the relayer when a trading key is set). Installing with pip or uvx downloads packages from PyPI through your package manager.

Your keys, the limit counters and the paper ledger stay on your machine. Your AI client sees every tool call and result, under its provider's own policy.

Configuration

If watch_book fails with CERTIFICATE_VERIFY_FAILED while everything else works, your Python has no CA bundle (common with the python.org installer on macOS). Run Install Certificates.command from the Python folder in Applications, or set SSL_CERT_FILE to the path printed by python -m certifi.

Polymarket Protocol V2

Polymarket is rolling out a new Protocol V2. It's separate from the CLOB V2 order format this server already uses for builder attribution, so don't read one as support for the other. The 0.20.0 release candidate on main updates the SDK and market discovery for V2, but live V2 orders and split, merge and redeem on V2 markets are refused before signing until they've been tested with real funds. The stable desktop bundle still pins oddsrail==0.19.0. Details are in the readiness notes.

Other options

If you're comparing tools: pmxt covers many more venues, offers a hosted mode and has a much bigger community. Simmer has a virtual-money sandbox, stop-loss and take-profit, and a strategy marketplace. Polymarket's own agent-skills document the API, including deposits and bridging, which oddsrail doesn't cover. oddsrail is narrower: self-hosted, your keys, your builder code, and a check that catches wrong-side or mispriced orders. (Compared in September 2026; these projects move quickly.)

Tests

The test suite runs offline in CI on Python 3.11, 3.12 and 3.13 and covers spending limits, concurrent submissions, order reconciliation, book walking, sizing, dry-run behavior and attribution. See the testing guide for the locked environment and commands. The latest release check placed no funded orders, and the live relayer test above was done with version 0.10.1.

Security

Please report vulnerabilities privately, not in a public issue. See SECURITY.md.

License

MIT. The MCP server in this repository is open source; the hosted service and the website are not.