Integração do Protocolo x402 da Solana com o Kora RPC

O Que Você Vai Construir

Este guia orienta você na implementação de uma integração completa do x402 (HTTP 402 Payment Required) com o Kora, a infraestrutura de assinatura sem gas da Solana. Ao final, você terá um sistema funcional onde:

APIs podem cobrar micropagamentos pelo acesso usando o protocolo x402
Usuários pagam em USDC sem precisar de SOL para taxas de gas
O Kora gerencia todas as taxas de transação como facilitador sem gas
Os pagamentos são liquidados atomicamente na blockchain Solana

O resultado final será uma API totalmente funcional com pagamento protegido:

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

O Que é x402?

x402 é um padrão de pagamento aberto que permite micropagamentos perfeitos para acesso a APIs. Em vez de modelos tradicionais de assinatura ou chaves de API, o x402 permite que servidores cobrem por chamadas individuais de API, criando uma verdadeira infrastrutura de pagamento por uso.

Principais benefícios do x402:

Micropagamentos Instantâneos: Pague frações de centavo por chamada de API
Habilite agentes de IA para pagar por chamadas de API: Pague por chamadas de API com agentes de IA
Sem Assinaturas: Os usuários pagam apenas pelo que utilizam
Pagamentos Web3: Pagamentos transparentes e verificáveis onchain
HTTP Padrão: Funciona com a infraestrutura web existente usando um código de status HTTP 402 quando o pagamento é necessário

Servidores que usam x402 para exigir micropagamentos pelo acesso à API retornarão um código de status HTTP 402 quando o pagamento for necessário. Para acessar endpoints protegidos, os clientes devem enviar um pagamento válido ao servidor no cabeçalho X-PAYMENT. O x402 depende de "Facilitadores" para verificar e liquidar transações, de modo que os servidores não precisam interagir diretamente com a infraestrutura blockchain.

Entendendo os Facilitadores

Os Facilitadores são um componente essencial no ecossistema x402. Eles atuam como serviços especializados que abstraem pagamentos blockchain em nome dos servidores de API.

O Que os Facilitadores Fazem:

Verificam Pagamentos: Validam que os payloads de pagamento dos clientes estão corretamente formados e são suficientes
Abstraem a Complexidade: Eliminam a necessidade de os servidores interagirem diretamente com a infraestrutura blockchain (assinatura e pagamento de taxas de rede)
Liquidam Transações: Enviam transações validadas para a Solana (ou outras redes)

Em nossa demonstração, criamos um facilitador que utiliza o Kora para verificar e liquidar transações (mais detalhes abaixo).

O Que é o Kora?

O Kora é um nó de assinatura Solana que fornece serviços de assinatura e transações sem gas. Ele permite que aplicações abstraiam as taxas de gas, possibilitando que os usuários paguem os custos de transação em tokens diferentes de SOL, ou tenham as taxas totalmente patrocinadas.

Principais recursos do Kora:

Transações Sem Gas: Os usuários não precisam de SOL para executar transações
Abstração de Taxas: Pague taxas em USDC ou outros tokens SPL
Interface JSON-RPC: API HTTP simples para gerenciamento de transações
Signatários Flexíveis: Suporte a múltiplos backends de assinatura (memória, Vault, Turnkey, Privy)
Motor de Políticas: Controle granular sobre validação de transações e políticas de taxas

No contexto do x402, o Kora serve como o backend ideal para facilitadores: ele gerencia as taxas de rede, assina transações e valida transações.

Visão Geral da Arquitetura

Nossa integração x402 + Kora consiste em quatro componentes interconectados com um ciclo completo de requisição/resposta:

Fluxo Completo de Pagamento:

O cliente solicita o recurso protegido → A API retorna 402 Payment Required
O cliente cria uma transação de pagamento com o wrapper fetch x402 (que monta uma transação Solana com uma instrução de pagamento)
O cliente envia o pagamento ao Facilitador para verificação
O Facilitador valida via Kora, que assina e envia para a Solana
Transação confirmada onchain, o Facilitador notifica a API
A API retorna o conteúdo protegido com o recibo de pagamento ao Cliente

Detalhamento dos Componentes

Servidor RPC Kora (Porta 8080)
- Serviço principal de transações sem gas
- Gerencia a assinatura de transações como pagador de taxas
- Valida transações de acordo com as políticas configuradas
Servidor Wrapper/Proxy do Facilitador (Porta 3000)
- Adapta o Kora ao protocolo x402
- Implementa os endpoints /verify, /settle e /supported
- Traduz entre os formatos de dados x402 e Kora
API Protegida (Porta 4021)
- Servidor de API de demonstração com endpoints protegidos por pagamento
- Usa o middleware x402-express para gerenciamento de pagamentos
- Retorna dados somente após pagamento bem-sucedido
Aplicação Cliente
- Demonstra o uso do wrapper fetch x402
- Assina transações com a chave privada do usuário

