Gửi request có trả phí đầu tiên với x402

Hướng dẫn này dẫn bạn gửi một request Solana qua x402: đọc giá, thanh toán và nhận kết quả kèm biên nhận quyết toán. 15 chain còn lại cũng hoạt động như vậy, mỗi chain ở path riêng.

Bạn cần một ví có USDC trên Solana, hoặc USDC hay EURC trên Base, và một client x402: phần mềm đọc response 402, ký một khoản thanh toán bằng ví của bạn rồi gửi lại request kèm khoản thanh toán đó. Về client x402, hãy xem tài liệu x402 tại x402.org.

1. Gửi request

Gửi request RPC mà không kèm thanh toán:

bash

curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

Response là 402 Payment Required. Các header cho biết phương thức và giá:

http

HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001

HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001

Body liệt kê các phương án thanh toán trong accepts, mỗi phương án cho một stablecoin có thể dùng để thanh toán request. amount tính theo đơn vị nhỏ nhất của stablecoin, nên 1000 là 0.001 USDC, hoặc 0.001 EURC:

json

{
  "error": { "code": "payment_required", "message": "Payment required", "request_id": "…" },
  "x402Version": 2,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "1000", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", … },
    { "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", … },
    { "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", … }
  ],
  "pricing": { "methods": ["getSlot"], …, "weight": 1000, "rawWeight": 42, …, "price": "$0.001", … },
  …
}

{
  "error": { "code": "payment_required", "message": "Payment required", "request_id": "…" },
  "x402Version": 2,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "1000", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", … },
    { "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", … },
    { "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", … }
  ],
  "pricing": { "methods": ["getSlot"], …, "weight": 1000, "rawWeight": 42, …, "price": "$0.001", … },
  …
}

2. Thanh toán bằng client x402

Đưa response 402 cho client x402 của bạn. Client chọn một phương án mà ví của bạn có thể thanh toán, ký một khoản thanh toán theo số tiền đó rồi encode nó để đưa vào header X-Payment. Khoản thanh toán không cần SOL hay ETH để trả phí mạng.

3. Gửi lại request kèm khoản thanh toán

Gửi lại đúng body đó, kèm khoản thanh toán trong header X-Payment:

bash

curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --header 'X-Payment: <PAYMENT_PAYLOAD>' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --header 'X-Payment: <PAYMENT_PAYLOAD>' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

Giữ nguyên body. Giá được tính từ body, nên nếu body đã sửa có giá khác thì khoản thanh toán không còn khớp và bạn sẽ nhận lỗi price_mismatch.

Khi khoản thanh toán đã được xác minh và quyết toán, response RPC trả về kèm biên nhận quyết toán trong header X-Payment-Response:

http

HTTP/2 200
x-payment-response: <RECEIPT>

HTTP/2 200
x-payment-response: <RECEIPT>

json

{ "jsonrpc": "2.0", "id": 1, "result": … }

{ "jsonrpc": "2.0", "id": 1, "result": … }

Mỗi khoản thanh toán chỉ dùng được cho một request. Nếu bạn gửi lại cùng khoản thanh toán đó, nó sẽ bị từ chối với 402 payment_invalid hoặc 409 duplicate_payment, và request không được chuyển tiếp lần nữa.

Response

Request mà x402.erpc.global trả về lỗi trước khi yêu cầu thanh toán thì không tốn phí.

Trạng thái HTTP	`error.code`	Ý nghĩa
402	`payment_required`	Không có khoản thanh toán nào được gửi kèm. Body cho biết giá và các phương án thanh toán.
402	`payment_invalid`	Khoản thanh toán không qua được bước xác minh. Hãy ký một khoản thanh toán mới và gửi lại request.
402	`price_mismatch`	Khoản thanh toán không khớp với phương án nào mà response 402 của request này đưa ra, chẳng hạn về giá.
402	`payment_amount_too_low`	Số tiền thấp hơn khoản thanh toán nhỏ nhất mà x402.erpc.global quyết toán.
402	`settlement_failed`	Việc quyết toán được báo là thất bại. Response đưa lại các phương án thanh toán.
409	`duplicate_payment`	Khoản thanh toán này đã được dùng trước đó.
400	`method_not_supported`, `invalid_request`	Path không bán phương thức đó, hoặc không nhận body đó. Không tính phí.
413	`batch_too_large`	Batch có hơn 100 lệnh gọi. Không tính phí.
500	`configuration_error`	Path hiện không thể phục vụ request. Không tính phí.
503	`payment_unavailable`	Hiện không thể đưa ra phương án thanh toán nào. Không tính phí. Hãy chờ số giây ghi trong header Retry-After rồi thử lại.
503	`service_busy`	Có quá nhiều request cùng lúc. Không tính phí. Hãy chờ số giây ghi trong header Retry-After rồi thử lại.
502	`settlement_failed`	Chưa rõ kết quả quyết toán: khoản thanh toán có thể đã được thực hiện, và không có biên nhận nào được đính kèm. Trước khi ký khoản mới, hãy kiểm tra trên Solana hoặc Base xem khoản thanh toán bạn đã ký có được thực hiện hay chưa.
502, 504	`upstream_error`, `upstream_timeout`	Khoản thanh toán đã được quyết toán, nhưng chain không phản hồi hoặc không phản hồi kịp. Biên nhận vẫn được đính kèm. Gửi lại request sẽ cần một khoản thanh toán mới.

Trên Solana, lệnh gọi nào phải đọc quá nhiều dữ liệu, chẳng hạn getProgramAccounts không có bộ lọc trên một program lớn, sẽ nhận HTTP 200 kèm lỗi JSON-RPC trước khi x402.erpc.global yêu cầu thanh toán, nên không tốn phí.

Bước tiếp theo

Cách x402 tính giá một request: giá của một lệnh gọi, mức tối thiểu $0.001 và batch.
Tổng quan về x402: path của từng chain và các phương án thanh toán.
Tài liệu OpenAPI: cấu trúc request và response của từng path.