Saltar para o conteúdo principal
O X402 envolve HTTP, SDK, assinaturas, Facilitator e transações on-chain. Ao investigar problemas de assinatura ou liquidação, recomenda-se confirmar camada por camada na ordem “entrada pública -> resposta 402 -> payment handler do SDK -> settlement on-chain”. Este tutorial explica os métodos de verificação de cada camada e lista erros comuns.

Verificar a entrada pública

Declaração de capacidades do Facilitator:
Se retornar facilitator, supportedKinds e endpoints do protocolo, isso indica que os metadados de capacidades estão normais. A descoberta de recursos da API foi descontinuada; chame diretamente a API de destino e use a resposta 402 em tempo real como referência. Capacidades suportadas pelo Facilitator:
Se retornar kinds, isso indica que a entrada do Facilitator está normal.

Verificar os accepts do 402

Envie uma solicitação não autenticada que não gere cobrança:
Verifique se os accepts retornados incluem a rede que você deseja usar. network é um identificador CAIP-2:
  • eip155:8453 + exact (Base)
  • eip155:8453 + upto (Base, medição posterior)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact (Solana)
Se a rede de destino não estiver presente, isso indica que essa API ou o ambiente atual não está configurado com o método de recebimento X402 correspondente.

Executar as ferramentas avançadas de validação do X402Client

O repositório X402Client fornece ferramentas avançadas de validação, que podem ser usadas para confirmar a seleção da resposta 402, geração de assinatura, paid retry e settlement on-chain. Elas exigem funded wallet, RPC, chave privada e dependências de desenvolvimento. Para integrações comerciais comuns, recomenda-se priorizar o SDK TypeScript ou Python; execute essas ferramentas apenas quando for necessário localizar problemas de assinatura ou liquidação on-chain. Endereço do repositório: https://github.com/AceDataCloud/X402Client
Base:
Solana:
As ferramentas de validação normalmente imprimem:
  1. A resposta 402 da primeira solicitação.
  2. O payment requirement selecionado.
  3. O resumo do PAYMENT-SIGNATURE após a assinatura.
  4. O status HTTP e o corpo da resposta após a tentativa novamente.
  5. A transação de settlement on-chain ou, em caso de falha, o motivo do erro do Facilitator.
Não envie chaves privadas ou o PAYMENT-SIGNATURE completo para sistemas de logs ou tickets. Exemplo de resultados de validação da API pública:
Explicação:
  • Base exact, Solana exact e Base upto concluíram o paid retry de HTTP 402 para HTTP 200.
  • A transação on-chain de Base exact pode ser consultada no BaseScan, e o valor da liquidação é 95215 atomic USDC.
  • O limite assinado de Base upto é 95215 atomic USDC, mas o settlement on-chain real é 3 atomic USDC, indicando que a medição posterior cobra com base no uso real.
  • O caminho Solana confirmou o paid retry e a saída do modelo. RPCs públicos podem sofrer limitação de taxa; quando for necessário um rigoroso processo de reconciliação on-chain, use seu próprio RPC Solana ou confirme a assinatura da transação usando os registros de liquidação da plataforma.

SDK smoke test

As ferramentas avançadas de validação são usadas para verificar assinaturas e liquidações on-chain. O lado comercial também deve executar o SDK smoke test para confirmar que o código da aplicação pode processar automaticamente o 402 por meio do payment handler. Abaixo são exibidos apenas os trechos principais; o código completo precisa incluir wallet, provider e import. TypeScript:
Python:
Se o modelo retornar a string fixa conforme solicitado, isso indica que o SDK, payment handler, Gateway, Facilitator e API de destino estão conectados. Os dois trechos de smoke test acima usam Base exact, com liquidação no valor fixo cotado pelo 402. Chat completions é um cenário medido por token; para a integração formal, recomenda-se passar preferScheme: 'upto' (em Python, prefer_scheme="upto"), com liquidação baseada no uso real. O objeto retornado pelo SDK Python é um dict, e é possível usar res["choices"][0]["message"]["content"] para ler o conteúdo.

E2E de pagamento de pedidos

