Integrazione x402 con Kora

Cosa Realizzerai

Questa guida ti accompagna nell'implementazione di un'integrazione completa x402 (HTTP 402 Payment Required) con Kora, l'infrastruttura di firma Solana senza commissioni. Al termine, avrai un sistema funzionante in cui:

Le API possono richiedere micropagamenti per l'accesso utilizzando il protocollo x402
Gli utenti pagano in USDC senza bisogno di SOL per le commissioni di gas
Kora gestisce tutte le commissioni di transazione come facilitatore senza gas
I pagamenti vengono regolati atomicamente sulla blockchain Solana

Il risultato finale sarà un'API completamente funzionale protetta da pagamento:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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"
    }
}

Cos'è x402?

x402 è uno standard di pagamento aperto che abilita micropagamenti fluidi per l'accesso alle API. Invece dei tradizionali modelli basati su abbonamento o chiavi API, x402 consente ai server di addebitare singole chiamate API, creando una vera infrastruttura pay-per-use.

Vantaggi principali di x402:

Micropagamenti Istantanei: Paga frazioni di centesimo per chiamata API
Consenti agli agenti AI di pagare le chiamate API: Paga le chiamate API con agenti AI
Nessun Abbonamento: Gli utenti pagano solo per ciò che utilizzano
Pagamenti Web3: Pagamenti trasparenti e verificabili on-chain
HTTP Standard: Funziona con l'infrastruttura web esistente utilizzando un codice di stato HTTP 402 quando è richiesto il pagamento

I server che utilizzano x402 per richiedere micropagamenti per l'accesso alle API restituiranno un codice di stato HTTP 402 quando è richiesto il pagamento. Per accedere agli endpoint protetti, i client devono passare un pagamento valido al server in un'intestazione X-PAYMENT. x402 si affida ai "Facilitatori" per verificare e regolare le transazioni in modo che i server non debbano interagire direttamente con l'infrastruttura blockchain.

Comprensione dei Facilitatori

I facilitatori sono un componente cruciale nell'ecosistema x402. Agiscono come servizi specializzati che astraggono i pagamenti blockchain per conto dei server API.

Cosa Fanno i Facilitatori:

Verificano i Pagamenti: Validano che i payload di pagamento del client siano correttamente formati e sufficienti
Astraggono la Complessità: Eliminano la necessità per i server di interagire direttamente con l'infrastruttura blockchain (firma e pagamento delle commissioni di rete)
Regolano le Transazioni: Inviano le transazioni validate a Solana (o altre reti)

Nella nostra demo, creiamo un facilitatore che sfrutta Kora per verificare e regolare le transazioni (maggiori dettagli di seguito).

Cos'è Kora?

Kora è un nodo firmatario Solana che fornisce servizi di firma e transazioni senza gas. Consente alle applicazioni di astrarre le commissioni gas, permettendo agli utenti di pagare i costi delle transazioni in token diversi da SOL, o di avere le commissioni completamente sponsorizzate.

Caratteristiche principali di Kora:

Transazioni Senza Gas: Gli utenti non hanno bisogno di SOL per eseguire transazioni
Astrazione delle Commissioni: Paga le commissioni in USDC o altri token SPL
Interfaccia JSON-RPC: API HTTP semplice per la gestione delle transazioni
Firmatari Flessibili: Supporto per più backend di firma (memory, Vault, Turnkey, Privy)
Motore di Policy: Controllo granulare sulla validazione delle transazioni e sulle politiche delle commissioni

Nel contesto di x402, Kora rappresenta il backend perfetto per i facilitatori: gestisce le commissioni di rete, firma le transazioni e le valida. Poiché Kora esamina ogni transazione prima di firmarla, i nodi Kora offrono un ulteriore livello di sicurezza e un controllo più preciso della validazione delle transazioni e delle politiche delle commissioni.

Panoramica dell'Architettura

La nostra integrazione x402 + Kora è composta da quattro componenti interconnessi con un ciclo completo richiesta/risposta:

Flusso di Pagamento Completo:

