Ενσωμάτωση Πρωτοκόλλου Solana x402 με Kora RPC

Τι Θα Δημιουργήσετε

Αυτός ο οδηγός σας καθοδηγεί στην υλοποίηση μιας πλήρους ενσωμάτωσης x402 (HTTP 402 Payment Required) με την Kora, την υποδομή gasless υπογραφής του Solana. Στο τέλος, θα έχετε ένα λειτουργικό σύστημα όπου:

Τα APIs μπορούν να χρεώνουν μικροπληρωμές για πρόσβαση χρησιμοποιώντας το πρωτόκολλο x402
Οι χρήστες πληρώνουν σε USDC χωρίς να χρειάζονται SOL για χρεώσεις gas
Η Kora αναλαμβάνει όλες τις χρεώσεις συναλλαγών ως gasless διαμεσολαβητής
Οι πληρωμές διακανονίζονται ατομικά στο blockchain Solana

Το τελικό αποτέλεσμα θα είναι ένα πλήρως λειτουργικό API με προστασία πληρωμών:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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;

x402 είναι ένα ανοικτό πρότυπο πληρωμών που επιτρέπει απρόσκοπτες μικροπληρωμές για πρόσβαση σε API. Αντί για παραδοσιακά μοντέλα συνδρομής ή κλειδιά API, το x402 επιτρέπει στους διακομιστές να χρεώνουν για μεμονωμένες κλήσεις API, δημιουργώντας αληθινή υποδομή πληρωμής ανά χρήση.

Βασικά πλεονεκτήματα του x402:

Άμεσες Μικροπληρωμές: Πληρώστε κλάσματα λεπτού ανά κλήση API
Ενεργοποίηση πληρωμών από AI agents για κλήσεις API: Πληρωμή κλήσεων API μέσω AI agents
Χωρίς Συνδρομές: Οι χρήστες πληρώνουν μόνο για ό,τι χρησιμοποιούν
Πληρωμές Web3: Διαφανείς, επαληθεύσιμες πληρωμές onchain
Τυπικό HTTP: Λειτουργεί με την υπάρχουσα διαδικτυακή υποδομή χρησιμοποιώντας κωδικό κατάστασης HTTP 402 όταν απαιτείται πληρωμή

Οι διακομιστές που χρησιμοποιούν x402 για να απαιτούν μικροπληρωμές για πρόσβαση σε API επιστρέφουν κωδικό κατάστασης HTTP 402 όταν απαιτείται πληρωμή. Για πρόσβαση σε προστατευμένα endpoints, οι clients πρέπει να διαβιβάσουν μια έγκυρη πληρωμή στον διακομιστή μέσω της κεφαλίδας X-PAYMENT. Το x402 βασίζεται σε "Facilitators" για την επαλήθευση και τον διακανονισμό συναλλαγών, ώστε οι διακομιστές να μην χρειάζεται να αλληλεπιδρούν άμεσα με την υποδομή blockchain.

Κατανόηση των Facilitators

Οι Facilitators αποτελούν κρίσιμο συστατικό στο οικοσύστημα x402. Λειτουργούν ως εξειδικευμένες υπηρεσίες που αφαιρούν την πολυπλοκότητα των πληρωμών blockchain εκ μέρους των διακομιστών API.

Τι Κάνουν οι Facilitators:

Επαλήθευση Πληρωμών: Επικύρωση ότι τα payloads πληρωμής του client είναι σωστά διαμορφωμένα και επαρκή
Αφαίρεση Πολυπλοκότητας: Εξαλείφεται η ανάγκη για τους διακομιστές να αλληλεπιδρούν άμεσα με την υποδομή blockchain (υπογραφή και καταβολή χρεώσεων δικτύου)
Διακανονισμός Συναλλαγών: Υποβολή επικυρωμένων συναλλαγών στο Solana (ή σε άλλα δίκτυα)

Στο demo μας, δημιουργούμε έναν facilitator που αξιοποιεί την Kora για την επαλήθευση και τον διακανονισμό συναλλαγών (περισσότερες λεπτομέρειες παρακάτω).

Τι είναι η Kora;