O pagamento de pedidos usa a API da plataforma em platform.acedata.cloud e requer um token de conta da plataforma. O fluxo completo é: criar um pedido Pending, POST /api/v1/orders/{order_id}/pay/ aciona o 402 e, em seguida, tentar novamente com PAYMENT-SIGNATURE. Exemplo de resultados de validação para pagamento de pedidos de pequeno valor:
Os registros de transação abaixo são exemplos históricos de testes reais sob a política antiga, e os valores e hashes de transação são mantidos como estão. Novos pedidos X402 não oferecem mais descontos por método de pagamento; use o amount da resposta 402 desta vez como base para assinatura e pagamento.
Explicação dos resultados:
  • Após criar o pedido, o estado do pedido é Pending, e o preço é 1.26.
  • A primeira solicitação pay/ retorna HTTP 402, há Base exact e Solana exact em accepts, e os valores são ambos 1200000 atomic USDC.
  • Após tentar novamente com a PAYMENT-SIGNATURE da Base, retorna HTTP 200, o estado do pedido muda para Finished, e pay_way é X402.
  • Após decodificar PAYMENT-RESPONSE, mostra success=True, network=base, e fornece o mesmo hash de transação.
  • No BaseScan, o estado da transação é 1, o valor da transferência é 1200000 atomic USDC, ou seja, 1.2 USDC.
  • O preço de criação 1.26 foi pago durante o período da antiga política de desconto de pagamento X402, e o valor final da assinatura e liquidação é 1.2 USDC.
Se o pagamento do pedido não tiver Authorization: Bearer {platform_token}, ou se o pedido não pertencer à conta atual, ele falhará na camada de permissões da plataforma; isso é diferente da API X402 sem conta que chama diretamente x402.acedata.cloud.

Erros comuns

Lista de verificação de upto da Base

Atualmente, upto é fornecido apenas na Base (eip155:8453). Como a assinatura upto vincula mais parâmetros de EVM typed data, ao integrar, deve-se confirmar especialmente que os campos em tempo real na resposta 402 sejam totalmente consistentes com a assinatura do cliente.
Se o Base upto retornar invalid_upto_evm_payload_invalid_signature, verifique prioritariamente:
  1. O extra.chainId (deve ser 8453) na entrada eip155:8453 + upto retornada pela API.
  2. O extra.facilitatorAddress retornado pela API.
  3. O endereço do facilitator Base upto retornado por https://facilitator.acedata.cloud/supported.
  4. O domínio Permit2, spender, contrato USDC e conta de assinatura.
  5. Se a carteira já fez approve do Permit2 para o USDC da Base.
O digest da assinatura de upto também vincula o domínio Permit2, chain ID, spender, endereço do destinatário, endereço do facilitator e validAfter. Se qualquer item for inconsistente, o Facilitator recuperará o signer incorreto, retornando assim invalid signature. Se todos estes forem consistentes, mas ainda retornar 402, verifique em seguida a allowance do Permit2; quando não autorizado, retorna PERMIT2_ALLOWANCE_REQUIRED.

Salvar informações de verificação

Uma verificação completa deve salvar ao menos:
  • API path e resumo do corpo da solicitação;
  • network e scheme selecionados;
  • maxAmountRequired;
  • endereço da carteira payer;
  • status final HTTP;
  • saída do modelo ou ID da tarefa na resposta;
  • link da transação de settlement;
  • ID de rastreamento do Gateway ou ID de registro de uso da plataforma.
Não salve chaves privadas, PAYMENT-SIGNATURE completa, signature EIP-712 completa ou frase mnemônica.

Erros de pagamento estruturados

As falhas X402 após a assinatura retornarão code estável, parâmetros de interpolação seguros, fase e sinalizador de repetição em extensions.acedatacloud.paymentError. Priorize usar essa estrutura para investigação, não analise o error em inglês de nível superior, nem exija que os usuários forneçam a assinatura da carteira ou o texto original da simulação on-chain.
  • charged: false: a verificação foi explicitamente recusada antes do settlement; nenhuma cobrança foi iniciada desta vez.
  • Sem charged: o resultado é desconhecido ou já entrou na fase de settlement; primeiro verifique o pedido e o estado on-chain, sendo proibido repetir diretamente o pagamento.
  • settlement_pending: não repita o pagamento por enquanto; primeiro atualize o pedido ou entre em contato com o suporte.
  • code não reconhecido: trate como payment_failed e preserve o código técnico público para consulta do atendimento ao cliente.