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 oTanto402 Payment Requirede oacceptsretornados 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.
@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 PythonEVMAccountSigner - 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:PAYMENT-SIGNATURE. Estrutura (excerto):
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
Assinatura completa de createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }>, correspondendo exatamente à assinatura do hook paymentHandler do SDK.
Uso 1: navegador (MetaMask / WalletConnect)
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 pelosignEVMUptoPaymentde nível mais baixo, encadeando por conta própria o caminhoaccepts → signed envelope → PAYMENT-SIGNATURE headere ignorando o hook do SDK; porém, ainda é recomendável priorizarcreateX402PaymentHandler, para evitar ter que manter atualizações do protocolo por conta própria.
Uso 3: Solana
exact é exposto, portanto preferScheme não tem efeito na Solana.
III. Python: modo de chave privada
Oacedatacloud-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
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 deMaxUint256 de USDC para o contrato Permit2. O acedatacloud-x402 inclui o approve_permit2:
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).- 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. createX402PaymentHandlerretorna 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_handlertambém realizou a mesma validação — o valor de retorno da função é callable, e a construção deAceDataCloud(...)não gera erro ao injetarpayment_handler=.... A semântica dos dois lados está alinhada.
V. Comparação com o «modo Bearer token»
VI. Armadilhas comuns
- A classe chat deve usar
preferScheme=upto: usarexactfará o facilitator deduzir USDC com base emmaxAmountRequired(e não no uso real). - 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 oWalletClientdo viem). - 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.
- 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. - 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. - A forma mais estável de adaptar
viem:evmProvider: walletClient as anyperde a verificação de tipos, mas tem a melhor compatibilidade; se quiser manter os tipos, encapsule separadamente o.transport.requestdo viem em um objeto{ request }e passe-o.

