fashionmascherine-svg/dsh-polymarket-knowhow

dsh-polymarket-knowhow

一个 DeepSeek Harness 插件，为你的 agent 赋予完整且经过验证的 Polymarket 超能力：覆盖所有 Polymarket API（Gamma、CLOB、Data API、Perps、Combos/RFQ、Bridge）的实时市场数据工具、可选启用的认证交易工具、一个 WebSocket 市场流服务，以及一个从官方文档提炼而来的内置 knowhow 技能——让模型永远不会臆造端点、参数或认证流程。

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

License: MIT
topic: dsh-plugin

为什么选择这个插件

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

能力

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

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

模型工具（始终注册）

- 发现：polymarket_search、polymarket_events_list（偏移量 + 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：polymarket_positions、polymarket_trades_public、polymarket_activity、polymarket_holders、polymarket_leaderboard、polymarket_open_interest、polymarket_live_volume、polymarket_portfolio_value
- 元工具：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/clob-client SDK 可解析时，下单通过该 SDK 进行签名（参见交易设置）。其他所有操作均使用零依赖的 Node crypto。

安装

从 GitHub 安装（固定一个 commit 以保证可复现性）
dsh plugin --profile my-profile add github:fashionmascherine-svg/dsh-polymarket-knowhow#

从本地检出安装
dsh plugin --profile my-profile add ./dsh-polymarket-knowhow

从 tarball 安装
pnpm pack && dsh plugin --profile my-profile add ./dsh-polymarket-knowhow-0.2.0.tgz

该包自带一个自包含的 prepare 构建。git 安装会拉取源码，因此 pnpm ≥10 会要求你允许一次构建——将 pnpm 打印出的包键复制到你 profile 的 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），暴露实时市场数据工具（搜索、事件、订单簿、价格、报价、价格历史、持仓、成交、排行榜、未平仓合约、perps 市场数据……）。交易/账户工具永远不会被暴露——该服务器在构建时禁用了凭证解析，并在其上叠加了拒绝列表防护。

从本仓库捆绑的 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 重新生成技能副本。

配置

默认值合理（公共端点、无凭证、交易关闭）。可从你 profile 的 cordis.patch.yml 覆盖任意字段：

- id: polymarket-service
config:
timeoutMs: 20000
maxRetries: 3
trading:
enabled: true
显式凭证……（或留空以从环境变量读取 POLY_API_KEY / POLY_SECRET /
POLY_PASSPHRASE / POLY_ADDRESS）
apiKey: ''
secret: ''
passphrase: ''
address: ''        # 出资方/代理钱包地址
signatureType: 2   # 0 EOA · 1 POLY_PROXY · 2 GNOSIS_SAFE
perps:
enabled: false     # 读取 POLYMARKET_PROXY / POLYMARKET_SECRET 环境变量
stream:
enabled: false
assetIds: []       # 启动时订阅的 CLOB token id
skills: true         # 注册内嵌的 knowhow 技能

- id: polymarket-stream
disabled: false         # 各行可单独开关

交易设置

1. 一次性创建 L2 API 凭证（任意方式）：
- py-clob-client：ClobClient(host, key=pk, chain_id=137).create_or_derive_api_creds()，或
- 将 @polymarket/clob-client 安装到 profile 中，并使用其 createOrDeriveApiKey()。
2. 将这四个值放入配置或 POLY_ 环境变量中。
3. 若要下单，还需让 SDK 可被解析，并设置 POLY_PRIVATE_KEY：
sh
dsh plugin --profile my-profile add @polymarket/clob-client

只读账户工具（订单、成交、撤单、余额、心跳）无需 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/错误映射、基于 stub fetch 的工具执行，包括撤单成功路径和失败传播。
- tests/live（11 个测试）：针对 Gamma/CLOB/Data-API/Perps 的生产环境冒烟测试。
sh
npm test        # 单元测试套件（先构建）
npm run test:live  # 访问真实 API，只读

仓库布局

├── cordis.patch.yml      # bundle 补丁：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），并依据当前官方文档进行了扩展和修正。