AgentShieldAgent API Reference

LOCAL EVM PAYMENT BOUNDARY

Agent API 可视化手册

Agent 通过用户创建的受限授权令牌调用本机 AgentShield。它可以读取账户、签名、发送、兑换、跨链和创建更小权限的子授权，但永远不会接触私钥、助记词或钱包密码。

Base URLhttp://127.0.0.1:9400/api/v1
授权格式Bearer cag_…
数据格式application/json
给 Agent 使用？优先把 SKILL.md 和授权令牌交给 Agent。需要机器可读的完整字段说明时，使用 Agent 文本版手册。

AUTHENTICATION

每个请求使用一枚受限令牌

所有 Agent 接口

把用户在 AgentShield 中创建的授权令牌放入请求头。令牌固定绑定创建时的钱包；切换到其他钱包后，它不会控制新钱包。

Authorization: Bearer cag_your_scoped_token
Accept: application/json
Content-Type: application/json
不要发送钱包密码Agent API 从不接受私钥、助记词或 PIN。钱包解锁只能由用户在本机控制台完成。

OPERATION LIFECYCLE

交易类请求是可追踪操作

pending_approval等待用户在本机核对
executing正在签名或提交
completed仅签名任务完成
submitted已广播，尚未最终确认
confirmed链上确认，任务完成
attention_required停止重试并请求人工检查

READ

钱包与余额

GET/wallet/statuswallet:read

返回当前钱包地址、锁定状态、自动锁定时间和已配置 Chain ID。

GET/wallet/addresswallet:read

返回授权绑定钱包的 ID 与 EVM 地址。

GET/wallet/balances有效授权即可

读取原生资产、维护列表内的 ERC-20 和曾通过 LI.FI 精确发现的资产。结果缓存最多 60 秒。

POST/wallet/balances/refresh有效授权即可

跳过余额缓存并立即刷新。只读取公开链上数据，不要求钱包处于解锁状态。

DISCOVERY

网络与资产

GET/network/statuswallet:read

查看当前支持的 EVM 网络、RPC 来源与路由验证模式，不暴露 RPC URL。

GET/assetswallet:read

获取可安全使用的链级资产别名和精确合约地址。未知资产必须传合约地址，不能猜测 ticker。

查询 LI.FI 资产目录
GET /assets?catalog=lifi&chain_id=42161
GET /assets?catalog=lifi&tag=stablecoin

SIGN

消息与结构化交易签名

POST/signwallet:sign_message

签署普通 personal message。Hex、JSON、digest 和交易结构会被拒绝，避免把消息签名变成盲签旁路。

请求
{
  "mode": "personal_sign",
  "message": "Approve invoice 42 for reconciliation"
}
POST/sign/payloadwallet:sign_transaction

签署任意结构化 EVM 交易 payload，但不广播。请求仍会经过授权策略和本机审批。

请求示例
{
  "payload": {
    "chain_id": 1,
    "nonce": 7,
    "gas_limit": 100000,
    "to": "0x0000000000000000000000000000000000000000",
    "value_wei": "0",
    "data": "0x",
    "gas_price_wei": "1000000000"
  },
  "idempotency_key": "task-42-sign-1",
  "reason": "Sign reviewed transaction for task 42"
}

TRANSFER

发送原生资产或 ERC-20

POST/sendwallet:send

金额必须使用资产最小单位的十进制整数字符串。使用 native 表示链的原生资产。

请求示例
{
  "chain_id": 42161,
  "to": "0x0000000000000000000000000000000000000000",
  "value_wei": "1000000",
  "token": "USDC",
  "idempotency_key": "invoice-42-send-1",
  "reason": "Pay invoice 42"
}

ROUTING

Swap

POST/swap/quotewallet:swap

只获取报价，不创建交易操作；报价请求不需要幂等键。

POST/swapwallet:swap
请求示例
{
  "from_chain": "8453",
  "to_chain": "8453",
  "from_token": "native",
  "to_token": "USDC",
  "from_amount": "10000000000000000",
  "slippage": 0.005,
  "idempotency_key": "task-42-swap-1",
  "reason": "Convert task budget"
}

CROSS-CHAIN

Bridge

POST/bridge/quotewallet:bridge

只获取跨链报价，不创建交易操作。

POST/bridgewallet:bridge
请求示例
{
  "from_chain": "42161",
  "to_chain": "8453",
  "from_token": "USDC",
  "to_token": "USDC",
  "from_amount": "20000000",
  "to_address": "0x0000000000000000000000000000000000000000",
  "slippage": 0.005,
  "idempotency_key": "task-42-bridge-1",
  "reason": "Move task budget to Base"
}

TRACK

查询操作与链上状态

GET/operations/{id}操作所属授权

持续查询直到进入终态。接口只返回当前授权自己创建的操作。

GET/status/{hash}?chain_id=42161wallet:read

查询已广播 EVM 交易的 receipt 状态。

APPROVAL

由 Agent 审核同一钱包的请求

wallet:approve

审批授权只能看到并处理与自己绑定到同一钱包的待审批操作。钱包必须已由用户在本机选择并解锁；其他钱包的操作即使 ID 已知也会返回未找到。

GET/approvalswallet:approve

返回待审批操作的完整 payload、策略检查结果、金额、收款地址、网络和原因。Agent 应先检查这些字段，再决定是否通过。

POST/approvals/{id}/approvewallet:approve

通过并立即执行一项同钱包操作。只有在用户明确授予审批决策权，且详情完全符合任务要求时才应调用。

审批不是绕过策略审批 Agent 不会获得私钥或跨钱包能力，目标操作仍需满足原授权、钱包状态和执行安全检查。

DELEGATION

创建不能逃逸的子授权

grant:delegate

子授权固定绑定同一钱包，scope 必须是父授权的子集，策略只能继承或收紧，有效期不能超过父授权。撤销父授权会同时使所有后代失效。

POST/grants/delegategrant:delegate
请求示例
{
  "label": "Settlement Agent",
  "scopes": ["wallet:read", "wallet:send"],
  "ttl_seconds": 7200,
  "allow_direct_execution": false,
  "policy": {
    "allowed_chain_ids": [42161],
    "max_amount_usd": "10",
    "allowed_tokens": ["USDC"],
    "max_operations_per_day": 5
  }
}
钱包必须已解锁创建根授权和子授权时，绑定钱包都必须由用户在本机选中并解锁；否则返回 423 WALLET_LOCKED。

ERRORS

失败时如何处理

401 UNAUTHORIZED令牌无效或已过期
403 INSUFFICIENT_SCOPE当前授权不含所需能力
409 WALLET_NOT_ACTIVE先让用户切换到令牌绑定的钱包
423 WALLET_LOCKED等待用户在本机解锁；不要索取密码
403 POLICY_DENIED请求超出网络、额度或白名单策略
409 IDEMPOTENCY_CONFLICT同一个幂等键被用于不同请求
不要盲目重试交易类请求必须复用稳定的 idempotency_key。遇到 attention_required 或提交结果未知时，停止重试并请用户检查。