Vai al contenuto principale
Oltre a pagare direttamente per le richieste API, Ace Data Cloud supporta anche il pagamento degli ordini della console tramite X402. Il protocollo principale per il pagamento degli ordini e le chiamate API è lo stesso: la prima richiesta restituisce 402, il client firma PAYMENT-SIGNATURE, quindi ritenta con la stessa richiesta. La differenza è che il pagamento degli ordini appartiene alle API della piattaforma e richiede un token dell’account; mentre la chiamata diretta alle API AI di x402.acedata.cloud può usare solo X402, senza richiedere un API Token.

Preparare l’ordine

Accedi alla console Ace Data Cloud, seleziona l’ordine da pagare e annota l’ID dell’ordine. Se non hai ancora un ordine, puoi creare un ordine in attesa di pagamento nella pagina dei pacchetti. Il prezzo dell’ordine fa fede a quello mostrato nella pagina, mentre l’amount nella risposta X402 402 è la base finale per la firma.

Creare un token dell’account

La richiesta di pagamento dell’ordine richiede un token dell’account. Apri la pagina Token della piattaforma e crea un token nel formato platform-v1-.... Le richieste successive utilizzano:
Il token dell’account è diverso dal normale API Token. Il normale API Token viene utilizzato per consumare il credito API; il token dell’account viene utilizzato per operare sulle risorse della piattaforma per conto del tuo account, ad esempio per il pagamento degli ordini.

Attivare 402

Invia prima una richiesta senza PAYMENT-SIGNATURE:
Lo stato restituito è 402 e la risposta include accepts:
Il pagamento degli ordini utilizza l’ufficiale x402 v2: x402Version è 2, network utilizza l’identificatore CAIP-2 e il campo dell’importo è amount. Risultato dell’esecuzione del programma che crea un ordine da 10 Credits e attiva 402:
I seguenti record di transazione sono campioni storici testati effettivamente nell’ambito della vecchia politica; l’importo e l’hash della transazione sono mantenuti invariati. I nuovi ordini X402 non offrono più sconti sul metodo di pagamento; utilizza l’amount della risposta 402 corrente come base per la firma e il pagamento.
Spiegazione del risultato:
  • Dopo che l’ordine è stato creato correttamente, lo stato è Pending; in questo momento non è ancora presente alcun pagamento on-chain.
  • La prima richiesta pay/ non includeva PAYMENT-SIGNATURE, quindi restituisce HTTP 402.
  • accepts fornisce contemporaneamente Base exact e Solana exact; questo tutorial seleziona successivamente Base.
  • Il prezzo al momento della creazione dell’ordine era 1.26; durante la vecchia politica di sconto per il pagamento X402, l’importo effettivo della firma e del regolamento era 1.2 USDC, corrispondente a 1200000 atomic USDC.
Nota che qui resource è un campo restituito dal server e che partecipa alla firma; il client non deve riscrivere autonomamente il protocollo, il percorso o l’ID dell’ordine al suo interno.

Firmare e ritentare

Il pagamento dell’ordine può riutilizzare le funzioni di firma di basso livello di @acedatacloud/x402-client o acedatacloud-x402. Di seguito è riportato un esempio TypeScript:
Risultato dell’esecuzione del programma dopo aver firmato e ritentato lo stesso ordine con Base exact:
Risultato della conferma on-chain:
Spiegazione del risultato:
  • status 200 indica che l’interfaccia di pagamento dell’ordine della piattaforma ha accettato questa PAYMENT-SIGNATURE.
  • has_x_payment_response True indica che l’intestazione della risposta contiene la ricevuta PAYMENT-RESPONSE codificata in Base64.
  • settle_header.success=True e network=base indicano che il Facilitator ha completato il settlement su Base.
  • Lo stato finale dell’ordine è Finished, pay_way è X402 e pay_id contiene l’hash della transazione on-chain.
  • L’evento Transfer su BaseScan mostra che l’indirizzo di pagamento ha trasferito 1200000 USDC atomic all’indirizzo di incasso della piattaforma, ovvero 1.2 USDC.

Risposta di successo e ricevuta

