oddsrail

AI 代理用来交易预测市场的轨道。

一个 MCP 服务器，让任何 agent（Claude Code、Claude Desktop 或任何兼容 MCP 的工具）都能通过 Polymarket 和 Kalshi 获取预测市场能力：市场搜索、订单簿、价格历史、持仓和订单路由——在 Polymarket 上配有链上 builder-code 溯源——外加两个高级信号工具（盘中超调/回落检测、决议争议风险）。

商业模式：被路由的订单流赚取 builder 费用；信号工具是付费的数据层（计划中的 x402 按次付费）。

为什么是它而不是 Parsec

最接近的竞争对手（parsecapi.com）是闭源托管服务：它保存你的交易密钥（或者持有一个替你签名的托管钱包），而且它的 Builder Program 会抽走 builder 收取费用的 55–85%。oddsrail 在每一个方面上恰恰相反：自托管，非托管（密钥永远不离开你的机器），开源，而且你保留 100% 的 Polymarket builder 费用，因为归属使用的是 Polymarket 的原生机制，而不是中间托管。Parsec 完全没有任何信号/分析工具，完全没有关于决议风险的内容——这正是我们付费分层所提供的。

快速开始

需要 Python 3.11 以上。创建 venv、安装，然后接入 Claude Code：

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

claude mcp add --transport stdio oddsrail -- /abs/path/to/oddsrail/.venv/bin/python -m oddsrail.server

然后让 agent 执行："搜索有关世界杯决赛的市场，并在热门选项上运行超调信号"。

具体有什么用（CLOB V2，2026 年 8 月已验证）

1. 在 polymarket.com → Settings → Builders 中获取你的 builder code（一个 bytes32 值）。在那里设置你的手续费率：taker 最高 100 个基点，maker 最高 50 个基点——这是在平台费用之外的，结算到你的 builder 钱包。

2. 在服务器运行时执行 export ODDSRAIL_BUILDER_CODE=0x...。

3. 每次任何 agent 通过 place_order 路由的订单，都会在签名前 将代码放在 V2 订单结构的 builder 字段——归属是在链上的，在 CTF Exchange V2 上每个 OrderFilled 事件中都可见。

4. 使用 builder_stats 工具进行验证（公共 builder-trades 端点 + 排行榜）。

环境变量

状态 —— 2026-08-23 实测验证

所有 10 个可调用工具都通过真正的 MCP 客户端会话在真实 Polymarket 上端到端驱动，运行于芬兰 VPS（/opt/oddsrail）。已验证可用的部分：搜索、市场查询、订单簿（9/65 层）、price 历史、超调信号、决议风险、builder 排行榜、dry-run 订单、open 订单、服务器信息。

在那一轮验证中，针对真实 API 修正了字段映射——文档猜测的形状在三处都是错的（outcomes 是一个以 yes/no 为键的字典，search() 把市场嵌套在 events 里，以及 book/volume/resolution 数据位于 prices/metrics/state/resolution 子对象中）。

⚠️ 网络说明

Polymarket API 的域名在**土耳其的（BTK）**被屏蔽；本地测试到网络拦截页面，无法建立 TLS。请把服务器放在能访问 Polymarket 的地方（例如芬兰 VPS /opt/oddsrail、VPN 或其他可用的网络）。信号逻辑和 MCP 层都可以完全即可离线测试。

Kalshi（第二交易所）

Kalshi 是自带密钥、单租户设计的：运营者提供自己的 API 私钥，自行对自己的账户交易，并且这个服务器不缓存任何数据。这是重大决定的——Kalshi 开发者协议限定了 API 只能用于成员自己交易（§3）、限制协助他人交易（§3.2）以及对 API 转授权（§3.7）、限制存储/共享 API 数据（§3.1）。一个托管式的多租户 Kalshi 服务并不合规；而自托管是合规的。

这里不存在归属。 Kalshi Builder Codes 是 Solana/DFlow/Jupiter 的集成功能——REST API 上没有任何 builder 或 affiliate 字段，因此 Kalshi 的订单流无法像 Polymarket 那样获得归属或赚取收入。Kalshi 纳入 oddsrail 是为了覆盖和信号能达的场景，而不是为了路由收入。

这个 API 有两个结构容易搞错，所以 oddsrail 对两种情况都做了规范化：

• 价格是美元字符串，不是美分整数（如 "0.5600"），数量是固定小数串（"10.00"）；旧的那些整数美分字段已在 2026 年 3 月移除。所有数值计算都用 Decimal。

• 订单簿两侧都只有 bid。 yes_dollars 和 no_dollars 都是升序排列的 bid 阶梯，所以最优出价是最后一个元素，而 NO bid $0.99 就是 YES ask $0.15。kalshi_get_orderbook 返回传统的最佳优先 bid/ask 的 YES 视图，并提供原始阶梯。

