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.
exact utiliza USDC EIP-3009 TransferWithAuthorization:
/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:
- O limite de autorização retornado em 402 é
95215atomic USDC, e o cliente assina com base nesse limite. - Após a resposta real do modelo, apenas
3atomic 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:
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:

