Tích Hợp Giao Thức x402 Solana với Kora RPC

Bạn Sẽ Xây Dựng Gì

Hướng dẫn này sẽ đưa bạn qua quá trình triển khai tích hợp x402 (HTTP 402 Payment Required) hoàn chỉnh với Kora, cơ sở hạ tầng ký giao dịch không cần gas của Solana. Khi hoàn thành, bạn sẽ có một hệ thống hoạt động đầy đủ trong đó:

Các API có thể tính phí micropayment cho quyền truy cập bằng giao thức x402
Người dùng thanh toán bằng USDC mà không cần SOL để trả phí gas
Kora xử lý tất cả phí giao dịch với tư cách là người hỗ trợ không cần gas
Các khoản thanh toán được xử lý theo cơ chế nguyên tử trên blockchain Solana

Kết quả cuối cùng sẽ là một API được bảo vệ bằng thanh toán hoạt động đầy đủ:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
X402 + KORA PAYMENT FLOW DEMONSTRATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1/4] Initializing payment signer
  → Network: solana-devnet
  → Payer address: BYJV...TbBc
  ✓ Signer initialized

[2/4] Attempting to access protected endpoint without payment
  → GET http://localhost:4021/protected
  → Response: 402 Payment Required
  ✅ Status code: 402

[3/4] Accessing protected endpoint with x402 payment
  → Using x402 fetch wrapper
  → Payment will be processed via Kora facilitator
  → Transaction submitted to Solana
  ✅ Status code: 200

[4/4] Processing response data
  ✓ Payment response decoded

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUCCESS: Payment completed and API accessed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Response Data:
{
    "data": {
        "message": "Protected endpoint accessed successfully",
        "timestamp": "2025-09-25T20:14:04.242Z"
    },
    "status_code": 200,
    "payment_response": {
        "transaction": "5ULZpdeThaMAy6hcEGfAoMFqJqPpCtxdCxb6JYUV6nA4x8Lk2hKEuzofGUPoe1pop6BdWMSmF5oRPrXsbdWmpruf",
        "success": true,
        "network": "solana-devnet"
    }
}

x402 là gì?

x402 là một tiêu chuẩn thanh toán mở cho phép thực hiện micropayment liền mạch để truy cập API. Thay vì các mô hình đăng ký truyền thống hoặc API key, x402 cho phép các máy chủ tính phí cho từng lần gọi API riêng lẻ, tạo ra cơ sở hạ tầng trả tiền theo mức sử dụng thực sự.

Các lợi ích chính của x402:

Micropayment Tức Thì: Trả một phần nhỏ của một xu cho mỗi lần gọi API
Cho Phép Tác Nhân AI Thanh Toán Cho Các Lần Gọi API: Thanh toán cho các lần gọi API bằng tác nhân AI
Không Cần Đăng Ký: Người dùng chỉ trả tiền cho những gì họ sử dụng
Thanh Toán Web3: Các khoản thanh toán minh bạch, có thể xác minh trên chuỗi
HTTP Tiêu Chuẩn: Hoạt động với cơ sở hạ tầng web hiện có bằng cách sử dụng mã trạng thái HTTP 402 khi yêu cầu thanh toán

Các máy chủ sử dụng x402 để yêu cầu micropayment khi truy cập API sẽ trả về mã trạng thái HTTP 402 khi cần thanh toán. Để truy cập các endpoint được bảo vệ, client phải truyền một khoản thanh toán hợp lệ đến máy chủ trong header X-PAYMENT. x402 dựa vào "Facilitator" để xác minh và xử lý giao dịch để các máy chủ không cần tương tác trực tiếp với cơ sở hạ tầng blockchain.

Hiểu Về Facilitator

Facilitator là thành phần quan trọng trong hệ sinh thái x402. Chúng hoạt động như các dịch vụ chuyên biệt để trừu tượng hóa các khoản thanh toán blockchain thay mặt cho máy chủ API.

Vai Trò Của Facilitator:

Xác Minh Thanh Toán: Xác nhận rằng các payload thanh toán của client được cấu trúc đúng và đủ điều kiện
Trừu Tượng Hóa Độ Phức Tạp: Loại bỏ nhu cầu máy chủ phải tương tác trực tiếp với cơ sở hạ tầng blockchain (ký và trả phí mạng)
Xử Lý Giao Dịch: Gửi các giao dịch đã được xác thực lên Solana (hoặc các mạng khác)

Trong bản demo của chúng tôi, chúng tôi tạo một facilitator tận dụng Kora để xác minh và xử lý giao dịch (chi tiết hơn ở bên dưới).

Kora là gì?

Kora là một node ký của Solana cung cấp dịch vụ ký và giao dịch không cần gas. Nó cho phép các ứng dụng trừu tượng hóa phí gas, cho phép người dùng thanh toán phí giao dịch bằng các token khác ngoài SOL, hoặc có phí được tài trợ hoàn toàn.

Các tính năng chính của Kora:

Giao Dịch Không Cần Gas: Người dùng không cần SOL để thực hiện giao dịch
Trừu Tượng Hóa Phí: Thanh toán phí bằng USDC hoặc các SPL token khác
Giao Diện JSON-RPC: API HTTP đơn giản để xử lý giao dịch
Signer Linh Hoạt: Hỗ trợ nhiều backend ký (memory, Vault, Turnkey, Privy)
Policy Engine: Kiểm soát chi tiết đối với việc xác thực giao dịch và chính sách phí

Trong ngữ cảnh của x402, Kora đóng vai trò là backend lý tưởng cho các facilitator: nó xử lý phí mạng, ký giao dịch và xác thực giao dịch.

Tổng Quan Kiến Trúc

Tích hợp x402 + Kora của chúng tôi bao gồm bốn thành phần kết nối với nhau trong một chu kỳ yêu cầu/phản hồi hoàn chỉnh:

Luồng Thanh Toán Hoàn Chỉnh:

Client yêu cầu tài nguyên được bảo vệ → API trả về 402 Payment Required
Client tạo giao dịch thanh toán với wrapper fetch x402 (lắp ráp một giao dịch Solana kèm lệnh thanh toán)
Client gửi thanh toán đến Facilitator để xác minh
Facilitator xác thực qua Kora, Kora ký và gửi lên Solana
Giao dịch được xác nhận trên chuỗi, Facilitator thông báo cho API
API trả về nội dung được bảo vệ kèm biên lai thanh toán cho Client

Phân Tích Các Thành Phần

Kora RPC Server (Cổng 8080)
- Dịch vụ giao dịch không cần gas cốt lõi
- Xử lý việc ký giao dịch với tư cách là người trả phí
- Xác thực giao dịch theo các chính sách đã cấu hình
Facilitator Wrapper/Proxy Server (Cổng 3000)
- Điều chỉnh Kora theo giao thức x402
- Triển khai các endpoint /verify, /settle và /supported
- Dịch giữa định dạng dữ liệu x402 và Kora
Protected API (Cổng 4021)
- Máy chủ API demo với các endpoint được bảo vệ bằng thanh toán
- Sử dụng middleware x402-express để xử lý thanh toán
- Chỉ trả về dữ liệu sau khi thanh toán thành công
Ứng Dụng Client
- Minh họa cách sử dụng wrapper fetch x402
- Ký giao dịch bằng khóa riêng tư của người dùng

Cách tiếp cận nhiều thành phần có thể có vẻ phức tạp, nhưng nó phản ánh các hệ thống sản xuất thực tế trong đó xử lý thanh toán, phục vụ API và ứng dụng client là các mối quan tâm riêng biệt.

Yêu Cầu Tiên Quyết

Trước khi bắt đầu, hãy đảm bảo bạn có:

Rust (phiên bản ổn định mới nhất)
Node.js (LTS hoặc mới hơn)
pnpm (phiên bản mới nhất)
Hiểu biết cơ bản về giao dịch Solana và SPL token