Dopo che il pagamento dell’ordine è andato a buon fine, il corpo della risposta contiene le informazioni dell’ordine. La piattaforma trasporta inoltre nell’intestazione della risposta PAYMENT-RESPONSE la settlement response codificata in Base64; dopo la decodifica, i campi comuni includono: Se hai bisogno di riconciliare i conti, si consiglia di salvare contemporaneamente l’ID dell’ordine, l’indirizzo del wallet pagatore, transaction e lo stato finale dell’ordine.

Note

  • Il pagamento dell’ordine richiede il token dell’account della piattaforma e non può essere completato solo con la firma del wallet X402.
  • amount utilizza USDC atomic units; 1200000 indica 1.2 USDC.
  • Non comporre autonomamente l’indirizzo di incasso o l’indirizzo dell’asset; fare riferimento a accepts nella risposta 402.
  • Se la stessa PAYMENT-SIGNATURE viene inviata ripetutamente, il Facilitator applicherà la protezione dal replay in base al nonce.

Risposta di pagamento non riuscito

Il primo HTTP 402 senza PAYMENT-SIGNATURE è una normale richiesta di pagamento e non indica un fallimento del pagamento. Gli errori di verifica o settlement dopo la firma mantengono comunque la stringa standard error come fallback di compatibilità e restituiscono una struttura di errore stabile in extensions.acedatacloud.paymentError:
Il client dovrebbe dare priorità alla localizzazione in base a code; i code sconosciuti devono ricadere nel generico fallimento del pagamento. charged è un campo a tre stati: solo quando il pagamento viene esplicitamente rifiutato prima del settlement viene restituito false; l’assenza del campo indica che lo stato dell’addebito è sconosciuto e non può essere interpretata come “nessun addebito”. Dopo che l’ordine corrente entra in Failed, non può essere ritentato sullo stesso ordine; crea un nuovo ordine dopo aver corretto il problema del wallet. metadata.x402.last_error e metadata.x402.errors nell’elenco e nei dettagli degli ordini mantengono lo stesso insieme di code, stage, retryable, charged e params; il testo descrittivo pubblico è memorizzato in reason e l’ora in cui si è verificato è memorizzata in timestamp. Ad esempio, insufficient_token_balance indica che il saldo USDC sulla rete selezionata è insufficiente, mentre invalid_signature indica che la firma di pagamento non è valida; rileggere l’ordine non li trasformerà nel generico payment_failed. Non registrare né inviare la PAYMENT-SIGNATURE completa, la firma del wallet, il payload di autorizzazione, le diagnosi originali del Facilitator o le risposte RPC. Per la verifica da parte dell’assistenza clienti sono necessari solo l’ID dell’ordine e il code di errore pubblico.

Riacquisto e burn di ACE per pagamenti Base e Solana

Dopo l’abilitazione della strategia di riacquisto, il 3% degli importi effettivamente ricevuti in Circle USDC sulla mainnet Base e USDC sulla mainnet Solana idonei viene utilizzato per acquistare e distruggere ACE, senza addebiti aggiuntivi al wallet pagatore. L’accantonamento viene effettuato una sola volta al momento della ricarica; l’utilizzo successivo di questi Credits per chiamare l’API non comporta un nuovo accantonamento; gli ordini storici scontati e gli ordini con vecchie strategie non ricevono automaticamente accantonamenti retroattivi. I pagamenti Base mantengono la ricevuta di pagamento sulla chain Base, mentre l’acquisto e la distruzione di ACE vengono eseguiti in modo asincrono su Solana. Per i pagamenti idonei viene accantonato esattamente il 3% dell’importo effettivamente ricevuto, senza limiti fissi di riacquisto per singola transazione o giornalieri; i fondi disponibili, le quotazioni di mercato e le conferme on-chain possono comunque influire sul tempo di completamento. L’oggetto ace_burn nei dettagli dell’ordine fornisce settlement_network, settlement_transaction e execution_network, e dopo il completamento fornisce swap_signature e burn_signature. Pending o Processing non indicano che il burn sia stato effettuato; solo Completed rappresenta che la prova finale on-chain è stata verificata. Quando il pagamento Base non ha ancora raggiunto la conferma finale, il riacquisto attenderà la conferma, ma ciò non influisce sui Credits già accreditati.