Vai al contenuto principale
X402 è un protocollo di pagamento on-chain basato su HTTP 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
Codice sorgente pubblico e indirizzi dei pacchetti: 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.
Descrizione:
  • 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 accepts include 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, Base upto e il pagamento dell’ordine dispongono tutti di indirizzi explorer apribili pubblicamente.
  • Il limite massimo firmato di Base upto è 95215 USDC atomici, mentre il settlement effettivo è 3 USDC atomici, riflettendo la caratteristica della fatturazione post-utilizzo in base al consumo reale.
  • Solana exact ha 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.facilitatorAddress e accepts[].extra.verifyingContract partecipano alla firma EVM typed data.
  • upto richiede che il wallet autorizzi prima Permit2 per USDC sulla catena di destinazione; se non autorizzato, verrà restituito PERMIT2_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 Authorization o PAYMENT-SIGNATURE restituiscono 402 Payment Required; accepts nella 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 accepts restituito 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.