SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场polymarket-pnl

polymarket-pnl

数据与分析

查看项目

更新于 10-28 16:11

技能介绍

用途

polymarket-pnl 用于为任意 Polymarket 地址计算精确、可审计的盈亏（PnL）。与多数分析工具采用持仓层面近似不同，它通过 Data API 的现金流方法，重建每一笔 BUY / SELL / REDEEM / MERGE / SPLIT / REBATE 事件，并与当前未实现持仓价值对账，得出最终 PnL 数值。

该工具在 Polymarket 公开排行榜上与官方 /profit 端点做过验证：MAPE（平均绝对百分比误差）约 0.2%，所有头部账户误差均在 1% 以内。

主要能力

  • 单地址精确 PnL 计算
  • 排行榜批量计算（自动抓取前 N 名）
  • 从文本文件读取地址列表批量计算（每行一个 0x 地址，支持 # 注释）
  • 基准模式：将本地 PnL 数据集与重新计算的精确 PnL 进行对比
  • 以 JSONL 流式输出，便于后续处理

使用方式

运行环境要求 python3（3.9+）与第三方包 httpx，安装一次即可：

pip install -r ${SKILL_DIR}/requirements.txt
# 或
pip install httpx

核心命令（${SKILL_DIR} 为本技能所在路径）：

# 单地址
python3 compute_precise_pnl.py --address 0x63ce342161250d705dc0b16df89036c8e5f9ba9a

# 批量：排行榜前 N 名（自动抓取）
python3 compute_precise_pnl.py --leaderboard 50

# 从文本文件读取地址列表
python3 compute_precise_pnl.py --addresses-file targets.txt

# 基准对比：本地 PnL JSONL vs 重新计算的精确 PnL
python3 compute_precise_pnl.py --leaderboard 100 \
  --benchmark local_pnl.jsonl \
  -o precise_vs_local.jsonl

输出为 JSONL 流，写入 --output 指定的文件（默认 ./precise_pnl.jsonl）。

输出字段

每行对应一个地址记录，包含：

  • address：小写 0x 代理钱包地址
  • pnl：交易现金流 PnL（BUY/SELL/REDEEM/MERGE/SPLIT/REBATE 加未实现），为主指标
  • pnl_inclusive：pnl 加上 REWARD、REFERRAL_REWARD、CONVERSION 等平台积分
  • total_buy、total_sell、total_redeem、total_merge、total_split、total_rebate、total_reward、total_referral、total_conversion：各活动类型的汇总金额
  • unrealized：当前未平仓头寸的市值
  • open_positions：未平仓头寸数量
  • trade_count：BUY 与 SELL 事件总数
  • computed_at：记录生成的 Unix 秒时间戳
  • complete：所有分页活动请求是否完整返回
  • pagination_incomplete：是否至少有一种活动类型触及 Data API 约 1 万条偏移上限
  • pagination_incomplete_types：触顶的活动类型列表（如 BUY、SELL 等），否则为 null

数据来源

均使用公开端点，无需认证：

  • data-api.polymarket.com/activity：BUY / SELL / REDEEM / MERGE / SPLIT / REBATE / REWARD / REFERRAL_REWARD / CONVERSION 事件
  • data-api.polymarket.com/positions：当前未平仓头寸，用于计算未实现价值
  • data-api.polymarket.com/v1/leaderboard：带官方 /profit 值的排名地址

适用场景

  • 需要对某个或多个 Polymarket 地址获得可审计 PnL
  • 对排行榜或地址列表做批量 PnL 统计
  • 将本地 PnL 数据集与官方 /profit 值做基准比对

如果只需要快速画像（胜率、持仓、品类分布），应改用 polymarket-profile 技能，它更轻量，仅依赖 curl 运行。两者可配合使用：polymarket-profile 提供定性概览，polymarket-pnl 在 PnL 数值需要经得起审查时使用。

限制与注意事项

  • Data API 偏移上限约 1 万条：极高交易频率的账户可能在某一活动类型上触顶。此时记录仍会输出，并标记 pagination_incomplete=True 及具体类型，可通过按时间戳分块回填重新抓取。
  • 同秒整页边界：基于时间戳的分页使用 end = oldest - 1，并带有一个启发式回填；仅当边界时间戳在当前页已出现多次时才触发。若一整页恰好以时间戳 T 的单行结束，而后续同秒行出现在下一页，这些行可能被跳过且不会设置 pagination_incomplete。此问题影响少数极高频率账户，多数地址仍与官方 /profit 保持在 1% 以内；更严格回填已在路线图中。
  • pnl 与 pnl_inclusive 的选择：Polymarket 官方 /profit 端点在不同地址上是否包含平台积分并不一致。主 pnl 字段有意排除平台积分，使其仅凭公开交易数据即可复现。
  • 依赖 httpx：唯一第三方依赖，用于对 Data API 的稳健 TLS/HTTP/1.1 处理。
  • 仅使用公开端点（data-api.polymarket.com、gamma-api.polymarket.com），无需管理 API 密钥，但无法访问私有端点。

安装部署

Claude Code：

export AGENT_SKILLS_DIR=/path/to/your/agent/skills
cp -R skills/polymarket-pnl "$AGENT_SKILLS_DIR/"
pip install httpx

OpenClaw：

cp -R skills/polymarket-pnl ~/.openclaw/skills/
pip install httpx

许可

MIT 许可，详见仓库根目录 LICENSE。