Saltar para o conteúdo principal
Além de pagar diretamente por solicitações de API, o Ace Data Cloud também oferece suporte ao uso do X402 para pagar pedidos no console. O protocolo central para pagamento de pedidos e chamadas de API é o mesmo: a primeira solicitação retorna 402, o cliente assina PAYMENT-SIGNATURE e então tenta novamente com a mesma solicitação. A diferença é que o pagamento de pedidos pertence à API da plataforma e requer um token de conta; enquanto chamar diretamente a API de IA em x402.acedata.cloud pode usar apenas X402, sem precisar de um API Token.

Preparar o pedido

Acesse o console do Ace Data Cloud, selecione o pedido que precisa ser pago e registre o ID do pedido. Se você ainda não tem um pedido, pode criar um pedido pendente de pagamento na página de planos. O preço do pedido está sujeito ao que é exibido na página, e o amount na resposta 402 do X402 é a base final para a assinatura.

Criar um token de conta

As solicitações de pagamento de pedidos exigem um token de conta. Abra a página de Tokens da plataforma e crie um token no formato platform-v1-.... Use nas solicitações subsequentes:
O token de conta é diferente de um API Token comum. Um API Token comum é usado para consumir créditos de API; o token de conta é usado para operar recursos da plataforma em nome da sua conta, como pagamentos de pedidos.

Acionar 402

Primeiro, envie uma solicitação sem PAYMENT-SIGNATURE:
O status retornado é 402, e a resposta inclui accepts:
O pagamento de pedidos usa o x402 v2 oficial: x402Version é 2, network usa o identificador CAIP-2, e o campo de valor é amount. Resultado da execução do programa ao criar um pedido de 10 Credits e acionar 402:
Os registros de transação abaixo são amostras históricas de testes reais sob a política antiga, e os valores e hashes de transação são mantidos como estavam. Novos pedidos X402 não oferecem mais descontos por método de pagamento; use o amount da resposta 402 atual como base para assinatura e pagamento.
Explicação dos resultados:
  • Após a criação bem-sucedida do pedido, o status é Pending; neste momento, ainda não há pagamento on-chain.
  • A primeira solicitação pay/ não inclui PAYMENT-SIGNATURE, portanto retorna HTTP 402.
  • accepts fornece simultaneamente Base exact e Solana exact; este tutorial seleciona Base posteriormente.
  • O preço ao criar o pedido é 1.26; durante o período da antiga política de desconto para pagamento X402, o valor real de assinatura e liquidação era 1.2 USDC, correspondente a 1200000 atomic USDC.
Observe que resource é um campo retornado pelo servidor e que participa da assinatura; o cliente não deve reescrever por conta própria o protocolo, o caminho ou o ID do pedido nele contidos.

Assinar e tentar novamente

O pagamento de pedidos pode reutilizar as funções de assinatura de baixo nível de @acedatacloud/x402-client ou acedatacloud-x402. Abaixo está um exemplo em TypeScript:
Resultado da execução do programa após assinar e tentar novamente o mesmo pedido usando Base exact:
Resultado da confirmação on-chain:
Explicação do resultado:
  • status 200 indica que a interface de pagamento de pedidos da plataforma aceitou este PAYMENT-SIGNATURE.
  • has_x_payment_response True indica que o cabeçalho de resposta contém o recibo PAYMENT-RESPONSE codificado em Base64.
  • settle_header.success=True e network=base indicam que o Facilitator concluiu o settlement na Base.
  • O status final do pedido é Finished, pay_way é X402, e pay_id registra o hash da transação on-chain.
  • O evento Transfer no BaseScan mostra que o endereço de pagamento transferiu 1200000 USDC atômicos para o endereço recebedor da plataforma, ou seja, 1.2 USDC.

Resposta bem-sucedida e recibo

Após o pagamento do pedido ser bem-sucedido, o corpo da resposta contém as informações do pedido. A plataforma também transportará no cabeçalho de resposta PAYMENT-RESPONSE a settlement response codificada em Base64, cujos campos comuns após a decodificação incluem: Se você precisar de reconciliação, é recomendável salvar simultaneamente o ID do pedido, o endereço da carteira pagadora, transaction e o status final do pedido.

Observações

  • O pagamento do pedido requer o token da conta da plataforma, não podendo ser concluído apenas com a assinatura da carteira X402.
  • amount usa USDC atomic units, 1200000 representa 1.2 USDC.
  • Não monte por conta própria o endereço de recebimento ou o endereço do ativo; prevalece o accepts na resposta 402.
  • Se o mesmo PAYMENT-SIGNATURE for submetido repetidamente, o Facilitator realizará proteção contra replay com base no nonce.

Resposta de falha de pagamento

O primeiro HTTP 402 sem PAYMENT-SIGNATURE é um desafio de pagamento normal e não representa falha de pagamento. A falha de verificação ou settlement após a assinatura ainda preserva a string padrão error como fallback de compatibilidade e retorna uma estrutura de erro estável em extensions.acedatacloud.paymentError:
O cliente deve priorizar a localização com base em code; códigos desconhecidos devem recorrer à falha de pagamento genérica. charged é um campo de três estados: somente retornará false quando houver uma rejeição explícita antes do settlement; a ausência do campo indica que o status da cobrança é desconhecido e não pode ser interpretada como “não cobrado”. Após o pedido atual entrar em Failed, não é possível tentar novamente o pedido original; crie um novo pedido após corrigir o problema da carteira. metadata.x402.last_error e metadata.x402.errors da lista e dos detalhes do pedido preservam o mesmo conjunto de code, stage, retryable, charged e params; o texto explicativo público é armazenado em reason, e o momento da ocorrência é armazenado em timestamp. Por exemplo, insufficient_token_balance indica saldo insuficiente de USDC na rede selecionada, e invalid_signature indica uma assinatura de pagamento inválida; reler o pedido não os transformará em um payment_failed genérico. Não registre nem envie o PAYMENT-SIGNATURE completo, a assinatura da carteira, o payload de autorização, os diagnósticos originais do Facilitator ou as respostas RPC. Para a investigação do suporte, basta o ID do pedido e o code de erro público.

Recompra e queima de ACE para pagamentos na Base e Solana

Após ativar a estratégia de recompra, 3% dos valores efetivamente recebidos elegíveis de Circle USDC na rede principal da Base e USDC na rede principal da Solana são usados para comprar e queimar ACE, sem cobrança adicional da carteira pagadora. A provisão é feita uma vez no momento da recarga; o uso posterior desses Credits para chamar a API não gera provisão repetida; pedidos históricos com desconto e pedidos de políticas antigas não recebem provisão retroativa automaticamente. Os pagamentos na Base retêm o recibo de pagamento na cadeia Base, e a compra e queima de ACE são executadas de forma assíncrona na Solana. Os pagamentos elegíveis recebem uma provisão precisa de 3% com base no valor efetivamente recebido, sem limite fixo de valor de recompra por transação ou por dia; os fundos disponíveis, as cotações de mercado e as confirmações on-chain ainda podem afetar o tempo de conclusão. O objeto ace_burn nos detalhes do pedido fornece settlement_network, settlement_transaction e execution_network, e fornece swap_signature e burn_signature após a conclusão. Pending ou Processing não indicam que a queima já ocorreu; somente Completed representa que a prova final on-chain foi verificada. Quando um pagamento na Base ainda não atingiu a confirmação final, a recompra aguardará a confirmação, mas isso não afeta os Credits já creditados.