Saltar para o conteúdo principal
O Facilitator é o componente de liquidação do lado do servidor na cadeia X402. O cliente é responsável pela assinatura, e o Gateway ou seu servidor é responsável por chamar /verify e /settle do Facilitator. O endereço de produção do Facilitator da Ace Data Cloud é:
Repositório do código-fonte: https://github.com/AceDataCloud/FacilitatorX402

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ção X-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: 2 e deve declarar o scheme e o network selecionados desta vez usando o objeto accepted.
  • network usa o identificador CAIP-2 (como eip155:8453) e não pode usar abreviações como base.
Estrutura do envelope:
Além do corpo JSON, a resposta 402 também incluirá um cabeçalho de resposta 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:
Exemplo de retorno:
Descrição dos resultados:
  • network usa o identificador CAIP-2, e não abreviações como base ou solana.
  • /supported indica que o Facilitator possui a capacidade correspondente de verificação e liquidação.
  • Base e Solana suportam exact; atualmente, upto é fornecido apenas na Base.
  • signers sã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 accepts da resposta 402 dessa API.

POST /verify

Verifique se o PAYMENT-SIGNATURE enviado pelo cliente atende a um determinado payment requirement. Corpo da solicitação:
Os campos 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:
Após a decodificação, o cabeçalho de resposta 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:
Descrição dos resultados:
  • success=True indica que a settlement do Facilitator foi bem-sucedida.
  • transaction é o hash da transação on-chain, e o pay_id do pedido também é gravado com o mesmo valor.
  • No explorer, é possível ver a transferência de 1200000 atomic USDC da Base.
  • errorReason=None indica que esta settlement não retornou um erro de negócio.
Falhas de verificação também normalmente retornam HTTP 200, mas 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:
Se o valor real de 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:
  1. O cliente solicita a API pela primeira vez, sem Authorization e PAYMENT-SIGNATURE.
  2. O Gateway calcula o preço estimado da solicitação e retorna 402 e accepts.
  3. Após assinar, o cliente tenta novamente com PAYMENT-SIGNATURE.
  4. O Gateway decodifica PAYMENT-SIGNATURE e seleciona o payment requirement correspondente.
  5. O Gateway chama o Facilitator /verify.
  6. Após o sucesso de /verify, o Gateway libera a solicitação para a API de destino.
  7. Após o retorno da API de destino, o Gateway chama o Facilitator /settle na etapa /record.
  8. 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:
  1. Prepare paymentRequirements for each paid endpoint, including network, amount, recipient address, asset address, and signature domain.
  2. If the request does not have PAYMENT-SIGNATURE, return HTTP 402 and accepts.
  3. If the request has PAYMENT-SIGNATURE, Base64 decode it to obtain paymentPayload.
  4. Call Facilitator /verify.
  5. Execute the business logic after successful verification.
  6. Call Facilitator /settle after successful business execution.
  7. Save payer, transaction, amount, network for reconciliation.
The server must use its own generated 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 /settle has submitted the transaction but has not been confirmed temporarily, you can retry /settle with the same nonce for idempotent reconciliation;
  • Do not cache the same PAYMENT-SIGNATURE and use it for multiple API calls.

Common Errors