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 oamount 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 formatoplatform-v1-....
Use nas solicitações subsequentes:
Acionar 402
Primeiro, envie uma solicitação semPAYMENT-SIGNATURE:
accepts:
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.
- 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 incluiPAYMENT-SIGNATURE, portanto retorna HTTP 402. acceptsfornece simultaneamente Baseexacte Solanaexact; 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 era1.2USDC, correspondente a1200000atomic USDC.
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:
exact:
status 200indica que a interface de pagamento de pedidos da plataforma aceitou estePAYMENT-SIGNATURE.has_x_payment_response Trueindica que o cabeçalho de resposta contém o reciboPAYMENT-RESPONSEcodificado em Base64.settle_header.success=Trueenetwork=baseindicam que o Facilitator concluiu o settlement na Base.- O status final do pedido é
Finished,pay_wayéX402, epay_idregistra o hash da transação on-chain. - O evento
Transferno BaseScan mostra que o endereço de pagamento transferiu1200000USDC atômicos para o endereço recebedor da plataforma, ou seja,1.2USDC.
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 respostaPAYMENT-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.
amountusa USDC atomic units,1200000representa1.2USDC.- Não monte por conta própria o endereço de recebimento ou o endereço do ativo; prevalece o
acceptsna resposta 402. - Se o mesmo
PAYMENT-SIGNATUREfor submetido repetidamente, o Facilitator realizará proteção contra replay com base no nonce.
Resposta de falha de pagamento
O primeiro HTTP 402 semPAYMENT-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:
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 objetoace_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.
