402 Payment Required. Grazie alle funzionalità X402 di Ace Data Cloud, il chiamante può effettuare direttamente pagamenti on-chain in USDC in ogni richiesta API senza creare un API Token né pre-caricare il saldo dell’account.
Questa serie di documenti è organizzata secondo il reale ordine di integrazione: prima eseguire una richiesta minima, poi integrare l’SDK, quindi comprendere reti, piani di fatturazione, pagamento degli ordini e Facilitator. Si consiglia di leggere dall’alto verso il basso seguendo la tabella seguente.
Percorso di integrazione consigliato
Se desideri soltanto chiamare l’API Ace Data Cloud, utilizza prioritariamente l’SDK ufficiale:- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
L’SDK completerà automaticamente i passaggi di prima richiesta non autenticata, analisi di
402 Payment Required, chiamata del payment handler e nuovo tentativo con PAYMENT-SIGNATURE. Devi soltanto preparare un wallet con USDC e scegliere la rete che desideri utilizzare.
Se desideri fare in modo che anche la tua API supporti la riscossione con X402, devi leggere la documentazione Facilitator per comprendere la relazione tra paymentRequirements, paymentPayload, /verify e /settle.
Stato del supporto
Ace Data Cloud X402 è stato verificato sulle API pubbliche, sugli SDK ufficiali, su Facilitator e nel flusso di liquidazione on-chain. La tabella seguente riassume lo stato attuale in base alle dimensioni delle funzionalità più comunemente utilizzate dagli sviluppatori durante l’integrazione.
Il seguente output è utilizzato soltanto per illustrare la forma delle risposte dei percorsi verificati. Durante l’effettiva integrazione, fai sempre riferimento agli
accepts restituiti dall’API corrente.
- I pacchetti npm e PyPI sono stati entrambi installati e importati con successo in un ambiente pulito.
- Le richieste API non pagate restituiscono 402 e
acceptsinclude metodi di pagamento disponibili per Base e Solana. accepts[].networkè un identificatore CAIP-2; il client deve effettuare la corrispondenza in base alla stringa CAIP-2 quando seleziona la rete.- Sia l’SDK TypeScript sia l’SDK Python possono gestire automaticamente 402 e completare il paid retry.
- Base
exact, Baseuptoe il pagamento dell’ordine dispongono tutti di indirizzi explorer apribili pubblicamente. - Il limite massimo firmato di Base
uptoè95215USDC atomici, mentre il settlement effettivo è3USDC atomici, riflettendo la caratteristica della fatturazione post-utilizzo in base al consumo reale. - Solana
exactha verificato HTTP 402 -> HTTP 200 e l’output del modello. Poiché le query RPC pubbliche possono subire limitazioni di frequenza, per una riconciliazione rigorosa si consiglia di utilizzare un proprio RPC Solana o i record di settlement lato piattaforma per confermare la firma della transazione.
Note di integrazione
Durante l’integrazione, gli sviluppatori devono dare priorità ai requisiti di pagamento in tempo reale restituiti dalla richiesta corrente, anziché copiare gli importi o gli indirizzi di esempio presenti nella documentazione:accepts[].maxAmountRequiredè l’importo massimo firmabile per la richiesta corrente.accepts[].assetè il contratto USDC o il mint da utilizzare per questa richiesta.accepts[].extra.chainId,accepts[].extra.facilitatorAddresseaccepts[].extra.verifyingContractpartecipano alla firma EVM typed data.uptorichiede che il wallet autorizzi prima Permit2 per USDC sulla catena di destinazione; se non autorizzato, verrà restituitoPERMIT2_ALLOWANCE_REQUIRED.- Se si desidera esplicitamente utilizzare la fatturazione post-utilizzo, passare
preferScheme: 'upto'nell’SDK TypeScript; altrimenti l’SDK selezionerà il primo requirement disponibile restituito dal server per quella rete.
Ambito verificabile pubblicamente
Prima dell’integrazione, è possibile verificare questi endpoint pubblici e il comportamento dell’SDK:- Le richieste API senza
AuthorizationoPAYMENT-SIGNATURErestituiscono402 Payment Required;acceptsnella risposta è l’unica base di firma per la richiesta corrente. - Sia l’SDK TypeScript sia l’SDK Python forniscono un payment handler; il livello di trasporto dell’SDK, dopo aver ricevuto 402, chiama l’handler e ritenta una volta.
https://facilitator.acedata.cloud/.well-known/x402: restituisce le reti, gli scheme e gli endpoint del protocollo supportati dal Facilitator; il prezzo dell’API continua a essere determinato dal 402 restituito in tempo reale dalla richiesta di destinazione.https://facilitator.acedata.cloud/supported: restituisce le reti e gli scheme supportati dal Facilitator.- Il repository X402Client include strumenti avanzati di verifica on-chain, che possono essere utilizzati per confermare il comportamento di firma, retry e settlement; l’output degli strumenti non sostituisce
acceptsrestituito dall’API online.
upto appartiene al settlement con fatturazione post-utilizzo ed è adatto ad API come completamenti chat e chiamate di modelli, per le quali l’utilizzo reale è noto solo dopo la risposta. Attualmente solo Base fornisce upto; se la verifica della firma non riesce, verificare che chain id, indirizzo del facilitator, spender, contratto USDC e Permit2 allowance siano coerenti con la risposta 402.
