> ## 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.
# x402 Pay
> Kích hoạt thương lượng thanh toán x402 cho URL mục tiêu.
Thương lượng và hoàn thành một thanh toán x402 cho URL mục tiêu. AgentWallex đánh giá chính sách của tác nhân, ký thanh toán qua MPC và trả về thông tin thanh toán cần thiết để truy cập tài nguyên trả phí.
## Nội dung Yêu cầu
Tác nhân có ví sẽ cung cấp thanh toán.
URL hỗ trợ x402 để thanh toán (ví dụ: `https://paid-api.example.com/v1/data`).
ID phiên tùy chọn để trừ từ ngân sách phiên hiện có. Xem [Phiên x402](/vi/api-reference/x402-sessions).
Định danh chuỗi CAIP-2 cho thanh toán (ví dụ: `eip155:84532`). Nếu bỏ qua, chuỗi mặc định của tác nhân được sử dụng.
## Phản hồi
ID mục sổ cái nội bộ cho thanh toán này.
Số tiền thanh toán.
Phí nền tảng được trừ.
Tỷ lệ phí được áp dụng (dựa trên giá theo cấp).
Token được sử dụng cho thanh toán (ví dụ: `USDC`).
Chuỗi được sử dụng cho thanh toán.
Trạng thái thanh toán: `completed`, `pending`, `failed`.
Giá trị `PAYMENT-SIGNATURE` để đưa vào yêu cầu thử lại đến URL mục tiêu.
## Ví dụ
```bash cURL 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_abc123",
"target_url": "https://paid-api.example.com/v1/data",
"session_id": "sess_xyz789",
"chain": "eip155:84532"
}'
```
```typescript TypeScript theme={null}
const result = await aw.x402.pay({
agentId: "agent_abc123",
targetUrl: "https://paid-api.example.com/v1/data",
sessionId: "sess_xyz789",
chain: "eip155:84532",
});
```
```python Python theme={null}
result = await aw.x402.pay(
agent_id="agent_abc123",
target_url="https://paid-api.example.com/v1/data",
session_id="sess_xyz789",
chain="eip155:84532",
)
```
```json Response theme={null}
{
"ledger_id": "ldg_abc123",
"amount": "0.10",
"fee_amount": "0.002",
"fee_rate": "2.0",
"token": "USDC",
"chain": "eip155:84532",
"status": "completed",
"payment_signature": "base64_encoded_signature..."
}
```
## Endpoint Liên quan
| Endpoint | Mô tả |
| --------------------------------- | ------------------------------------------------------------- |
| `POST /x402/check` | Kiểm tra xem URL có hỗ trợ thương lượng thanh toán x402 không |
| `POST /x402/facilitator/verify` | Xác minh chữ ký thanh toán (cho nhà cung cấp dịch vụ) |
| `POST /x402/facilitator/settle` | Thanh toán khoản đã xác minh (cho nhà cung cấp dịch vụ) |
| `GET /x402/facilitator/supported` | Liệt kê chuỗi được hỗ trợ cho x402 |
| `GET /x402/fees/tiers` | Lấy biểu phí theo cấp hiện tại |
## OpenAPI
````yaml POST /api/v1/x402/pay
openapi: 3.1.0
info:
title: AgentWallex API
description: >-
REST API for managing AI agent wallets, on-chain transactions, spending
policies, webhooks, and x402 micropayments.
version: 1.0.0
contact:
name: AgentWallex Support
url: https://agentwallex.com
servers:
- url: https://api.agentwallex.com
description: Production
- url: https://api-sandbox.agentwallex.com
description: Sandbox
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Agents
description: Create and manage AI agent wallets.
- name: Transactions
description: Send payments and query transaction history.
- name: Policies
description: Configure spending limits and access controls.
- name: Webhooks
description: Register and manage webhook endpoints.
- name: x402
description: x402 micropayment negotiation and session management.
paths:
/api/v1/x402/pay:
post:
tags:
- x402
summary: x402 Pay
description: >-
Negotiate and complete one x402 payment for a target URL. AgentWallex
evaluates the agent's policies, signs the payment via MPC, and returns
the payment info needed to access the paid resource.
operationId: x402Pay
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
- target_url
properties:
agent_id:
type: string
description: The agent whose wallet will fund the payment.
target_url:
type: string
format: uri
description: >-
The x402-enabled URL to pay for (e.g.,
`https://paid-api.example.com/v1/data`).
session_id:
type: string
description: >-
Optional session ID to deduct from an existing session
budget.
chain:
type: string
description: >-
CAIP-2 chain identifier for payment settlement (e.g.,
`eip155:84532`). If omitted, the agent's default chain is
used.
example:
agent_id: agent_abc123
target_url: https://paid-api.example.com/v1/data
session_id: sess_xyz789
chain: eip155:84532
responses:
'200':
description: Payment completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/X402PayResult'
example:
ledger_id: ldg_abc123
amount: '0.10'
fee_amount: '0.002'
fee_rate: '2.0'
token: USDC
chain: eip155:84532
status: completed
payment_signature: base64_encoded_signature...
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
X402PayResult:
type: object
description: Result of an x402 payment negotiation.
properties:
ledger_id:
type: string
description: Internal ledger entry ID for this payment.
amount:
type: string
description: Payment amount.
fee_amount:
type: string
description: Platform fee deducted.
fee_rate:
type: string
description: Fee percentage applied (based on tiered pricing).
token:
type: string
description: Token used for payment (e.g., `USDC`).
chain:
type: string
description: Chain used for settlement.
status:
type: string
enum:
- completed
- pending
- failed
description: Payment status.
payment_signature:
type: string
description: >-
The `PAYMENT-SIGNATURE` value to include in the retry request to the
target URL.
ErrorResponse:
type: object
description: Standard error response.
required:
- code
- type
- message
properties:
code:
type: string
description: Machine-readable error code.
type:
type: string
enum:
- invalid_request_error
- authentication_error
- authorization_error
- not_found_error
- rate_limit_error
- internal_error
description: Error type category.
message:
type: string
description: Human-readable error description.
responses:
BadRequest:
description: Invalid request body or parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: invalid_request
type: invalid_request_error
message: The request body is missing required fields.
Unauthorized:
description: Missing or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: authentication_failed
type: authentication_error
message: The provided API key is invalid or expired.
Forbidden:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: insufficient_permissions
type: authorization_error
message: You do not have permission to perform this action.
RateLimited:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: rate_limit_exceeded
type: rate_limit_error
message: Too many requests. Please retry after a short delay.
InternalError:
description: Server-side error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: server_error
type: internal_error
message: An unexpected error occurred. Please try again later.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key authentication. Keys are prefixed with `awx_`.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT bearer token authentication.
````