委托就是用自然语言描述——outcome（yes/no）、action（buy/sell）、price = 该结果出现的概率——然后内部映射为 Kalshi 的 YES-book bid/ask`（0.25 买单 NO 对应 0.75 的 ask）。这个翻译有单元测试把关，因为它是最容易造成持仓反向 bug 的地方。

凭据：KALSHI_KEY_ID 加上 KALSHI_PRIVATE_KEY_PATH（PKCS#8 PEM）或直接提供一个 KALSHI_PRIVATE_KEY。设置 KALSHI_DEMO=1 指向演示环境。读取类工具完全不需要任何 key。

工具（21）

• search_markets、get_market、get_orderbook、price_history、get_positions —— 只读，不需要 key，不需要 key

• overshoot_signal — 高级：追踪 panic-jump 波数个，并给出该市场历史占比中的回归倾向（从 polymarket-wc 分析器移植来）

• dispute_risk —— 高级：为争议型（UMA 争议风险较高）的决议提供透明无保留的 0–100 启发式评分

• place_order、cancel_order、open_orders —— 交易，默认 dry-run

• builder_stats —— 归属检验 + 公开 builder 排行榜

• server_info —— 每个交易场景的配置情况

Kalshi 类型：kalshi_search_markets、kalshi_get_market、kalshi_get_orderbook、kalshi_get_trades、kalshi_balance、kalshi_positions、kalshi_open_orders、kalshi_place_order、kalshi_cancel_order。

技术栈说明

• 官方 SDK polymarket-client（0.6.x）: 用 AsyncPublicClient 获取数据，用 AsyncSecureClient.place_limit_order(..., builder_code=...) 发出作归属的订单。旧版 py-clob-client 已经不再维护，无法附加 builder codes——请别再用。

• MCP SDK 2.0: 从 mcp.server.mcpserver 中使用 MCPServer（旧版的 mcp.server.fastmcp.FastMCP 在 2.x 里不再提供）。

• 支持 Kalshi 的是简陋的 httpx + cryptography，而非官方 SDK：kalshi-python-sync 需要 Python >=3.13，并且与公开 API 每周发布以对版本相符。验签用 RAPSS-, PSS(SHA512, salt = 消息摘要长度)，在 str(unix_ms) + METHOD + path 上做，其中 path 会包含 /trade-api/v2 且不含查询串。基础 URL 现在是 external-api.kalshi.com。

• x402（筹划中）：官方 PyPI 包封装 x402（v2.20+）可直接包住 MCP 工具端（x402.mcp，支付通过 _meta 注入），但目前它的相关 helpers 只支持 MCP 1.x——集成时要么固定 mcp>=1.28,<2，要么等待 2.x 兼容的版本。产生真实交易的结算需要接入中介（Coinbase CDP：前一千次每月免费，之后每笔 $0.001）。保留两个信号的少量免费额度，这样目录索引器就能仍旧索引我们的服务器索引。

builder 经济形态（实时，2026-08-23）

从公开的排行榜上提取信息（通过 builder_stats）：

真正能说明问题的是那些小户行：MagicMarkets 每周路由 $354K 但只有 1 个没有任何主动用户，Gate 每秒 $1.11M 但只有 2 个用户在背后，PolymarketScan 每周 $277K 有 3 个 客户。这个是纯做策略的马甲机器人——这正符合 oddsrail 的目标——说明一个努力运营的主力 agent 交易者对规模来说很实际。钱包形式（比如 MetaMask，37K 用户）占优势的是参与 wallet 的数量 ，但每用户贡献的规模却在 wallet 上的总交易量。

路线图

1. 在有合法网络的设备上做完整直播测试 —— 2026-08-23 已完成，所有工具通过

2. 注册 builder code（polymarket.com → Settings → Builders），改为 0 bps 开始，导出 ODDSRAIL_BUILDER_CODE；首笔用月数很小额度下单

3. 让 Kalshi 作为第二项 交易场景 —— 2026-08-23 已完成，9 个工具，并做有效验证

4. 在 mcp-2.x 兼容事宜后，为两个信号添加 x402 付费访问接口

5. 注册在列表上：官方 MCP 注册表（mcp-publisher，PyPI 上的 mcp-name:字段）、Smithery（需要 一个公开 streamable-HTTP 和一个允许他们扫描的自由工具）、Glama（glama.json）

上架 / 分发

• GitHub：https://github.com/hmesutozsoy/oddsrail（公开 MIT 许可）

• Glama：Glama 会自动爬 GitHub；项目根目录的 glama.json 用来表明维护身份。

• 官方 MCP 注册表：server.json 已就绪。需先在 PyPI 上发布包（注册表会通过 PyPI README 文件中的 mcp-name: io.github.hmesutozsoy/oddsrail 标记来验证所有权），然后执行 mcp-publisher login github 和 mcp-publisher publish。

• Smithery：需要公开的 HTTPS streamable-HTTP 端点，可在有机会时，当 oddsrail 是部署在线上而非本地 stdio 运行。