Dokumentasi SolanaPaymentsPembayaran Agentik

Panduan Demo Lengkap Integrasi x402 dengan Kora

Integrasi Protokol x402 Solana dengan Kora RPC

Apa yang Akan Anda Bangun

Panduan ini memandu Anda dalam mengimplementasikan integrasi x402 (HTTP 402 Payment Required) yang lengkap dengan Kora, infrastruktur penandatanganan gasless Solana. Pada akhirnya, Anda akan memiliki sistem yang berfungsi di mana:

  • API dapat mengenakan micropayment untuk akses menggunakan protokol x402
  • Pengguna membayar dengan USDC tanpa memerlukan SOL untuk biaya gas
  • Kora menangani semua biaya transaksi sebagai fasilitator gasless
  • Pembayaran diselesaikan secara atomik di blockchain Solana

Hasil akhirnya adalah API yang dilindungi pembayaran dan berfungsi penuh:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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"

    }

}

Apa itu x402?

x402 adalah standar pembayaran terbuka yang memungkinkan micropayment yang mulus untuk akses API. Alih-alih model langganan tradisional atau kunci API, x402 memungkinkan server mengenakan biaya untuk setiap panggilan API secara individual, menciptakan infrastruktur pay-per-use yang sesungguhnya.

Manfaat utama x402:

  • Micropayment Instan: Bayar sebagian kecil sen per panggilan API
  • Memungkinkan agen AI membayar panggilan API: Bayar panggilan API dengan agen AI
  • Tanpa Langganan: Pengguna hanya membayar untuk apa yang mereka gunakan
  • Pembayaran Web3: Pembayaran yang transparan dan dapat diverifikasi secara onchain
  • HTTP Standar: Bekerja dengan infrastruktur web yang sudah ada menggunakan kode status HTTP 402 ketika pembayaran diperlukan

Server yang menggunakan x402 untuk mensyaratkan micropayment pada akses API akan mengembalikan kode status HTTP 402 ketika pembayaran diperlukan. Untuk mengakses endpoint yang dilindungi, klien harus menyertakan pembayaran yang valid ke server dalam header X-PAYMENT. x402 bergantung pada "Fasilitator" untuk memverifikasi dan menyelesaikan transaksi sehingga server tidak perlu berinteraksi langsung dengan infrastruktur blockchain.

Memahami Fasilitator

Fasilitator adalah komponen penting dalam ekosistem x402. Mereka bertindak sebagai layanan khusus yang mengabstraksi pembayaran blockchain atas nama server API.

Apa yang Dilakukan Fasilitator:

  • Verifikasi Pembayaran: Memvalidasi bahwa payload pembayaran klien terbentuk dengan benar dan mencukupi
  • Abstraksi Kompleksitas: Menghilangkan kebutuhan server untuk berinteraksi langsung dengan infrastruktur blockchain (penandatanganan dan pembayaran biaya jaringan)
  • Penyelesaian Transaksi: Mengirimkan transaksi yang telah divalidasi ke Solana (atau jaringan lainnya)

Dalam demo kami, kami membuat fasilitator yang memanfaatkan Kora untuk memverifikasi dan menyelesaikan transaksi (detail lebih lanjut di bawah).

Apa itu Kora?

Kora adalah node penanda tangan Solana yang menyediakan layanan penandatanganan dan transaksi gasless. Ini memungkinkan aplikasi untuk mengabstraksi biaya gas, sehingga pengguna dapat membayar biaya transaksi dalam token selain SOL, atau biaya sepenuhnya disponsori.

Fitur utama Kora:

  • Transaksi Gasless: Pengguna tidak memerlukan SOL untuk mengeksekusi transaksi
  • Abstraksi Biaya: Bayar biaya dalam USDC atau token SPL lainnya
  • Antarmuka JSON-RPC: API HTTP sederhana untuk penanganan transaksi
  • Penanda Tangan Fleksibel: Dukungan untuk berbagai backend penanda tangan (memory, Vault, Turnkey, Privy)
  • Mesin Kebijakan: Kontrol terperinci atas validasi transaksi dan kebijakan biaya

Dalam konteks x402, Kora berfungsi sebagai backend yang sempurna untuk fasilitator: ia menangani biaya jaringan, menandatangani transaksi, dan memvalidasi transaksi.

Gambaran Arsitektur

