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

# Thanh toán nhỏ x402

> Thanh toán theo cuộc gọi API sử dụng giao thức HTTP 402 — ngân sách phiên, thương lượng tự động và thanh toán.

## x402 là gì?

x402 là giao thức thanh toán máy-với-máy được xây dựng xung quanh HTTP `402 Payment Required`. Nó cho phép các tác nhân AI tự động thanh toán cho quyền truy cập API mà không cần sự can thiệp của con người. AgentWallex triển khai x402 v2 với payload ủy quyền EIP-3009.

## Header x402 v2

Giao thức sử dụng ba header HTTP:

| Header              | Hướng             | Mục đích                            |
| ------------------- | ----------------- | ----------------------------------- |
| `PAYMENT-REQUIRED`  | Server đến Client | Thách thức 402 với thông tin giá cả |
| `PAYMENT-SIGNATURE` | Client đến Server | Payload thanh toán đã ký            |
| `PAYMENT-RESPONSE`  | Server đến Client | Xác nhận thanh toán                 |

## Luồng Thanh toán

```
Client Agent               Paid API               AgentWallex
    |                        |                         |
    |-- GET /resource ------>|                         |
    |<-- 402 + PAYMENT-REQUIRED                        |
    |                        |                         |
    |-- POST /api/v1/x402/pay -----------------------> |
    |                        |     (sign + policy)     |
    |<-- payment_info        |                         |
    |                        |                         |
    |-- GET /resource + PAYMENT-SIGNATURE -----------> |
    |<-- 200 + PAYMENT-RESPONSE                        |
```

<Steps>
  <Step title="Tác nhân yêu cầu tài nguyên">
    Tác nhân gửi yêu cầu HTTP tiêu chuẩn đến endpoint API trả phí.
  </Step>

  <Step title="Server trả về 402">
    API phản hồi với HTTP 402 và header `PAYMENT-REQUIRED` chứa chi tiết giá cả (số tiền, token, chuỗi, địa chỉ payTo).
  </Step>

  <Step title="Tác nhân thanh toán qua AgentWallex">
    Tác nhân gửi chi tiết thanh toán đến `POST /x402/pay`. AgentWallex đánh giá chính sách và ký thanh toán.
  </Step>

  <Step title="Tác nhân thử lại với bằng chứng thanh toán">
    Tác nhân thử lại yêu cầu ban đầu với header `PAYMENT-SIGNATURE` được đính kèm.
  </Step>

  <Step title="Server xác minh và phản hồi">
    API xác minh chữ ký thanh toán (qua facilitator AgentWallex) và trả về tài nguyên.
  </Step>
</Steps>

## Sử dụng API x402

### Kiểm tra URL có Hỗ trợ x402 không

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/check \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paid-api.example.com/v1/data"}'
```

### Tạo Ngân sách Phiên

Phiên cho phép bạn ủy quyền trước ngân sách chi tiêu cho các cuộc gọi API lặp lại:

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/sessions \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_uuid",
    "budget_limit": "100.00",
    "chain": "eip155:84532",
    "ttl_seconds": 3600,
    "allowed_urls": ["https://paid-api.example.com/v1/data"]
  }'
```

### Kích hoạt Thương lượng Thanh toán

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/pay \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_uuid",
    "target_url": "https://paid-api.example.com/v1/data",
    "session_id": "optional_session_uuid",
    "chain": "eip155:84532"
  }'
```

Phản hồi bao gồm `payment_info` với:

| Trường       | Mô tả                             |
| ------------ | --------------------------------- |
| `ledger_id`  | ID mục sổ cái nội bộ              |
| `amount`     | Số tiền thanh toán                |
| `fee_amount` | Phí nền tảng được trừ             |
| `fee_rate`   | Tỷ lệ phí được áp dụng            |
| `token`      | Token được sử dụng (ví dụ: USDC)  |
| `chain`      | Chuỗi được sử dụng cho thanh toán |
| `status`     | Trạng thái thanh toán             |

## Tích hợp SDK

### Bộ chặn HTTP Tự động

SDK TypeScript cung cấp bộ chặn xử lý toàn bộ luồng x402 tự động:

```typescript theme={null}
const fetchWithPayment = aw.x402.httpInterceptor({
  agentId: "agent_abc123",
  chain: "eip155:84532",
});

// This automatically handles 402 challenges
const response = await fetchWithPayment("https://paid-api.example.com/v1/data");
const data = await response.json();
```

### Luồng Thủ công

```typescript theme={null}
// 1. Create a session budget
const session = await aw.x402.createSession({
  agentId: "agent_abc123",
  budgetLimit: "100.00",
  chain: "eip155:84532",
  ttlSeconds: 3600,
  allowedUrls: ["https://paid-api.example.com/v1/data"],
});

// 2. Pay for an API call
const result = await aw.x402.pay({
  agentId: "agent_abc123",
  targetUrl: "https://paid-api.example.com/v1/data",
  sessionId: session.id,
  chain: "eip155:84532",
});

// 3. Or pay using the session directly
await aw.x402.sessionPay(session.id, {
  targetUrl: "https://paid-api.example.com/v1/data",
});
```

## Dành cho Nhà cung cấp Dịch vụ

Nếu bạn cung cấp API trả phí, server của bạn nên trả về thách thức x402 v2 khi thiếu thanh toán.

### Trả về 402 với PAYMENT-REQUIRED

Mã hóa thách thức JSON (base64) vào header `PAYMENT-REQUIRED`:

```json theme={null}
{
  "x402Version": 2,
  "resource": "https://your-api.com/v1/data",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "0.10",
      "asset": "USDC",
      "payTo": "0xYourAddress",
      "maxTimeoutSeconds": 300
    }
  ]
}
```

### Xác minh và Thanh toán

Sử dụng các endpoint facilitator của AgentWallex:

```bash theme={null}
# Verify a payment signature
POST /api/v1/x402/facilitator/verify

# Settle a verified payment
POST /api/v1/x402/facilitator/settle

# Query supported chains
GET /api/v1/x402/facilitator/supported
```

## Giá trị Mặc định Vận hành

| Tham số                     | Giá trị                                                 |
| --------------------------- | ------------------------------------------------------- |
| Khoảng thời gian thanh toán | 300 giây                                                |
| Ngưỡng thanh toán           | \$10.00                                                 |
| Độ trễ thanh toán tối đa    | 3,600 giây                                              |
| Chuỗi được hỗ trợ           | `eip155:84532`, `eip155:8453`, `eip155:1`, `eip155:137` |