Verificar a entrada pública
Declaração de capacidades do Facilitator: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:
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:
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)
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- A resposta 402 da primeira solicitação.
- O payment requirement selecionado.
- O resumo do
PAYMENT-SIGNATUREapós a assinatura. - O status HTTP e o corpo da resposta após a tentativa novamente.
- A transação de settlement on-chain ou, em caso de falha, o motivo do erro do Facilitator.
PAYMENT-SIGNATURE completo para sistemas de logs ou tickets.
Exemplo de resultados de validação da API pública:
- Base
exact, Solanaexacte Baseuptoconcluíram o paid retry de HTTP 402 para HTTP 200. - A transação on-chain de Base
exactpode ser consultada no BaseScan, e o valor da liquidação é95215atomic USDC. - O limite assinado de Base
uptoé95215atomic USDC, mas o settlement on-chain real é3atomic 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: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 emplatform.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.
- 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á Baseexacte Solanaexactemaccepts, e os valores são ambos1200000atomic USDC. - Após tentar novamente com a
PAYMENT-SIGNATUREda Base, retorna HTTP 200, o estado do pedido muda paraFinished, epay_wayéX402. - Após decodificar
PAYMENT-RESPONSE, mostrasuccess=True,network=base, e fornece o mesmo hash de transação. - No BaseScan, o estado da transação é
1, o valor da transferência é1200000atomic USDC, ou seja,1.2USDC. - O preço de criação
1.26foi pago durante o período da antiga política de desconto de pagamento X402, e o valor final da assinatura e liquidação é1.2USDC.
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.
upto retornar invalid_upto_evm_payload_invalid_signature, verifique prioritariamente:
- O
extra.chainId(deve ser8453) na entradaeip155:8453+uptoretornada pela API. - O
extra.facilitatorAddressretornado pela API. - O endereço do facilitator Base
uptoretornado porhttps://facilitator.acedata.cloud/supported. - O domínio Permit2, spender, contrato USDC e conta de assinatura.
- Se a carteira já fez approve do Permit2 para o USDC da Base.
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.
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 emextensions.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_failede preserve o código técnico público para consulta do atendimento ao cliente.