Thiết Lập Dự Án

Bước 1: Clone và Build Kora

# Clone the repository
git clone https://github.com/solana-foundation/kora.git
cd kora

# Checkout the release branch as Kora is currently in a feature freeze for audit
git checkout release/feature-freeze-for-audit

# Build and install Kora
make install

Thao tác này cài đặt binary kora vào hệ thống của bạn, dùng để chạy máy chủ RPC.

Bước 2: Điều Hướng Đến Thư Mục Demo

cd docs/x402/demo

Bước 3: Cài Đặt Dependencies

Cài đặt các dependency Node.js cho tất cả các thành phần demo:

# Install dependencies for all components (facilitator, API, and client)
pnpm run install:all

Script này cài đặt dependencies cho:

Dịch vụ facilitator wrapper
Máy chủ API được bảo vệ
Ứng dụng demo client

Bước 4: Build Kora SDK

Build Kora SDK để chúng ta có thể sử dụng Kora TypeScript SDK trong Facilitator:

pnpm run build:kora-sdk

Bước 5: Cấu Hình Môi Trường

Demo bao gồm tệp .env.example với các biến môi trường cần thiết. Đầu tiên, hãy thiết lập cấu hình cơ bản:

# Copy the example environment file
cp .env.example .env

Bây giờ bạn cần tạo hoặc cung cấp keypair cho demo. Chạy lệnh sau để tạo các keypair:

pnpm run setup

Thao tác này sẽ tạo các keypair và thêm chúng vào tệp .env:

KORA_SIGNER_ADDRESS - Địa chỉ của Kora signer
KORA_SIGNER_PRIVATE_KEY - Khóa riêng tư của Kora signer
PAYER_ADDRESS - Địa chỉ của người thanh toán sẽ trả tiền để truy cập API được bảo vệ
PAYER_PRIVATE_KEY - Khóa riêng tư của người thanh toán

Bước 5: Cập Nhật Các Tệp Cấu Hình

kora.toml

Tệp kora/kora.toml cấu hình máy chủ Kora RPC. Bạn thường không cần thực hiện bất kỳ thay đổi nào đối với tệp này, nhưng bạn có thể xác minh các cài đặt sau:

Token Thanh Toán: Đảm bảo USDC mint trên Devnet có trong danh sách cho phép:

allowed_tokens = [
    "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", # USDC devnet
]

Xác Thực API: Demo sử dụng API key để truy cập Kora. Điều này phải khớp với KORA_API_KEY trong tệp .env:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

Chính Sách Fee Payer: Được cấu hình để hạn chế ký các giao dịch không mong muốn:

[validation.fee_payer_policy]
allow_sol_transfers = false
# all other settings are false

Chương Trình Được Phép: Đảm bảo System Program, Token Program, associated token program và compute budget program có trong danh sách cho phép:

allowed_programs = [
    "11111111111111111111111111111111",             # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # Token Program
    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token Program
    "ComputeBudget111111111111111111111111111111",  # Compute Budget Program
]

signers.toml

Tệp kora/signers.toml cấu hình Kora signer. Bạn thường không cần thực hiện bất kỳ thay đổi nào đối với tệp này, nhưng bạn có thể xác minh các cài đặt sau:

Biến Môi Trường Signer: Đảm bảo biến môi trường signer, private_key_env được đặt thành KORA_SIGNER_PRIVATE_KEY (khớp với tên biến môi trường trong tệp .env).

[[signers]]
name = "main_signer"
type = "memory"
private_key_env = "KORA_SIGNER_PRIVATE_KEY"
weight = 1

Bước 6: Nạp Tiền Cho Các Tài Khoản

Devnet SOL

Địa chỉ Kora signer của chúng tôi sẽ cần SOL để trả phí giao dịch. Bạn có thể airdrop SOL devnet đến địa chỉ Kora signer bằng Solana CLI:

# Airdrop SOL
solana airdrop 1 <KORA_SIGNER_ADDRESS> --url devnet

