Integración del protocolo x402 de Solana con Kora RPC

Lo que construirás

Esta guía te muestra cómo implementar una integración completa de x402 (HTTP 402 Payment Required) con Kora, la infraestructura de firma sin gas de Solana. Al finalizar, tendrás un sistema funcional donde:

Las APIs pueden cobrar micropagos por acceso mediante el protocolo x402
Los usuarios pagan en USDC sin necesitar SOL para las tarifas de gas
Kora gestiona todas las tarifas de transacción como facilitador sin gas
Los pagos se liquidan de forma atómica en la blockchain de Solana

El resultado final será una API completamente funcional con pagos protegidos:

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

¿Qué es x402?

x402 es un estándar de pago abierto que permite micropagos fluidos para el acceso a APIs. En lugar de los modelos de suscripción tradicionales o claves de API, x402 permite a los servidores cobrar por llamadas individuales a la API, creando una infraestructura de pago por uso real.

Principales ventajas de x402:

Micropagos instantáneos: Paga fracciones de centavo por llamada a la API
Habilita a los agentes de IA para pagar llamadas a la API: Paga las llamadas a la API con agentes de IA
Sin suscripciones: Los usuarios solo pagan por lo que utilizan
Pagos Web3: Pagos transparentes y verificables en cadena
HTTP estándar: Compatible con la infraestructura web existente mediante un código de estado HTTP 402 cuando se requiere pago

Los servidores que utilizan x402 para requerir micropagos por acceso a la API devolverán un código de estado HTTP 402 cuando se requiera pago. Para acceder a los endpoints protegidos, los clientes deben enviar un pago válido al servidor en un encabezado X-PAYMENT. x402 se apoya en "Facilitadores" para verificar y liquidar transacciones, de modo que los servidores no necesiten interactuar directamente con la infraestructura blockchain.

Comprendiendo los Facilitadores

Los Facilitadores son un componente esencial en el ecosistema x402. Actúan como servicios especializados que abstraen los pagos blockchain en nombre de los servidores de API.

Qué hacen los Facilitadores:

Verificar pagos: Validan que los payloads de pago del cliente estén correctamente formados y sean suficientes
Abstraer la complejidad: Eliminan la necesidad de que los servidores interactúen directamente con la infraestructura blockchain (firma y pago de tarifas de red)
Liquidar transacciones: Envían transacciones validadas a Solana (u otras redes)

En nuestra demo, creamos un facilitador que aprovecha Kora para verificar y liquidar transacciones (más detalles a continuación).

¿Qué es Kora?

Kora es un nodo firmante de Solana que proporciona servicios de firma y transacciones sin gas. Permite a las aplicaciones abstraer las tarifas de gas, habilitando a los usuarios a pagar los costos de transacción en tokens distintos a SOL, o tener las tarifas patrocinadas por completo.

Características principales de Kora:

Transacciones sin gas: Los usuarios no necesitan SOL para ejecutar transacciones
Abstracción de tarifas: Paga las tarifas en USDC u otros tokens SPL
Interfaz JSON-RPC: API HTTP sencilla para el manejo de transacciones
Firmantes flexibles: Soporte para múltiples backends de firma (memoria, Vault, Turnkey, Privy)
Motor de políticas: Control granular sobre la validación de transacciones y las políticas de tarifas

En el contexto de x402, Kora sirve como el backend perfecto para los facilitadores: gestiona las tarifas de red, firma las transacciones y las valida.

Descripción general de la arquitectura

Nuestra integración x402 + Kora consta de cuatro componentes interconectados con un ciclo completo de solicitud/respuesta:

Flujo de pago completo:

El cliente solicita el recurso protegido → La API devuelve 402 Payment Required
El cliente crea la transacción de pago con el wrapper fetch de x402 (que ensambla una transacción de Solana con una instrucción de pago)
El cliente envía el pago al Facilitador para su verificación
El Facilitador valida a través de Kora, que firma y envía a Solana
Transacción confirmada en cadena, el Facilitador notifica a la API
La API devuelve el contenido protegido con el recibo de pago al Cliente

Desglose de componentes

Servidor Kora RPC (Puerto 8080)
- Servicio central de transacciones sin gas
- Gestiona la firma de transacciones como pagador de tarifas
- Valida las transacciones según las políticas configuradas
Servidor Wrapper/Proxy del Facilitador (Puerto 3000)
- Adapta Kora al protocolo x402
- Implementa los endpoints /verify, /settle y /supported
- Traduce entre los formatos de datos de x402 y Kora
API Protegida (Puerto 4021)
- Servidor de API de demostración con endpoints protegidos por pago
- Utiliza el middleware x402-express para el manejo de pagos
- Devuelve datos solo tras un pago exitoso
Aplicación Cliente
- Demuestra el uso del wrapper fetch de x402
- Firma transacciones con la clave privada del usuario