Η Kora είναι ένας κόμβος υπογραφής Solana που παρέχει υπηρεσίες υπογραφής και gasless συναλλαγών. Επιτρέπει στις εφαρμογές να αφαιρέσουν τις χρεώσεις gas, επιτρέποντας στους χρήστες να πληρώνουν τα κόστη συναλλαγών σε tokens διαφορετικά από το SOL, ή να έχουν τις χρεώσεις χρηματοδοτημένες πλήρως.

Βασικά χαρακτηριστικά της Kora:

Gasless Συναλλαγές: Οι χρήστες δεν χρειάζονται SOL για την εκτέλεση συναλλαγών
Αφαίρεση Χρεώσεων: Πληρωμή χρεώσεων σε USDC ή άλλα SPL tokens
Διεπαφή JSON-RPC: Απλό HTTP API για διαχείριση συναλλαγών
Ευέλικτοι Signers: Υποστήριξη πολλαπλών backends υπογραφής (memory, Vault, Turnkey, Privy)
Μηχανισμός Πολιτικής: Λεπτομερής έλεγχος επικύρωσης συναλλαγών και πολιτικών χρεώσεων

Στο πλαίσιο του x402, η Kora χρησιμεύει ως το ιδανικό backend για τους facilitators: διαχειρίζεται τα τέλη δικτύου, υπογράφει συναλλαγές και επικυρώνει συναλλαγές.

Επισκόπηση Αρχιτεκτονικής

Η ενσωμάτωση x402 + Kora αποτελείται από τέσσερα αλληλένδετα συστατικά με έναν πλήρη κύκλο αίτησης/απόκρισης:

Πλήρης Ροή Πληρωμής:

Ο client ζητά προστατευμένο πόρο → Το API επιστρέφει 402 Payment Required
Ο client δημιουργεί συναλλαγή πληρωμής με το x402 fetch wrapper (το οποίο συναρμολογεί μια συναλλαγή Solana με εντολή πληρωμής)
Ο client αποστέλλει την πληρωμή στον Facilitator για επαλήθευση
Ο Facilitator επικυρώνει μέσω Kora, η οποία υπογράφει και υποβάλλει στο Solana
Η συναλλαγή επιβεβαιώνεται onchain, ο Facilitator ειδοποιεί το API
Το API επιστρέφει προστατευμένο περιεχόμενο με απόδειξη πληρωμής στον Client

Ανάλυση Συστατικών

Kora RPC Server (Θύρα 8080)
- Βασική υπηρεσία gasless συναλλαγών
- Διαχειρίζεται την υπογραφή συναλλαγών ως fee payer
- Επικυρώνει συναλλαγές σύμφωνα με διαμορφωμένες πολιτικές
Facilitator Wrapper/Proxy Server (Θύρα 3000)
- Προσαρμόζει την Kora στο πρωτόκολλο x402
- Υλοποιεί τα endpoints /verify, /settle και /supported
- Μεταφράζει μεταξύ των μορφών δεδομένων x402 και Kora
Protected API (Θύρα 4021)
- Demo διακομιστής API με προστατευμένα endpoints πληρωμής
- Χρησιμοποιεί το middleware x402-express για διαχείριση πληρωμών
- Επιστρέφει δεδομένα μόνο μετά από επιτυχή πληρωμή
Εφαρμογή Client
- Επιδεικνύει τη χρήση του x402 fetch wrapper
- Υπογράφει συναλλαγές με το ιδιωτικό κλειδί του χρήστη

Η προσέγγιση με πολλά συστατικά μπορεί να φαίνεται πολύπλοκη, αλλά αντικατοπτρίζει πραγματικά συστήματα παραγωγής όπου η επεξεργασία πληρωμών, η εξυπηρέτηση API και οι εφαρμογές client αποτελούν ξεχωριστές ανησυχίες.

Προαπαιτούμενα

Πριν ξεκινήσετε, βεβαιωθείτε ότι έχετε:

Rust (τελευταία σταθερή έκδοση)
Node.js (LTS ή νεότερη)
pnpm (τελευταία έκδοση)
Βασική κατανόηση συναλλαγών Solana και SPL tokens

Ρύθμιση Έργου

Βήμα 1: Κλωνοποίηση και Κατασκευή της 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

Αυτό εγκαθιστά το δυαδικό αρχείο kora στο σύστημά σας, το οποίο θα χρησιμοποιήσουμε για την εκτέλεση του διακομιστή RPC.

