> ## 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.

# Kiến trúc Bảo mật

> Bốn lớp bảo mật — định danh, công cụ chính sách, ký MPC và con người tham gia — bảo vệ tác nhân của bạn.

## Tổng quan

AgentWallex được xây dựng trên nguyên tắc rằng các tác nhân AI **không bao giờ nên có quyền truy cập khóa riêng tư**. Thay vào đó, giao dịch được ký bằng Tính toán Đa bên (MPC), trong đó không bên đơn lẻ nào nắm giữ khóa hoàn chỉnh.

Nền tảng thực thi bảo mật thông qua bốn lớp độc lập. Một giao dịch phải đi qua tất cả các lớp trước khi được phát sóng lên blockchain.

## Bốn Lớp Bảo mật

### Lớp 1: Định danh và Xác thực

Mọi yêu cầu API được xác thực bằng hệ thống hai token:

* **API Key** (`awx_...`) — Tồn tại lâu dài, xác định tài khoản của bạn. Lưu trữ an toàn trong biến môi trường.
* **Session Token** — Tồn tại ngắn hạn, phạm vi cho các tác nhân và hoạt động cụ thể. Được xoay tự động.

```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
```

**Thuộc tính chính:**

| Thuộc tính            | Chi tiết                           |
| --------------------- | ---------------------------------- |
| Xoay khóa             | Không có thời gian ngừng hoạt động |
| Hết hạn phiên         | Có thể cấu hình: 1-24 giờ          |
| Phạm vi quyền         | Theo tác nhân                      |
| Danh sách IP cho phép | Gói Growth và Enterprise           |

### Lớp 2: Công cụ Chính sách

Mọi giao dịch phải đi qua công cụ chính sách trước khi ký. Các chính sách được đánh giá theo thứ tự — vi phạm đầu tiên sẽ dừng giao dịch.

Công cụ chính sách hỗ trợ:

* Giới hạn chi tiêu (theo giao dịch, hàng ngày, hàng tháng)
* Danh sách trắng và danh sách đen địa chỉ
* Hạn chế token
* Kiểm soát tốc độ (giới hạn tần suất)
* Quy tắc lịch trình theo thời gian
* Định tuyến phê duyệt của con người

Xem [Công cụ Chính sách](/vi/features/policy-engine) để biết chi tiết cấu hình đầy đủ.

### Lớp 3: Ký MPC (Paratro)

AgentWallex sử dụng giao thức MPC ngưỡng 2-trong-3 của Paratro:

| Mảnh   | Người giữ              | Mục đích              |
| ------ | ---------------------- | --------------------- |
| Mảnh 1 | Dịch vụ ký AgentWallex | Tham gia ký hoạt động |
| Mảnh 2 | Node giám sát độc lập  | Tham gia ký hoạt động |
| Mảnh 3 | Lưu trữ lạnh           | Chỉ phục hồi          |

**Thuộc tính bảo mật quan trọng:**

* Khóa riêng tư đầy đủ **không bao giờ được tái tạo** trong bộ nhớ
* Bất kỳ 2 trong 3 mảnh có thể ký giao dịch
* Xâm phạm một mảnh đơn lẻ không xâm phạm ví
* Tạo khóa sử dụng Tạo khóa Phân tán (DKG) — không bên đơn lẻ nào nhìn thấy toàn bộ khóa

### Lớp 4: Con người Tham gia

Đối với giao dịch giá trị cao hoặc bất thường, AgentWallex có thể định tuyến đến phê duyệt của con người:

* Giao dịch vượt ngưỡng có thể cấu hình
* Giao dịch đến địa chỉ mới (chưa thấy)
* Mẫu bất thường được phát hiện bởi giám sát bất thường

```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"
  }
}
```

Phê duyệt có thể được xử lý qua dashboard, API hoặc tích hợp webhook.

## Kiến trúc Chính sách Hai Lớp

AgentWallex thực thi chính sách ở hai cấp độ độc lập:

### Lớp Nghiệp vụ (Do Nhà phát triển Cấu hình)

Các quy tắc tùy chỉnh của bạn — giới hạn chi tiêu, danh sách trắng, kiểm soát tốc độ. Chúng được thiết lập qua API hoặc dashboard và có thể được cập nhật bất kỳ lúc nào.

### Mạng lưới An toàn Cơ sở hạ tầng (Được Paratro Thực thi)

Giới hạn cứng được thực thi ở cấp độ ký MPC **không thể bị ghi đè** bởi các cuộc gọi API:

| Kiểm soát                    | Mặc định      | Mô tả                                                  |
| ---------------------------- | ------------- | ------------------------------------------------------ |
| Giới hạn hàng ngày tuyệt đối | \$50,000      | Trần cứng bất kể chính sách nghiệp vụ                  |
| Phát hiện bất thường         | Đã bật        | Phân tích mẫu dựa trên ML                              |
| Đóng băng khẩn cấp           | Luôn sẵn sàng | Khóa ví tức thì                                        |
| Thời gian chờ                | 10 phút       | Sau khi đóng băng, không thể mở đóng băng ngay lập tức |

<Warning>
  Ngay cả khi khóa API của bạn bị xâm phạm, mạng lưới an toàn cơ sở hạ tầng ngăn chặn tổn thất nghiêm trọng. Kẻ tấn công không thể ghi đè giới hạn được Paratro thực thi.
</Warning>

## Vòng đời Quản lý Khóa

### Tạo Khóa

Khóa được tạo bằng Tạo Khóa Phân tán (DKG). Tại không thời điểm nào bất kỳ bên nào nhìn thấy toàn bộ khóa riêng tư:

1. Mỗi trong 3 node MPC tạo một phần ngẫu nhiên.
2. Các phần được kết hợp bằng mật mã để tạo khóa công khai.
3. Khóa riêng tư tương ứng chỉ tồn tại dưới dạng các mảnh phân tán.

### Xoay Khóa

Các mảnh khóa được xoay định kỳ mà không thay đổi địa chỉ ví. Điều này được gọi là "chia sẻ bí mật chủ động" — các mảnh cũ trở nên vô dụng sau khi xoay.

### Đóng băng Khẩn cấp

Bất kỳ bên được ủy quyền nào có thể đóng băng ví ngay lập tức:

<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>

Ví bị đóng băng không thể ký bất kỳ giao dịch nào cho đến khi được mở đóng băng rõ ràng (với thời gian chờ bắt buộc).

## Ghi nhật ký Kiểm toán

Mọi hành động được ghi nhật ký không thể thay đổi:

* Tất cả yêu cầu API (với IP, user agent, dấu thời gian)
* Tất cả đánh giá chính sách (đạt/không đạt với lý do)
* Tất cả hoạt động ký
* Tất cả sự kiện đóng băng/mở đóng băng
* Tất cả giao hàng webhook

| Gói        | Thời gian lưu trữ nhật ký |
| ---------- | ------------------------- |
| Starter    | 90 ngày                   |
| Growth     | 1 năm                     |
| Enterprise | Tùy chỉnh                 |

Truy vấn nhật ký kiểm toán qua 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"
```