Polymarket Intel

Polymarket 钱包智能分析

一个 MCP 服务和 REST API，可将 Polymarket 钱包分类为人类或机器人，为其交易优势打 0–10 分，并实时推送当前未平仓头寸。 专为采用跟单交易和信号跟随技术栈的 AI Agent 打造。

# Use it from any MCP client (Claude Desktop, Cursor, etc.)
pip install polymarket-intel-mcp
polymarket-intel-mcp

# Or call the hosted REST API directly
curl https://polymarket-intel-production.up.railway.app/wallet/0xf1528f12e645462c344799b62b1b421a6a4c64aa

与其他 Polymarket MCP 服务的配合方式

状态

最新版本： v1.2（2026 年 5 月）——改进了分类器，能够区分活跃的人类交易者与高频交易机器人。有关后续计划，请查看发布说明和 v1.3 待办事项。

每日快照任务于 08:00 UTC 运行，为排行榜前 50 名钱包重新评分，并构建分类稳定性的历史数据集。

有多个 MCP 服务支持 Polymarket，覆盖不同层面：

服务	功能	适用场景
polymarket-intel（本服务）	钱包智能分析——区分人类与机器人，为交易优势打分，读取未平仓头寸	决定要跟随谁的信号
graph-polymarket-mcp	通过 The Graph 子图提供市场数据（20 个工具、8 个子图）	读取原始链上市场数据
whitmorelabs/polymarket-mcp	滑点、流动性、套利、价格数据	为自己的交易定价
joinQuantish/polymarket	可自托管的交易 Agent	运行自主机器人

这些服务相辅相成。跟单交易 Agent 可以使用 polymarket-intel 筛选值得跟随的钱包，然后通过 graph-polymarket-mcp 读取这些钱包投注的市场，再使用 whitmorelabs/polymarket-mcp 为自己的入场头寸定量。

它能回答哪些问题

• “这位交易者是人类还是机器人？” — score_polymarket_wallet(wallet_address) → 返回 classification ∈ {human, bot, insufficient_data}，以及置信度评分和原因代码。
• “他们真的有优势吗？” — edge_score 为 0–10 分，并以已实现净 PnL 为门槛，避免将分散但亏损的钱包误判为有优势。
• “他们现在在押注什么？” — get_open_positions(wallet_address) 返回按规模排序的实时头寸，每 30 秒刷新一次。
• “他们的优势随时间发生了怎样的变化？” — /wallet/{address}/history 返回每日快照中的评分时间序列。

为什么需要这个服务

Polymarket 排行榜容易误导人。它包含按当前价格计算的未实现 PnL，因此榜首主要是运行结构性套利的机器人，以及少数持有巨额未平仓头寸的钱包，而这些头寸可能永远不会朝有利方向结算。盲目跟随排行榜交易的 Agent 往往会蒙受损失。

本服务会对排行榜上的每个钱包进行行为特征分析（专注度、持仓时长、交易时机规律性、类别集中度），并根据原始活动重建 PnL，只展示那些看起来是真正具备优势的人类交易者。

数据集会随着时间推移越来越有价值——每日快照任务运行时，历史信号都会不断累积。连续 90 天优势评分都高于 7 的钱包，比任何单个时间点的评分都更能说明问题。

同时以 REST API 和 MCP 服务形式提供

接入方式	使用场景	设置方式
MCP 服务	需要以工具方式访问的 Agent	pip install polymarket-intel-mcp
REST API	自定义 HTTP 集成、仪表板	curl https://polymarket-intel-production.up.railway.app/...
托管式 MCP	在任意兼容 MCP 的客户端上运行的 Agent	将 https://polymarket-intel-production.up.railway.app/mcp 添加到客户端配置

架构

┌──────────────────────────────────────────────┐
│  core/                                       │
│    client.py    — Polymarket data API client │
│    signals.py   — pure signal calculators    │
│    scorer.py    — classifier + edge score    │
│    models.py    — Pydantic response schemas  │
├──────────────────────────────────────────────┤
│  db/                                         │
│    schema.sql   — Postgres tables + indexes  │
│    repository.py — Repository protocol +     │
│                    InMemoryRepository        │
│    supabase_repo.py — Supabase impl          │
│    converters.py — ScoreResult ↔ records     │
├──────────────────────────────────────────────┤
│  api/main.py    — FastAPI HTTP server        │
│  mcp_server/    — MCP server (stdio)         │
│  scripts/                                    │
│    analyze_wallet.py — CLI                   │
│    snapshot_job.py   — daily cron entry      │
│  tests/                                      │
└──────────────────────────────────────────────┘

