Vai al contenuto principale
X402 coinvolge HTTP, SDK, firme, Facilitator e transazioni on-chain. Durante la risoluzione di problemi di firma o settlement, si consiglia di confermare livello per livello nell’ordine “ingresso pubblico -> risposta 402 -> SDK payment handler -> settlement on-chain”. Questo tutorial descrive come controllare ogni livello ed elenca gli errori comuni.

Controllare l’ingresso pubblico

Dichiarazione delle capacità del Facilitator:
Se restituisce facilitator, supportedKinds e gli endpoint del protocollo, i metadati delle capacità sono normali. La scoperta delle risorse API è stata ritirata; chiamare direttamente l’API di destinazione e fare riferimento alla risposta 402 in tempo reale. Capacità supportate dal Facilitator:
Se restituisce kinds, l’ingresso del Facilitator è normale.

Controllare accepts di 402

Inviare una richiesta non autenticata che non comporta addebiti:
Controllare se accepts nella risposta contiene la rete che si desidera utilizzare. network è un identificatore CAIP-2:
  • eip155:8453 + exact (Base)
  • eip155:8453 + upto (Base, misurazione post-utilizzo)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact (Solana)
Se la rete di destinazione non è presente, significa che questa API o l’ambiente corrente non ha configurato il corrispondente metodo di pagamento X402.

Eseguire gli strumenti di verifica avanzata di X402Client

Il repository X402Client fornisce strumenti di verifica avanzata, utilizzabili per confermare la selezione della risposta 402, la generazione della firma, il paid retry e il settlement on-chain. Richiedono funded wallet, RPC, chiavi private e dipendenze di sviluppo. Per le normali integrazioni aziendali, si consiglia di utilizzare prioritariamente l’SDK TypeScript o Python; eseguire questi strumenti solo quando è necessario individuare problemi di firma o settlement on-chain. Indirizzo del repository: https://github.com/AceDataCloud/X402Client
Base:
Solana:
Gli strumenti di verifica di solito stampano:
  1. La risposta 402 della prima richiesta.
  2. Il payment requirement selezionato.
  3. Il riepilogo del PAYMENT-SIGNATURE dopo la firma.
  4. Lo stato HTTP e il corpo della risposta dopo il retry.
  5. La settlement transaction on-chain, oppure il motivo dell’errore del Facilitator in caso di fallimento.
Non inviare chiavi private o PAYMENT-SIGNATURE completi ai sistemi di log o nei ticket. Esempio di risultati di verifica dell’API pubblica:
Note:
  • Base exact, Solana exact e Base upto hanno tutti completato il paid retry da HTTP 402 a HTTP 200.
  • La transazione on-chain di Base exact è consultabile su BaseScan e l’importo del settlement è 95215 atomic USDC.
  • Il limite firmato di Base upto è 95215 atomic USDC, ma il settlement on-chain effettivo è 3 atomic USDC, indicando che la misurazione post-utilizzo addebita in base all’utilizzo reale.
  • Il percorso Solana ha confermato il paid retry e l’output del modello. L’RPC pubblico potrebbe essere soggetto a rate limit; quando è necessaria una rigorosa riconciliazione on-chain, utilizzare il proprio RPC Solana o i record di settlement lato piattaforma per confermare la firma della transazione.

SDK smoke test

Gli strumenti di verifica avanzata vengono utilizzati per controllare firme e settlement on-chain. Il lato aziendale deve inoltre eseguire uno SDK smoke test per confermare che il codice dell’applicazione possa gestire automaticamente il 402 tramite il payment handler. Di seguito vengono mostrati solo i frammenti principali; il codice completo deve integrare wallet, provider e import. TypeScript:
Python:
Se il modello restituisce la stringa fissa come richiesto, significa che SDK, payment handler, Gateway, Facilitator e API di destinazione sono collegati. I due smoke test sopra utilizzano Base exact e regolano l’importo fisso quotato dal 402. Il completamento della chat è uno scenario misurato in base ai token; nell’integrazione formale si consiglia di passare preferScheme: 'upto' (in Python prefer_scheme="upto"), per regolare in base all’utilizzo reale. L’oggetto restituito dall’SDK Python è un dict; è possibile utilizzare res["choices"][0]["message"]["content"] per leggere il contenuto.

E2E del pagamento dell’ordine

