Vai al contenuto principale
Questo tutorial utilizza una richiesta API minima per illustrare il flusso completo di Ace Data Cloud X402. L’obiettivo non è scrivere subito codice complesso, ma capire prima: perché la prima richiesta restituisce 402, cosa contiene accepts e come PAYMENT-SIGNATURE trasforma la stessa richiesta API in una richiesta già pagata.

Preparazione

Devi preparare: Non è necessario un API Token quando si chiama l’API Ace Data Cloud tramite X402. La prima richiesta dell’SDK non include Authorization, il Gateway restituirà 402 Payment Required e i requisiti di pagamento; l’SDK riprova automaticamente dopo la firma.

Installare l’SDK

Codice sorgente e indirizzi dei pacchetti: TypeScript:
Python:
Se vuoi utilizzare Solana, devi anche installare le dipendenze corrispondenti:
La dipendenza del signer Solana per la versione Python è già inclusa in acedatacloud-x402. Output di installazione e controllo degli import in un ambiente temporaneo pulito:
Spiegazione dei risultati:
  • Sia i pacchetti npm sia i pacchetti PyPI sono pacchetti realmente pubblicati, non nomi segnaposto nella documentazione.
  • acedatacloud-x402[cli] installerà la CLI e il sottocomando approve-permit2 può essere utilizzato per l’autorizzazione Permit2 nello scenario upto.

La prima richiesta restituirà 402

Puoi prima usare curl per vedere cosa restituisce una richiesta non pagata. L’esempio seguente non comporterà alcun addebito, perché non include PAYMENT-SIGNATURE:
Il corpo della risposta includerà l’array accepts, con una struttura comune come segue:
Lo stesso contenuto della challenge viene anche inserito in formato base64 nell’header di risposta PAYMENT-REQUIRED, per consentire al client di leggere i requisiti di pagamento senza analizzare il body. Il riepilogo dell’output del programma per una richiesta non pagata dell’API di produzione è il seguente:
Spiegazione dei risultati:
  • La prima richiesta non include Authorization o PAYMENT-SIGNATURE, quindi restituisce HTTP 402 e non comporta alcun addebito.
  • accepts è l’unica base affidabile per la firma di questa richiesta e contiene le reti opzionali, lo scheme, il limite massimo dell’importo, l’indirizzo del destinatario e l’indirizzo dell’asset.
  • network è un identificatore CAIP-2; il client deve effettuare la corrispondenza in base alla stringa CAIP-2 quando seleziona la rete.
  • Il limite massimo per questa richiesta di chat minima gpt-4o-mini è 95215 atomic USDC, ovvero 0.095215 USDC.
  • Ogni richiesta dovrebbe leggere la risposta 402 corrente; non codificare rigidamente gli importi di esempio nel codice aziendale.
Significato dei campi:

Completare il nuovo tentativo di pagamento con l’SDK

Di seguito è riportato l’esempio TypeScript minimo. Specifica network: 'base'; l’handler selezionerà il payment requirement di Base dalla risposta 402 corrente; l’importo effettivo e l’indirizzo del destinatario restano soggetti a accepts:
Dietro questo codice avvengono quattro passaggi:
  1. L’SDK invia una normale richiesta API, senza Authorization.
  2. Il Gateway restituisce 402 Payment Required e accepts.
  3. createX402PaymentHandler seleziona il payment requirement con network = 'base' e firma PAYMENT-SIGNATURE.
  4. L’SDK ritenta con lo stesso corpo della richiesta, e il Gateway chiama il Facilitator per verificare e regolare prima di consentire l’accesso all’API di destinazione.

Visualizzare le capacità supportate dal Facilitator

L’API X402 non dipende da un catalogo di risorse. Il client chiama direttamente un’API nota e usa 402 Payment Required e accepts, restituiti in tempo reale da quella richiesta, come unica base per il prezzo e la firma. La dichiarazione delle capacità del Facilitator si trova in:
Descrive solo /supported, /verify, /settle e le reti di pagamento attualmente abilitate, senza elencare le risorse API. L’indirizzo del Facilitator di produzione di Ace Data Cloud è:
È possibile vedere quali reti e scheme supporta:
I kinds restituiti elencano le reti e gli scheme supportati dal Facilitator. Durante le chiamate effettive, fare comunque riferimento agli accepts restituiti dall’API. Output di Facilitator /supported:
Il risultato indica:
  • /supported indica che il Facilitator dispone delle capacità di verifica e regolamento per queste reti e scheme.
  • Sia Base sia Solana supportano exact; upto è attualmente disponibile solo su Base.
  • Se una specifica API consente una determinata rete dipende comunque dagli accepts 402 di quell’API.