Core 完全不知道持久化的存在。API 和快照任务依赖 Repository 协议——生产环境使用 Supabase，测试环境和未设置环境变量时使用内存存储。正因如此，测试套件无需数据库即可运行；以后只需添加一个文件，就能将 Supabase 换成 Neon、RDS 或其他任何方案。

快速入门

git clone <repo> && cd polymarket-intel
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
pytest                             # 19 tests, all green

CLI

python scripts/analyze_wallet.py phonesculptor
python scripts/analyze_wallet.py 0xf1528f12e645462c344799b62b1b421a6a4c64aa --json

REST API

uvicorn api.main:app --reload --port 8000
open http://localhost:8000/docs

API 分为慢速层（积极缓存、成本低，非常适合一次性发现）和快速层（缓存时间短，非常适合实时跟单 Agent）。之所以这样划分，是因为底层数据对新鲜度的需求不同——钱包的分类不会每分钟都变，但其未平仓头寸会变。

层级	方法	路径	TTL	说明
慢速	GET	/wallet/{address}	1h	评分数据——分类、edge_score、信号。不含头寸。写入历史记录（防抖）。
快速	GET	/wallet/{address}/positions	30s	仅未平仓头寸。每次调用都不会写入数据库。
—	GET	/wallet/{address}/history	DB	评分时间序列
—	GET	/wallet/{address}/positions/history	DB	头寸随时间的变化
—	GET	/wallet/by-username/{username}	1h	便捷查询
—	GET	/leaderboard?limit=50	30m	Polymarket 原始顶级交易者
—	GET	/leaderboard/verified?min_edge=5	1h	筛选出经过评分的人类交易者
—	GET	/leaderboard/historical?date=…	DB	任意过去日期的排行榜
—	GET	/snapshots/latest	DB	cron 上次运行的时间？

为什么头寸数据的缓存时间是 30s，而不是更短？ Polygon 的出块时间约为 2s，Polymarket 的活动索引会滞后几秒。轮询间隔低于 10s 不会让数据更新，只会导致触发速率限制。30s 是成本、新鲜度和上游服务友好度之间的最佳平衡点。

为什么要对数据库写入进行防抖？ 交易 Agent 每小时可能会调用 /wallet/{address} 数千次。每次调用都写入一行，会让历史记录堆满几乎重复的快照。评分端点对每个钱包每小时最多持久化一次。每日快照任务则确保无论 API 流量如何，排名前 50 的钱包都会被覆盖。

MCP 服务（Claude Desktop、Cursor、Continue）

python mcp_server/server.py

然后，将 mcp_server/claude_desktop_config.example.json 放入 Claude Desktop 配置中，并编辑绝对路径。

该服务提供四个工具：

• score_polymarket_wallet(wallet_address) — 完整评分
• score_polymarket_user(username) — 按显示名称查询
• get_polymarket_leaderboard(limit) — 原始排行榜
• get_open_positions(wallet_address) — 实时投注的快速快照

评分方法

机器人触发条件（任一条件满足 → 判定为机器人）

信号	阈值	来源
专注度比率	> 12	Hubble Research，经实证验证
持仓中位时间	< 60s	HFT / MEV 模式
时序 CV	< 0.3（n≥100）	定时交易

软信号会叠加：加密市场做市商模式、每天 > 200 笔交易等。

人类交易者的 Edge 评分（0–10）

Hard gate: net realised PnL ≤ 0  →  capped at 2.0
Hard gate: < 10 winning markets  →  capped at 3.0

35%  PnL magnitude (log-scaled)
25%  win rate (capped at 70%)
15%  PnL distribution (penalises top-1 concentration)
15%  sample size (winning markets, capped at 50)
10%  win/loss ratio (capped at 3x)

净 PnL 是硬性门槛，因此像 neutralwave23 这样用许多分散的小额盈利掩盖 375k 美元亏损的钱包，会被正确标记为表现不佳。

盈亏重建

money_in   = sum(BUY usdcSize per conditionId)
money_out  = sum(SELL usdcSize) + sum(REDEEM usdcSize)
pnl        = money_out - money_in

status:
  REDEEM exists                                    → won
  SELL exists, no REDEEM                           → exited
  no SELL, no REDEEM, last trade > 7 days old      → lost
  no SELL, no REDEEM, last trade within 7 days     → open

为什么要用活动记录而不是持仓端点：赎回后，持仓会从 API 中消失，因此使用 /positions 进行的任何简单分析都会低估盈利。始终通过 /activity?type=TRADE + /activity?type=REDEEM 重建（需要分别调用——用逗号连接类型会返回 400）。

持久化（Supabase）

历史数据集是我们的护城河。每天，快照任务都会获取排行榜、为排名前 N 的钱包评分，并持久化三项内容：分数本身（wallet_scores）、该时刻钱包的未平仓持仓（open_position_snapshots），以及当时的排行榜（leaderboard_snapshots）。90 天后，你就能回答其他人无法回答的问题：“过去一个季度，哪些钱包一直高于 edge 7？”“哪些钱包刚进入前 50 名？”“列出所有在市场结算前三天持有 YES 的钱包。”

