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

# 安全架构

> 四层安全体系 — 身份认证、策略引擎、MPC 签名和人工审批 — 保护您的代理。

## 概述

AgentWallex 建立在一个核心原则之上：AI 代理**绝不应该接触私钥**。取而代之的是，交易通过多方计算（MPC）签名，没有任何单一方持有完整密钥。

平台通过四个独立的安全层实施保护。每笔交易必须通过所有层级，才能被广播到区块链。

## 四层安全体系

### 第一层：身份认证

每个 API 请求都通过双令牌系统进行认证：

* **API 密钥**（`awx_...`）— 长期有效，标识您的账户。请安全存储在环境变量中。
* **会话令牌** — 短期有效，限定于特定代理和操作。自动轮换。

```typescript theme={null}
// API key authenticates your account
const aw = new AgentWallex({ apiKey: process.env.AGENTWALLEX_API_KEY! });

// Session tokens are managed internally by the SDK
// Each agent gets its own scoped session
```

**关键属性：**

| 属性     | 详情                     |
| ------ | ---------------------- |
| 密钥轮换   | 无停机时间                  |
| 会话过期   | 可配置：1-24 小时            |
| 权限范围   | 按代理                    |
| IP 白名单 | Growth 和 Enterprise 计划 |

### 第二层：策略引擎

每笔交易在签名之前必须通过策略引擎。策略按顺序评估 — 第一个违规即停止交易。

策略引擎支持：

* 消费限额（单笔、每日、每月）
* 地址白名单和黑名单
* 代币限制
* 频率控制（速率限制）
* 基于时间的调度规则
* 人工审批路由

详情请参阅[策略引擎](/zh/features/policy-engine)的完整配置说明。

### 第三层：MPC 签名（Paratro）

AgentWallex 使用 Paratro 的 2-of-3 阈值 MPC 协议：

| 分片   | 持有者              | 用途    |
| ---- | ---------------- | ----- |
| 分片 1 | AgentWallex 签名服务 | 主动签名  |
| 分片 2 | 独立托管节点           | 主动签名  |
| 分片 3 | 冷存储              | 仅用于恢复 |

**关键安全属性：**

* 完整的私钥**永远不会在内存中重建**
* 3 个分片中的任意 2 个即可签署交易
* 单个分片被泄露不会危及钱包安全
* 密钥生成使用分布式密钥生成（DKG）— 没有任何单一方看到过完整密钥

### 第四层：人工审批

对于高价值或异常交易，AgentWallex 可以路由至人工审批：

* 超过可配置阈值的交易
* 发往新（未见过的）地址的交易
* 异常监控检测到的异常模式

```json theme={null}
{
  "event": "approval.requested",
  "data": {
    "transactionId": "tx_pending_123",
    "agentId": "agent_abc123",
    "amount": "2500.00",
    "reason": "Amount exceeds humanApprovalThreshold (1000)",
    "expiresAt": "2025-01-15T11:00:00Z"
  }
}
```

审批可通过仪表盘、API 或 Webhook 集成处理。

## 双层策略架构

AgentWallex 在两个独立层级执行策略：

### 业务层（开发者配置）

您的自定义规则 — 消费限额、白名单、频率控制。这些通过 API 或仪表盘设置，可随时更新。

### 基础设施安全网（Paratro 执行）

在 MPC 签名层执行的硬限制，**无法通过** API 调用覆盖：

| 控制项    | 默认值      | 说明           |
| ------ | -------- | ------------ |
| 绝对每日上限 | \$50,000 | 无论业务策略如何的硬上限 |
| 异常检测   | 已启用      | 基于 ML 的模式分析  |
| 紧急冻结   | 始终可用     | 即时钱包锁定       |
| 冷却期    | 10 分钟    | 冻结后无法立即解冻    |

<Warning>
  即使您的 API 密钥被泄露，基础设施安全网也能防止灾难性损失。攻击者无法覆盖 Paratro 执行的限制。
</Warning>

## 密钥管理生命周期

### 密钥生成

密钥使用分布式密钥生成（DKG）创建。在任何时候都没有任何一方看到完整的私钥：

1. 3 个 MPC 节点中的每一个独立生成一个随机分片。
2. 分片通过密码学方式组合以生成公钥。
3. 对应的私钥仅以分布式分片的形式存在。

### 密钥轮换

密钥分片会定期轮换，且不会更改钱包地址。这称为"主动密钥共享" — 旧的分片在轮换后变得无效。

### 紧急冻结

任何授权方都可以立即冻结钱包：

<CodeGroup>
  ```typescript SDK theme={null}
  await aw.agents.freeze("agent_abc123");
  ```

  ```bash API theme={null}
  curl -X PUT https://api.agentwallex.com/api/v1/agents/agent_abc123/status \
    -H "X-API-Key: awx_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"status": "inactive"}'
  ```
</CodeGroup>

冻结的钱包在被明确解冻之前无法签署任何交易（有强制冷却期）。

## 审计日志

每个操作都会被不可变地记录：

* 所有 API 请求（包括 IP、用户代理、时间戳）
* 所有策略评估（通过/失败及原因）
* 所有签名操作
* 所有冻结/解冻事件
* 所有 Webhook 投递

| 计划         | 日志保留期 |
| ---------- | ----- |
| Starter    | 90 天  |
| Growth     | 1 年   |
| Enterprise | 自定义   |

通过 API 查询审计日志：

```bash theme={null}
curl -X GET "https://api.agentwallex.com/api/v1/audit-logs?page_num=1&page_size=20" \
  -H "X-API-Key: awx_your_api_key"
```