Ngoài ra, bạn có thể sử dụng Solana Faucet để airdrop SOL đến địa chỉ Kora signer.

Devnet USDC

PAYER_ADDRESS của bạn được đặt trong tệp .env sẽ cần USDC để trả phí giao dịch.

Nhận USDC Devnet từ Circle's Faucet. Hãy đảm bảo chọn "Solana Devnet" và sử dụng PAYER_ADDRESS của bạn để yêu cầu USDC.

Chạy Demo

Bạn sẽ cần bốn cửa sổ terminal để chạy tất cả các thành phần từ thư mục docs/x402/demo.

Terminal 1: Khởi Động Kora RPC Server

Chạy lệnh sau để khởi động máy chủ Kora RPC:

pnpm run start:kora

Bạn sẽ thấy một loạt log cho biết máy chủ Kora RPC đang chạy, bao gồm:

INFO kora_lib::rpc_server::server: RPC server started on 0.0.0.0:8080, port 8080

Terminal 2: Khởi Động Facilitator

Chạy lệnh sau để khởi động Facilitator:

pnpm run start:facilitator

Bạn sẽ thấy:

Server listening at http://localhost:3000

Terminal 3: Khởi Động Protected API

Chạy lệnh sau để khởi động Protected API:

pnpm run start:api

Bạn sẽ thấy:

Server listening at http://localhost:4021

Terminal 4: Chạy Demo Client

pnpm run demo

Hiểu Về Cách Triển Khai

Đây là những gì xảy ra trong một luồng thanh toán thành công:

Yêu Cầu Client → API trả về 402 kèm yêu cầu thanh toán
Tạo Thanh Toán → Client tạo giao dịch Solana kèm thanh toán
Gửi Thanh Toán → Client gửi yêu cầu đến máy chủ với thanh toán trong header X-PAYMENT
Xác Minh → Facilitator xác minh qua signTransaction của Kora
Xử Lý → Facilitator xử lý qua signAndSendTransaction của Kora (gửi giao dịch thanh toán lên Solana)
Cấp Quyền Truy Cập → Facilitator trả về chữ ký giao dịch và API trả về nội dung được bảo vệ kèm biên lai thanh toán

Hãy cùng tìm hiểu sâu hơn về cách hoạt động của từng thành phần:

Kora RPC (Cổng 8080): Xử lý ký giao dịch không cần gas
Facilitator (Cổng 3000): Kết nối giao thức x402 với Kora
Protected API (Cổng 4021): Endpoint API được kiếm tiền của bạn
Client: Minh họa luồng thanh toán tự động

Facilitator Wrapper/Proxy Server

Facilitator chạy trên cổng 3000. Đây là máy chủ xử lý giao tiếp với Solana (trong trường hợp của chúng tôi, thông qua Kora). Nó được dùng để xác minh và xử lý các khoản thanh toán x402.

Facilitator (facilitator/src/facilitator.ts) là cầu nối giữa giao thức x402 và Kora RPC. Nó triển khai ba endpoint chính:

1. Endpoint `/verify`

Endpoint này:

Nhận payload thanh toán x402 từ máy chủ Protected API
Trích xuất giao dịch Solana bằng các helper x402
Sử dụng signTransaction của Kora để xác minh tính hợp lệ mà không phát sóng
Trả về trạng thái xác minh, isValid

2. Endpoint `/settle`

Endpoint này:

Nhận payload thanh toán x402 sau khi thanh toán đã được xác minh bởi endpoint /verify
Sử dụng signAndSendTransaction của Kora để ký và phát sóng giao dịch
Trả về chữ ký giao dịch làm bằng chứng xử lý

3. Endpoint `/supported`

Endpoint này về cơ bản quảng bá các khả năng của facilitator, bao gồm:

Phiên bản x402 được hỗ trợ
Sơ đồ thanh toán (thanh toán chính xác)
Mạng (solana-devnet)
Địa chỉ fee payer mà chúng tôi lấy từ Kora bằng phương thức getPayerSigner

Protected API

