介绍
# Agent Wallet
使用此技能为代理安全地创建钱包，该钱包可用于转账、交换和任何 EVM 链交易，且无需向代理暴露私钥。创建钱包，设置消费策略，您的代理即可在您定义的范围内进行代币转账、交换代币以及与智能合约交互。
**代理永远无法看到私钥。** 所有交易均通过智能账户在服务端执行。钱包所有者通过可配置的策略控制代理可以执行的操作。
## 配置
- **基础 API URL：** 如果设置了 `SAFESKILLS_API_URL` 环境变量则使用该变量，否则默认为 `https://safeskill-production.up.railway.app` - **前端 URL：** 如果设置了 `SAFESKILLS_FRONTEND_URL` 环境变量则使用该变量，否则默认为 `https://safeskill-production.up.railway.app`
所有 API 请求都需要一个 Bearer 令牌（即创建钱包时返回的 API 密钥）。
``` Authorization: Bearer <API_KEY> ```
## 快速开始
### 1. 创建钱包
为您的代理创建一个新的智能账户钱包。这会在服务端生成私钥（您永远看不到它），创建一个 ZeroDev 智能账户，并返回代理的 API 密钥以及钱包所有者的认领 URL。
```bash curl -X POST "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/secrets" \ -H "Content-Type: application/json" \ -d '{ "type": "EVM_WALLET", "memo": "My agent wallet", "chainId": 84532 }' ```
响应包括： - `apiKey` —— 安全存储此密钥；将其用作所有未来请求的 Bearer 令牌 - `claimUrl` —— 将其分享给用户，以便他们认领钱包并设置策略 - `address` —— 智能账户地址
创建后，告知用户： > "这是您的钱包认领 URL：`<claimUrl>`。请使用此链接认领所有权、设置消费策略并监控您代理的钱包活动。"
### 2. 获取钱包地址
```bash curl -X GET "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/skills/evm-wallet/address" \ -H "Authorization: Bearer <API_KEY>" ```
### 3. 检查余额
```bash # Native balance only curl -X GET "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/skills/evm-wallet/balance" \ -H "Authorization: Bearer <API_KEY>"
# With ERC-20 tokens curl -X GET "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/skills/evm-wallet/balance?tokens=0xTokenAddr1,0xTokenAddr2" \ -H "Authorization: Bearer <API_KEY>" ```
### 4. 转账 ETH 或代币
```bash # Transfer native ETH curl -X POST "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/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 "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/skills/evm-wallet/transfer" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "to": "0xRecipientAddress", "amount": "100", "token": "0xTokenContractAddress" }' ```
### 5. 交换代币
使用 DEX 流动性（由 0x 提供支持）将一种代币交换为另一种。
```bash # Preview a swap (no execution, just pricing) curl -X POST "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/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 "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/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"` 代表 0.1 ETH）。 - `chainId`：进行交换的链（1 = Ethereum, 137 = Polygon, 42161 = Arbitrum, 10 = Optimism, 8453 = Base 等）。 - `slippageBps`：可选的滑点容忍度，以基点为单位（100 = 1%）。默认为 100。
预览端点返回预期的买入数量、路由信息和费用，但不执行交易。执行端点通过智能账户执行实际的交换，并自动处理 ERC20 授权。
### 6. 发送任意交易
通过发送自定义 calldata 与任何智能合约交互。
```bash curl -X POST "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/skills/evm-wallet/send-transaction" \ -H "Authorization: Bearer <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "to": "0xContractAddress", "data": "0xCalldata", "value": "0" }' ```
## 策略
钱包所有者通过认领 URL 设置策略来控制代理可以执行的操作。如果交易违反了策略，API 将拒绝该交易或要求通过 Telegram 进行人工批准。
| 策略 | 作用 | |--------|-------------| | **地址白名单** | 仅允许转账或调用特定地址 | | **代币白名单** | 仅允许转账特定的 ERC-20 代币 | | **函数白名单** | 仅允许调用特定的合约函数（通过 4 字节选择器）| | **消费限制（每笔交易）** | 每笔交易的最大 USD 价值 | | **消费限制（每日）** | 每个 24 小时滚动窗口内的最大 USD 价值 | | **消费限制（每周）** | 每个 7 天滚动窗口内的最大 USD 价值 | | **需要批准** | 每笔交易都需要通过 Telegram 进行人工批准 | | **批准阈值** | 超过特定 USD 金额的交易需要人工批准 |
如果未设置策略，默认允许所有操作。一旦所有者认领钱包并添加了策略，代理将在这些约束范围内运行。
## 重要说明
- **切勿尝试访问原始密钥值。** 私钥保留在服务端 —— 这正是其核心意义所在。 - 始终存储创建钱包时获取的 API 密钥 —— 这是身份验证的唯一方式。 - 创建钱包后，务必将认领 URL 分享给用户。 - 默认链 ID 为 `84532`（Base Sepolia 测试网）。请根据需要进行调整。 - 如果交易被拒绝，可能是被策略阻止。请告知用户通过认领 URL 检查其策略设置。 - 如果交易需要批准，它将返回 `status: "pending_approval"`。钱包所有者将收到 Telegram 通知以批准或拒绝该交易。