Vai al contenuto principale
Ace Data Cloud X402 utilizza attualmente due tipi di scheme: exact e upto. Risolvono problemi di fatturazione diversi.

exact

exact indica che il prezzo può essere determinato prima che questa richiesta entri nell’API di destinazione. L’importo firmato dal client è l’importo finale addebitato. Adatto per:
  • Generazione di immagini a prezzo fisso;
  • Creazione di attività video a prezzo fisso;
  • API di ricerca o strumenti API a prezzo fisso;
  • Pagamento degli ordini.
EVM exact utilizza USDC EIP-3009 TransferWithAuthorization:
Il Facilitator verifica la firma e l’importo nella fase /verify e invia questa autorizzazione on-chain nella fase /settle.

upto

upto indica che il client autorizza un limite massimo e Ace Data Cloud effettua il regolamento in base all’utilizzo effettivo dopo il completamento della richiesta; l’addebito effettivo non può superare il limite massimo. Adatto per:
  • Completamenti chat: il prezzo finale dipende dai prompt token e dai completion token;
  • Risposte in streaming: la reale lunghezza dell’output è nota solo al termine;
  • Future API con misurazione successiva.
upto utilizza Permit2 PermitWitnessTransferFrom. Il client non firma un trasferimento fisso, ma un’autorizzazione con limite massimo con witness:
permitted.amount è il limite massimo, non necessariamente l’addebito finale. Il Gateway converte l’utilizzo effettivo in amount e lo passa al Facilitator nella fase /record. Il Facilitator consente il regolamento solo se amount <= permitted.amount. Risultato dell’esecuzione del programma Base upto:
Spiegazione:
  • Il limite di autorizzazione restituito nel 402 è 95215 atomic USDC e il client firma in base a questo limite.
  • Dopo la risposta effettiva del modello, vengono regolati solo 3 atomic USDC; la transazione on-chain è consultabile su BaseScan.
  • Questo risultato dimostra la differenza chiave di upto: l’importo firmato è un limite massimo e il settlement on-chain può essere inferiore al limite massimo.
  • Se l’utilizzo effettivo supera il limite massimo, il Facilitator deve rifiutare il settlement e il client deve autorizzare nuovamente con un limite massimo più elevato.
upto è attualmente disponibile solo su Base. Quando è necessaria una misurazione successiva, utilizzare Base.

Perché è necessario Permit2 approve

upto preleva infine USDC dal wallet pagatore tramite Permit2 attraverso il proxy x402. Prima del primo utilizzo, il wallet pagatore deve concedere a Permit2 una ERC-20 allowance una tantum. CLI Python:
A livello di programma:
Dopo il completamento dell’autorizzazione, ogni richiesta deve comunque firmare un nuovo envelope upto, poiché nonce, deadline, witness e limite massimo dell’importo sono tutti diversi.

Regolamento a importo zero

upto supporta i casi in cui l’importo effettivo è 0. Ad esempio, se l’API di destinazione non produce correttamente un utilizzo fatturabile, il Gateway può passare amount = "0". Il Facilitator restituisce un esito positivo, ma non invia una transazione on-chain. Questo può evitare il problema di “la richiesta non è andata a buon fine ma vengono comunque addebitate commissioni on-chain”.

Suggerimenti per la scelta

Se non sei sicuro di quale scegliere, utilizza prima il comportamento predefinito dell’SDK; l’SDK selezionerà il payment requirement della rete corrispondente restituito dal server.

Lista di controllo Base upto

Durante l’integrazione o la risoluzione dei problemi, assicurarsi che i seguenti parametri provengano dalla stessa risposta 402 e rimangano coerenti durante la firma del client: Errori comuni e modalità di gestione: