> ## 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 Key**（`awx_...`）— 長效，標識您的帳戶。安全儲存在環境變數中。
* **Session Token** — 短效，範圍限定於特定代理和操作。自動輪換。

```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-Hant/features/policy-engine)了解完整配置詳情。

### 第三層：MPC 簽名（Paratro）

AgentWallex 使用 Paratro 的 2-of-3 門檻 MPC 協議：

| 分片      | 持有者              | 用途     |
| ------- | ---------------- | ------ |
| Shard 1 | AgentWallex 簽名服務 | 主動簽名   |
| Shard 2 | 獨立託管節點           | 主動簽名   |
| Shard 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"
```