Βήμα 2: Μετάβαση στον Κατάλογο Demo

cd docs/x402/demo

Βήμα 3: Εγκατάσταση Εξαρτήσεων

Εγκατάσταση εξαρτήσεων Node.js για όλα τα συστατικά του demo:

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

Αυτό το script εγκαθιστά εξαρτήσεις για:

Την υπηρεσία facilitator wrapper
Τον διακομιστή API με προστασία
Την εφαρμογή επίδειξης client

Βήμα 4: Κατασκευή του Kora SDK

Κατασκευάστε το Kora SDK ώστε να μπορούμε να χρησιμοποιήσουμε το Kora TypeScript SDK στον Facilitator:

pnpm run build:kora-sdk

Βήμα 5: Διαμόρφωση Περιβάλλοντος

Το demo περιλαμβάνει ένα αρχείο .env.example με τις απαιτούμενες μεταβλητές περιβάλλοντος. Αρχικά, ας ρυθμίσουμε τη βασική διαμόρφωση:

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

Τώρα πρέπει να δημιουργήσετε ή να παράσχετε keypairs για το demo. Εκτελέστε την ακόλουθη εντολή για να δημιουργήσετε τα keypairs:

pnpm run setup

Αυτό θα δημιουργήσει τα keypairs και θα τα προσθέσει στο αρχείο .env:

KORA_SIGNER_ADDRESS - Η διεύθυνση του Kora signer
KORA_SIGNER_PRIVATE_KEY - Το ιδιωτικό κλειδί του Kora signer
PAYER_ADDRESS - Η διεύθυνση του πληρωτή που θα πληρώνει για πρόσβαση στο προστατευμένο API
PAYER_PRIVATE_KEY - Το ιδιωτικό κλειδί του πληρωτή

Βήμα 5: Ενημέρωση Αρχείων Διαμόρφωσης

kora.toml

Το αρχείο kora/kora.toml διαμορφώνει τον Kora RPC server. Δεν χρειάζεται να κάνετε αλλαγές σε αυτό το αρχείο, αλλά μπορείτε να επαληθεύσετε τις ακόλουθες ρυθμίσεις:

Token Πληρωμής: Βεβαιωθείτε ότι το Devnet USDC mint βρίσκεται στη λίστα επιτρεπόμενων:

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

Πιστοποίηση API: Το demo χρησιμοποιεί κλειδί API για πρόσβαση στην Kora. Αυτό πρέπει να ταιριάζει με το KORA_API_KEY στο αρχείο .env:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

Πολιτική Fee Payer: Διαμορφωμένη για περιορισμό υπογραφής ανεπιθύμητων συναλλαγών:

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

Επιτρεπόμενα Προγράμματα: Βεβαιωθείτε ότι το System Program, το Token Program, το associated token program και το compute budget program βρίσκονται στη λίστα επιτρεπόμενων:

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

signers.toml

Το αρχείο kora/signers.toml διαμορφώνει τον Kora signer. Δεν χρειάζεται να κάνετε αλλαγές σε αυτό το αρχείο, αλλά μπορείτε να επαληθεύσετε τις ακόλουθες ρυθμίσεις:

Μεταβλητή Περιβάλλοντος Signer: Βεβαιωθείτε ότι η μεταβλητή περιβάλλοντος του signer, private_key_env έχει οριστεί σε KORA_SIGNER_PRIVATE_KEY (αντιστοιχεί στο όνομα της μεταβλητής περιβάλλοντος στο αρχείο .env).

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

Βήμα 6: Χρηματοδότηση Λογαριασμών

Devnet SOL

Η διεύθυνση του Kora signer θα χρειαστεί SOL για την πληρωμή χρεώσεων συναλλαγών. Μπορείτε να κάνετε airdrop devnet SOL στη διεύθυνση του Kora signer χρησιμοποιώντας το Solana CLI:

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

Εναλλακτικά, μπορείτε να χρησιμοποιήσετε το Solana Faucet για να κάνετε airdrop SOL στη διεύθυνση του Kora signer.

Devnet USDC

Το PAYER_ADDRESS που ορίζεται στο αρχείο .env θα χρειαστεί USDC για την πληρωμή χρεώσεων συναλλαγών.