El enfoque de múltiples componentes puede parecer complejo, pero refleja los sistemas de producción del mundo real donde el procesamiento de pagos, el servicio de API y las aplicaciones cliente son preocupaciones separadas.

Requisitos previos

Antes de comenzar, asegúrate de tener:

Rust (última versión estable)
Node.js (LTS o posterior)
pnpm (última versión)
Conocimientos básicos de transacciones de Solana y tokens SPL

Configuración del proyecto

Paso 1: Clonar y compilar 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

Esto instala el binario kora en tu sistema, que usaremos para ejecutar el servidor RPC.

Paso 2: Navegar al directorio de la demo

cd docs/x402/demo

Paso 3: Instalar dependencias

Instala las dependencias de Node.js para todos los componentes de la demo:

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

Este script instala las dependencias para:

El servicio wrapper del facilitador
El servidor de API protegida
La aplicación de demostración del cliente

Paso 4: Compilar el SDK de Kora

Compila el SDK de Kora para poder usar el SDK de TypeScript de Kora en el Facilitador:

pnpm run build:kora-sdk

Paso 5: Configurar el entorno

La demo incluye un archivo .env.example con las variables de entorno necesarias. Primero, configuremos la configuración básica:

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

Ahora necesitas generar o proporcionar keypairs para la demo. Ejecuta el siguiente comando para generarlos:

pnpm run setup

Esto generará los keypairs y los añadirá al archivo .env:

KORA_SIGNER_ADDRESS - La dirección del firmante de Kora
KORA_SIGNER_PRIVATE_KEY - La clave privada del firmante de Kora
PAYER_ADDRESS - La dirección del pagador que pagará para acceder a la API protegida
PAYER_PRIVATE_KEY - La clave privada del pagador

Paso 5: Actualizar los archivos de configuración

kora.toml

El archivo kora/kora.toml configura el servidor Kora RPC. No debería ser necesario realizar cambios en este archivo, pero puedes verificar los siguientes ajustes:

Token de pago: Asegúrate de que el mint de USDC de Devnet esté en la lista de permitidos:

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

Autenticación de API: La demo usa una clave de API para el acceso a Kora. Debe coincidir con el KORA_API_KEY en el archivo .env:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

Política del pagador de tarifas: Configurada para restringir la firma de transacciones no deseadas:

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

Programas permitidos: Asegúrate de que System Program, Token Program, el programa de token asociado y el programa de presupuesto de cómputo estén en la lista de permitidos:

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

signers.toml

El archivo kora/signers.toml configura el firmante de Kora. No debería ser necesario realizar cambios en este archivo, pero puedes verificar los siguientes ajustes:

Variable de entorno del firmante: Asegúrate de que la variable de entorno del firmante, private_key_env, esté configurada como KORA_SIGNER_PRIVATE_KEY (que coincide con el nombre de la variable de entorno en el archivo .env).

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

Paso 6: Fondear las cuentas

SOL de Devnet

La dirección de nuestro firmante de Kora necesitará SOL para pagar las tarifas de transacción. Puedes hacer un airdrop de SOL de devnet a la dirección del firmante de Kora usando la CLI de Solana:

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

Alternativamente, puedes usar el Faucet de Solana para hacer un airdrop de SOL a la dirección del firmante de Kora.

USDC de Devnet

Tu PAYER_ADDRESS configurada en el archivo .env necesitará USDC para pagar las tarifas de transacción.

Obtén USDC de Devnet desde el Faucet de Circle. Asegúrate de seleccionar "Solana Devnet" y usar tu PAYER_ADDRESS para solicitar USDC.

Ejecutar la demo

Necesitarás cuatro ventanas de terminal para ejecutar todos los componentes desde el directorio docs/x402/demo.

Terminal 1: Iniciar el servidor Kora RPC

Ejecuta el siguiente comando para iniciar el servidor Kora RPC:

pnpm run start:kora

Deberías ver una serie de registros que indican que el servidor Kora RPC está en funcionamiento, incluidos:

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

Terminal 2: Iniciar el Facilitador

Ejecuta el siguiente comando para iniciar el Facilitador:

pnpm run start:facilitator

Deberías ver:

Server listening at http://localhost:3000

Terminal 3: Iniciar la API Protegida

Ejecuta el siguiente comando para iniciar la API Protegida:

pnpm run start:api

Deberías ver:

Server listening at http://localhost:4021

Terminal 4: Ejecutar la demo del cliente

pnpm run demo

Comprendiendo la implementación

Esto es lo que ocurre durante un flujo de pago exitoso:

