内容
# PolyGate
**从任何支持MCP的LLM交易[Polymarket](https://polymarket.com)。**
[](LICENSE)
PolyGate是一个[模型上下文协议](https://modelcontextprotocol.io)服务器，为您的AI代理提供Polymarket作为一组工具。指向任何支持MCP的主机（Claude Desktop、Claude Code、VS Code、Cursor、OpenClaw等），您的代理可以：
- **研究市场** - 搜索、列出和阅读事件、市场和分辨率规则；
- **读取实时价格** - 订单簿、中间价、价差、最新交易、价格历史；
- **检查您的账户** - 持仓、余额、投资组合价值、订单、活动；
- **交易** - 买卖和管理Polymarket账户上的真实订单。
它使用**您的**Polymarket账户。研究和阅读市场不需要凭证 - 无需密钥即可运行。让代理**交易**，您需要提供两个值（您的资金地址和签名密钥）；PolyGate然后签名订单，派生凭证，并为您检测签名类型 - 所有这些都在启动时在内存中完成。无需运行HTTP服务器，无需打开端口，也无需代理管理的API密钥。您的所有交易也将在Polymarket.com上可见，您可以像往常一样使用该网站管理您的账户。
> **真实货币**。一旦配置了资金钱包，交易工具就会在您的Polymarket账户上花费真实资金。
## 快速开始
唯一的要求是 **[uv](https://docs.astral.sh/uv/)**。为您的平台安装它：
<details open>
<summary><b>macOS</b></summary>
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
或使用 [Homebrew](https://brew.sh)：`brew install uv`。
</details>
<details>
<summary><b>Linux</b></summary>
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
</details>
<details>
<summary><b>Windows</b></summary>
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
或使用 [winget](https://learn.microsoft.com/windows/package-manager/): `winget install --id=astral-sh.uv -e`。
</details>
`uvx`（与uv捆绑）然后按需获取并运行PolyGate，无需克隆或 `pip install`。
要 **研究和阅读** 市场 - 不需要Polymarket账户或密钥 - 将以下内容粘贴到您的MCP主机的配置文件中：
```json
{
"mcpServers": {
"polygate": {
"command": "uvx",
"args": ["--from", "git+https://github.com/ilmari99/polygate@v0.3.0", "polygate-mcp"]
}
}
}
```
重新加载您的主机，市场数据、价格和研究工具就会出现。
### 添加您的钱包进行交易
凭证 **仅用于交易**。要让代理在您的Polymarket账户上下订单和管理订单，请添加一个包含来自 [polymarket.com](https://polymarket.com) 的两个值的 `env` 块：
- **资金地址** - 设置 → 个人资料 → 地址（`0x…`）。
- **私钥** - 设置 → 账户 → 私钥。 **请保密**。
```json
{
"mcpServers": {
"polygate": {
"command": "uvx",
"args": ["--from", "git+https://github.com/ilmari99/polygate@v0.3.0", "polygate-mcp"],
"env": {
"FUNDER_ADDRESS": "0x您的资金地址",
"PRIVATE_KEY": "0x您的签名私钥"
}
}
}
}
```
这些环境变量由您的主机传递给PolyGate进程；它们存储在您机器上的本地配置文件中。
此 `mcpServers` 结构是事实上的标准，适用于Claude Desktop、Claude Code、Cursor和大多数MCP主机。 **VS Code除外** - 请参见下面的 [其他主机](#其他主机)。
## 与您的代理交互
一旦加载了工具，只需询问有关Polymarket的任何问题。例如：
- “当前交易量最大的市场有哪些？”
- “建议市场中存在优势且最新新闻尚未正确定价。”
- “我的投资组合表现如何？”
- “购买500股法国队赢得世界杯的YES份额。”
> 希望模型在开始交易之前了解 **如何交易** - Polymarket的代币与市场模型、价格即概率的概念、常见陷阱以及保留其学习内容 - 请交给它 [`llm.md`](llm.md)，这是一份可选的简介，专为代理编写。
## 工作原理
每个工具都是对进程内核心 `PolymarketService` 的薄封装，它拥有所有上游访问权限：
```mermaid
flowchart LR
Host["您的MCP主机\n(代理)"] -- "MCP工具（标准输入/输出）" --> Core["PolyGate核心\n(PolymarketService)"]
Core --> Gamma["Gamma API\n(市场、事件)"]
Core --> CLOB["CLOB API\n(订单簿、订单 - 签名)"]
Core --> Data["数据API\n(持仓、活动)"]
```
在Polymarket上交易涉及两个地址，您需要提供这两个地址：
- **您的签名者**（`PRIVATE_KEY`）- 一个普通的以太坊密钥对，其私钥 **签名**您的订单。这是polymarket.com在 **设置 → 账户 → 私钥**下透露的密钥；如果您连接了您自己的钱包，它就是该钱包的密钥。无论哪种方式，您都不需要一个新的钱包。
- **您的资金提供者**（`FUNDER_ADDRESS`）- 持有您的USDC并下订单的Polymarket账户。您的签名者控制它；您永远不会获得单独的密钥。
启动时，核心从签名密钥中派生出CLOB API凭证，并 **自动检测订单签名类型** - 无论是代理钱包、连接的（安全）钱包、存款钱包还是普通的EOA持有您的资金（您需要有资金），以便正确签名订单，无需链上设置、代币许可或单独的RPC。因为钱包每次启动时都通过 `env`块传入，因此这些凭证在内存中派生， **从不写入其他地方**。
核心 **只读取市场/账户数据** 和 **下订单**。它不管理您的钱包，不处理存款或取款，不签名除订单之外的任何交易，也不包含任何交易逻辑。它是Polymarket API的抽象，以便您可以构建自己的代理，而不会失去Polymarket平台固有的任何功能。
## 配置
所有设置都是在MCP配置的 `env`块中设置的环境变量（如下面的快速入门）：
| 变量 | 必需 | 描述 |
| ----------------- | :------: | -------------------------------------------------------- |
| `PRIVATE_KEY` | 交易必填 | 签名密钥。 **请保密**。 |
| `FUNDER_ADDRESS` | 交易必填 | 持有您的资金并下订单的地址。 |
| `DRY_RUN` | 否 | `true`模拟订单而不签名或发送它们。 |
| `LOG_LEVEL` | 否 | 日志级别（默认`INFO`）。 |
| `SIGNATURE_TYPE`, `CLOB_API_KEY`, `CLOB_SECRET`, `CLOB_PASSPHRASE` | 自动 | 在启动时在内存中派生/检测；仅在需要覆盖时设置。 |
市场数据和研究工具（`list_markets`, `get_order_book`, `get_price`, `search`, `get_holders`, ...）**无需钱包** 即可工作。账户和交易工具（`get_positions`, `get_balance`, `place_order`, `cancel_order`, ...）需要 `PRIVATE_KEY` 和 `FUNDER_ADDRESS`。使用 `DRY_RUN=true` 安全地执行 `place_order`。
> 价格和订单始终按 **结果代币**（`clobTokenId`）计算，而不是按市场计算。份额在结果发生时支付1美元，在结果不发生时支付0美元，因此代币的价格是市场的隐含概率。
## 其他主机
快速入门的JSON文件可以直接用于Claude Desktop、Claude Code、Cursor和大多数MCP主机。两种情况有所不同：
**VS Code（Copilot）** 使用 `servers` 键（不是 `mcpServers`）和 `type` 字段。将此内容放入 `.vscode/mcp.json`，然后重新加载窗口：
```json
{
"servers": {
"polygate": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/ilmari99/polygate@v0.3.0", "polygate-mcp"],
"env": {
"FUNDER_ADDRESS": "0x您的资金地址",
"PRIVATE_KEY": "0x您的签名私钥"
}
}
}
}
```
**运行您自己的检出版本**（在开发PolyGate时）：将 `--from` 指向本地路径而不是git URL - `uvx --from /path/to/polygate polygate-mcp`。
## 可选：用于算法交易的REST网关
同一个核心也作为语言无关的 **REST网关** （FastAPI）暴露给不是MCP主机的客户端 - 例如，用另一种语言编写的算法交易机器人通过普通的HTTP驱动PolyGate。它提供相同的功能，由生成的 `PLATFORM_API_KEY` 保护。
```bash
git clone https://github.com/ilmari99/polygate.git && cd polygate
python -m venv .venv && source .venv/bin/activate
pip install .
polygate # 服务 http://127.0.0.1:8000，交互式文档在 /docs
```
在 `http://127.0.0.1:8000/setup` （在您自己的机器上）或使用 `polygate setup` （远程/SSH）连接您的钱包，然后通过HTTP驱动它。 [examples/sample_agent.py](examples/sample_agent.py) 是一个可运行的、无依赖的参考示例，演示读取 → 决策 → 订单循环，完整的端点参考在 `/docs` 中，一旦服务器运行。
## 开发
```bash
git clone https://github.com/ilmari99/polygate.git && cd polygate
pip install ".[dev]"
pytest -q
```
测试套件完全离线运行（模拟HTTP），并使用 `DRY_RUN` 开关进行测试，该开关模拟订单而不签名或发送它们。
## 安全
- 您的 `PRIVATE_KEY` 控制您的资金。它位于您的MCP配置的 `env` 块中，在您自己的机器上的本地文件中 - 这样就可以了；只是不要将包含它的配置文件提交到共享或公共存储库中。公开 `PRIVATE_KEY` 会使您的资金面临风险。
- 交易工具在配置了资金钱包后会花费真实货币。在测试时保持 `DRY_RUN=true`，并让您的代理在下订单前确认。
## 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
