polymarket-kalshi-trading

oddsrail

为你的 AI Agent 提供 Polymarket 工具，并支持本地签名和支出限额。

如果 oddsrail 对你有帮助，请在此仓库点一个 ⭐，帮助更多人发现它。

oddsrail 是一个开源 MCP 服务。它为兼容 MCP 的 AI 客户端提供 Polymarket 的 实时市场数据、含成本的成交信息和订单路由。 由运营者设置的防护措施会强制执行订单限额。单独的确定性 check_order 工具会在提交前检查市场、结果和价格； 请让你的 Agent 在每笔订单前调用它。它无法保证 Agent 会选择或执行合理的策略。

披露。 oddsrail 提供的是信息工具，不构成财务 建议。每笔订单都由你决定：除非你使用自己的密钥开启实时 交易，否则不会发送任何真实订单。预测市场在许多司法管辖区受到限制， 你有责任确认自己是否有资格在居住地进行交易。oddsrail 是独立项目，与 Polymarket 或 Kalshi 无关联，也未获其认可。

这是实时市场上的真实 check_order 结果，并非模型图。Agent 的意图是 NO，却构建了 YES 订单。若没有这项检查，它就会站在交易的 另一方，而且不会有任何提示。

• 提交前检查。 check_order 会检查市场、方向、 价格和平台最低限额。运营者设置的防护措施会在订单路径中生效； 是否调用单独的检查工具仍由 Agent 负责。
• 非托管。 你的密钥保留在自己的设备上。一切都从 dry-run 开始，并使用实时订单簿进行模拟账本成交。
• 免费使用，费率为 0 bps。 oddsrail 不会从你的交易中收取费用；参见 资金来源。

请阅读 OddsRail 文档，了解设置、 钱包、交易限额和开发者说明。

选择设置方式

使用本地 MCP 服务搭配你偏好的 AI 客户端，包括 Codex 或 Cursor。安装会连接工具，但不会启动 Agent。 客户端无关的设置方法请参阅开发者快速入门。

开发者快速入门

需要 Python 3.11+。

pip install oddsrail

在客户端中配置本地 stdio MCP 服务，命令为 oddsrail， 且不带参数。对于使用 JSON 配置的客户端：

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

各客户端的配置格式有所不同；命令和参数保持不变。 请先使用 server_info 验证连接和 dry-run 模式。

或者从克隆的仓库运行，无需安装：

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

在客户端的本地 MCP 配置中，使用命令 /abs/path/to/oddsrail/.venv/bin/python，参数为 ["-m", "oddsrail.server"]。

然后询问 Agent：“搜索世界杯决赛相关市场，并对热门方运行 overshoot 信号。”

按客户端安装

各客户端的安装命令和链接

客户端	操作方法
可读取技能的任意 Agent	npx skills add hmesutozsoy/oddsrail
Cursor	在 Cursor 中安装 oddsrail
VS Code	在 VS Code 中安装 oddsrail
其他任何支持通过 stdio 使用 MCP 的客户端	{"command": "uvx", "args": ["oddsrail"]}（或者运行 pip install oddsrail 并执行 oddsrail）

该插件和一键安装链接会通过 uvx 启动服务，因此机器上需要安装 uv。如果没有 uv，pip install oddsrail 会提供一个 oddsrail 命令，供任意客户端调用。 所有操作均以试运行模式启动。

