# Polymarket Skill

一个让 Claude / 命令行操作 [Polymarket](https://polymarket.com) 的技能包:查询行情、事件、盘口、价格、持仓、成交、排行榜等公开数据,以及在 CLOB 上真实下单 / 撤单 / 查单。

A skill for driving the Polymarket APIs (Gamma, Data, CLOB, Bridge, Relayer) from
Python — read market data and place/cancel/query real orders.

---

## 安装 Install

从 git 仓库安装(把仓库克隆为技能目录):

```bash
git clone <仓库地址> ~/.claude/skills/polymarket
```

或双击预打包的 `polymarket.skill` 由 Claude 桌面端安装,或把目录放进 `~/.claude/skills/`。

依赖:

```bash
pip install requests            # 公开数据(行情/盘口/持仓/排行榜),无需账户
pip install py-clob-client-v2   # 仅真实交易时需要(官方 v2 SDK)
```

> macOS/Homebrew 若报 `externally-managed-environment`,用虚拟环境:
> `python3 -m venv .venv && source .venv/bin/activate`,激活后再 `pip install`。

---

## 快速开始:查数据(无需任何配置)

```bash
cd scripts
python polymarket.py list-commands                       # 列出全部命令
python polymarket.py gamma.list_markets --json '{"limit":5,"closed":false}'
python polymarket.py gamma.search --q "world cup"
python polymarket.py clob.midpoint --token_id <TOKEN>
python polymarket.py clob.order_book --token_id <TOKEN>
python polymarket.py data.positions --user 0xADDR --json '{"limit":50}'
python polymarket.py data.leaderboard --json '{"limit":10}'
```

简单参数用 `--key value`;结构化参数(数字/布尔/多参数)用一个 `--json '{...}'`。

**ID 概念**:`slug`(市场/事件的 URL 片段)、`condition_id`(标识一个市场)、
`token_id`(某个结果 YES/NO 的资产 id,盘口/价格/历史都按它查)。从
`gamma.list_markets` / `gamma.get_market` 返回的 `clobTokenIds` 拿 token_id。

Python 里用:

```python
import sys; sys.path.insert(0, "scripts")
from polymarket import GammaClient, DataClient, ClobPublicClient
g = GammaClient()
markets = g.list_markets(limit=10, closed=False, order="volume24hr", ascending=False)
book = ClobPublicClient().order_book(token_id="...")
```

---

## 真实交易(动用钱包私钥与真金白银)⚠️

每个人用自己的钱包。配置环境变量后从 Python 调用:

```bash
export PK=0x你的私钥
export POLY_PROXY_ADDRESS=0x你的交易账户地址     # 代理钱包持有 USDC 的地址
export POLY_SIGNATURE_TYPE=...                  # 0 / 1 / 2 / 3,见下
```

```python
import sys; sys.path.insert(0, "scripts")
from polymarket import TradingClient
t = TradingClient()                      # 首次构造自动派生 L2 API 凭证

t.get_balance_allowance()                # 查 USDC 余额 + 授权
t.create_and_post_order(token_id="...", price=0.42, size=10, side="BUY", order_type="GTC")
t.create_and_post_market_order(token_id="...", amount=5, side="BUY")  # amount=USDC金额
t.get_open_orders(asset_id="...")
t.cancel_all()
```

### 签名类型(每个账户不同,务必选对)

| 注册方式 | `signature_type` |
|---|---|
| 自有钱包直接充值的 EOA | `0` |
| 旧版 邮箱/Magic 登录 | `1` |
| 浏览器钱包(MetaMask 等) | `2` |
| 新版 邮箱/Google 内嵌钱包 | `3` |

**关键坑**:类型选错会让 `get_balance_allowance` 静默返回 `balance: 0`(查错了代理)。
若认证成功(凭证 + 签名地址正确)但余额是 0,**逐个试 `signature_type=1/2/3`**;当
`balance` 等于你网页上的现金、且三个 `allowances` 是一个很大的数(≈2^256-1)时即为正确类型。
新账户首次交易需先在网页端成交一笔以部署代理 + 设置授权。

详见 `references/trading.md`。

---

## 文件结构

```
polymarket/
├── SKILL.md                  # 技能说明(给 Claude 读)+ 用法
├── README.md                 # 本文件
├── scripts/polymarket.py     # 客户端 + CLI(78+ 公开命令 + 交易)
└── references/
    ├── endpoints.md          # 每个端点 → 方法/路径/参数 全表
    └── trading.md            # 认证、签名类型、下单类型、安全
```

---

## 安全须知

- 私钥 = 钱包完全控制权。**只在自己的终端 `export`,绝不写入文件、不贴给任何人、不进 git。**
- 交易是真实、难以撤销的资金操作。先小额测试,量力而行。
- 本工具调用的是 Polymarket 内部 API,可能随其更新而变化;若某端点 404,见
  `references/endpoints.md` 核对路径。
- 仅供学习与个人使用;遵守 Polymarket 的服务条款与你所在地区的法律法规。