Αποκτήστε Devnet USDC από το Circle's Faucet. Βεβαιωθείτε να επιλέξετε "Solana Devnet" και χρησιμοποιήστε το PAYER_ADDRESS για να ζητήσετε USDC.

Εκτέλεση του Demo

Θα χρειαστείτε τέσσερα παράθυρα τερματικού για να εκτελέσετε όλα τα συστατικά από τον κατάλογο docs/x402/demo.

Τερματικό 1: Εκκίνηση Kora RPC Server

Εκτελέστε την ακόλουθη εντολή για να εκκινήσετε τον Kora RPC server:

pnpm run start:kora

Θα δείτε μια σειρά από logs που υποδεικνύουν ότι ο Kora RPC server εκτελείται, συμπεριλαμβανομένων:

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

Τερματικό 2: Εκκίνηση Facilitator

Εκτελέστε την ακόλουθη εντολή για να εκκινήσετε τον Facilitator:

pnpm run start:facilitator

Θα δείτε:

Server listening at http://localhost:3000

Τερματικό 3: Εκκίνηση Protected API

Εκτελέστε την ακόλουθη εντολή για να εκκινήσετε το Protected API:

pnpm run start:api

Θα δείτε:

Server listening at http://localhost:4021

Τερματικό 4: Εκτέλεση Demo Client

pnpm run demo

Κατανόηση της Υλοποίησης

Αυτό συμβαίνει κατά τη διάρκεια μιας επιτυχημένης ροής πληρωμής:

Αίτηση Client → Το API επιστρέφει 402 με απαιτήσεις πληρωμής
Δημιουργία Πληρωμής → Ο Client δημιουργεί συναλλαγή Solana με πληρωμή
Υποβολή Πληρωμής → Ο Client αποστέλλει αίτηση στον διακομιστή με την πληρωμή στην κεφαλίδα X-PAYMENT
Επαλήθευση → Ο Facilitator επαληθεύει μέσω του signTransaction της Kora
Διακανονισμός → Ο Facilitator διακανονίζει μέσω του signAndSendTransaction της Kora (αποστέλλοντας τη συναλλαγή πληρωμής στο Solana)
Εκχώρηση Πρόσβασης → Ο Facilitator επιστρέφει την υπογραφή συναλλαγής και το API επιστρέφει προστατευμένο περιεχόμενο με απόδειξη πληρωμής

Ας εξετάσουμε πώς λειτουργεί κάθε συστατικό:

Kora RPC (Θύρα 8080): Διαχειρίζεται gasless υπογραφή συναλλαγών
Facilitator (Θύρα 3000): Γεφυρώνει το πρωτόκολλο x402 με την Kora
Protected API (Θύρα 4021): Το monetized endpoint του API σας
Client: Επιδεικνύει αυτόματη ροή πληρωμής

Ο Facilitator Wrapper/Proxy Server

Ο Facilitator εκτελείται στη θύρα 3000. Αυτός είναι ο διακομιστής που διαχειρίζεται την επικοινωνία με το Solana (στην περίπτωσή μας, μέσω Kora). Χρησιμοποιείται για την επαλήθευση και τον διακανονισμό πληρωμών x402.

Ο facilitator (facilitator/src/facilitator.ts) είναι η γέφυρα μεταξύ του πρωτοκόλλου x402 και του Kora RPC. Υλοποιεί τρία βασικά endpoints:

1. Endpoint `/verify`

Αυτό το endpoint:

Λαμβάνει ένα payload πληρωμής x402 από τον διακομιστή Protected API
Εξάγει τη συναλλαγή Solana χρησιμοποιώντας βοηθητικές συναρτήσεις x402
Χρησιμοποιεί το signTransaction της Kora για επαλήθευση εγκυρότητας χωρίς broadcast
Επιστρέφει κατάσταση επαλήθευσης, isValid

2. Endpoint `/settle`

Αυτό το endpoint:

Λαμβάνει το payload πληρωμής x402 αφού η πληρωμή έχει επαληθευτεί από το endpoint /verify
Χρησιμοποιεί το signAndSendTransaction της Kora για να υπογράψει και να μεταδώσει τη συναλλαγή
Επιστρέφει την υπογραφή συναλλαγής ως απόδειξη διακανονισμού

3. Endpoint `/supported`