Il pagamento dell’ordine utilizza l’API della piattaforma di platform.acedata.cloud e richiede un token dell’account della piattaforma. Il flusso completo è: creare un ordine Pending, POST /api/v1/orders/{order_id}/pay/ attiva il 402, quindi eseguire un retry con PAYMENT-SIGNATURE. Esempio di risultati di verifica per il pagamento di un piccolo ordine:
I seguenti record di transazione sono campioni di test storici secondo la vecchia politica; gli importi e gli hash delle transazioni sono mantenuti invariati. I nuovi ordini X402 non offrono più sconti sul metodo di pagamento; utilizzare l’amount nella risposta 402 corrente come base per la firma e il pagamento.
Spiegazione dei risultati:
  • Dopo la creazione dell’ordine, lo stato dell’ordine è Pending e il prezzo è 1.26.
  • La prima richiesta pay/ restituisce HTTP 402; in accepts sono presenti Base exact e Solana exact, con importi entrambi pari a 1200000 atomic USDC.
  • Dopo aver riprovato con la PAYMENT-SIGNATURE di Base, viene restituito HTTP 200, lo stato dell’ordine diventa Finished e pay_way è X402.
  • Dopo la decodifica di PAYMENT-RESPONSE, vengono mostrati success=True, network=base e lo stesso hash della transazione.
  • Su BaseScan, lo stato della transazione è 1, l’importo del trasferimento è 1200000 atomic USDC, ovvero 1.2 USDC.
  • Il prezzo di creazione 1.26 è stato pagato durante il periodo della vecchia politica di sconto dei pagamenti X402; l’importo finale della firma e del regolamento è 1.2 USDC.
Se il pagamento dell’ordine non include Authorization: Bearer {platform_token}, oppure se l’ordine non appartiene all’account corrente, fallirà al livello dei permessi della piattaforma; questo è diverso dall’API X402 senza account chiamata direttamente su x402.acedata.cloud.

Errori comuni

Checklist di controllo Base upto

upto è attualmente disponibile solo su Base (eip155:8453). Poiché la firma upto vincola più parametri EVM typed data, durante l’integrazione occorre confermare in particolare che i campi in tempo reale della risposta 402 coincidano completamente con la firma del client.
Se Base upto restituisce invalid_upto_evm_payload_invalid_signature, controllare prioritariamente:
  1. extra.chainId (deve essere 8453) nell’elemento eip155:8453 + upto restituito dall’API.
  2. extra.facilitatorAddress restituito dall’API.
  3. L’indirizzo del facilitator Base upto restituito da https://facilitator.acedata.cloud/supported.
  4. Il dominio Permit2, spender, contratto USDC e account di firma.
  5. Se il wallet ha già approvato Permit2 per Base USDC.
Il digest della firma di upto vincola contemporaneamente il dominio Permit2, chain ID, spender, indirizzo del destinatario, indirizzo del facilitator e validAfter. Se uno qualsiasi di essi non coincide, il Facilitator recupererà un signer errato, restituendo quindi invalid signature. Se tutti coincidono ma viene comunque restituito 402, controllare successivamente la allowance Permit2; in assenza di autorizzazione viene restituito PERMIT2_ALLOWANCE_REQUIRED.

Salvare le informazioni di verifica

Per una verifica completa, salvare almeno:
  • Il path API e il riepilogo del corpo della richiesta;
  • Il network e lo scheme selezionati;
  • maxAmountRequired;
  • L’indirizzo del wallet payer;
  • Lo stato HTTP finale;
  • L’output del modello o l’ID del task nella risposta;
  • Il link della transazione di settlement;
  • Il Gateway trace ID o l’ID del record di utilizzo della piattaforma.
Non salvare chiavi private, PAYMENT-SIGNATURE completa, signature EIP-712 completa o frase mnemonica.

Errori di pagamento strutturati

I fallimenti X402 dopo la firma restituiscono in extensions.acedatacloud.paymentError un code stabile, parametri di interpolazione sicuri, fase e indicatore di ripetibilità. Per la diagnosi, usare prioritariamente questa struttura; non analizzare l’error inglese di primo livello e non richiedere agli utenti la firma del wallet o il testo originale della simulazione on-chain.
  • charged: false: la verifica è stata esplicitamente rifiutata prima del settlement; in questa occasione non è stato avviato alcun addebito.
  • Senza charged: il risultato è sconosciuto oppure è già entrato nella fase di settlement; controllare prima l’ordine e lo stato on-chain, ed è vietato ripetere direttamente il pagamento.
  • settlement_pending: non ripetere per ora il pagamento; aggiornare prima l’ordine o contattare il supporto.
  • Code non riconosciuto: trattare come payment_failed e conservare il codice tecnico pubblico per la ricerca da parte del servizio clienti.