Protocolo de Pagamento x402

O que Protocolo de Pagamento x402 faz?

O x402 permite pagamentos instantâneos em stablecoin diretamente via HTTP, usando o código de status 402 Payment Required. Perfeito para agentes de IA pagarem por APIs, dados ou processamento computacional sob demanda.

Introdução Rápida

Instalar SDK

npm install x402
# ou
pnpm add x402

Configuração de Ambiente

# Armazene a chave privada da wallet de forma segura
export WALLET_PRIVATE_KEY="0x..."

# Opcional: especificar o RPC da rede
export BASE_RPC_URL="https://mainnet.base.org"

Como o x402 Funciona

1. Requisição → O cliente chama uma API paga
2. Resposta 402 → O servidor retorna detalhes de pagamento no cabeçalho PAYMENT-REQUIRED
3. Pagar e Tentar Novamente → O cliente assina o pagamento e tenta novamente com o cabeçalho PAYMENT-SIGNATURE
4. Acesso → O servidor verifica, liquida e retorna o recurso

Usando o Cliente x402

TypeScript/Node.js

import { x402Client } from 'x402';

const client = x402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'base', // ou 'ethereum', 'arbitrum', etc.
});

// Manipulação automática de 402
const response = await client.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();

Com wrapper fetch

import { wrapFetch } from 'x402';

const fetch402 = wrapFetch(fetch, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
});

// Use como fetch normal - 402 são manipulados automaticamente
const res = await fetch402('https://paid-api.com/data');

Fluxo Manual (curl)

Passo 1: Descobrir requisitos de pagamento

curl -i https://api.example.com/paid-resource
# Retorna 402 com o cabeçalho PAYMENT-REQUIRED (JSON em base64)

Passo 2: Decodificar detalhes do pagamento

# O cabeçalho PAYMENT-REQUIRED contém JSON codificado em base64:
# {
#   "amount": "1000000",      # 1 USDC (6 casas decimais)
#   "currency": "USDC",
#   "network": "base",
#   "recipient": "0x...",
#   "scheme": "exact"
# }

Passo 3: Assinar e pagar

# Use a CLI ou SDK do x402 para criar a assinatura de pagamento
npx x402 pay \
  --amount 1000000 \
  --recipient 0x... \
  --network base

Passo 4: Tentar novamente com prova

curl -H "PAYMENT-SIGNATURE: <base64_payload>" \
  https://api.example.com/paid-resource

Padrões Comuns

Pagar por chamadas de API

// API de clima que custa 0,001 USDC por chamada
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');

Pagar por inferência de IA

// API LLM com precificação por token
const completion = await client.fetch('https://llm.example.com/v1/chat', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'Hello' }),
});

Verificar saldo antes de pagar

import { getBalance } from 'x402';

const balance = await getBalance({
  address: walletAddress,
  network: 'base',
  token: 'USDC',
});

if (balance < requiredAmount) {
  console.log('Saldo USDC insuficiente');
}

Redes Suportadas

Rede	Chain ID	Status
Base	8453	✅ Primária
Ethereum	1	✅ Suportada
Arbitrum	42161	✅ Suportada
Optimism	10	✅ Suportada
Polygon	137	✅ Suportada

Esquemas de Pagamento

• exact: Pagar valor fixo (ex: $0,01 por chamada de API)
• upto: Pagar até o máximo com base no uso (ex: tokens LLM)
• subscription: Acesso baseado em wallet com sessões (V2)

Tratamento de Erros

try {
  const res = await client.fetch(url);
} catch (err) {
  if (err.code === 'INSUFFICIENT_BALANCE') {
    // Necessário fundar a wallet
  } else if (err.code === 'PAYMENT_FAILED') {
    // Transação falhou na chain
  } else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
    // O servidor enviou resposta 402 malformada
  }
}

Notas de Segurança

• Nunca exponha chaves privadas em logs ou chat
• Use variáveis de ambiente para credenciais da wallet
• Prefira op run ou similar para injeção de segredos
• Revise os valores de pagamento antes de confirmar transações grandes

Funcionalidades V2 (Dezembro de 2025)

• Identidade baseada em wallet: Evite pagar novamente em cada chamada com sessões
• Descoberta automática: APIs expõem metadados de pagamento em /.well-known/x402
• Multi-processador: Escolha entre processadores de pagamento
• Padrões CAIP: Identificadores universais de chain/asset

Recursos

• Especificação: https://github.com/coinbase/x402
• Documentação: https://docs.cdp.coinbase.com/x402
• APIs de demonstração: https://www.x402.org