/verify e /settle do Facilitator.
O endereço de produção do Facilitator da Ace Data Cloud é:
Convenções wire v2
A cadeia X402 da Ace Data Cloud já utiliza integralmente o x402 v2 oficial e não aceita mais o cabeçalho de solicitaçãoX-Payment do v1. Há três pontos aos quais é necessário prestar atenção durante a integração:
- O cabeçalho de solicitação é
PAYMENT-SIGNATURE, e seu valor é um JSON envelope codificado em base64. - O nível superior do envelope deve ser
x402Version: 2e deve declarar oschemee onetworkselecionados desta vez usando o objetoaccepted. networkusa o identificador CAIP-2 (comoeip155:8453) e não pode usar abreviações comobase.
PAYMENT-REQUIRED, cujo valor é a codificação base64 do mesmo conteúdo de desafio, facilitando a leitura dos requisitos de pagamento pelo cliente sem analisar o body.
Interfaces principais
GET /supported
Visualize as redes e schemes suportados:
networkusa o identificador CAIP-2, e não abreviações comobaseousolana./supportedindica que o Facilitator possui a capacidade correspondente de verificação e liquidação.- Base e Solana suportam
exact; atualmente,uptoé fornecido apenas na Base. signerssão os endereços usados pelo Facilitator para enviar transações de liquidação.- Se uma API específica permite essas opções ainda depende do
acceptsda resposta 402 dessa API.
POST /verify
Verifique se o PAYMENT-SIGNATURE enviado pelo cliente atende a um determinado payment requirement.
Corpo da solicitação:
paymentRequirements do v2 são scheme, network, asset, amount, payTo, maxTimeoutSeconds e extra, e o campo de valor é amount. O accepts[] da resposta 402 da API também retornará adicionalmente maxAmountRequired para que o cliente leia o limite superior, mas ele não faz parte dos campos do corpo da solicitação do Facilitator.
Resposta de sucesso:
PAYMENT-RESPONSE do pagamento de pedidos de produção contém o resultado da settlement. O resultado da execução do programa para pagamento de pedidos na Base:
success=Trueindica que a settlement do Facilitator foi bem-sucedida.transactioné o hash da transação on-chain, e opay_iddo pedido também é gravado com o mesmo valor.- No explorer, é possível ver a transferência de
1200000atomic USDC da Base. errorReason=Noneindica que esta settlement não retornou um erro de negócio.
isValid é false. O lado do negócio deve ler invalidReason, em vez de verificar apenas o código de status HTTP.
POST /settle
Liquide on-chain uma autorização que já foi verificada.
O corpo da solicitação é basicamente igual ao de /verify. A diferença de upto é: paymentRequirements.amount é reescrito como o valor real da liquidação durante o settle; o limite de assinatura é registrado pelo Facilitator na etapa de verify, e durante o settle é verificado que o valor real não excede esse limite.
Resposta de sucesso:
upto for 0, transaction poderá ser uma string vazia, indicando que não é necessário enviar uma transação on-chain.
Como o Ace Data Cloud Gateway usa o Facilitator
A cadeia do Ace Data Cloud API Gateway é a seguinte:- O cliente solicita a API pela primeira vez, sem
AuthorizationePAYMENT-SIGNATURE. - O Gateway calcula o preço estimado da solicitação e retorna 402 e
accepts. - Após assinar, o cliente tenta novamente com
PAYMENT-SIGNATURE. - O Gateway decodifica
PAYMENT-SIGNATUREe seleciona o payment requirement correspondente. - O Gateway chama o Facilitator
/verify. - Após o sucesso de
/verify, o Gateway libera a solicitação para a API de destino. - Após o retorno da API de destino, o Gateway chama o Facilitator
/settlena etapa/record. - O Gateway grava o hash da transação on-chain nos metadados do registro de uso.
exact liquida o valor assinado na etapa 7; upto grava o amount de acordo com o uso real na etapa 7 e então liquida o valor real.
Como integrar sua própria API
Se você deseja que sua própria API ofereça suporte ao X402, pode implementar de acordo com esta estrutura:- Prepare
paymentRequirementsfor each paid endpoint, including network, amount, recipient address, asset address, and signature domain. - If the request does not have
PAYMENT-SIGNATURE, return HTTP 402 andaccepts. - If the request has
PAYMENT-SIGNATURE, Base64 decode it to obtainpaymentPayload. - Call Facilitator
/verify. - Execute the business logic after successful verification.
- Call Facilitator
/settleafter successful business execution. - Save
payer,transaction,amount,networkfor reconciliation.
paymentRequirements to call /verify and /settle; do not trust the amount, recipient address, or asset address returned by the client.
Replay Protection
Facilitator records nonces. Authorization with the same nonce cannot be verified and settled repeatedly. This means:- The client should sign a new envelope for every request;
- If
/settlehas submitted the transaction but has not been confirmed temporarily, you can retry/settlewith the same nonce for idempotent reconciliation; - Do not cache the same
PAYMENT-SIGNATUREand use it for multiple API calls.