设置

# 1. Create a Supabase project, get the URL and service_role key
cp .env.example .env  # fill in SUPABASE_URL and SUPABASE_KEY

# 2. Apply the schema (Supabase dashboard → SQL editor → paste db/schema.sql → run)
#    Or via psql:
#    psql "$DATABASE_URL" -f db/schema.sql

# 3. Run the snapshot job once to verify it writes:
python scripts/snapshot_job.py --top 10

如果未设置 SUPABASE_URL 和 SUPABASE_KEY，API 和快照任务都会回退到内存仓库——测试套件仍会通过，API 仍会提供实时评分，但在接入 Supabase 之前，历史端点将返回空结果。

每日快照任务

每天安排运行 python scripts/snapshot_job.py --top 50（可使用 Railway cron、GitHub Actions，或由 Supabase pg_cron 触发边缘函数——由你决定）。该任务具有幂等性：运行两次会创建两个快照，这没有问题——历史查询会选取最接近的快照。

python scripts/snapshot_job.py --top 50              # production
python scripts/snapshot_job.py --top 5  --dry-run    # local testing, no writes

每次运行都会在 snapshot_runs 中记录一行审计信息，包括开始和结束时间、已评分的钱包数以及错误数。

架构概览

表	用途
wallets	每个曾出现过的钱包对应一行
wallet_scores	仅追加的评分时间序列
open_position_snapshots	每个时间点各钱包持有的内容
leaderboard_snapshots	每日保存的完整排行榜
snapshot_runs	cron 任务的审计记录

两个视图（latest_wallet_scores、latest_leaderboard）让常见的“当前情况如何”查询更加高效。

仓库模式

db/repository.py 定义了一个 Repository 协议。该协议有两种实现：

• InMemoryRepository——线程安全，但重启后数据会丢失。用于测试，并作为开发模式下的回退方案。
• SupabaseRepository——用于生产环境。封装 supabase-py 客户端。

API 和快照任务只依赖该协议。若要将 Supabase 换成 Neon 或可自托管的 Postgres，只需编写一个实现相同六个方法签名的新类。

定价维度

端点拆分经过设计，可让每个层级与一种计费模式清晰对应。建议价格范围：

层级	端点	建议价格	原因
发现	/wallet/{address}, /leaderboard/*	$0.001–$0.01 / 次调用	缓存更新较慢，主要读取数据库
监控	/wallet/{address}/positions	$0.01–$0.05 / 次调用	数据新鲜，每次都会请求 Polymarket
流式（v2）	持仓变更的 SSE 信息流	$20–$100 / 月固定费用	由我们一侧持续获取
历史	/wallet/{address}/history 等	$0.005 / 次调用	纯数据库读取，价值随时间增长

流式端点是严肃的跟单机器人真正愿意付费使用的功能，但它需要我们一侧运行持续获取数据的工作进程——先留到 v2，等我们确认按次调用的业务模式可行后再实现。

部署

Railway

推送代码仓库并指定它即可。其余工作由 railway.toml 处理。

Render / Heroku 风格

已配置好 Procfile。

缓存

api/cache.py 是一个线程安全的内存 TTL 缓存，接口与 Redis 客户端相同。对于多工作进程的生产环境，只需在一个文件中将单例替换为 redis.Redis()。TTL：

• 钱包评分：1h
• 仅开放持仓：5m
• 排行榜：30m
• 已验证排行榜：1h

测试

pytest -v

tests/fixtures.py 中的合成测试数据模拟了研究阶段发现的三种真实钱包模式（MLB 人类用户 phonesculptor、HFT 机器人 gabigol、情绪失控的亏损者 neutralwave23），以及一位数据量较少的新手。测试仅使用测试数据，不会调用实时 API，因此测试套件具有确定性且适用于 CI。

发布路线图

1. 现在 — 在 Railway 上提供 REST API，使用 Supabase 持久化每日快照
2. 接下来 — 发布到 MCP Hub、Replit Agent Market、awesome-mcp-servers
3. 之后 — 按次调用的 x402 小额支付（USDC）、历史查询端点（护城河：每运行一天，数据集就会增长）

已验证的钱包示例

这些是测试数据所针对的角色。随着活动变化，实时数据会有所不同：

钱包	评分	说明
phonesculptor	~9/10	专注 MLB 的人类用户，盈利分散，确有优势
gabigol	机器人	加密货币 5 分钟 Up/Down 套利（2026 年 2 月后优势基本消失）
neutralwave23	~1/10	分散的小额盈利掩盖了较大的净亏损