Il client richiede una risorsa protetta → l'API restituisce 402 Payment Required
Il client crea una transazione di pagamento con il wrapper fetch x402 (che assembla una transazione Solana con un'istruzione di pagamento)
Il client invia il pagamento al Facilitator per la verifica
Il Facilitator convalida tramite Kora, che firma e invia a Solana
La transazione viene confermata on-chain, il Facilitator notifica l'API
L'API restituisce il contenuto protetto con la ricevuta di pagamento al Client

Suddivisione dei Componenti

Server RPC Kora (Porta 8080)
- Servizio di transazioni gasless principale
- Gestisce la firma delle transazioni come pagatore delle commissioni
- Convalida le transazioni rispetto alle policy configurate
Server Wrapper/Proxy Facilitator (Porta 3000)
- Adatta Kora al protocollo x402
- Implementa gli endpoint /verify, /settle e /supported
- Traduce tra i formati dati x402 e Kora
API Protetta (Porta 4021)
- Server API demo con endpoint protetti da pagamento
- Utilizza il middleware x402-express per la gestione dei pagamenti
- Restituisce i dati solo dopo il pagamento avvenuto con successo
Applicazione Client
- Dimostra l'utilizzo del wrapper fetch x402
- Firma le transazioni con la chiave privata dell'utente

L'approccio multi-componente potrebbe sembrare complesso, ma rispecchia i sistemi di produzione reali in cui l'elaborazione dei pagamenti, l'erogazione delle API e le applicazioni client sono aspetti separati.

Prerequisiti

Prima di iniziare, assicurati di avere:

Rust (ultima versione stabile)
Node.js (LTS o successive)
Kora CLI (ultima versione - cargo install kora-cli)
pnpm (ultima versione)
Comprensione di base delle transazioni Solana e dei token SPL

Configurazione del Progetto

Passo 1: Clonare e Compilare Kora

Importante: Il branch main di Kora è un branch di integrazione e potrebbe contenere modifiche non rilasciate o in beta. Utilizza sempre l'ultima versione stabile rilasciata. Puoi trovare l'ultima versione stabile nella pagina dei rilasci di Kora.

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

# Checkout the latest stable tag
git checkout v2.0.5

# Build and install Kora
just install

Questo installa il binario kora nel tuo sistema, che useremo per eseguire il server RPC.

Passaggio 2: Naviga nella Directory Demo

cd examples/x402/demo

Passaggio 3: Installa le Dipendenze

Installa le dipendenze Node.js per tutti i componenti della demo:

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

Questo script installa le dipendenze per:

Il servizio wrapper del facilitatore
Il server API protetto
L'app di dimostrazione client

Passaggio 4: Configura l'Ambiente

La demo include un file .env.example con le variabili d'ambiente richieste. Innanzitutto, impostiamo la configurazione di base:

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

Ora devi generare o fornire le coppie di chiavi per la demo. Esegui il seguente comando per generare le coppie di chiavi:

pnpm run setup

Questo genererà le coppie di chiavi e le aggiungerà al file .env:

KORA_SIGNER_ADDRESS - L'indirizzo del firmatario Kora
KORA_SIGNER_PRIVATE_KEY - La chiave privata del firmatario Kora
PAYER_ADDRESS - L'indirizzo del pagatore che pagherà per accedere all'API protetta
PAYER_PRIVATE_KEY - La chiave privata del pagatore

Passaggio 5: Aggiorna i File di Configurazione

kora.toml

Il file kora/kora.toml configura il server RPC Kora. Non dovresti aver bisogno di apportare modifiche a questo file, ma puoi verificare le seguenti impostazioni:

Token di Pagamento: Assicurati che il mint USDC Devnet sia nella lista consentiti:

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

Autenticazione API: La demo utilizza una chiave API per l'accesso a Kora. Questa deve corrispondere a KORA_API_KEY nel file .env:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

Policy del Pagatore delle Commissioni: Configurata per limitare la firma di transazioni indesiderate utilizzando controlli granulari:

[validation.fee_payer_policy.system]
allow_transfer = false
allow_assign = false
allow_create_account = false
allow_allocate = false

[validation.fee_payer_policy.system.nonce]
allow_initialize = false
allow_advance = false
allow_authorize = false
allow_withdraw = false

[validation.fee_payer_policy.spl_token]
allow_transfer = false
allow_burn = false
allow_close_account = false
allow_approve = false
allow_revoke = false
allow_set_authority = false
allow_mint_to = false
allow_initialize_mint = false
allow_initialize_account = false
allow_initialize_multisig = false
allow_freeze_account = false
allow_thaw_account = false

[validation.fee_payer_policy.token_2022]
allow_transfer = false
allow_burn = false
allow_close_account = false
allow_approve = false
allow_revoke = false
allow_set_authority = false
allow_mint_to = false
allow_initialize_mint = false
allow_initialize_account = false
allow_initialize_multisig = false
allow_freeze_account = false
allow_thaw_account = false

Programmi Consentiti: Assicurati che il System Program, il Token Program, l'Associated Token Program e il Compute Budget Program siano nella lista dei programmi autorizzati:

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

signers.toml

Il file kora/signers.toml configura il firmatario Kora. Non dovrebbe essere necessario apportare modifiche a questo file, ma puoi verificare le seguenti impostazioni:

Variabile d'Ambiente del Firmatario: Assicurati che la variabile d'ambiente del firmatario, private_key_env, sia impostata su KORA_SIGNER_PRIVATE_KEY (corrispondente al nome della variabile d'ambiente nel file .env).

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

Passaggio 6: Finanziare gli Account

Devnet SOL

L'indirizzo del firmatario Kora avrà bisogno di SOL per pagare le commissioni sulle transazioni. Puoi inviare SOL devnet all'indirizzo del firmatario Kora utilizzando la Solana CLI:

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

In alternativa, puoi utilizzare il Faucet Solana per inviare SOL all'indirizzo del firmatario Kora.

Devnet USDC

Il tuo PAYER_ADDRESS, impostato nel file .env, avrà bisogno di USDC per pagare le commissioni sulle transazioni.

Ottieni USDC Devnet dal Faucet di Circle. Assicurati di selezionare "Solana Devnet" e di utilizzare il tuo PAYER_ADDRESS per richiedere USDC.

Esecuzione della Demo

Avrai bisogno di quattro finestre del terminale per eseguire tutti i componenti dalla directory examples/x402/demo.

Terminale 1: Avviare il Server RPC Kora

Esegui il seguente comando per avviare il server RPC Kora:

pnpm run start:kora

Dovresti vedere una serie di log che indicano che il server RPC Kora è in esecuzione, tra cui:

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

Terminale 2: Avviare il Facilitator

Esegui il seguente comando per avviare il Facilitator:

pnpm run start:facilitator

Dovresti vedere:

Server listening at http://localhost:3000

Terminale 3: Avvia l'API Protetta

Esegui il seguente comando per avviare l'API Protetta:

pnpm run start:api

Dovresti vedere:

Server listening at http://localhost:4021

Terminale 4: Esegui la Demo del Client

pnpm run demo

Comprendere l'Implementazione

Ecco cosa accade durante un flusso di pagamento riuscito:

Richiesta del Client → L'API restituisce 402 con i requisiti di pagamento
Creazione del Pagamento → Il client crea una transazione Solana con il pagamento
Invio del Pagamento → Il client invia la richiesta al server con il pagamento nell'header X-PAYMENT
Verifica → Il Facilitator verifica tramite l'signTransaction di Kora
Regolamento → Il Facilitator regola tramite l'signAndSendTransaction di Kora (inviando la transazione di pagamento a Solana)
Accesso Consentito → Il Facilitator restituisce la firma della transazione e l'API restituisce il contenuto protetto con la ricevuta di pagamento

Flusso della Transazione

Fonte: x402 GitHub

Approfondiamo il funzionamento di ciascun componente:

Kora RPC (Porta 8080): Gestisce la firma delle transazioni senza gas
Facilitator (Porta 3000): Collega il protocollo x402 a Kora
API Protetta (Porta 4021): Il tuo endpoint API monetizzato
Client: Dimostra il flusso di pagamento automatico

Il Server Wrapper/Proxy Facilitator

Il Facilitator viene eseguito sulla porta 3000. Questo è il server che gestisce la comunicazione con Solana (nel nostro caso, tramite Kora). Viene utilizzato per verificare e regolare i pagamenti x402.

Il facilitator (facilitator/src/facilitator.ts) è il ponte tra il protocollo x402 e Kora RPC. Implementa tre endpoint chiave:

1. Endpoint `/verify`

Questo endpoint:

Riceve un payload di pagamento x402 dal server dell'API Protetta
Estrae la transazione Solana utilizzando gli helper x402
Utilizza l'signTransaction di Kora per verificare la validità senza trasmettere
Restituisce lo stato di verifica, isValid

2. Endpoint `/settle`

Questo endpoint:

Riceve il payload di pagamento x402 dopo che il pagamento è stato verificato dall'endpoint /verify
Utilizza signAndSendTransaction di Kora per firmare e trasmettere la transazione
Restituisce la firma della transazione come prova di liquidazione

3. Endpoint `/supported`

Questo endpoint pubblicizza efficacemente le capacità del facilitatore, tra cui:

Versione x402 supportata
Schema di pagamento (pagamenti esatti)
Rete (solana-devnet)
Indirizzo del pagatore delle commissioni, recuperato da Kora utilizzando il metodo getPayerSigner

L'API Protetta

Il server API (api/src/api.ts) utilizza il middleware x402-express per proteggere gli 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
    }
  )
);

