Saltar para o conteúdo principal
X402 é um protocolo de pagamento on-chain de “cobrança por HTTP 402” proposto pela Coinbase: o servidor retorna 402 Payment Required em solicitações sem token, incluindo o campo accepts: [...] que lista as chains / ativos / preços aceitos; o cliente assina localmente uma autorização (na EVM é Permit2 / EIP-712, na Solana é autorização de transferência de token SPL), coloca o envelope codificado em base64 no cabeçalho PAYMENT-SIGNATURE e reenvia. Após a validação, o servidor efetivamente liquida on-chain e então retorna o resultado de negócio.
O cliente X402 do Ace Data Cloud chama diretamente a API de destino e usa o 402 Payment Required e o accepts retornados em tempo real por essa solicitação como base para preço e assinatura. A capacidade de pagamento do Facilitator pode ser verificada em /.well-known/x402.
Tanto @acedatacloud/sdk quanto acedatacloud expõem um hook paymentHandler: quando uma solicitação emitida pelo próprio SDK recebe 402, ele chama o handler que você injetou para obter o cabeçalho PAYMENT-SIGNATURE e então reenvia a solicitação original. Combinando @acedatacloud/x402-client / acedatacloud-x402 com o SDK, todo o processo é completamente transparente para o código de negócio — você só usa client.openai.chat.completions.create(...), parecendo exatamente igual ao modo token, mas por baixo é pagamento por chamada, sem precisar recarregar antecipadamente. Este artigo:
  • Executa de verdade a cadeia de “sem token + injeção de handler X402” no lado TS (validação T12)
  • Lista as diferenças entre as duas cadeias de assinatura EVM / Solana
  • Fornece três adaptações: modo de chave privada viem, modo de carteira do navegador e modo Python EVMAccountSigner
  • Explica claramente o campo preferScheme / prefer_scheme, que é fácil de causar problemas

Um, Visão geral do protocolo (leitura obrigatória)

Uma chamada X402 bem-sucedida envolve 3 RTTs HTTP:
O envelope X402 é um trecho de JSON que, após ser codificado em base64, é inserido no cabeçalho PAYMENT-SIGNATURE. Estrutura (excerto):
No nível superior, o envelope possui x402Version: 2 e declara o scheme e o network selecionados nesta ocasião por meio do objeto accepted (identificador CAIP-2). preferScheme / prefer_scheme é usado para selecionar uma preferência quando o servidor oferece simultaneamente vários schemes. Se o servidor expuser apenas exact, esse campo será ignorado; se upto for definido mas não estiver exposto pelo servidor, haverá fallback para o primeiro item correspondente.

Dois, TypeScript: dois usos, carteira do navegador + viem no servidor

Instalação

Versões testadas:

Assinatura completa de createX402PaymentHandler

O valor retornado é um (ctx) => Promise&lt;{ headers: Record<string, string> }>, correspondendo exatamente à assinatura do hook paymentHandler do SDK.

Uso 1: navegador (MetaMask / WalletConnect)

Na primeira chamada, o navegador exibirá dois prompts de assinatura: o primeiro é um approve único de Permit2 para USDC (o valor é MaxUint256, gravado on-chain); o segundo é a assinatura EIP-712 do envelope X402 (não vai on-chain, apenas para validação pelo facilitator). As chamadas subsequentes precisam apenas da segunda assinatura; em termos de experiência, é “clicar uma vez para assinar → obter o resultado”.

Uso 2: servidor Node + chave privada viem (adequado para backend / CLI)

No lado TS, @acedatacloud/x402-client aceita apenas provider EIP-1193 — ele não gerencia chaves privadas diretamente. Em cenários Node / CLI, a prática padrão é usar viem para empacotar a chave privada como WalletClient, e então passar pelo adaptador EIP-1193 de @ethereumjs/util ou interno do viem.
Se achar que a adaptação EIP-1193 do viem não é estável o suficiente, também pode seguir pelo signEVMUptoPayment de nível mais baixo, encadeando por conta própria o caminho accepts → signed envelope → PAYMENT-SIGNATURE header e ignorando o hook do SDK; porém, ainda é recomendável priorizar createX402PaymentHandler, para evitar ter que manter atualizações do protocolo por conta própria.

Uso 3: Solana

Atualmente, na cadeia Solana, apenas o scheme exact é exposto, portanto preferScheme não tem efeito na Solana.

III. Python: modo de chave privada

O acedatacloud-x402 do Python segue o caminho de assinar diretamente com a chave privada (sem abstração EIP-1193), sendo mais adequado para servidores / executores de tarefas.

Instalação

Versões testadas:

EVM (Base)

Solana

Approve único (somente na primeira vez no EVM)

No EVM Base, o X402 usa Permit2, sendo necessário que a carteira faça uma vez um approve de MaxUint256 de USDC para o contrato Permit2. O acedatacloud-x402 inclui o approve_permit2:
Essa transação só precisa ser enviada uma vez; depois disso, todos os pagamentos X402 EVM usam essa autorização. A Solana não precisa disso.

IV. Verificação de execução real

Objetivo do teste: o SDK TS não passa token, injeta o handler X402 e consegue construir e iniciar requisições normalmente (verificação leve que não consome USDC real na cadeia).
Saída:
O resultado indica:
  • Sem passar apiToken, a construção do SDK não gera erro, provando que o modo X402 é de fato uma alternativa válida ao token.
  • createX402PaymentHandler retorna uma função (hook), que o SDK só chamará ao receber um 402.
  • O teste ponta a ponta do pagamento real na cadeia, por envolver desconto real de USDC, não foi incluído neste tutorial; consulte o exemplo e2e no guia de integração X402.
No lado Python, create_x402_payment_handler também realizou a mesma validação — o valor de retorno da função é callable, e a construção de AceDataCloud(...) não gera erro ao injetar payment_handler=.... A semântica dos dois lados está alinhada.

V. Comparação com o «modo Bearer token»

VI. Armadilhas comuns

  1. A classe chat deve usar preferScheme=upto: usar exact fará o facilitator deduzir USDC com base em maxAmountRequired (e não no uso real).
  2. No lado Node, não passe a chave privada bruta para createX402PaymentHandler: o pacote TS não aceita { privateKey }, é necessário encapsulá-la como um provider EIP-1193 (recomenda-se o WalletClient do viem).
  3. A primeira chamada exige duas assinaturas: a primeira assina o approve do Permit2 (on-chain, com gas), a segunda assina o envelope X402 (não on-chain). As chamadas subsequentes terão apenas a segunda.
  4. Solana não possui o conceito de Permit2: assina diretamente a autorização de transferência de token SPL, sem necessidade de approve; porém, atualmente, on-chain no Solana suporta apenas exact.
  5. Diferencie erros de negócio e erros de pagamento: 402 → a falha do handler lança X402SignError (o tipo específico varia conforme a chain); após o reenvio, os erros da interface de negócio (401 / 422 / 5xx) ainda são classificados como exceções normais do SDK.
  6. A forma mais estável de adaptar viem: evmProvider: walletClient as any perde a verificação de tipos, mas tem a melhor compatibilidade; se quiser manter os tipos, encapsule separadamente o .transport.request do viem em um objeto { request } e passe-o.

Saiba mais