介绍
# Vincent - Polymarket for agents
使用此技能为您的智能体创建 Polymarket 钱包并在预测市场上进行交易。浏览市场、下注、跟踪持仓和管理订单——所有这些操作都无需向智能体暴露私钥。钱包在 Polygon 上使用 Gnosis Safe，并通过 Polymarket 的中继器实现无 Gas 交易。
**智能体永远无法看到私钥。** 所有操作均在服务端执行。智能体获得一个范围受限的 API 密钥，该密钥只能执行钱包所有者策略允许的操作。私钥永远不离开 Vincent 服务器。
## 安全模型
此技能专为**通过服务端控制进行人工监督的自主智能体交易**而设计。理解此模型非常重要：
**不需要环境变量**，因为此技能采用智能体优先的接入流程：智能体通过调用 Vincent API 在运行时创建自己的 Polymarket 钱包，该 API 返回一个范围受限的 API 密钥。没有预先存在的凭据需要配置。智能体在钱包创建期间生成并存储自己的 API 密钥——在技能运行之前无需存在任何机密信息。智能体持久化返回的 API 密钥的配置路径（`${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/agentwallet/` 或 `./agentwallet/`）已在此技能的元数据中声明。
**智能体的 API 密钥不是私钥。** 它是一个范围受限的 Bearer 令牌，只能执行钱包所有者设定的策略范围内的操作。Vincent 服务器在服务端强制执行所有策略——无论智能体发送什么内容，都无法绕过这些策略。如果交易违反策略，服务器将拒绝该交易。如果交易需要审批，服务器将暂存该交易并通过 Telegram 通知钱包所有者进行带外人工审批。
**有意启用了模型调用。** 此技能的目的是赋予 AI 智能体自主的 Polymarket 交易能力。期望智能体在人工操作员定义的边界内自主调用交易操作（浏览市场、下注、管理持仓）。人工操作员通过策略（支出限额、审批门槛）控制智能体可以执行的操作，而不是通过限制单个调用。智能体将其范围受限的 API 密钥持久化到声明的配置路径，以便跨会话恢复交易；这对于自主交易智能体来说是预期行为。存储的密钥是受限的且受策略约束——即使其他进程读取了它，也只能执行钱包所有者策略允许的操作，且所有者可以立即撤销它。
**所有 API 调用仅通过 HTTPS/TLS 发送到 `heyvincent.ai`**。不会联系任何其他端点、服务或外部主机。智能体不会读取、收集或传输任何超出 Polymarket 钱包操作所需的数据。
**密钥生命周期：**
- **创建**：智能体调用 `POST /api/secrets` 创建钱包。API 返回一个范围受限的 API 密钥和一个认领 URL。 - **认领**：人工操作员使用认领 URL 在 `https://heyvincent.ai` 获取所有权并配置策略。 - **撤销**：钱包所有者可以随时从 Vincent 前端撤销智能体的 API 密钥。服务器将立即拒绝已撤销的密钥。 - **重新关联**：如果智能体丢失了其 API 密钥，钱包所有者会生成一个一次性重新关联令牌（10 分钟后过期），智能体将其交换以获取新密钥。 - **轮换**：钱包所有者可以随时撤销当前密钥并颁发重新关联令牌以轮换凭据。
## 配置
所有 API 请求都需要一个 Bearer 令牌（创建钱包时返回的范围受限 API 密钥）。此密钥不是私钥——它是一个服务端强制执行的、受限策略的凭据，钱包所有者可以随时撤销。
在创建钱包后，将 API 密钥存储在声明的配置路径之一中。如果您是 OpenClaw 实例，请将其存储并从 `${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/agentwallet/<API_KEY_ID>.json` 检索。否则，请将其存储在当前工作目录的 `agentwallet/<API_KEY_ID>.json` 中。这些路径已在此技能的元数据中声明，以便宿主环境能够审计和管理凭据存储。
``` Authorization: Bearer <API_KEY> ```
## 快速入门
### 1. 创建 Polymarket 钱包
为您的智能体创建一个新的 Polymarket 钱包。这会在服务端生成一个私钥（智能体永远看不到它），在 Polygon 上创建一个 Gnosis Safe，并为智能体返回一个范围受限的 API 密钥，以及供钱包所有者使用的认领 URL。
```bash curl -X POST "https://heyvincent.ai/api/secrets" \ -H "Content-Type: application/json" \ -d '{ "type": "POLYMARKET_WALLET", "memo": "My prediction market wallet" }' ```
响应包括：
- `apiKey` -- 一个范围受限的 API 密钥；请安全存储并将其用作所有后续请求的 Bearer 令牌 - `claimUrl` -- 分享给用户以认领所有权并设置策略 - `walletAddress` -- EOA 地址（Safe 在首次使用时惰性部署）
创建后，请告知用户：
> "这是您的钱包认领 URL：`<claimUrl>`。使用此链接认领所有权、设置支出策略，并在 https://heyvincent.ai 监控您智能体的钱包活动。"
**重要提示：** 创建后，钱包中没有资金。用户必须先在 Polygon 上将 **USDC.e（跨链 USDC）** 发送到 Safe 地址，然后才能下注。
### 2. 获取余额
```bash curl -X GET "https://heyvincent.ai/api/skills/polymarket/balance" \ -H "Authorization: Bearer <API_KEY>" ```
返回：
- `walletAddress` -- Safe 地址（如果需要，在首次调用时部署） - `collateral.balance` -- 可用于交易的 USDC.e 余额 - `collateral.allowance` -- 已批准给 Polymarket 合约的金额
**注意：** 第一次余额调用将触发 Safe 部署和抵押品批准（通过中继器无 Gas 操作）。这可能需要 30-60 秒。
### 3. 为钱包充值
在下注之前，用户必须将 USDC.e 发送到 Safe 地址：
1. 从 `/balance` 端点获取钱包地址 2. 将 Polygon 上的 USDC.e（跨链 USDC，合约 `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`）发送到该地址 3. 每笔押注最低需要 $1（Polymarket 最低限额）
**不要发送原生 USDC** (`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`)。Polymarket 只接受跨链 USDC.e。
### 4. 从 Vincent EVM 钱包转账（替代充值方法）
如果您拥有资金的 Vincent EVM 钱包，可以使用 `/transfer-between-secrets` 端点直接转账到您的 Polymarket 钱包。Vincent 会验证您拥有这两个密钥，并自动处理代币转换和跨链桥接，以在 Polygon 上获取 USDC.e。
**示例：从 Base 转账 USDC 到 Polygon 上的 Polymarket**
```bash # Preview the transfer first curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/transfer-between-secrets/preview" \ -H "Authorization: Bearer <EVM_WALLET_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "toSecretId": "<POLYMARKET_SECRET_ID>", "fromChainId": 8453, "toChainId": 137, "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "tokenInAmount": "10", "tokenOut": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", "slippage": 100 }'
# Execute the transfer curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/transfer-between-secrets/execute" \ -H "Authorization: Bearer <EVM_WALLET_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "toSecretId": "<POLYMARKET_SECRET_ID>", "fromChainId": 8453, "toChainId": 137, "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "tokenInAmount": "10", "tokenOut": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", "slippage": 100 }' ```
**关键点：**
- 使用您的 **EVM 钱包的 API 密钥**（而不是 Polymarket API 密钥）作为 Bearer 令牌 - `toSecretId` 必须是您的 Polymarket 钱包的密钥 ID - 对于 Polymarket 目标，仅允许 `toChainId: 137` (Polygon) 和 `tokenOut: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` (USDC.e) - 服务器验证您拥有这两个密钥——拒绝向其他用户的钱包转账 - 同链、同代币转账使用直接转账；否则使用 Relay.link 进行跨链交换 - 对于跨链转账，请使用状态端点和返回的 `relayRequestId` 来跟踪完成情况：
```bash curl -X GET "https://heyvincent.ai/api/skills/evm-wallet/transfer-between-secrets/status/<RELAY_REQUEST_ID>" \ -H "Authorization: Bearer <EVM_WALLET_API_KEY>" ```
这通常比手动桥接和交换更容易，尤其是当从 Base、Arbitrum 或 Optimism 等其他链转账时。
### 5. 浏览和搜索市场
```bash # Search markets by keyword (recommended) curl -X GET "https://heyvincent.ai/api/skills/polymarket/markets?query=bitcoin&limit=20" \ -H "Authorization: Bearer <API_KEY>"
# Search by Polymarket URL or slug (for specific markets) curl -X GET "https://heyvincent.ai/api/skills/polymarket/markets?slug=btc-updown-5m-1771380900&limit=5" \ -H "Authorization: Bearer <API_KEY>"
# Or use a full Polymarket URL as the slug parameter curl -X GET "https://heyvincent.ai/api/skills/polymarket/markets?slug=https://polymarket.com/event/btc-updown-5m-1771380900" \ -H "Authorization: Bearer <API_KEY>"
# Get all active markets (paginated) curl -X GET "https://heyvincent.ai/api/skills/polymarket/markets?active=true&limit=50" \ -H "Authorization: Bearer <API_KEY>"
# Get specific market by condition ID curl -X GET "https://heyvincent.ai/api/skills/polymarket/market/<CONDITION_ID>" \ -H "Authorization: Bearer <API_KEY>" ```
**市场响应包括：**
- `question`：市场问题 - `outcomes`：数组，如 `["Yes", "No"]` 或 `["Team A", "Team B"]` - `outcomePrices`：每个结果的当前价格 - `tokenIds`：**每个结果的代币 ID 数组** - 使用这些进行下注 - `acceptingOrders`：市场是否开放交易 - `closed`：市场是否已结算
**重要提示：** 始终使用市场响应中的 `tokenIds` 数组。每个结果在相同索引处都有一个对应的代币 ID。对于 "Yes/No" 市场：
- `tokenIds[0]` = "Yes" 代币 ID - `tokenIds[1]` = "No" 代币 ID
### 6. 获取订单簿
```bash curl -X GET "https://heyvincent.ai/api/skills/polymarket/orderbook/<TOKEN_ID>" \ -H "Authorization: Bearer <API_KEY>" ```
返回带有价格和数量的买卖单。在下达订单之前，使用此信息确定当前市场价格。
### 7. 下注
```bash curl -X POST "https://heyvincent.ai/api/skills/polymarket/bet" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "tokenId": "<OUTCOME_TOKEN_ID>", "side": "BUY", "amount": 5, "price": 0.55 }' ```
参数：
- `tokenId`：结果代币 ID（来自市场数据或订单簿） - `side`：`"BUY"` 或 `"SELL"` - `amount`：对于 BUY 订单，要花费的美元金额。对于 SELL 订单，要出售的股份数量。 - `price`：可选限价（0.01 到 0.99）。省略则以市价单执行。除非用户指定限价，否则始终使用市价单。
**BUY 订单：**
- `amount` 是您想要花费的美元金额（例如，`5` = $5） - 您将收到 `amount / price` 股（例如，$5 以 0.50 价格 = 10 股） - 最低订单金额为 $1
**SELL 订单：**
- `amount` 是要出售的股份数量 - 您将收到 `amount * price` 美元 - 必须先拥有股份（来自之前的 BUY）
**重要时机：** BUY 成交后，请等待几秒钟再出售。股份需要时间在链上结算。
如果交易违反策略，服务器将返回错误，说明触发了哪个策略。如果交易需要人工审批（基于审批门槛策略），服务器将返回 `status: "pending_approval"`，钱包所有者将收到 Telegram 通知以批准或拒绝。
### 8. 查看持仓、仓位和订单
```bash # Get current holdings with P&L (recommended) curl -X GET "https://heyvincent.ai/api/skills/polymarket/holdings" \ -H "Authorization: Bearer <API_KEY>"
# Get open orders curl -X GET "https://heyvincent.ai/api/skills/polymarket/positions" \ -H "Authorization: Bearer <API_KEY>"
# Get trade history curl -X GET "https://heyvincent.ai/api/skills/polymarket/trades" \ -H "Authorization: Bearer <API_KEY>" ```
**持仓端点** 返回所有仓位，包括拥有的股份、平均入场价格、当前价格和未实现盈亏：
```json { "success": true, "data": { "walletAddress": "0x...", "holdings": [ { "tokenId": "123456...", "shares": 42.5, "averageEntryPrice": 0.55, "currentPrice": 0.62, "pnl": 2.97, "pnlPercent": 12.73, "marketTitle": "Will Bitcoin hit $100k by end of 2025?", "outcome": "Yes" } ] } } ```
这是用于以下操作的最佳端点：
- 在下达卖出订单之前检查当前仓位 - 设置止损或止盈规则 - 计算总投资组合价值和绩效 - 向用户展示他们的有效押注
**仓位端点** 返回开放限价单（订单簿中等待成交的订单）。
**交易端点** 返回历史交易活动。
### 9. 取消订单
```bash # Cancel specific order curl -X DELETE "https://heyvincent.ai/api/skills/polymarket/orders/<ORDER_ID>" \ -H "Authorization: Bearer <API_KEY>"
# Cancel all open orders curl -X DELETE "https://heyvincent.ai/api/skills/polymarket/orders" \ -H "Authorization: Bearer <API_KEY>" ```
### 10. 赎回已结算仓位
市场结算后，可以赎回获胜仓位以将条件代币转换回 USDC.e。使用持仓端点检查哪些仓位具有 `redeemable: true`，然后调用赎回端点。
```bash # Redeem all redeemable positions curl -X POST "https://heyvincent.ai/api/skills/polymarket/redeem" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{}'
# Redeem specific markets by condition ID curl -X POST "https://heyvincent.ai/api/skills/polymarket/redeem" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "conditionIds": ["0xabc123...", "0xdef456..."] }' ```
参数：
- `conditionIds`：可选的条件 ID 数组，用于赎回。如果省略，则赎回**所有**可赎回的仓位。
响应：
```json { "success": true, "data": { "walletAddress": "0x...", "redeemed": [ { "conditionId": "0xabc123...", "marketTitle": "Will Bitcoin hit $100k by end of 2025?", "outcome": "Yes", "shares": 42.5 } ], "transactionHash": "0x..." } } ```
如果没有可赎回的仓位，`redeemed` 将是一个空数组，并且不会提交交易。
**工作原理：** 赎回是无gas的（通过 Safe 由 Polymarket 的中继器执行）。对于标准市场，它会调用 CTF 合约上的 `redeemPositions`。对于负风险市场，它会调用 NegRiskAdapter 上的 `redeemPositions`。这两种类型都是自动处理的——您不需要知道市场是哪种类型。
**何时赎回：** 定期检查持仓端点。市场解决后，仓位可能需要一段时间才会变得可赎回。请在持仓响应中查找 `redeemable: true`。
## 策略（服务器端强制执行）
钱包所有者通过 `https://heyvincent.ai` 上的认领 URL 设置策略来控制代理可以执行的操作。所有策略均由 Vincent API 在服务器端强制执行——代理无法绕过或修改它们。如果交易违反策略，API 将拒绝该交易。如果交易触发了批准阈值，API 将挂起该交易并向钱包所有者发送 Telegram 通知，以便进行带外人工批准。
| 策略 | 作用 | | --------------------------- | ---------------------------------------------------------------- | | **Spending limit (per tx)** | 每笔交易的最大 USD 价值 | | **Spending limit (daily)** | 每个滚动 24 小时内的最大 USD 价值 | | **Spending limit (weekly)** | 每个滚动 7 天内的最大 USD 价值 | | **Require approval** | 每笔交易都需要通过 Telegram 进行人工批准 | | **Approval threshold** | 超过一定 USD 金额的交易需要通过 Telegram 进行人工批准 |
在钱包被认领之前，代理可以在没有策略限制的情况下操作。这是设计使然：代理优先的引导流程允许代理立即开始交易。一旦人工操作员通过认领 URL 认领了钱包，他们就可以添加任何策略组合来约束代理的行为。钱包所有者还可以随时完全撤销代理的 API 密钥。
## 重新链接（恢复 API 访问）
如果代理丢失了其 API 密钥，钱包所有者可以从前端生成一个**重新链接令牌 (re-link token)**。然后，代理可以使用此令牌交换一个新的范围限定 API 密钥。
**工作原理：**
1. 用户从 `https://heyvincent.ai` 的钱包详情页面生成重新链接令牌 2. 用户将令牌提供给代理（例如通过在聊天中粘贴） 3. 代理调用重新链接端点，用令牌交换一个新的范围限定 API 密钥
```bash curl -X POST "https://heyvincent.ai/api/secrets/relink" \ -H "Content-Type: application/json" \ -d '{ "relinkToken": "<TOKEN_FROM_USER>", "apiKeyName": "Re-linked API Key" }' ```
响应包括：
- `secret` -- 钱包元数据（id、type、address、chainId 等） - `apiKey.key` -- 新的范围限定 API 密钥，将其用作所有未来请求的 Bearer 令牌
**重要提示：** 重新链接令牌是一次性使用的，并且在 10 分钟后过期，因此用户通过聊天向您发送重新链接令牌是安全的，因为您会立即使用它。此端点不需要身份验证——令牌本身就是授权。确保保存返回的 API 密钥。如果您是 OpenClaw 实例，请将其存储并从 `${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/agentwallet/<API_KEY_ID>.json` 中检索。否则，请将其存储在当前工作目录下的 `agentwallet/<API_KEY_ID>.json` 中。
如果用户告诉您他们有重新链接令牌，请使用此端点重新获得对钱包的访问权限。保存返回的 API 密钥并将其用于所有后续请求。
## 工作流示例
1. **创建钱包：**
```bash POST /api/secrets {"type": "POLYMARKET_WALLET", "memo": "Betting wallet"} ```
2. **获取 Safe 地址（触发部署）：**
```bash GET /api/skills/polymarket/balance # Returns walletAddress -- give this to user to fund ```
3. **用户将 USDC.e 发送到 Polygon 上的 Safe 地址**
4. **搜索市场：**
```bash # Search by keyword - returns only active, tradeable markets GET /api/skills/polymarket/markets?query=bitcoin&active=true
# Or search by slug from a Polymarket URL GET /api/skills/polymarket/markets?slug=btc-updown-5m-1771380900 ```
响应示例：
```json { "markets": [ { "question": "Will Bitcoin hit $100k by end of 2025?", "outcomes": ["Yes", "No"], "outcomePrices": ["0.65", "0.35"], "tokenIds": ["123456...", "789012..."], "acceptingOrders": true } ] } ```
5. **查看您想要的结果的订单簿：**
```bash # Use the tokenId from the market response GET /api/skills/polymarket/orderbook/123456... # Note the bid/ask prices ```
6. **使用正确的令牌 ID 下注买入：**
```bash # tokenId must be from the tokenIds array, NOT the conditionId POST /api/skills/polymarket/bet {"tokenId": "123456...", "side": "BUY", "amount": 5, "price": 0.55} ```
7. **等待结算**（几秒钟）
8. **卖出仓位：**
```bash POST /api/skills/polymarket/bet {"tokenId": "123456...", "side": "SELL", "amount": 9.09, "price": 0.54} ```
9. **市场解决后赎回**（如果持有至解决）： ```bash # Check holdings for redeemable positions GET /api/skills/polymarket/holdings # If redeemable: true, redeem to get USDC.e back POST /api/skills/polymarket/redeem {} ```
## 重要说明
- **在任何下注或交易之后**，请分享用户的 Polymarket 个人资料链接，以便他们验证和查看其仓位：`https://polymarket.com/profile/<polymarketWalletAddress>`（使用钱包的 Safe 地址）。 - **无需 gas。** 所有 Polymarket 交易都是通过 Polymarket 的中继器无gas执行的。 - **切勿尝试访问原始密钥值。** 私钥保留在服务器端——这正是其全部意义所在。 - 始终将钱包创建时生成的 API 密钥存储在声明的配置路径中。如果您是 OpenClaw 实例，请将其存储在 `${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/agentwallet/<API_KEY_ID>.json` 中。否则，请将其存储在当前工作目录下的 `agentwallet/<API_KEY_ID>.json` 中。 - 在创建新钱包之前，请始终在声明的配置路径中搜索现有的 API 密钥。如果您是 OpenClaw 实例，请在 `${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/agentwallet/` 中搜索。否则，请在 `./agentwallet/` 中搜索。 - 创建钱包后，请始终与用户分享认领 URL。 - 如果交易被拒绝，可能是被服务器端策略阻止了。请告诉用户在 `https://heyvincent.ai` 检查其策略设置。 - 如果交易需要批准，它将返回 `status: "pending_approval"`。钱包所有者将收到 Telegram 通知以批准或拒绝。
**常见错误：**
- `"No orderbook exists for the requested token id"` - 市场已关闭或您使用了错误的 ID。请确保： - 市场具有 `acceptingOrders: true` - 您使用的是 `tokenIds` 数组中的 `tokenId`，而不是 `conditionId` - 市场尚未解决