> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体钱包运行时 API

> 鉴权智能体签名请求，并使用智能体钱包运行时路由。

请通过 Agents 应用或 Anyway CLI 创建和管理钱包、资金分配、策略及密钥。

```text theme={null}
Base URL: https://api.anyway.sh
```

## 鉴权

每个运行时请求都使用智能体钱包密钥中的 P-256 密钥，并发送：

| 请求头                 | 值                                  |
| ------------------- | ---------------------------------- |
| `X-Agent-Pubkey`    | 使用标准 Base64 编码的 SPKI P-256 公钥      |
| `X-Agent-Timestamp` | 当前 Unix 秒级时间戳                      |
| `X-Agent-Signature` | 使用标准 Base64 编码的 ASN.1 DER ECDSA 签名 |

对以下 UTF-8 内容的 SHA-256 摘要签名：

```text theme={null}
METHOD
/registered/route/path
unix_timestamp
```

使用不含查询字符串的已注册路径。时间戳必须与服务端时间相差不超过 300 秒。CLI 会自动处理签名、编码和本地密钥选择。

## 路由汇总

| 方法     | 路径                                 | 结果                    |
| ------ | ---------------------------------- | --------------------- |
| `GET`  | `/v1/agent-wallet`                 | 智能体及其钱包身份             |
| `GET`  | `/v1/agent-wallet/policies`        | 钱包绑定的策略               |
| `GET`  | `/v1/agent-wallet/history`         | 钱包活动                  |
| `GET`  | `/v1/agent-wallet/credit-balance`  | 组织额度余额                |
| `POST` | `/v1/agent-wallet/sign-typed-data` | 为 EIP-712 类型化数据生成钱包签名 |

智能体运行环境不会获得商户管理权限。

## 智能体身份

```http theme={null}
GET https://api.anyway.sh/v1/agent-wallet
```

`data` 对象包含：

| 字段                         | 含义                     |
| -------------------------- | ---------------------- |
| `agentId`、`name`           | 智能体身份                  |
| `publicKey`、`keyQuorumId`  | 当前签名身份                 |
| `walletId`、`walletAddress` | 已分配的 Anyway 钱包和 EOA 地址 |
| `providerWalletId`、`appId` | 构造钱包授权签名所需的信息          |
| `revoked`                  | 智能体身份是否已撤销             |

可以使用 `anyway wallets agents whoami` 执行相同的运行时检查。

## 策略

```http theme={null}
GET https://api.anyway.sh/v1/agent-wallet/policies
```

每项策略包含公开标识、名称和执行配置。策略在服务端执行；客户端确认或页面显示的限额不是最终的支出限制。

```bash theme={null}
anyway wallets agents policies
```

## 历史

```http theme={null}
GET https://api.anyway.sh/v1/agent-wallet/history?limit=50
```

`limit` 默认为 `50`，允许 `1` 至 `200`。记录可能包含 `agentId`、目标地址、金额、状态、交易哈希、失败信息、转账类型、区块浏览器 URL 和创建时间。

```bash theme={null}
anyway wallets agents history --limit 50 --format json
```

## 组织额度

```http theme={null}
GET https://api.anyway.sh/v1/agent-wallet/credit-balance
```

```json theme={null}
{
  "success": true,
  "message": "Credit balance retrieved",
  "data": {
    "balance": 12.5,
    "unit": "USDC"
  }
}
```

这是组织级 Anyway 额度池，不是智能体钱包的链上 USDC 分配。

## 签名 EIP-712 类型化数据

```http theme={null}
POST https://api.anyway.sh/v1/agent-wallet/sign-typed-data
Content-Type: application/json
```

```json theme={null}
{
  "typed_data": {
    "domain": {},
    "types": {
      "Example": [{ "name": "value", "type": "uint256" }]
    },
    "primary_type": "Example",
    "message": { "value": "1" }
  },
  "signature": "<wallet authorization signature>"
}
```

成功响应中的 `data.signature` 是带 `0x` 前缀的 secp256k1 Ethereum 签名。请求体里的 `signature` 是另一份钱包授权签名，不是三个 P-256 HTTP 鉴权请求头之一。

建议使用 CLI 构造请求：

```bash theme={null}
anyway wallets agents sign --typed-data-file ./typed-data.json
```

## 常见错误

| 状态    | 含义                      |
| ----- | ----------------------- |
| `400` | 请求体无效或未分配钱包             |
| `401` | P-256 身份缺失、过期、无效、未知或已撤销 |
| `500` | 运行时操作失败                 |

<Warning>
  智能体钱包密钥是支出凭证。不要把私钥材料发送到此 API、写入遥测或放入模型提示词。HTTP 请求头中只应出现公钥和请求签名。
</Warning>