Saltar para o conteúdo principal
A Ace Data Cloud X402 atualmente utiliza dois tipos de scheme: exact e upto. Eles resolvem problemas de cobrança diferentes.

exact

exact indica que o preço desta solicitação pode ser determinado antes de entrar na API de destino. O valor assinado pelo cliente é o valor final cobrado. Adequado para:
  • geração de imagens com preço fixo;
  • criação de tarefas de vídeo com preço fixo;
  • APIs de busca ou ferramentas com preço fixo;
  • pagamento de pedidos.
O EVM exact utiliza USDC EIP-3009 TransferWithAuthorization:
O Facilitator verifica a assinatura e o valor na fase /verify e envia esta autorização para a blockchain na fase /settle.

upto

upto indica que o cliente autoriza um limite máximo, e a Ace Data Cloud faz a liquidação com base no uso real após a conclusão da solicitação; a cobrança real não pode exceder o limite. Adequado para:
  • completamentos de chat: o preço final depende dos prompt tokens e completion tokens;
  • respostas em streaming: só se sabe o comprimento real da saída depois que ela termina;
  • futuras APIs de medição posterior.
upto utiliza Permit2 PermitWitnessTransferFrom. O cliente não assina uma transferência fixa, mas uma autorização de limite com witness:
permitted.amount é o limite, não necessariamente a cobrança final. O Gateway converterá o uso real em amount e o enviará ao Facilitator na fase /record. O Facilitator só permite a liquidação de amount <= permitted.amount. Resultado da execução do programa Base upto:
Explicação:
  • O limite de autorização retornado em 402 é 95215 atomic USDC, e o cliente assina com base nesse limite.
  • Após a resposta real do modelo, apenas 3 atomic USDC são liquidados, e a transação on-chain já pode ser consultada no BaseScan.
  • Este resultado demonstra a diferença fundamental de upto: o valor assinado é o limite, e o settlement on-chain pode ser menor que o limite.
  • Se o uso real exceder o limite, o Facilitator deverá rejeitar o settlement, e o cliente precisará autorizar novamente com um limite maior.
upto atualmente é fornecido apenas na Base. Quando for necessária medição posterior, use a Base.

Por que é necessário o approve do Permit2

No fim, upto faz com que o proxy x402 retire USDC da carteira pagadora através do Permit2. Antes do primeiro uso, a carteira pagadora precisa conceder ao Permit2 uma allowance ERC-20 única. CLI Python:
De forma programática:
Após a autorização ser concluída, cada solicitação ainda precisa assinar um novo envelope upto, porque nonce, deadline, witness e o limite de valor são todos diferentes.

Liquidação de valor zero

upto suporta casos em que o valor real é 0. Por exemplo, se a API de destino não produziu com sucesso uso faturável, o Gateway pode passar amount = "0". O Facilitator retornará sucesso, mas não enviará uma transação on-chain. Isso pode evitar o problema de “a solicitação não foi bem-sucedida, mas ainda assim são cobradas taxas on-chain”.

Recomendações de escolha

Se você não tiver certeza de qual escolher, primeiro use o comportamento padrão do SDK; o SDK escolherá o payment requirement de rede correspondente retornado pelo servidor.

Lista de verificação do Base upto

Ao integrar ou investigar problemas, confirme que os seguintes parâmetros vêm da mesma resposta 402 e permanecem consistentes ao assinar no cliente: Erros comuns e formas de tratamento: