# Polymarket 对接凭据获取说明

更新时间：2026-03-31

这个项目当前真正会用到的配置字段有 7 个：

1. `portfolio_wallet_address`
2. `polymarket_private_key`
3. `polymarket_funder_address`
4. `polymarket_signature_type`
5. `polymarket_api_key`
6. `polymarket_api_secret`
7. `polymarket_api_passphrase`

下面按“这个字段是什么、去哪里拿、填到系统哪里”来说明。

## 1. `portfolio_wallet_address`

用途：

- 用来统计账户总金额、总收益、日均收益、收益曲线
- 也是本系统默认查询持仓和 PnL 的主账户地址

怎么获取：

- 直接打开 Polymarket 网页端，查看你当前账户展示的钱包地址
- 如果你使用的是普通 EOA 钱包，这个地址通常就是你的钱包地址
- 如果你使用的是 Magic / 邮箱钱包或代理钱包，这个地址通常是你的资金地址，也就是 `funder`

系统里怎么填：

- 后台 “系统设置” -> “资产钱包地址”

## 2. `polymarket_private_key`

用途：

- 官方 `py-clob-client` 用它做 L1 签名
- 创建或派生 API 凭据时也需要它
- 提交真实订单时同样需要它

怎么获取：

- 如果你是 EOA 钱包：从你的钱包导出私钥
- 如果你是 Magic / 邮箱钱包：从 Polymarket 官方文档提到的导出路径导出私钥
- 如果你是浏览器钱包代理模式：使用连接 Polymarket 的签名钱包私钥，不是随便填一个地址

注意：

- 这是最高敏感度信息
- 一旦泄漏，资金和 API 凭据都可能被接管
- 只建议在本地机器保存，严禁上传到云端仓库

系统里怎么填：

- 后台 “系统设置” -> “Polymarket 私钥”

## 3. `polymarket_funder_address`

用途：

- 官方 SDK 文档里叫 `funder`
- 当你的签名地址和真正持有资金的地址不是同一个地址时，必须填写

什么时候必须填：

1. Magic / 邮箱钱包
2. 浏览器钱包代理模式
3. 任何“签名地址”和“资金地址”分离的账户体系

什么时候可以和主地址相同：

- 如果你是标准 EOA 直接持币交易，通常可以填你的 EOA 地址

怎么获取：

- 以 Polymarket 页面上实际显示的资金地址为准
- 如果你的账户是代理钱包 / Safe / 智能合约钱包，填页面显示的那个资金地址

系统里怎么填：

- 后台 “系统设置” -> “Funder 地址”

## 4. `polymarket_signature_type`

用途：

- 告诉官方客户端应该按哪一种签名方式验证订单

怎么选：

1. `0`：标准 EOA
   适用于 MetaMask 直连地址、硬件钱包、你自己直接控制私钥的普通钱包

2. `1`：Magic / 邮箱钱包
   适用于 Polymarket 邮箱登录、Magic Link 类账户

3. `2`：浏览器钱包代理签名
   适用于浏览器钱包连接后实际资金放在代理合约 / Safe 钱包里的情况

系统里怎么填：

- 后台 “系统设置” -> “签名类型”

## 5. `polymarket_api_key` / `polymarket_api_secret` / `polymarket_api_passphrase`

用途：

- 这是 CLOB Level 2 认证凭据
- 有了它们才能调用需要二级认证的下单、撤单、订单查询接口

怎么获取：

有两种方式。

### 方式 A：直接用本项目后台派生

这是当前最推荐的方法。

前提：

1. 先正确填写 `polymarket_private_key`
2. 先正确填写 `polymarket_funder_address`
3. 先正确选择 `polymarket_signature_type`

然后：

1. 打开后台 “系统设置”
2. 点击 “派生 API 凭据”
3. 系统会调用官方 `create_or_derive_api_creds()` 逻辑
4. 自动把 `api_key / api_secret / api_passphrase` 保存到本地加密配置中

### 方式 B：你自己通过官方 SDK 获取

示例：

```python
from py_clob_client.client import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    key="<private_key>",
    chain_id=137,
    signature_type=1,
    funder="<funder_address>",
)

creds = client.create_or_derive_api_creds()
print(creds.api_key)
print(creds.api_secret)
print(creds.api_passphrase)
```

系统里怎么填：

- 后台 “系统设置” -> `API Key`
- 后台 “系统设置” -> `API Secret`
- 后台 “系统设置” -> `API Passphrase`

## 6. 推荐配置组合

### 情况 A：标准 EOA 钱包

- `portfolio_wallet_address` = 你的钱包地址
- `polymarket_private_key` = 你的钱包私钥
- `polymarket_funder_address` = 你的钱包地址
- `polymarket_signature_type` = `0`

### 情况 B：Magic / 邮箱钱包

- `portfolio_wallet_address` = Polymarket 显示的账户地址
- `polymarket_private_key` = 导出的 Magic 私钥
- `polymarket_funder_address` = Polymarket 显示的资金地址
- `polymarket_signature_type` = `1`

### 情况 C：浏览器钱包代理模式

- `portfolio_wallet_address` = Polymarket 显示的账户地址 / 资金地址
- `polymarket_private_key` = 连接钱包的私钥
- `polymarket_funder_address` = 页面显示的代理资金地址
- `polymarket_signature_type` = `2`

## 7. 实盘前必须确认的事项

1. 先保持 `Dry Run` 打开，确认跟单记录在后台能正常生成
2. 确认 `portfolio_wallet_address` 查得到持仓和收益
3. 确认 API 凭据能成功派生
4. 对于 EOA / MetaMask 用户，确认已按官方说明完成 token allowance
5. 先用极小仓位测试，再切到真实策略参数

## 8. 本项目字段和官方概念对应表

| 本项目字段 | 官方概念 |
| --- | --- |
| `portfolio_wallet_address` | 用于 Data API 查询的 user 地址 |
| `polymarket_private_key` | `ClobClient(..., key=...)` |
| `polymarket_funder_address` | `ClobClient(..., funder=...)` |
| `polymarket_signature_type` | `ClobClient(..., signature_type=...)` |
| `polymarket_api_key` | Level 2 API key |
| `polymarket_api_secret` | Level 2 API secret |
| `polymarket_api_passphrase` | Level 2 API passphrase |

## 9. 安全建议

1. 永远先在 `Dry Run` 下测试
2. 不要把私钥和 API Secret 发给任何第三方
3. 不要把 `.env`、`storage/`、数据库文件上传到 Git 仓库
4. 如果怀疑泄漏，立即更换钱包或重新派生 / 作废 API 凭据

## 10. 官方参考链接

- `py-clob-client` 官方仓库：
  https://github.com/Polymarket/py-clob-client

- 官方 CLOB 认证文档：
  https://docs.polymarket.com/developers/CLOB/authentication

- 官方下单文档：
  https://docs.polymarket.com/developers/CLOB/orders/create-order

- 官方 Data API 用户活动：
  https://docs.polymarket.com/api-reference/core/get-user-activity

- 官方 Data API 用户持仓：
  https://docs.polymarket.com/api-reference/core/get-positions

- 官方 Data API 用户价值：
  https://docs.polymarket.com/api-reference/core/get-value

## 11. 本项目里的推荐填写顺序

1. 先填 `资产钱包地址`
2. 再填 `Polymarket 私钥`
3. 再填 `Funder 地址`
4. 再选 `签名类型`
5. 点击 “派生 API 凭据”
6. 保持 `Dry Run`，新增一个跟单地址做联调
7. 确认日志和收益数据正常后，再关闭 `Dry Run`