介绍
# Vincent - A wallet for agents
使用此技能可以安全地创建一个钱包，供智能体用于转账、交换以及任何 EVM 链交易，而无需向智能体暴露私钥。创建钱包、设置消费策略后，您的智能体便可在您定义的范围内进行代币转账、交换以及与智能合约交互。
**智能体永远无法获取私钥。** 所有交易均通过 ZeroDev 智能账户在服务端执行。智能体获得一个仅可执行钱包所有者策略所允许操作的受限 API 密钥。私钥绝不离开 Vincent 服务器。
## 安全模型
此技能专为**通过服务端控制进行人类监督的自主智能体操作**而设计。理解此模型非常重要：
**无需环境变量**，因为此技能使用智能体优先的接入流程：智能体通过调用 Vincent API 在运行时创建自己的钱包，该 API 返回一个受限 API 密钥。无需预先配置凭据。智能体在创建钱包期间生成并存储其自己的 API 密钥 —— 在技能运行之前无需存在任何机密信息。智能体持久化返回的 API 密钥的配置路径（`${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/agentwallet/` 或 `./agentwallet/`）已在此技能的元数据中声明。
**智能体的 API 密钥不是私钥。** 它是一个受限的 Bearer 令牌，只能执行钱包所有者设定的策略内的交易。Vincent 服务器在服务端执行所有策略 —— 无论智能体发送什么内容，都无法绕过这些策略。如果交易违反策略，服务器将拒绝该交易。如果交易需要批准，服务器会将其挂起，并通过 Telegram 通知钱包所有者进行带外人工批准。
**模型调用已被有意启用。** 此技能的目的是赋予 AI 智能体自主的钱包能力。期望智能体在人类操作员定义的范围内自行调用钱包操作（转账、交换、合约调用）。人类通过策略（消费限额、地址白名单、代币白名单、函数白名单、批准阈值）来控制智能体可以执行的操作 —— 而非通过限制单独的调用。智能体将其受限的 API 密钥持久化到声明的配置路径，以便跨会话恢复钱包操作；这对于自主钱包智能体来说是预期行为。存储的密钥是受限的且受策略约束 —— 即使其他进程读取了它，它也只能执行钱包所有者策略允许的操作，且所有者可以立即撤销它。
**所有 API 调用仅通过 HTTPS/TLS 发送到 `heyvincent.ai`**。不会联系任何其他端点、服务或外部主机。智能体不会读取、收集或传输超出钱包操作所需范围的任何数据。
**Vincent 是开源且经过审计的。** 执行策略、管理私钥和执行交易的服务端代码可在 [github.com/HeyVincent-ai/Vincent](https://github.com/HeyVincent-ai/Vincent) 上公开审计。Vincent 后台会持续进行安全审计，涵盖密钥管理、策略执行、交易签名和 API 身份验证。您可以验证策略执行的工作原理、私钥的存储方式、受限 API 密钥的验证方式以及撤销的处理方式 —— 没有任何内容是不透明的。如果您想自托管 Vincent 而不是使用托管服务，该存储库包含部署说明。
**密钥生命周期：**
- **创建**：智能体调用 `POST /api/secrets` 创建钱包。API 返回一个受限 API 密钥和一个认领 URL。 - **认领**：人类操作员使用认领 URL 来取得所有权并配置策略。 - **撤销**：钱包所有者可以随时从 Vincent 前端 (`https://heyvincent.ai`) 撤销智能体的 API 密钥。撤销的密钥会被服务器立即拒绝。撤销逻辑是[开源的](https://github.com/HeyVincent-ai/Vincent)。 - **重新关联**：如果智能体丢失了其 API 密钥，钱包所有者会生成一个一次性重新关联令牌（10 分钟后过期），智能体将其交换为新密钥。 - **轮换**：钱包所有者可以随时撤销当前密钥并颁发重新关联令牌以轮换凭据。
## 使用哪种密钥类型
| 类型 | 用例 | 网络 | Gas | | ------------ | ----------------------------------------- | ----------------------- | ---------------- | | `EVM_WALLET` | 转账、交换、DeFi、合约调用 | 任何 EVM 链 | 赞助（免费） | | `RAW_SIGNER` | 用于特殊协议的原始消息签名 | 任何（Ethereum + Solana） | 您支付 |
**选择 `EVM_WALLET`**（默认）用于：
- 发送 ETH 或代币 - 在 DEX 上交换代币 - 与智能合约交互 - 任何标准 EVM 交易
**仅在需要时选择 `RAW_SIGNER`**：
- 用于不兼容智能账户的协议的原始 ECDSA/Ed25519 签名 - 签署您将自行广播的交易哈希 - Solana 签名
## 配置
所有 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. 创建钱包
为您的智能体创建一个新的智能账户钱包。这会在服务端生成一个私钥（智能体无法获取），创建一个 ZeroDev 智能账户，并为智能体返回一个受限 API 密钥，以及供钱包所有者使用的认领 URL。
```bash curl -X POST "https://heyvincent.ai/api/secrets" \ -H "Content-Type: application/json" \ -d '{ "type": "EVM_WALLET", "memo": "My agent wallet", "chainId": 84532 }' ```
响应包括：
- `apiKey` -- 一个受限 API 密钥；请安全存储并将其用作所有未来请求的 Bearer 令牌 - `claimUrl` -- 将此分享给用户，以便他们认领钱包并设置策略 - `address` -- 智能账户地址
创建后，请告知用户：
> "这是您的钱包认领 URL：`<claimUrl>`。使用此 URL 认领所有权、设置消费策略，并在 https://heyvincent.ai 监控您智能体的钱包活动。"
### 2. 获取钱包地址
```bash curl -X GET "https://heyvincent.ai/api/skills/evm-wallet/address" \ -H "Authorization: Bearer <API_KEY>" ```
### 3. 检查余额
```bash # Get all token balances across all supported chains (ETH, WETH, USDC, etc.) curl -X GET "https://heyvincent.ai/api/skills/evm-wallet/balances" \ -H "Authorization: Bearer <API_KEY>"
# Filter to specific chains (comma-separated chain IDs) curl -X GET "https://heyvincent.ai/api/skills/evm-wallet/balances?chainIds=1,137,42161" \ -H "Authorization: Bearer <API_KEY>" ```
返回所有 ERC-20 代币和原生余额，包括符号、精度、Logo 和 USD 价值。
### 4. 转账 ETH 或代币
```bash # Transfer native ETH curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/transfer" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "to": "0xRecipientAddress", "amount": "0.01" }'
# Transfer ERC-20 token curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/transfer" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "to": "0xRecipientAddress", "amount": "100", "token": "0xTokenContractAddress" }' ```
如果交易违反策略，服务器将返回一个错误，解释触发了哪条策略。如果交易需要人工批准（基于批准阈值策略），服务器将返回 `status: "pending_approval"`，并且钱包所有者会收到 Telegram 通知以批准或拒绝。
### 5. 交换代币
使用 DEX 流动性（由 0x 提供支持）将一种代币交换为另一种。
```bash # Preview a swap (no execution, just pricing) curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/swap/preview" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "sellToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "sellAmount": "0.1", "chainId": 1 }'
# Execute a swap curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/swap/execute" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "sellToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "sellAmount": "0.1", "chainId": 1, "slippageBps": 100 }' ```
- `sellToken` / `buyToken`：代币合约地址。原生 ETH 使用 `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`。 - `sellAmount`：要出售的人类可读数量（例如 0.1 ETH 使用 `"0.1"`）。 - `chainId`：进行交换的链（1 = Ethereum, 137 = Polygon, 42161 = Arbitrum, 10 = Optimism, 8453 = Base 等）。 - `slippageBps`：可选的滑点容忍度，以基点为单位（100 = 1%）。默认为 100。
预览端点返回预期的购买数量、路由信息和费用，而不执行操作。执行端点通过智能账户执行实际交换，并自动处理 ERC20 批准。
### 6. 发送任意交易
通过发送自定义 calldata 与任何智能合约交互。
```bash curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/send-transaction" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "to": "0xContractAddress", "data": "0xCalldata", "value": "0" }' ```
### 7. 在您的密钥之间转账
在您拥有的 Vincent 密钥之间转移资金（例如，从一个 EVM 钱包到另一个，或到一个 Polymarket 钱包）。Vincent 会验证您是否拥有这两个密钥，并自动处理任何代币转换或跨链桥接。
#### 预览转账
获取一份报价，显示预期的输出、费用以及您的余额是否充足 —— 而不执行任何操作。
```bash curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/transfer-between-secrets/preview" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "toSecretId": "<DESTINATION_SECRET_ID>", "fromChainId": 8453, "toChainId": 8453, "tokenIn": "ETH", "tokenInAmount": "0.1", "tokenOut": "ETH" }' ```
#### 执行转账
```bash curl -X POST "https://heyvincent.ai/api/skills/evm-wallet/transfer-between-secrets/execute" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "toSecretId": "<DESTINATION_SECRET_ID>", "fromChainId": 8453, "toChainId": 8453, "tokenIn": "ETH", "tokenInAmount": "0.1", "tokenOut": "ETH" }' ```
#### 检查跨链转账状态
对于跨链转账，执行响应包含一个 `relayRequestId`。使用它来轮询完成状态。
```bash curl -X GET "https://heyvincent.ai/api/skills/evm-wallet/transfer-between-secrets/status/<RELAY_REQUEST_ID>" \ -H "Authorization: Bearer <API_KEY>" ```
**参数：**
- `toSecretId`：目标密钥的 ID（必须归同一用户所有）。 - `fromChainId` / `toChainId`：源和目标的链 ID。 - `tokenIn` / `tokenOut`：代币地址，或原生 ETH 使用 `"ETH"`。 - `tokenInAmount`：要发送的人类可读数量（例如 `"0.1"`）。 - `slippage`：可选的滑点容忍度，以基点为单位（例如 `100` = 1%）。
**行为：**
- **相同代币 + 相同链**：作为直接转账执行（Gas 赞助）。 - **不同代币或链**：使用中继服务进行原子交换 + 桥接。 - 目标密钥可以是 `EVM_WALLET` 或 `POLYMARKET_WALLET`。 - 服务器会验证您同时拥有源密钥和目标密钥 —— 转账到您不拥有的密钥将被拒绝。 - 转账遵循与普通转账相同的服务端策略（消费限额、批准阈值等）。
## 策略（服务端执行）
钱包所有者通过 `https://heyvincent.ai` 上的认领 URL 设置策略来控制代理可以执行的操作。所有策略均由 Vincent API 在服务端强制执行——代理无法绕过或修改这些策略。如果交易违反策略，API 将拒绝该交易。如果交易触发了批准阈值，API 将暂存该交易，并向钱包所有者发送 Telegram 通知，以进行带外的人工批准。策略强制执行逻辑是开源且可审计的，详见 [github.com/HeyVincent-ai/Vincent](https://github.com/HeyVincent-ai/Vincent)。
| Policy | What it does | | --------------------------- | ------------------------------------------------------------------- | | **Address allowlist** | 仅允许向特定地址进行转账/调用 | | **Token allowlist** | 仅允许转账特定的 ERC-20 代币 | | **Function allowlist** | 仅允许调用特定的合约函数（通过 4 字节选择器） | | **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 密钥，钱包所有者可以从前端生成一个**重新链接令牌**。然后，代理可以使用此令牌换取新的 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 密钥，并将其用于所有后续请求。
## 重要说明
- **无需 Gas 费。** Paymaster 已完全配置——所有交易 Gas 费用均由系统自动赞助。钱包不需要 ETH 用于支付 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 通知以批准或拒绝该交易。
---
## 原始签名者（高级）
用于智能账户无法工作时的原始 ECDSA/Ed25519 签名。
### 创建原始签名者
```bash curl -X POST "https://heyvincent.ai/api/secrets" \ -H "Content-Type: application/json" \ -d '{ "type": "RAW_SIGNER", "memo": "My raw signer" }' ```
响应包括从同一种子派生的以太坊 和 Solana (ed25519) 地址。
### 获取地址
```bash curl -X GET "https://heyvincent.ai/api/skills/raw-signer/addresses" \ -H "Authorization: Bearer <API_KEY>" ```
返回 `ethAddress` 和 `solanaAddress`。
### 对消息进行签名
```bash curl -X POST "https://heyvincent.ai/api/skills/raw-signer/sign" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "message": "0x<hex-encoded-bytes>", "curve": "ethereum" }' ```
- `message`: 要签名的十六进制编码字节（必须以 `0x` 开头） - `curve`: 用于 secp256k1 ECDSA 的 `"ethereum"`，用于 ed25519 的 `"solana"`
返回十六进制编码的签名。对于以太坊，这是 `r || s || v`（65 字节）。对于 Solana，它是 64 字节的 ed25519 签名。