A abordagem de múltiplos componentes pode parecer complexa, mas reflete sistemas de produção do mundo real onde o processamento de pagamentos, a disponibilização de APIs e as aplicações cliente são preocupações separadas.

Pré-requisitos

Antes de começar, certifique-se de ter:

Rust (versão estável mais recente)
Node.js (LTS ou posterior)
pnpm (versão mais recente)
Compreensão básica de transações Solana e tokens SPL

Configuração do Projeto

Passo 1: Clonar e Compilar o 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

Isso instala o binário kora no seu sistema, que usaremos para executar o servidor RPC.

Passo 2: Navegar até o Diretório de Demonstração

cd docs/x402/demo

Passo 3: Instalar Dependências

Instale as dependências do Node.js para todos os componentes da demonstração:

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

Este script instala as dependências para:

O serviço wrapper do facilitador
O servidor de API protegida
O aplicativo de demonstração do cliente

Passo 4: Compilar o SDK do Kora

Compile o SDK do Kora para que possamos usar o SDK TypeScript do Kora no Facilitador:

pnpm run build:kora-sdk

Passo 5: Configurar o Ambiente

A demonstração inclui um arquivo .env.example com as variáveis de ambiente necessárias. Primeiro, vamos configurar a configuração básica:

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

Agora você precisa gerar ou fornecer keypairs para a demonstração. Execute o seguinte comando para gerar os keypairs:

pnpm run setup

Isso irá gerar os keypairs e adicioná-los ao arquivo .env:

KORA_SIGNER_ADDRESS - O endereço do signatário do Kora
KORA_SIGNER_PRIVATE_KEY - A chave privada do signatário do Kora
PAYER_ADDRESS - O endereço do pagador que pagará para acessar a API protegida
PAYER_PRIVATE_KEY - A chave privada do pagador

Passo 5: Atualizar os Arquivos de Configuração

kora.toml

O arquivo kora/kora.toml configura o servidor RPC do Kora. Você não deve precisar fazer alterações neste arquivo, mas pode verificar as seguintes configurações:

Token de Pagamento: Certifique-se de que o mint USDC da Devnet está na lista de permissões:

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

Autenticação de API: A demonstração usa uma chave de API para acesso ao Kora. Isso deve corresponder ao KORA_API_KEY no arquivo .env:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

Política do Pagador de Taxas: Configurada para restringir a assinatura de transações indesejadas:

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

Programas Permitidos: Certifique-se de que o System Program, Token Program, associated token program e compute budget program estão na lista de permissões:

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

signers.toml

O arquivo kora/signers.toml configura o signatário do Kora. Você não deve precisar fazer alterações neste arquivo, mas pode verificar as seguintes configurações:

Variável de Ambiente do Signatário: Certifique-se de que a variável de ambiente do signatário, private_key_env, está definida como KORA_SIGNER_PRIVATE_KEY (correspondendo ao nome da variável de ambiente no arquivo .env).

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

Passo 6: Financiar Contas

SOL da Devnet

O endereço do nosso signatário do Kora precisará de SOL para pagar as taxas de transação. Você pode fazer airdrop de SOL da Devnet para o endereço do signatário do Kora usando a CLI da Solana:

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

Alternativamente, você pode usar o Faucet da Solana para fazer airdrop de SOL para o endereço do signatário do Kora.

USDC da Devnet

O seu PAYER_ADDRESS definido no arquivo .env precisará de USDC para pagar as taxas de transação.

Obtenha USDC da Devnet no Faucet da Circle. Certifique-se de selecionar "Solana Devnet" e usar seu PAYER_ADDRESS para solicitar USDC.

Executando a Demonstração

Você precisará de quatro janelas de terminal para executar todos os componentes a partir do diretório docs/x402/demo.

Terminal 1: Iniciar o Servidor RPC Kora

Execute o seguinte comando para iniciar o servidor RPC do Kora:

pnpm run start:kora

Você deverá ver uma série de logs indicando que o servidor RPC do Kora está em execução, incluindo:

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

Terminal 2: Iniciar o Facilitador

Execute o seguinte comando para iniciar o Facilitador:

pnpm run start:facilitator

Você deverá ver:

Server listening at http://localhost:3000

Terminal 3: Iniciar a API Protegida

Execute o seguinte comando para iniciar a API Protegida:

pnpm run start:api

Você deverá ver:

Server listening at http://localhost:4021

Terminal 4: Executar a Demonstração do Cliente

pnpm run demo

