代理钱包

使用此功能可安全创建一个钱包，供代理用于转账、兑换以及任何EVM链交易，同时确保私钥永不暴露给代理。创建钱包、设置支出策略后，您的代理即可在您定义的权限范围内转移代币、进行兑换并与智能合约交互。

代理永远无法查看私钥。所有交易均通过智能账户在服务器端执行。钱包所有者可通过可配置策略控制代理的操作权限。

配置

• 基础API地址：若已设置SAFESKILLS_API_URL环境变量则使用该值，否则默认使用https://safeskill-production.up.railway.app
• 前端地址：若已设置SAFESKILLS_FRONTEND_URL环境变量则使用该值，否则默认使用https://safeskill-production.up.railway.app

所有API请求均需携带Bearer令牌（即创建钱包时返回的API密钥）。

Authorization: Bearer <API_KEY>

快速开始

1. 创建钱包

为您的智能体创建一个新的智能账户钱包。这将在服务器端生成一个私钥（您永远看不到它），创建一个 ZeroDev 智能账户，并返回智能体的 API 密钥以及钱包所有者的领取 URL。

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-- 智能账户地址

创建完成后，请告知用户：

"这是您的钱包领取链接：<claimUrl>。请使用此链接领取所有权、设置支出策略并监控您的智能体钱包活动。"

2. 获取钱包地址

curl -X GET "${SAFESKILLS_API_URL:-https://safeskill-production.up.railway.app}/api/skills/evm-wallet/address" \
  -H "Authorization: Bearer <API_KEY>"

3. 查询余额

# 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 或代币

# 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 提供支持）将一个代币兑换为另一个。

# 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
  }'

• 卖出代币/buyToken：代币合约地址。使用0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE表示原生ETH。
• sellAmount：要出售的可读数量（例如，"0.1"表示0.1 ETH）。
• chainId：进行兑换的链（1 = 以太坊，137 = Polygon，42161 = Arbitrum，10 = Optimism，8453 = Base，等等）。
• slippageBps：可选滑点容差，以基点表示（100 = 1%）。默认为100。

预览端点返回预期的购买数量、路由信息和费用，但不执行交易。执行端点通过智能账户执行实际的兑换，并自动处理ERC20授权。

6. 发送任意交易

通过发送自定义调用数据与任何智能合约交互。

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进行人工批准。

如果未设置任何策略，默认允许所有操作。一旦所有者认领钱包并添加策略，代理将在这些边界内运行。

重要说明

• 切勿尝试访问原始密钥值。私钥始终保留在服务器端——这是核心原则。
• 务必保存创建钱包时生成的API密钥——这是唯一的身份验证方式。
• 创建钱包后，请务必将领取链接分享给用户。
• 默认链ID为84532（Base Sepolia测试网）。请根据需要调整。
• 如果交易被拒绝，可能是被策略规则拦截。请提示用户通过领取链接检查其策略设置。
• 若交易需要审批，系统将返回状态："pending_approval"。钱包所有者将通过Telegram收到批准或拒绝的通知。