Solicitud del cliente → La API devuelve 402 con los requisitos de pago
Creación del pago → El cliente crea una transacción de Solana con el pago
Envío del pago → El cliente envía la solicitud al servidor con el pago en el encabezado X-PAYMENT
Verificación → El Facilitador verifica a través del signTransaction de Kora
Liquidación → El Facilitador liquida mediante el signAndSendTransaction de Kora (enviando la transacción de pago a Solana)
Acceso concedido → El Facilitador devuelve la firma de la transacción y la API devuelve el contenido protegido con el recibo de pago

Profundicemos en cómo funciona cada componente:

Kora RPC (Puerto 8080): Gestiona la firma de transacciones sin gas
Facilitador (Puerto 3000): Conecta el protocolo x402 con Kora
API Protegida (Puerto 4021): Tu endpoint de API monetizado
Cliente: Demuestra el flujo de pago automático

El Servidor Wrapper/Proxy del Facilitador

El Facilitador se ejecuta en el puerto 3000. Este es el servidor que gestiona la comunicación con Solana (en nuestro caso, a través de Kora). Se utiliza para verificar y liquidar los pagos x402.

El facilitador (facilitator/src/facilitator.ts) es el puente entre el protocolo x402 y Kora RPC. Implementa tres endpoints clave:

1. Endpoint `/verify`

Este endpoint:

Recibe un payload de pago x402 del servidor de la API Protegida
Extrae la transacción de Solana usando los helpers de x402
Usa el signTransaction de Kora para verificar la validez sin difundir la transacción
Devuelve el estado de verificación, isValid

2. Endpoint `/settle`

Este endpoint:

Recibe el payload de pago x402 una vez que el pago ha sido verificado por el endpoint /verify
Usa el signAndSendTransaction de Kora para firmar y difundir la transacción
Devuelve la firma de la transacción como prueba de liquidación

3. Endpoint `/supported`

Este endpoint anuncia efectivamente las capacidades del facilitador, incluyendo:

Versión de x402 compatible
Esquema de pago (pagos exactos)
Red (solana-devnet)
Dirección del pagador de tarifas que obtenemos de Kora mediante el método getPayerSigner

La API Protegida

El servidor de API (api/src/api.ts) usa el middleware x402-express para proteger los 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
    }
  )
);

El middleware:

Intercepta las solicitudes a los endpoints protegidos (en nuestro caso, el endpoint /protected)
Devuelve el estado 402 si falta el pago
Valida y gestiona los pagos a través del facilitador
Permite el acceso tras un pago exitoso

Aunque estamos usando Express, la biblioteca x402 incluye soporte de middleware para muchos frameworks comunes. Consulta los paquetes TypeScript de x402 para obtener más información.

La Aplicación Cliente

El cliente (client/src/index.ts) demuestra automáticamente cómo funciona x402 enviando una solicitud con una llamada estándar fetch y luego reintentando la solicitud con el wrapper de pago:

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

El wrapper fetch de x402:

Detecta respuestas 402
Crea automáticamente una transacción de pago basada en los requisitos de pago de la API protegida
Firma con la clave privada del usuario
Envía el pago al facilitador para su verificación y procesamiento
Reintenta la solicitud con la prueba de pago en el encabezado x-payment-response
Devuelve una respuesta exitosa

Conclusión

¡Felicitaciones! 🔥 Has implementado con éxito un flujo de pago x402 completo con la infraestructura sin gas de Kora. Esta demostración muestra cómo:

El protocolo x402 permite la monetización de APIs sin fricciones mediante micropagos
Kora RPC actúa como facilitador para los pagos x402 verificando y liquidando transacciones
Los usuarios pueden pagar por el acceso a la API sin necesidad de tener SOL ni gestionar tarifas de gas

Esta arquitectura crea una base sólida para:

Marketplaces de agentes de IA
APIs de pago por uso
Plataformas de contenido con micropagos
Precios SaaS basados en el consumo
Cualquier servicio que requiera pagos instantáneos y verificables

La combinación de x402 y Kora lleva el poder de Solana a la infraestructura web tradicional.

Sigue Construyendo

Personaliza los precios: Modifica la API para cobrar distintas cantidades según los diferentes endpoints
Agrega múltiples tokens: Configura Kora para aceptar diversos tokens SPL como método de pago
Despliegue en producción: Despliega en mainnet con firmantes de producción (Vault, Turnkey o Privy)
Crea tu propia API: Desarrolla un servicio real que se monetice mediante pagos x402

Haz preguntas en Solana Stack Exchange con las etiquetas kora y x402
Abre issues en el repositorio de Kora en GitHub

Guía completa de integración de x402 con Kora