Entendendo a Implementação

Veja o que acontece durante um fluxo de pagamento bem-sucedido:

Requisição do Cliente → A API retorna 402 com os requisitos de pagamento
Criação do Pagamento → O cliente cria uma transação Solana com o pagamento
Envio do Pagamento → O cliente envia a requisição ao servidor com o pagamento no cabeçalho X-PAYMENT
Verificação → O Facilitador verifica via signTransaction do Kora
Liquidação → O Facilitador liquida via signAndSendTransaction do Kora (enviando a transação de pagamento para a Solana)
Acesso Concedido → O Facilitador retorna a assinatura da transação e a API retorna o conteúdo protegido com o recibo de pagamento

Vamos analisar como cada componente funciona:

Kora RPC (Porta 8080): Gerencia a assinatura de transações sem gas
Facilitador (Porta 3000): Faz a ponte entre o protocolo x402 e o Kora
API Protegida (Porta 4021): Seu endpoint de API monetizado
Cliente: Demonstra o fluxo de pagamento automático

O Servidor Wrapper/Proxy do Facilitador

O Facilitador é executado na porta 3000. Este é o servidor que gerencia a comunicação com a Solana (em nosso caso, via Kora). Ele é usado para verificar e liquidar pagamentos x402.

O facilitador (facilitator/src/facilitator.ts) é a ponte entre o protocolo x402 e o Kora RPC. Ele implementa três endpoints principais:

1. Endpoint `/verify`

Este endpoint:

Recebe um payload de pagamento x402 do servidor da API Protegida
Extrai a transação Solana usando os helpers x402
Usa o signTransaction do Kora para verificar a validade sem transmitir
Retorna o status de verificação, isValid

2. Endpoint `/settle`

Este endpoint:

Recebe o payload de pagamento x402 após o pagamento ter sido verificado pelo endpoint /verify
Usa o signAndSendTransaction do Kora para assinar e transmitir a transação
Retorna a assinatura da transação como prova de liquidação

3. Endpoint `/supported`

Este endpoint anuncia efetivamente as capacidades do facilitador, incluindo:

Versão x402 suportada
Esquema de pagamento (pagamentos exatos)
Rede (solana-devnet)
Endereço do pagador de taxas que buscamos do Kora usando o método getPayerSigner

A API Protegida

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

O middleware:

Intercepta requisições para endpoints protegidos (em nosso caso, o endpoint /protected)
Retorna status 402 se o pagamento estiver ausente
Valida e gerencia pagamentos via facilitador
Permite o acesso após pagamento bem-sucedido

Embora estejamos usando Express, a biblioteca x402 inclui suporte a middleware para muitos frameworks comuns. Consulte os Pacotes TypeScript x402 para mais informações.

A Aplicação Cliente

O cliente (client/src/index.ts) demonstra automaticamente como o x402 funciona ao enviar uma requisição com uma chamada fetch padrão e depois repetir a requisição com o wrapper de 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

O wrapper fetch do x402:

Detecta respostas 402
Cria automaticamente uma transação de pagamento com base nos requisitos de pagamento da API protegida
Assina com a chave privada do usuário
Envia o pagamento ao facilitador para verificação e processamento
Repete a requisição com a prova de pagamento no cabeçalho x-payment-response
Retorna resposta bem-sucedida

Conclusão

Parabéns! 🔥 Você implementou com sucesso um fluxo de pagamento x402 completo com a infraestrutura gasless da Kora. Esta demonstração mostra como:

Protocolo x402 viabiliza a monetização de APIs sem fricção por meio de micropagamentos
Kora RPC atua como facilitador para pagamentos x402, verificando e liquidando transações
Usuários podem pagar pelo acesso à API sem precisar ter SOL ou gerenciar taxas de gas

Esta arquitetura cria uma base poderosa para:

Marketplaces de Agentes de IA
APIs pay-per-use
Plataformas de conteúdo com micropagamentos
Precificação SaaS baseada em uso
Qualquer serviço que exija pagamentos instantâneos e verificáveis

A combinação do x402 e da Kora traz o poder da Solana para a infraestrutura web tradicional.

Continue Construindo

Personalizar Preços: Modifique a API para cobrar valores diferentes para endpoints diferentes
Adicionar Múltiplos Tokens: Configure a Kora para aceitar diversos tokens SPL como pagamento
Implantação em Produção: Faça o deploy na mainnet com signatários de produção (Vault, Turnkey ou Privy)
Crie Sua Própria API: Desenvolva um serviço real que monetize por meio de pagamentos x402

Faça perguntas no Solana Stack Exchange com as tags kora e x402
Abra issues no repositório Kora no GitHub

Guia Completo de Integração x402 com Kora