Il middleware:

Intercetta le richieste agli endpoint protetti (nel nostro caso, l'endpoint /protected)
Restituisce lo stato 402 se manca il pagamento
Convalida e gestisce i pagamenti tramite il facilitatore
Consente l'accesso dopo il pagamento riuscito

Sebbene stiamo utilizzando Express, la libreria x402 include il supporto middleware per molti framework comuni. Consulta i Pacchetti TypeScript x402 per maggiori informazioni.

L'Applicazione Client

Il client (client/src/index.ts) dimostra automaticamente come funziona x402 inviando una richiesta con una chiamata fetch standard e poi ritentando la richiesta con il wrapper di pagamento:

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

Il wrapper fetch x402:

Rileva le risposte 402
Crea automaticamente la transazione di pagamento in base ai requisiti di pagamento dell'API protetta
Firma con la chiave privata dell'utente
Invia il pagamento al facilitatore per la verifica e l'elaborazione
Ritenta la richiesta con la prova di pagamento nell'header x-payment-response
Restituisce una risposta riuscita

Conclusione

Congratulazioni! 🔥 Hai implementato con successo un flusso di pagamento x402 completo con l'infrastruttura gasless di Kora. Questa dimostrazione mostra come:

Il protocollo x402 consente la monetizzazione fluida delle API attraverso micropagamenti
Kora RPC funge da facilitatore per i pagamenti x402 verificando e regolando le transazioni
Gli utenti possono pagare per l'accesso alle API senza detenere SOL o gestire commissioni gas

Questa architettura crea una base solida per:

Marketplace di agenti AI
API pay-per-use
Piattaforme di contenuti a micropagamento
Tariffazione SaaS basata sull'utilizzo
Qualsiasi servizio che richiede pagamenti istantanei e verificabili

La combinazione di x402 e Kora porta la potenza di Solana all'infrastruttura web tradizionale.

Continua a costruire

Personalizza i prezzi: Modifica l'API per addebitare importi diversi per endpoint diversi
Aggiungi più token: Configura Kora per accettare vari token SPL come pagamento
Distribuzione in produzione: Distribuisci sulla mainnet con firmatari di produzione (Vault, Turnkey o Privy)
Crea la tua API: Realizza un servizio reale che monetizza attraverso pagamenti x402

Poni domande su Solana Stack Exchange con i tag kora e x402
Apri segnalazioni sul repository GitHub di Kora