Polymarket 全能工具 fashionmascherine-svg/dsh-polymarket-knowhow

dsh-polymarket-knowhow

一个 DeepSeek Harness 插件，为你的智能体赋予完整、经过验证的 Polymarket 超能力：覆盖所有 Polymarket API（Gamma、CLOB、Data API、Perps、Combos/RFQ、Bridge）的实时行情数据工具、可选开启的认证交易工具、WebSocket 行情流服务，以及一份打包的 knowhow 技能，提炼自官方文档——这样模型再也不会编造端点、参数或认证流程。

基于 atompilot/polymarket-skill（MIT）的知识库构建，并对照当前官方 OpenAPI 规范和实时 API 响应重新验证。

为什么选这个插件

| | 本插件 | 原始文档 / MCP 服务器 |
| knowhow 可离线使用（打包技能 + polymarket_knowledge 工具） | ✅ | ❌ |
| 实时工具，带类型化 schema 和输出上限 | ✅ | 部分支持 |
| 端到端覆盖认证流程（L1 EIP-712 → L2 HMAC → builder 请求头） | ✅ | 部分支持 |
| 2026 年新增接口：Perps（56 个操作）和 Combos/RFQ | ✅ 有文档 + 读取工具 | 零散 |
| 修正端点漂移（volume24hr 排序、扁平批量载荷、geoblock 主机、合约迁移） | ✅ 实时验证 | ❌ |

能力

四个相互独立的 Cordis 行（可在后续补丁层中按 id 禁用任意一个）：

| 行 id | 提供内容 |
| polymarket-service | ctx.polymarket 服务：每个 Polymarket API（Gamma、CLOB、Data、Perps、RFQ、Bridge、Relayer）各一个已配置客户端，HTTP 支持超时/重试/geoblock 感知 |
| polymarket-tools | 约 25 个常开行情数据工具 + 可选开启的账户/交易工具 + Perps 工具 + polymarket_knowledge |
| polymarket-skills | 通过 ctx.skills 嵌入运行时技能 polymarket（16 个知识模块作为资源） |
| polymarket-stream | 可选的行情频道 WebSocket 桥接，发出 polymarket/market-event Cordis 事件 |

模型工具（始终注册）

- 发现类：polymarket_search、polymarket_events_list（offset + keyset 分页）、polymarket_event_get、polymarket_markets_list、polymarket_market_get、polymarket_tags_list
- CLOB 数据：polymarket_orderbook（单个/批量）、polymarket_price（单个/批量）、polymarket_quote（一次调用返回中间价 + 价差 + 最新价）、polymarket_price_history、polymarket_token_info（tick size、neg-risk、token→market 解析）
- Data API v2：polymarket_positions（状态生命周期 + 游标分页）、polymarket_trades_public、polymarket_activity、polymarket_holders、polymarket_leaderboard、polymarket_open_interest、polymarket_live_volume、polymarket_portfolio_value、polymarket_user_stats、polymarket_resolutions、polymarket_approvals
- 元信息：polymarket_geoblock_check、polymarket_combo_markets、polymarket_knowledge

可选开启的工具（仅在配置后注册）

- trading.enabled + L2 凭据 → polymarket_account_orders、polymarket_account_trades、polymarket_cancel_orders、polymarket_balance_allowance、polymarket_heartbeat、polymarket_api_keys、polymarket_place_order*
- perps.enabled + perps 凭据 → polymarket_perps_market_data、polymarket_perps_account

\* 下单时，只要能解析到官方统一 @polymarket/client SDK，就通过它签名（见 Trading setup）——V1 CTF token id 和 Protocol V2 position id 都支持。其余部分用零依赖的 Node crypto。

安装

From GitHub (pin a commit for reproducibility)
dsh plugin --profile my-profile add github:fashionmascherine-svg/dsh-polymarket-knowhow#<sha>

From a local checkout
dsh plugin --profile my-profile add ./dsh-polymarket-knowhow

From a tarball
pnpm pack && dsh plugin --profile my-profile add ./dsh-polymarket-knowhow-0.3.0.tgz

包内自带 prepare 构建，无需额外依赖。git 安装会拉取源码，所以 pnpm ≥10 会要求你放行一次构建——把 pnpm 打印的包键复制到你配置档的 pnpm-workspace.yaml：

allowBuilds:
dsh-polymarket-knowhow: true

然后启动：dsh --profile my-profile。四行全部激活；除非你启用 trading/perps，否则只显示安全的只读工具。

在 Claude Code 中使用

同一个仓库也是 Claude Code 插件。它打包了：

- polymarket 技能 —— skills/polymarket/references/ 下的 15 个知识模块（由 knowledge/ 生成，单一数据源）；
- 只读 MCP 服务器（scripts/mcp-server.mjs），暴露实时行情数据工具（search、events、orderbook、prices、quote、price history、positions、trades、leaderboard、open interest、perps market data……）。交易/账户工具永不暴露——服务器构建时禁用了凭据解析，并在其上加了拒绝名单防护。

从本仓库自带的 marketplace 安装：

/plugin marketplace add fashionmascherine-svg/dsh-polymarket-knowhow
/plugin install polymarket-knowhow@fashionmascherine-svg-polymarket