Integrasi x402 + Kora kami terdiri dari empat komponen yang saling terhubung dengan siklus permintaan/respons yang lengkap:

Alur Pembayaran Lengkap:

  1. Klien meminta sumber daya yang dilindungi → API mengembalikan 402 Payment Required
  2. Klien membuat transaksi pembayaran dengan wrapper fetch x402 (yang merakit transaksi Solana dengan instruksi pembayaran)
  3. Klien mengirimkan pembayaran ke Fasilitator untuk verifikasi
  4. Fasilitator memvalidasi melalui Kora, yang menandatangani dan mengirimkan ke Solana
  5. Transaksi dikonfirmasi secara onchain, Fasilitator memberi tahu API
  6. API mengembalikan konten yang dilindungi beserta tanda terima pembayaran kepada Klien

Rincian Komponen

  1. Kora RPC Server (Port 8080)

    • Layanan transaksi gasless inti
    • Menangani penandatanganan transaksi sebagai pembayar biaya
    • Memvalidasi transaksi terhadap kebijakan yang dikonfigurasi

  2. Server Wrapper/Proxy Fasilitator (Port 3000)

    • Mengadaptasi Kora ke protokol x402
    • Mengimplementasikan endpoint /verify, /settle, dan /supported
    • Menerjemahkan antara format data x402 dan Kora

  3. API yang Dilindungi (Port 4021)

    • Server API demo dengan endpoint yang dilindungi pembayaran
    • Menggunakan middleware x402-express untuk penanganan pembayaran
    • Mengembalikan data hanya setelah pembayaran berhasil

  4. Aplikasi Klien

    • Mendemonstrasikan penggunaan wrapper fetch x402
    • Menandatangani transaksi dengan kunci privat pengguna

Pendekatan multi-komponen mungkin terlihat kompleks, namun ini mencerminkan sistem produksi dunia nyata di mana pemrosesan pembayaran, penyajian API, dan aplikasi klien merupakan perhatian yang terpisah.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Pengaturan Proyek

Langkah 1: Clone dan 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

Ini menginstal binary kora ke sistem Anda, yang akan kita gunakan untuk menjalankan server RPC.

Langkah 2: Navigasi ke Direktori Demo

cd docs/x402/demo

Langkah 3: Instal Dependensi

Instal dependensi Node.js untuk semua komponen demo:

# Install dependencies for all components (facilitator, API, and client)

pnpm run install:all

Skrip ini menginstal dependensi untuk:

  • Layanan wrapper fasilitator
  • Server API yang dilindungi
  • Aplikasi demonstrasi klien

Langkah 4: Build Kora SDK

Build Kora SDK agar kita dapat menggunakan Kora TypeScript SDK di Fasilitator:

pnpm run build:kora-sdk

Langkah 5: Konfigurasi Lingkungan

Demo ini menyertakan file .env.example dengan variabel lingkungan yang diperlukan. Pertama, mari siapkan konfigurasi dasar:

# Copy the example environment file

cp .env.example .env

Sekarang Anda perlu membuat atau menyediakan keypair untuk demo. Jalankan perintah berikut untuk membuat keypair:

pnpm run setup

Ini akan membuat keypair dan menambahkannya ke file .env:

  • KORA_SIGNER_ADDRESS - Alamat dari penanda tangan Kora
  • KORA_SIGNER_PRIVATE_KEY - Kunci privat dari penanda tangan Kora
  • PAYER_ADDRESS - Alamat pembayar yang akan membayar untuk mengakses API yang dilindungi
  • PAYER_PRIVATE_KEY - Kunci privat dari pembayar

Langkah 5: Perbarui File Konfigurasi

kora.toml

File kora/kora.toml mengonfigurasi server Kora RPC. Anda seharusnya tidak perlu melakukan perubahan apa pun pada file ini, tetapi Anda dapat memverifikasi pengaturan berikut:

  1. Token Pembayaran: Pastikan mint USDC Devnet ada dalam daftar yang diizinkan:
allowed_tokens = [

    "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", # USDC devnet

]
  1. Autentikasi API: Demo ini menggunakan kunci API untuk akses Kora. Ini harus cocok dengan KORA_API_KEY di file .env:
[kora.auth]

api_key = "kora_facilitator_api_key_example"
  1. Kebijakan Pembayar Biaya: Dikonfigurasi untuk membatasi penandatanganan transaksi yang tidak diinginkan:
[validation.fee_payer_policy]

allow_sol_transfers = false

# all other settings are false
  1. Program yang Diizinkan: Pastikan System Program, Token Program, program token terkait, dan program anggaran komputasi ada dalam daftar yang diizinkan:
allowed_programs = [

    "11111111111111111111111111111111",             # System Program

    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # Token Program

    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token Program

    "ComputeBudget111111111111111111111111111111",  # Compute Budget Program

]

signers.toml

File kora/signers.toml mengonfigurasi penanda tangan Kora. Anda seharusnya tidak perlu melakukan perubahan apa pun pada file ini, tetapi Anda dapat memverifikasi pengaturan berikut:

  1. Variabel Lingkungan Penanda Tangan: Pastikan variabel lingkungan penanda tangan, private_key_env diatur ke KORA_SIGNER_PRIVATE_KEY (cocok dengan nama variabel lingkungan di file .env).
[[signers]]

name = "main_signer"

type = "memory"

private_key_env = "KORA_SIGNER_PRIVATE_KEY"

weight = 1

Langkah 6: Danai Akun

Devnet SOL

Alamat penanda tangan Kora kami akan membutuhkan SOL untuk membayar biaya transaksi. Anda dapat melakukan airdrop SOL devnet ke alamat penanda tangan Kora menggunakan Solana CLI:

# Airdrop SOL

solana airdrop 1 <KORA_SIGNER_ADDRESS> --url devnet

Atau, Anda dapat menggunakan Solana Faucet untuk melakukan airdrop SOL ke alamat penanda tangan Kora.

Devnet USDC

PAYER_ADDRESS Anda yang diatur di file .env akan membutuhkan USDC untuk membayar biaya transaksi.

Dapatkan USDC Devnet dari Faucet Circle. Pastikan untuk memilih "Solana Devnet" dan gunakan PAYER_ADDRESS Anda untuk meminta USDC.

Menjalankan Demo

Anda memerlukan empat jendela terminal untuk menjalankan semua komponen dari direktori docs/x402/demo.

Terminal 1: Mulai Kora RPC Server

Jalankan perintah berikut untuk memulai server Kora RPC:

pnpm run start:kora

Anda akan melihat serangkaian log yang menunjukkan bahwa server Kora RPC sedang berjalan, termasuk:

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

Terminal 2: Mulai Fasilitator

Jalankan perintah berikut untuk memulai Fasilitator:

pnpm run start:facilitator

Anda akan melihat:

Server listening at http://localhost:3000

Terminal 3: Mulai API yang Dilindungi

Jalankan perintah berikut untuk memulai API yang Dilindungi:

pnpm run start:api

Anda akan melihat:

Server listening at http://localhost:4021

Terminal 4: Jalankan Demo Klien

pnpm run demo

Memahami Implementasi

Inilah yang terjadi selama alur pembayaran yang berhasil:

  1. Permintaan Klien → API mengembalikan 402 beserta persyaratan pembayaran
  2. Pembuatan Pembayaran → Klien membuat transaksi Solana dengan pembayaran
  3. Pengiriman Pembayaran → Klien mengirimkan permintaan ke server dengan pembayaran di header X-PAYMENT
  4. Verifikasi → Fasilitator memverifikasi melalui signTransaction Kora
  5. Penyelesaian → Fasilitator menyelesaikan melalui signAndSendTransaction Kora (mengirimkan transaksi pembayaran ke Solana)
  6. Akses Diberikan → Fasilitator mengembalikan tanda tangan transaksi dan API mengembalikan konten yang dilindungi beserta tanda terima pembayaran

Mari kita telusuri cara kerja setiap komponen:

  • Kora RPC (Port 8080): Menangani penandatanganan transaksi gasless
  • Fasilitator (Port 3000): Menjembatani protokol x402 ke Kora
  • API yang Dilindungi (Port 4021): Endpoint API Anda yang dimonetisasi
  • Klien: Mendemonstrasikan alur pembayaran otomatis

Server Wrapper/Proxy Fasilitator

Fasilitator berjalan di port 3000. Ini adalah server yang menangani komunikasi dengan Solana (dalam kasus kami, melalui Kora). Digunakan untuk memverifikasi dan menyelesaikan pembayaran x402.

Fasilitator (facilitator/src/facilitator.ts) adalah jembatan antara protokol x402 dan Kora RPC. Ia mengimplementasikan tiga endpoint utama:

1. Endpoint /verify

Endpoint ini:

  • Menerima payload pembayaran x402 dari server API yang Dilindungi
  • Mengekstrak transaksi Solana menggunakan helper x402
  • Menggunakan signTransaction Kora untuk memverifikasi validitas tanpa menyiarkan
  • Mengembalikan status verifikasi, isValid

2. Endpoint /settle

Endpoint ini:

  • Menerima payload pembayaran x402 setelah pembayaran diverifikasi oleh endpoint /verify
  • Menggunakan signAndSendTransaction Kora untuk menandatangani dan menyiarkan transaksi
  • Mengembalikan tanda tangan transaksi sebagai bukti penyelesaian

3. Endpoint /supported

Endpoint ini secara efektif mengiklankan kemampuan fasilitator, termasuk:

  • Versi x402 yang didukung
  • Skema pembayaran (pembayaran tepat)
  • Jaringan (solana-devnet)
  • Alamat pembayar biaya yang kami ambil dari Kora menggunakan metode getPayerSigner

API yang Dilindungi

Server API (api/src/api.ts) menggunakan middleware x402-express untuk melindungi 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 ini:

  • Mencegat permintaan ke endpoint yang dilindungi (dalam kasus kami, endpoint /protected)
  • Mengembalikan status 402 jika pembayaran tidak ada
  • Memvalidasi dan menangani pembayaran melalui fasilitator
  • Mengizinkan akses setelah pembayaran berhasil

Meskipun kami menggunakan Express, pustaka x402 menyertakan dukungan middleware untuk banyak framework umum. Lihat Paket TypeScript x402 untuk informasi lebih lanjut.

Aplikasi Klien

Klien (client/src/index.ts) mendemonstrasikan cara kerja x402 secara otomatis dengan mengirim permintaan menggunakan pemanggilan fetch standar, lalu mencoba ulang permintaan dengan pembungkus pembayaran:

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

Pembungkus fetch x402:

  • Mendeteksi respons 402
  • Secara otomatis membuat transaksi pembayaran berdasarkan persyaratan pembayaran dari API yang dilindungi
  • Menandatangani dengan kunci privat pengguna
  • Mengirim pembayaran ke fasilitator untuk verifikasi dan pemrosesan
  • Mencoba ulang permintaan dengan bukti pembayaran di header x-payment-response
  • Mengembalikan respons yang berhasil

Rangkuman

Selamat! 🔥 Anda telah berhasil mengimplementasikan alur pembayaran x402 yang lengkap dengan infrastruktur gasless Kora. Demonstrasi ini menunjukkan bagaimana:

  • Protokol x402 memungkinkan monetisasi API tanpa hambatan melalui micropayment
  • Kora RPC berfungsi sebagai fasilitator untuk pembayaran x402 dengan memverifikasi dan menyelesaikan transaksi
  • Pengguna dapat membayar akses API tanpa menyimpan SOL atau mengelola biaya gas

Arsitektur ini menciptakan fondasi yang kuat untuk:

  • Marketplace AI Agent
  • API berbasis bayar per penggunaan
  • Platform konten micropayment
  • Penetapan harga SaaS berbasis penggunaan
  • Layanan apa pun yang memerlukan pembayaran instan dan terverifikasi

Kombinasi x402 dan Kora membawa kekuatan Solana ke infrastruktur web tradisional.

Terus Membangun

  • Sesuaikan Harga: Modifikasi API untuk mengenakan biaya yang berbeda pada endpoint yang berbeda
  • Tambahkan Beberapa Token: Konfigurasikan Kora untuk menerima berbagai token SPL sebagai pembayaran
  • Deployment Produksi: Deploy ke mainnet dengan penanda tangan produksi (Vault, Turnkey, atau Privy)
  • Bangun API Anda Sendiri: Buat layanan nyata yang dimonetisasi melalui pembayaran x402

Sumber Daya Tambahan

Protokol x402

Solana

Dukungan

Butuh bantuan?

Is this page helpful?

Sebelumnya

Cara memulai dengan x402 di Solana

Berikutnya

Alat pengembang

Daftar Isi

Edit Halaman
Gunakan Solana
Bangun
Perusahaan
Produk
Ekosistem
Agen AI
© 2026 Yayasan Solana. Semua hak dilindungi.