这四个技能（skills/*/SKILL.md）由 scripts/gen_skills.py 根据服务自身的 MCP 提示词生成，并且测试会在内容不一致时失败，因此技能及其对应的提示词绝不会相互矛盾。

oddsrail 与其他方案的对比

直接对照每种替代方案进行核实（查看其代码仓库、在线端点和注册表条目，时间为 2026 年 9 月），而非依据其营销宣传：

	oddsrail	原始平台 API	pmxt	Simmer	Polymarket agent-skills
产品形态	可自托管的 MCP 服务	平台本身	统一 API + SDK + MCP，“预测市场领域的 CCXT”	Agent 交易平台 + SDK + MCP	面向 Agent 的 Markdown 技能文档
资金托管	非托管；密钥不会离开你的设备	由你掌控	托管模式：“PMXT 负责资金托管和签名基础设施”；自托管模式：使用你的密钥	自托管，使用本地签名	由你掌控（仅提供文档）
由你掌控的归因	是：ODDSRAIL_BUILDER_CODE 可覆盖默认的 0 bps	不适用	未说明	未说明	为你自己的代码提供 builder 标头文档
交易者的成本	0 bps，工具免费	免费	README 中未说明托管模式的定价	未说明	免费
开源	MIT，MCP 服务的完整源代码	不适用	MIT，约 2.1k 个 star	未说明	文档；未说明许可证
操作员护栏	名义金额上限、未平仓订单上限、允许交易的市场；发送订单前进行检查。每笔订单上限和允许交易的市场在 dry-run 模式下也适用；会话上限和未平仓订单上限仅统计实盘订单。	无	未说明	单笔交易限额、每日限额、止损／止盈、紧急停止开关	无
模拟交易	根据实时订单簿模拟成交并计算盈亏	无	未说明	虚拟 $SIM 沙盒，然后再过渡到真实资金	无
按订单簿计算的成本、结算审计、按司法管辖区分类的失败情况、带日期的平台特性说明	是，四项俱全	无	未说明	未说明	部分记录了平台特性
实时功能	watch_book，有界	websocket，由你自行接入	README 中未说明	未说明	文档说明了 websocket

核实日期为 2026-09-02，信息来自各项目自己的 README 或文档（pmxt：github.com/pmxt-dev/pmxt；Simmer：docs.simmer.markets；agent-skills：github.com/Polymarket/agent-skills）。“未说明”仅表示确实未作说明，并不代表“没有”。引用前请重新核实；这些项目都在不断发展。

一句话概括差异化优势： pmxt 是面向“在所有平台交易”的标杆；Simmer 是拥有沙盒和声誉层的 Agent 经济体标杆；oddsrail 则是“以正确、非托管且归因由你掌控的方式进行交易”的标杆。

其他方案确实领先之处： pmxt 提供更广泛的交易和数据平台覆盖，托管模式更便捷，社区规模也大得多。Simmer 提供我们尚不具备的虚拟余额沙盒、止损和止盈护栏、公开的推理／声誉层，以及策略技能市场。Polymarket 的 agent-skills 是平台自己的文档，涵盖了桥接和存款，而 oddsrail 不涉及这些内容。

原始 Polymarket API 确实包含这些端点。但它也将拒绝操作表示为 ok:false 返回值，按从差到好的顺序排列订单簿，提供一个返回市场公开成交记录的交易端点，并强制执行一笔未公开说明的 1 美元最低名义金额。oddsrail 正是因为遇到了上述所有问题，才应运而生并将解决方案落实其中。

免费使用，且不收取费用

默认情况下，订单会携带 oddsrail 自己的 builder code，该代码的费率已登记为 0 bps；这会将订单归因到项目，而不会给任何人的交易增加哪怕一个基点。设置 ODDSRAIL_BUILDER_CODE 后，订单会改为携带你的代码。项目收入来自 Polymarket 每周 builder 奖励池的分成，由 Polymarket 自己的计划支付，而非由你支付。 server_info 始终会告知当前使用的代码。所有工具都免费： 没有费用等级、付费工具或账户要求，目前也不提供付费等级。

托管服务：无需安装

mcp.oddsrail.app 以远程 MCP 端点的形式运行同一服务，并提供账户功能。请使用支持远程 HTTP 连接和 OAuth 的 MCP 客户端。添加 https://mcp.oddsrail.app/mcp，然后在客户端请求授权时使用电子邮件登录（通过一次性登录链接）。后续调用将使用该账户。示例提示词和故障排查信息见托管连接器文档。

简而言之，这个 MCP 端点提供 Polymarket 市场数据、信号工具、check_order，以及每个账户拥有 $1,000 虚拟资金、按实时订单簿成交的模拟交易。它不是什么？不是资金会实际流动的地方。其工具不使用钱包密钥、不执行真实订单，也不提供 Kalshi 工具。账户范围内的工具和操作员工具会被移除，因为在共享服务上，它们会指向无人拥有的账户，或列出其他人的钱包：open_orders、order_status、my_fills、my_positions、my_balance、cancel_all_orders、无 Gas 中继工具、redeemable_positions、builder_stats、attribution_ledger、compare_venues、settlement_audit，以及所有 kalshi_ 工具。共保留 22 个工具：

• 市场数据：search_markets、find_markets、get_market、 get_orderbook、price_history、watch_book、closing_soon、 resolution_criteria、get_positions
• 信号与成本：overshoot_signal、dispute_risk、quote_cost、 position_size
• 模拟交易：check_order、place_order、cancel_order、 paper_positions、paper_reset
• 公共竞技场榜单：arena_register、arena_unregister、arena_status， 可将账户的模拟交易账本以你选择的显示名称发布到公共榜单， 也可将其移除
• 状态：server_info

这里的 check_order 也需主动调用：Agent 会在调用 place_order 前调用它；它不会自行运行。

通过 MCP 进行实时交易仍需自托管：使用自己的密钥运行 pip install oddsrail，并在设置 ODDSRAIL_DRY_RUN=0 时，相同的 place_order 会提交真实订单。托管运行器是独立服务。账户会保存你的电子邮件地址、你所连接客户端的 OAuth 记录、模拟交易账本（你可以使用 paper_reset 重置），以及仅在你进行设置时才保存的竞技场条目或托管模拟 Agent。隐私政策：oddsrail.app/privacy。此仓库包含 MCP 服务；oddsrail/hosted.py 列出了托管配置会移除的内容。托管服务和网站在单独的私有仓库中开发，并非开源项目。

Builder 页面与竞赛

你可以通过选择策略、市场和风险限额来构建自己的 Agent。托管报价有单独的账户检查和启动流程。对于本地策略，请保存草稿并打开 AI 客户端设置，查看连接说明和保留你设置的策略简介。

策略简介会要求 AI 客户端进行只读审查。它不会安装策略、启动自主运行器，也不会强制执行 Builder 请求的每日亏损、敞口或市场规则。本地实时交易需要单独设置账户、操作员防护措施和明确授权。激活托管 Agent 需要 Deposit Wallet 的会话密钥；在试点期间，还需要所有者已加入许可名单。

排行榜会列出所有登录 oddsrail.app 的钱包，展示形式与 Polymarket 的排行榜相似。每行显示缩短后的地址（前后各四个字符）；不显示名称、完整地址或个人资料链接。预测市场的利润和交易量采用 Polymarket 公布的数据，统计该地址控制的交易钱包，并经链上验证；Perps 数据则是账户公开的利润、交易量和价值。无需加入或退出：想要移除信息的所有者可通过电子邮件提出申请，并附上由钱包签名的消息。

Protocol V2 兼容性

新版 Polymarket Protocol V2 与下文所述的旧版 CLOB V2 订单格式升级相互独立。不要将 CLOB V2 归因支持视为已验证的端到端 Protocol V2 交易支持。

当前源码使用 Data API v2 读取公开账户数据。托管的 Protocol V2 报价仍仅限于明确指定所有者和市场的金丝雀测试。0.20.0rc2 本地 MCP 候选版本升级了 SDK，并支持协议感知的发现功能。在完成资金验证之前，系统会在签名前拒绝实时 V2 订单以及拆分／合并／赎回操作；不要将此候选版本视为完整的 Protocol V2 实时支持。现有 CTF 市场必须保留各自的路由。

请参阅迁移状态和剩余检查项。 网站部署不会升级本地安装。当前稳定版桌面程序包固定使用 oddsrail==0.19.0；要向这些用户提供后续修复，需要发布经过测试的程序包和桌面程序包。

归因工作原理（CLOB V2，已于 2026 年 8 月验证）

1. 在 polymarket.com → Settings → Builders 获取你的 构建者代码（一个 bytes32）。在那里设置费率：吃单费最高 100 bps，挂单费最高 50 bps；这些费用在平台费用之外另行收取，并结算到你的构建者钱包。
2. 在服务运行的环境中执行 export ODDSRAIL_BUILDER_CODE=0x...。
3. 设置后，任何 Agent 通过 place_order 路由的订单，都会在签名前将你的代码写入 V2 订单结构体的 builder 字段，因此归因会记录在链上，并显示在 CTF Exchange V2 的每个 OrderFilled 事件中。
4. 使用 builder_stats 工具验证（公开的构建者交易端点和排行榜）。

如果不设置，订单会在同一字段中携带随 oddsrail 附带的构建者代码（0xa576c5ce…，已注册的挂单费率为 0 bps、吃单费率为 0 bps），你无需承担费用，交易量则会归因于该项目。设置你自己的代码后会优先使用你的代码；默认值只是默认选项，不会限制你使用自己的代码。

oddsrail 构建者资料已加入 Polymarket 的构建者计划并获得 Verified 认证（2026-09-02）。Polymarket 的构建者团队确认，构建者代码归因是可自托管、非托管式工具的正确做法：产品不会随附任何密钥，代码由运营者自己的钱包附加并签名。

环境变量

变量	默认值	含义
ODDSRAIL_DRY_RUN	1	模拟并返回订单，不会提交。只有设置为 0、false 或 no 才会启用真实交易；其他任何值都会保持模拟运行模式。
ODDSRAIL_BUILDER_CODE	项目默认值	你的 bytes32 构建者代码。覆盖随项目打包的默认值，使归属（以及任何奖励池份额）转而计入你的名下。
POLYMARKET_PRIVATE_KEY	未设置	操作方钱包密钥；仅真实交易时需要。绝不会离开此设备。
POLYMARKET_WALLET_ADDRESS	未设置	代理／存款钱包地址（如果账户使用了此类钱包）。
POLYMARKET_RELAYER_API_KEY	未设置	你自己的 Relayer API 密钥（polymarket.com → Settings → Relayer API keys），用于免 Gas 的 split_position / merge_positions / redeem_positions。
POLYMARKET_RELAYER_API_KEY_ADDRESS	未设置	Relayer 密钥签发对象的地址。必须同时提供这两项；否则免 Gas 工具不会发送任何内容。
ODDSRAIL_MAX_ORDER_NOTIONAL	未设置	防护限制：每笔订单的 USDC 最大名义金额。任何请求发出前都会进行检查，模拟运行时也不例外。
ODDSRAIL_MAX_SESSION_NOTIONAL	未设置	防护限制：此服务进程提交的实时订单累计名义金额上限。
ODDSRAIL_MAX_OPEN_ORDERS	未设置	防护限制：账户挂单数量上限（实时；下单前会与交易平台核对）。
ODDSRAIL_ALLOWED_MARKETS	未设置	防护限制：以逗号分隔的允许交易市场标识符。对于 Polymarket，请使用准确的结果代币 ID。其他任何标识符都会被拒绝。
ODDSRAIL_PAPER	1	使用真实订单簿对 Polymarket 订单进行纸面交易模拟。设置为 0 可禁用。
ODDSRAIL_PAPER_LEDGER	~/.oddsrail/paper.json	纸面交易账本的存放位置。单个本地 JSON 文件。
ODDSRAIL_PAPER_BANKROLL	1000	初始纸面交易资金，单位为 USDC。

隐私和网络访问

本地服务器不会发送遥测、分析或使用数据，也绝不会联系 oddsrail.app 或该项目运行的任何其他服务器。它只会与下方的交易平台和区块链主机通信，而且仅在工具需要时才会通信。每个主机都能看到这台机器的 IP 地址。

主机	何时访问	发送的内容
gamma-api.polymarket.com	搜索市场、查看详情和列表（search_markets、find_markets、get_market、closing_soon、resolution_criteria、check_order、dispute_risk）	你的搜索文本，以及所查询的市场 ID、slug 或代币 ID
clob.polymarket.com	订单簿（get_orderbook、quote_cost、check_order、模拟成交）、构建者交易；使用交易密钥时，还包括订单、撤单和账户读取	代币 ID 和构建者代码；使用密钥时，还包括在此机器上签名的订单，以及通过该密钥派生的凭据进行身份验证的请求。私钥本身绝不会发送。
data-api.polymarket.com	价格历史、持仓、成交记录、投资组合价值、构建者排行榜	代币 ID 和要查询的钱包地址（my_fills 和 my_positions 使用已配置的钱包）
ws-subscriptions-clob.polymarket.com	watch_book websocket	已订阅的代币 ID
polymarket.com/api/geoblock	server_info	请求本身，以便 Polymarket 返回此 IP 所属司法辖区的判定结果
relayer-v2.polymarket.com	使用交易密钥时，在交易客户端启动时进行钱包检查；使用你的中继器密钥时，执行免 gas 的 split_position、merge_positions、redeem_positions	你的钱包地址、签名交易和中继器 API 密钥
公共 Polygon RPC（polygon.drpc.org，即固定版本 polymarket-client SDK 的默认值）	SDK 为免 gas 工具执行链上读取，例如查询余额和预估 gas	公开的钱包和合约地址
external-api.kalshi.com（设置 KALSHI_DEMO=1 时为 external-api.demo.kalshi.co）	kalshi_* 工具、compare_venues 和 settlement_audit；当 venues 包含 Kalshi 时的 find_markets / closing_soon（默认包含两个交易平台）；以及使用 venue='kalshi' 时的 quote_cost / resolution_criteria / check_order	搜索文本和交易代码；使用你的 Kalshi 密钥时，还包括在此机器上签名的请求

server_info 还会分别向 gamma-api、clob、data-api 和 external-api.kalshi.com 发送一次未经身份验证的连通性请求（设置了交易密钥时，还会请求中继器）。使用 pip 或 uvx 安装会从 PyPI 下载软件包及其依赖项；这是你的软件包管理器的行为，不是服务器的行为。

以下内容会保留在此机器上：你的密钥、防护栏计数器和模拟账本（默认路径为 ~/.oddsrail/paper.json）。你的 AI 客户端会看到每次工具调用及其结果，具体受其提供商自身的政策约束。托管连接器 mcp.oddsrail.app 是一项独立服务，需要账户；关于它存储的内容，请参阅隐私政策。

安全

请私下报告漏洞，不要在公开议题中报告。报告方式和漏洞范围请参阅 SECURITY.md。

状态

测试： 0.18.1 版本及后续仅测试版本在 Python 3.11、3.12 和 3.13 上通过了 1,356 项 Python 测试，另通过了 119 项 JavaScript 测试。测试覆盖支出限额、并发提交、订单核对、订单簿遍历、下单规模、试运行行为、钱包身份验证和构建者移交。锁定环境和命令请参阅测试指南。

发布验证： 安装器启动命令安装了已发布的 PyPI 软件包，并完成了一次真实的 MCP 会话。默认和意外的模式设置均保持在模拟状态。此次发布检查未提交任何有资金支持的订单；仍需测试通过桌面宿主界面安装以及使用真实资金交易。

更早进行的 Polymarket 集成检查（包括归因订单和免 gas 持仓管理）记录在实时验证说明中。

适用范围

有两种不同的情况会阻止 oddsrail 交易，且应对方法截然相反。一种是交易平台施加的限制，会在下单时生效；另一种是网络过滤，会直接切断连接。

Polymarket 限制。 Polymarket 将受限司法管辖区列表作为 API 参考文档发布：https://docs.polymarket.com/api-reference/geoblock。限制分为三个级别。受 OFAC 制裁的司法管辖区（伊朗、叙利亚、古巴、朝鲜，以及乌克兰的克里米亚、顿涅茨克和卢甘斯克地区）在前端和 API 上均被屏蔽，既不能下新单，也不能平掉现有头寸。更长的第二级名单在前端和 API 上均仅允许平仓：可以平掉现有头寸，但不能开新仓。其中包括美国、英国、法国、德国、意大利、波兰、斯洛伐克、比利时、新加坡、澳大利亚、新西兰、巴西、俄罗斯、台湾、泰国，以及加拿大的安大略省、魁北克省、不列颠哥伦比亚省和艾伯塔省。第三级名单包括爱尔兰、日本、马耳他（仅限体育类）和荷兰，在 Polymarket 前端仅允许平仓，但 API 明确不受限制。

请注意这种故障的表现：它发生在下单时，而不是连接时。公开读取请求会正常返回，因此 oddsrail 看起来会一直正常工作，直到订单被拒绝。以上内容已于 2026-08-31 根据 Polymarket 文档核实；Polymarket 可能随时更新名单而不另行通知，因此请查阅该 URL，不要只依赖本段内容。

美国。 oddsrail 接入的交易平台 polymarket.com 在美国仅允许平仓。Polymarket 还单独运营 Polymarket US（polymarket.us），由 QCX LLC 运营，是受 CFTC 监管的指定合约市场。**oddsrail 不支持它。**它使用不同的 API 主机、不同的身份验证方式（使用 API 密钥请求头，而非 EIP-712 钱包签名）、不同的 SDK 和不同的资金渠道。polymarket.us 账户及其密钥无法用于此服务。

网络过滤。 除交易平台自身的规则外，国家级过滤可能会直接屏蔽相关域名。土耳其就是如此：Polymarket 不限制土耳其，但土耳其的 ISP 会屏蔽 polymarket.com。这是连接问题，而不是资格问题，其表现也有所不同：DNS 故障、TLS 错误、连接重置，或在本应返回 JSON 的地方出现 ISP 的拦截页面。oddsrail 会识别这两种情况，并告知调用它的 Agent 遇到了哪一种。

资格由运营者负责，而非工具。 oddsrail 可自托管且非托管，这确实有优势，但也意味着账户由你持有，平台要求的声明也由你作出；没有中间方代你作出这些声明。Polymarket 的交易流程要求你确认自己不是美国人士、不位于受限司法管辖区，也没有“使用 VPN 或其他措施规避或试图规避”限制，并声明 Polymarket 保留将不合规钱包设为仅允许平仓模式的权利。server_info 会报告 Polymarket 根据此设备的 IP 得出的地理封锁判定，但技术探测不等于合规审查：条款约束的是居住地、公民身份和注册地，而不是出口 IP。请阅读相关条款；如果这涉及你的情况，请自行寻求法律意见。本文不构成法律建议。

无论如何，信号逻辑、MCP 层和整套测试都能在离线环境下正常运行。

护栏：Agent 无法争辩的限制

任何要把密钥交给 Agent 的人，首先都希望设置三项限制：单笔订单上限、 单次会话上限，以及限制它可以操作哪些市场。再加上挂单上限，这些限制 都由运营者通过环境变量设置（见上表），并且会在发送订单之前进行检查。 单笔订单上限和允许操作的市场在 dry-run 模式下同样适用；会话上限和未结订单 上限只统计实盘订单。拒绝操作时会返回结构化答复，指出规则、限制和请求：

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

会话计数器存储在服务进程中；重启服务会重置预算，由运营者自行决定。 server_info 会报告当前生效的限制，以及会话预算的使用情况。

模拟交易：带记忆的 dry-run

默认情况下，每笔 Polymarket dry-run 订单都会在实时订单簿中成交，并在 限价范围内逐档撮合；未成交部分会作为模拟订单挂起，如果之后市场价格触及该价格， 便会成交。paper_positions 会报告现金、按当前标记价格计算的持仓、已实现和未实现 盈亏，以及挂起的模拟订单；paper_reset 会重新开始。账本是一个本地 JSON 文件。 请明确其局限：成交模拟假设没有排队位置、延迟、市场影响和手续费，因此模拟结果 只是同一策略实盘表现的上限。

实时行情：观察订单簿变化

watch_book(token_id, seconds, max_events) 会订阅某个 token 的实时行情流，并返回 收到的事件（订单簿快照，随后是价格变化和交易），时长最多为 60 秒，避免 Agent 在 行情平淡时一直占用会话。当决策取决于订单簿的变化，而不仅仅是其当前状态时， 请在调用 get_orderbook 后使用此工具。

如果实时行情流报错 CERTIFICATE_VERIFY_FAILED，而 REST 工具可以正常工作，说明你的 Python 没有 CA 证书包（这在通过 python.org 安装的 macOS 版本中很常见）。 oddsrail 会将其归类为 local_tls，并告知 Agent 如何修复：在 /Applications 中的 Python 文件夹里运行 Install Certificates.command，或将 SSL_CERT_FILE 设为 python -m certifi 输出的路径。

免 Gas 持仓管理（中继器）

以下三个工具通过 Polymarket 的中继器转移抵押品，无需支付 Gas： split_position（USDC → 一整组 YES+NO）、merge_positions（匹配的 YES+NO → USDC，或 max）以及 redeem_positions（已结算市场中的获胜 份额 → USDC）。这三个工具都遵循 dry-run 设置，并返回中继器交易 ID 和哈希，以及最终结果。

它们使用你自己的 Relayer API 密钥，可在 polymarket.com → Settings → Relayer API keys 中创建，并导出为 POLYMARKET_RELAYER_API_KEY + POLYMARKET_RELAYER_API_KEY_ADDRESS。这是 Polymarket 构建团队为可自托管的 工具推荐的做法：oddsrail 不会附带构建者密钥，每位运营者都以自己的身份向中继器 进行身份验证。中继器的请求限制因构建者等级而异：未验证用户每天 100 次，已验证用户 每天 10,000 次。没有密钥时，这些工具会返回结构化的“未配置”答复，不会发送任何请求； 也绝不会回退到由签名者支付 Gas 的广播方式。

已进行实盘测试（2026-09-02）： 使用本代码进行的 1 USDC 拆分及对应合并， 通过中继器以免 Gas 方式完成，测试账户是维护者自己的账户，使用其专属 Relayer API 密钥。中继器 ID 和 Polygon 交易哈希见 docs/live-proof.md。 redeem_positions 尚未经过实盘验证：它需要一个有获胜份额的已结算市场，而该账户 目前还没有持有此类份额。redeemable_positions 会列出已配置钱包当前可赎回或合并的 持仓；settle_resolved 提示词会串联这两个操作。

市场发现与交易成本

• find_markets(query, venues="polymarket")：搜索 Polymarket，并 返回标准化的市场 ID、标题、结果价格、买价／卖价、 点差、交易量和收盘时间。此工作流中请明确设置交易场所。
• quote_cost("polymarket", market_id, side, size)：按请求的份额数量遍历订单簿。 返回平均成交价、滑点、 名义金额、消耗的档位、该数量是否可成交，以及市场已公布的 费率表。

订单生命周期与发现

• order_status(order_id)：resting / partially_filled / filled / gone，并附带 size_matched。下单后，Agent 需要这个答案。
• my_fills()、my_positions()：操作者的成交记录和持仓， 无需在地址之间切换。（成交记录来自 Data API 活动信息流；不使用 SDK 的 list_account_trades，因为它返回的是市场的公开交易记录。）
• cancel_all_orders()：紧急停止开关，可一次性撤销所有挂单。
• resolution_criteria(venue, market_id) 返回完整的结算规则： 什么情况判定为 YES、由谁判定、依据哪些来源。信任价格之前，请先阅读。
• closing_soon(hours, venues="polymarket")：列出 N 小时内收盘的 Polymarket 市场， 活动较为集中的市场。

工作流提示词

MCP 提示词会以现成工作流的形式显示在客户端中，并明确操作 顺序，帮助 Agent 避免出错；专业知识体现在步骤编排中，扁平的工具列表无法传达这一点。

• /find_fade_setup(query, bankroll)：信号 → 订单簿 → 成本 → 结算 → 仓位大小 → 模拟运行，并列出每个步骤的拒绝条件
• /daily_review：持仓、挂单、成交记录、即将收盘的市场、归因

交易前检查与仓位大小

• check_order(venue, market_id, side, price, size, intent)：调用 place_order 前的最后一步。 根据对请求订单（市场和结果）的简短释义及实时 市场数据，对拟议订单进行确定性检查：市场是否存在并接受 订单，意图描述中的措辞是否与市场及 YES/NO 方向匹配，价格相对于订单簿是否合理，数量是否高于 Polymarket 的 1 美元最低限额且处于限制范围内，限价内是否有流动性，是否注明结算来源。返回 ok / caution / block，并附上每项检查的依据和一行回读结果。没有第二个模型来判断；不会发送任何内容。 此检查为可选项：place_order 不会替你运行，因此请让 Agent 在每次下单前调用它。
• position_size(bankroll_usd, price, fair_value)：分数凯利仓位计算， 设有上限，拒绝负优势下注，并返回其自身假设。

Polymarket 工具亮点

• search_markets、get_market、get_orderbook、price_history、 get_positions：只读，无需密钥
• overshoot_signal，免费：检测最新的恐慌性跳涨，并计算同一窗口内更早跳涨后的中位数 回归幅度（移植自 polymarket-wc 分析器）
• dispute_risk，免费：对存在争议风险（容易引发 UMA 争议）的 结算进行透明的 0 至 100 启发式评分
• place_order、cancel_order、open_orders：交易，默认采用模拟运行。 price 是介于 0 和 1 之间的概率，size 的单位是 SHARES，且交易所 对可立即成交的订单执行 1 美元最低名义金额。交易工具带有 destructiveHint 注释，客户端可据此进行控制。
• builder_stats：归因验证 + 公开的构建者排行榜
• find_markets、quote_cost：市场发现与交易成本（见上文）
• server_info：服务模式、已配置的凭据和操作者限制

技术栈说明

• 官方统一 SDK polymarket-client（此候选版本为 0.12.0）：使用 AsyncPublicClient 获取数据，使用 AsyncSecureClient.place_limit_order(..., builder_code=...) 下达带归属信息的订单。旧版 py-clob-client 已归档，无法附加 builder code。请勿使用。
• MCP SDK 2.0：使用 mcp.server.mcpserver 中的 MCPServer（旧的 mcp.server.fastmcp.FastMCP 导入方式已在 2.x 中移除）。

适用对象

Polymarket 的公开 builder 排行榜展示了由单个运营者为自己的交易流转发订单所能创造的价值。数据于 2026-08-31 通过此服务自己的 builder_stats 工具获取。重新运行后，数字会有所变化：

	周交易量
#1（traderline）	$7.70M
前 25 名的中位数	$533K
进入前 25 名的门槛	$140K

值得关注的是规模较小的几项：MagicMarkets 每周转发 $901K 的交易量，只有一名活跃用户；Jupiter 有一名用户，交易量为 $515K；Sharkbetting 有两名用户，交易量为 $1.15M。这些都是转发自身交易流的机器人运营者，而这正是本项目的目标用户。

路线图

1. 从未受限网络进行实时冒烟测试：已于 2026-08-23 完成，所有工具均通过
2. 注册 builder code（polymarket.com → Settings → Builders），上线时将费用设为 0 bps，导出 ODDSRAIL_BUILDER_CODE；先以极小规模下达第一笔可归属订单

目前没有付费层级，也不提供任何付费层级：所有工具（包括两个信号）均免费。