Αυτό το endpoint διαφημίζει ουσιαστικά τις δυνατότητες του facilitator, συμπεριλαμβανομένων:

Υποστηριζόμενη έκδοση x402
Σχήμα πληρωμής (ακριβείς πληρωμές)
Δίκτυο (solana-devnet)
Διεύθυνση fee payer την οποία λαμβάνουμε από την Kora χρησιμοποιώντας τη μέθοδο getPayerSigner

Το Protected API

Ο διακομιστής API (api/src/api.ts) χρησιμοποιεί το middleware x402-express για την προστασία των endpoints:

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:

Υποκλέπτει αιτήσεις προς προστατευμένα endpoints (στην περίπτωσή μας, το endpoint /protected)
Επιστρέφει κατάσταση 402 εάν λείπει η πληρωμή
Επικυρώνει και διαχειρίζεται πληρωμές μέσω του facilitator
Επιτρέπει την πρόσβαση μετά από επιτυχή πληρωμή

Αν και χρησιμοποιούμε το Express, η βιβλιοθήκη x402 περιλαμβάνει υποστήριξη middleware για πολλά κοινά frameworks. Δείτε τα x402 TypeScript Packages για περισσότερες πληροφορίες.

Η Εφαρμογή Πελάτη

Ο πελάτης (client/src/index.ts) δείχνει αυτόματα πώς λειτουργεί το x402 στέλνοντας ένα αίτημα με μια τυπική κλήση fetch και στη συνέχεια επαναλαμβάνοντας το αίτημα με το περιτύλιγμα πληρωμής:

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

Το περιτύλιγμα fetch του x402:

Εντοπίζει αποκρίσεις 402
Δημιουργεί αυτόματα συναλλαγή πληρωμής βάσει των απαιτήσεων πληρωμής του προστατευμένου API
Υπογράφει με το ιδιωτικό κλειδί του χρήστη
Αποστέλλει την πληρωμή στον διευκολυντή για επαλήθευση και επεξεργασία
Επαναλαμβάνει το αίτημα με απόδειξη πληρωμής στην κεφαλίδα x-payment-response
Επιστρέφει επιτυχή απόκριση

Ολοκλήρωση

Συγχαρητήρια! 🔥 Υλοποιήσατε επιτυχώς μια πλήρη ροή πληρωμών x402 με την υποδομή gasless του Kora. Αυτή η επίδειξη δείχνει πώς:

Το Πρωτόκολλο x402 επιτρέπει την αβίαστη δημιουργία εσόδων από API μέσω micropayments
Το Kora RPC λειτουργεί ως διευκολυντής για πληρωμές x402 επαληθεύοντας και διακανονίζοντας τις συναλλαγές
Οι Χρήστες μπορούν να πληρώνουν για πρόσβαση σε API χωρίς να κατέχουν SOL ή να διαχειρίζονται τέλη gas

Αυτή η αρχιτεκτονική δημιουργεί μια ισχυρή βάση για:

Αγορές AI Agent
APIs με πληρωμή ανά χρήση
Πλατφόρμες περιεχομένου με micropayments
Τιμολόγηση SaaS βάσει χρήσης
Οποιαδήποτε υπηρεσία απαιτεί άμεσες, επαληθεύσιμες πληρωμές

Ο συνδυασμός x402 και Kora φέρνει τη δύναμη του Solana στην παραδοσιακή υποδομή του web.

Συνεχίστε να Δημιουργείτε

Προσαρμογή Τιμολόγησης: Τροποποιήστε το API για να χρεώνει διαφορετικά ποσά για διαφορετικά endpoints
Προσθήκη Πολλαπλών Tokens: Ρυθμίστε το Kora να δέχεται διάφορα SPL tokens για πληρωμή
Παραγωγική Ανάπτυξη: Εγκατάσταση στο mainnet με signers παραγωγής (Vault, Turnkey ή Privy)
Δημιουργήστε το Δικό σας API: Δημιουργήστε μια πραγματική υπηρεσία που δημιουργεί έσοδα μέσω πληρωμών x402

Κάντε ερωτήσεις στο Solana Stack Exchange με τις ετικέτες kora και x402
Ανοίξτε ζητήματα στο Kora GitHub repository

Ενσωμάτωση x402 με Kora - Πλήρης Οδηγός Demo