Skip to main content
X402 è un protocollo di pagamento on-chain basato su HTTP 402 Payment Required. Grazie alle capacità di X402 di Ace Data Cloud, il chiamante può effettuare pagamenti on-chain in USDC senza creare un API Token o pre-caricare il saldo dell’account, effettuando il pagamento direttamente in ogni richiesta API. Questo insieme di documenti è organizzato secondo l’ordine di integrazione reale: prima eseguire una richiesta minima, poi integrare l’SDK, e infine comprendere rete, piani tariffari, pagamento degli ordini e Facilitator. Si consiglia di leggere la tabella seguente dall’alto verso il basso.

​
Percorso di integrazione consigliato

Se desideri solo chiamare l’API di Ace Data Cloud, utilizza prioritariamente l’SDK ufficiale:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Indirizzi del codice sorgente e dei pacchetti pubblici: L’SDK gestirà automaticamente la prima richiesta senza autenticazione, analizzerà il 402 Payment Required, chiamerà il gestore dei pagamenti e ripeterà questi passaggi con PAYMENT-SIGNATURE. Devi solo preparare un wallet con USDC e scegliere la rete che desideri utilizzare. Se desideri che la tua API supporti anche i pagamenti X402, dovrai leggere la documentazione del Facilitator e comprendere la relazione tra paymentRequirements, paymentPayload, /verify e /settle.

​
Stato di supporto

Ace Data Cloud X402 ha completato la verifica su API pubbliche, SDK ufficiali, Facilitator e percorsi di regolamento on-chain. La tabella seguente riassume lo stato attuale secondo le dimensioni delle capacità più comunemente utilizzate dagli sviluppatori durante l’integrazione. Le seguenti uscite sono solo per illustrare la forma di ritorno dei percorsi verificati. Durante l’integrazione reale, fare sempre riferimento ai accepts restituiti dall’API corrente.
Nota:
  • I pacchetti npm e PyPI sono stati installati e importati con successo in un ambiente pulito.
  • La richiesta API non pagata restituisce 402, accetta include i metodi di pagamento disponibili per Base, SKALE e Solana.
  • accepts[].network è un identificatore CAIP-2, il client deve abbinare la rete secondo la stringa CAIP-2.
  • Sia il TypeScript SDK che il Python SDK possono gestire automaticamente il 402 e completare il pagamento retry.
  • Gli indirizzi dell’esploratore per Base exact, SKALE exact, Base upto e pagamento dell’ordine sono tutti pubblicamente accessibili.
  • Il limite di firma per Base upto è di 95215 atomic USDC, il regolamento effettivo è di 3 atomic USDC, riflettendo la caratteristica di regolamento posteriore basata sul consumo reale.
  • Solana exact ha verificato HTTP 402 -> HTTP 200 e l’output del modello. Poiché le query RPC pubbliche possono essere limitate, si consiglia di utilizzare un proprio RPC Solana o registri di regolamento della piattaforma per confermare la firma della transazione.

​
Considerazioni per l’integrazione

Quando gli sviluppatori si integrano, si prega di prestare attenzione ai requisiti di pagamento in tempo reale restituiti dalla richiesta attuale, piuttosto che copiare gli importi o gli indirizzi di esempio nel documento:
  • accepts[].maxAmountRequired è l’importo massimo che può essere firmato per la richiesta attuale.
  • accepts[].asset è il contratto o mint USDC da utilizzare per questa richiesta.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress e accepts[].extra.verifyingContract parteciperanno alla firma dei dati tipizzati EVM.
  • upto richiede che il portafoglio autorizzi prima il USDC della catena di destinazione tramite Permit2; se non autorizzato, restituirà PERMIT2_ALLOWANCE_REQUIRED.
  • Se si desidera esplicitamente utilizzare il calcolo posteriore, si prega di passare preferScheme: 'upto' nel TypeScript SDK, altrimenti il SDK selezionerà il primo requisito disponibile restituito dal server per quella rete.

​
Ambito di verifica pubblica

Prima di integrarsi, è possibile verificare questi ingressi pubblici e il comportamento del SDK:
  • Le richieste API senza Authorization o PAYMENT-SIGNATURE restituiranno 402 Payment Required, e accepts nella risposta è l’unica base per la firma di questa richiesta.
  • Sia il TypeScript SDK che il Python SDK forniscono un gestore di pagamento, il livello di trasporto del SDK, dopo aver ricevuto il 402, chiamerà il gestore e riproverà una volta.
  • https://facilitator.acedata.cloud/.well-known/x402: restituisce le reti, gli schemi e i punti finali del protocollo supportati dal Facilitator; il prezzo API rimane basato sul 402 restituito in tempo reale dalla richiesta di destinazione.
  • https://facilitator.acedata.cloud/supported: restituisce le reti e gli schemi supportati dal Facilitator.
  • Il repository X402Client include strumenti avanzati di verifica on-chain, utilizzabili per confermare firme, retry e comportamenti di regolamento; l’output degli strumenti non sostituisce l’accepts restituito dall’API online.
upto appartiene al regolamento di calcolo posteriore, adatto per API come completamento di chat, chiamate a modelli e altre quantità reali che si conoscono solo dopo la risposta. Attualmente solo Base offre upto; se la verifica della firma fallisce, si prega di controllare se l’id della catena, l’indirizzo del facilitatori, lo spender, il contratto USDC e l’autorizzazione Permit2 corrispondono alla risposta 402.