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 formatoplatform-v1-....
Le richieste successive utilizzano:
Attivare 402
Invia prima una richiesta senzaPAYMENT-SIGNATURE:
accepts:
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.
- 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 includevaPAYMENT-SIGNATURE, quindi restituisce HTTP 402. acceptsfornisce contemporaneamente Baseexacte Solanaexact; 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 era1.2USDC, corrispondente a1200000atomic USDC.
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:
exact:
status 200indica che l’interfaccia di pagamento dell’ordine della piattaforma ha accettato questaPAYMENT-SIGNATURE.has_x_payment_response Trueindica che l’intestazione della risposta contiene la ricevutaPAYMENT-RESPONSEcodificata in Base64.settle_header.success=Trueenetwork=baseindicano che il Facilitator ha completato il settlement su Base.- Lo stato finale dell’ordine è
Finished,pay_wayèX402epay_idcontiene l’hash della transazione on-chain. - L’evento
Transfersu BaseScan mostra che l’indirizzo di pagamento ha trasferito1200000USDC atomic all’indirizzo di incasso della piattaforma, ovvero1.2USDC.
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 rispostaPAYMENT-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.
amountutilizza USDC atomic units;1200000indica1.2USDC.- Non comporre autonomamente l’indirizzo di incasso o l’indirizzo dell’asset; fare riferimento a
acceptsnella risposta 402. - Se la stessa
PAYMENT-SIGNATUREviene inviata ripetutamente, il Facilitator applicherà la protezione dal replay in base al nonce.
Risposta di pagamento non riuscito
Il primo HTTP 402 senzaPAYMENT-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:
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’oggettoace_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.