或者只把 MCP 服务器挂到任意 MCP 客户端：

claude mcp add polymarket-knowhow -- node /path/to/dsh-polymarket-knowhow/scripts/mcp-server.mjs

预构建的 lib/ 已提交，所以两种方式开箱即用；改动 src/ 后运行 npm run build 并提交重新构建的 lib/。编辑 knowledge/.md 后，用 npm run sync:claude-skill 重新生成技能副本。

配置

默认值很合理（公共端点、无凭据、关闭交易）。可在配置档的 cordis.patch.yml 里覆盖任意字段：

- id: polymarket-service
config:
timeoutMs: 20000
maxRetries: 3
trading:
enabled: true
Explicit creds… (or leave empty to read POLY_API_KEY / POLY_SECRET / POLY_PASSPHRASE / POLY_ADDRESS from the environment)yaml apiKey: '' secret: '' passphrase: '' address: '' # funder/proxy wallet address signatureType: 2 # 0 EOA · 1 POLY_PROXY · 2 GNOSIS_SAFE perps: enabled: false # reads POLYMARKET_PROXY / POLYMARKET_SECRET env stream: enabled: false
assetIds: [] # CLOB token ids to subscribe at startup
skills: true # register the embedded knowhow skill

- id: polymarket-stream
disabled: false # rows can be toggled individually

交易配置

1. 先创建一次 L2 API 凭据（任选一种方式）：
- polymarket-client（Python）：AsyncSecureClient.create(private_key=pk).credentials，或者
- 把 @polymarket/client 装进配置档，在 createSecureClient 之后读取 client.credentials。
2. 把这四个值写进配置，或者放进 POLY_ 环境变量。
3. 如果要下单，还得让统一 SDK 能被解析到，并设置 POLY_PRIVATE_KEY： sh
dsh plugin --profile my-profile add @polymarket/client viem

只读账户工具（订单、成交、撤单、余额、心跳）不需要 SDK —— 它们用 Node 内置的 HMAC 给请求签名（L2 请求头 POLY_ADDRESS/SIGNATURE/TIMESTAMP/API_KEY/PASSPHRASE）。

⚠️ 交易动的是真金白银。心跳一旦中断超过 10 秒，所有挂单都会被撤销；FOK/FAK 买单的 amount 是美元，卖单是份额。先读 knowledge/order-patterns.md。

在其他插件里调用这个服务 ts
export const inject = ['polymarket']

export function apply(ctx) {
const { gamma, clob, dataApi } = ctx.polymarket
const events = await ctx.polymarket.gamma.listEvents({ active: true, limit: 10 })
const book = await clob.getBook(tokenId)
ctx.on('polymarket/market-event', (event) => { /* stream.enabled */ })
}

知识模块（随包提供）

SKILL.md（入口）· api-endpoints（完整且已验证的清单）· authentication · order-patterns · market-data · websocket · concepts · ctf-operations · fees · bridge · gasless · error-codes · rate-limits · geoblock · perps · combos-rfq

用 skill 工具加载（名称：polymarket），或者直接用 polymarket_knowledge（按主题或自由文本搜索）。

验证方法

- 每个 REST 接口都对照从 docs.polymarket.com 抓取的官方 OpenAPI 规范交叉核对过。
- 随后又实盘跑了一遍这些接口（只读路径）—— 结果抓到了真实的偏差：排序字段是 camelCase（volume_24hr → 422）、批量请求体要扁平结构（套一层 params 会返回 []）、/live-volume?id=（不是 ?event=）、geoblock 实际在 polymarket.com/api/geoblock、以及交易所合约地址已经迁移。
- tests/unit（28 个测试）：硬编码的 HMAC 黄金向量、在本地服务器上验证重试/Retry-After/错误映射、在打桩的 fetch 上跑工具执行，包括撤单正常路径和失败传播。
- tests/live（11 个测试）：针对 Gamma/CLOB/Data-API/Perps 的生产环境冒烟测试。
sh
npm test # unit suite (builds first)
npm run test:live # 会请求真实 API，只读

仓库结构

├── cordis.patch.yml # 打包补丁：4 行插件 ├── src/ │ ├── http.ts # fetch + 重试 + 地域封锁错误映射 │ ├── config.ts # Schemastery schema + 凭据解析 │ ├── gamma.ts # Gamma 客户端 ├── data.ts # Data API 客户端 │ ├── clob.ts # CLOB 客户端 + L2 HMAC 签名 │ ├── perps.ts # Perps 客户端 ├── extras.ts # Bridge/RFQ/Relayer/geoblock │ ├── signing.ts # 可选的官方 SDK 订单签名 │ ├── service.ts # PolymarketService（ctx.polymarket） │ ├── tools.ts # 全部模型工具 │ ├── skills.ts # 运行时技能注册 │ └── stream.ts # WebSocket 桥接 ├── knowledge/ # 16 个 markdown 模块（「knowhow」） └── tests/{unit,live}/

面向智能体的开发指引见 CLAUDE.md。

致谢与许可

MIT —— 见 LICENSE 和 THIRD_PARTY_NOTICES.md。
知识模块改编自 atompilot/polymarket-skill（MIT © atompilot），并对照当前官方文档做了扩充与修正。