Máy chủ API (api/src/api.ts) sử dụng middleware x402-express để bảo vệ các endpoint:

app.use(
  paymentMiddleware(
    KORA_PAYER_ADDRESS, // Where payments should go
    {
      "GET /protected": {
        price: "$0.0001", // Price in USD
        network: NETWORK // solana-devnet
      }
    },
    {
      url: FACILITATOR_URL // Our facilitator wrapper
    }
  )
);

Middleware này:

Chặn các yêu cầu đến các endpoint được bảo vệ (trong trường hợp của chúng tôi, endpoint /protected)
Trả về trạng thái 402 nếu thiếu thanh toán
Xác thực và xử lý thanh toán qua facilitator
Cho phép truy cập sau khi thanh toán thành công

Mặc dù chúng ta đang sử dụng Express, thư viện x402 hỗ trợ middleware cho nhiều framework phổ biến. Xem x402 TypeScript Packages để biết thêm thông tin.

Ứng Dụng Client

Client (client/src/index.ts) minh họa cách x402 hoạt động bằng cách gửi một yêu cầu với lệnh gọi fetch tiêu chuẩn rồi thử lại yêu cầu với trình bao bọc thanh toán:

// Create a signer from private key
const payer = await createSigner(NETWORK, PAYER_PRIVATE_KEY);

// Wrap fetch with x402 payment capabilities
const fetchWithPayment = wrapFetchWithPayment(fetch, payer);

// First attempt: Regular fetch (will fail with 402)
const expect402Response = await fetch(PROTECTED_API_URL);
console.log(`Status: ${expect402Response.status}`); // 402

// Second attempt: Fetch with payment wrapper (succeeds)
const response = await fetchWithPayment(PROTECTED_API_URL);
console.log(`Status: ${response.status}`); // 200

Trình bao bọc fetch của x402:

Phát hiện các phản hồi 402
Tự động tạo giao dịch thanh toán dựa trên yêu cầu thanh toán của API được bảo vệ
Ký bằng khóa riêng tư của người dùng
Gửi thanh toán đến facilitator để xác minh và xử lý
Thử lại yêu cầu với bằng chứng thanh toán trong header x-payment-response
Trả về phản hồi thành công

Tổng Kết

Xin chúc mừng! 🔥 Bạn đã triển khai thành công một luồng thanh toán x402 hoàn chỉnh với cơ sở hạ tầng không phí gas của Kora. Bản demo này cho thấy cách:

Giao thức x402 cho phép kiếm tiền từ API một cách liền mạch thông qua micropayment
Kora RPC hoạt động như một facilitator cho các khoản thanh toán x402 bằng cách xác minh và thanh toán các giao dịch
Người dùng có thể thanh toán để truy cập API mà không cần giữ SOL hoặc quản lý phí gas

Kiến trúc này tạo ra nền tảng mạnh mẽ cho:

Chợ AI Agent
API tính phí theo lượt dùng
Nền tảng nội dung micropayment
Định giá SaaS theo mức sử dụng
Bất kỳ dịch vụ nào yêu cầu thanh toán tức thời và có thể xác minh

Sự kết hợp giữa x402 và Kora mang sức mạnh của Solana đến với cơ sở hạ tầng web truyền thống.

Tiếp Tục Xây Dựng

Tùy Chỉnh Giá: Sửa đổi API để tính các mức phí khác nhau cho các endpoint khác nhau
Thêm Nhiều Token: Cấu hình Kora để chấp nhận nhiều loại SPL token làm phương thức thanh toán
Triển Khai Sản Xuất: Triển khai lên mainnet với các signer sản xuất (Vault, Turnkey hoặc Privy)
Xây Dựng API Của Riêng Bạn: Tạo một dịch vụ thực sự kiếm tiền thông qua thanh toán x402

Đặt câu hỏi trên Solana Stack Exchange với các thẻ kora và x402
Mở issue trên Kora GitHub repository

Hướng Dẫn Demo Toàn Diện về Tích Hợp x402 với Kora