/verify e /settle del Facilitator.
L’indirizzo del Facilitator di produzione di Ace Data Cloud è:
Convenzioni wire v2
Il flusso X402 di Ace Data Cloud utilizza interamente l’x402 v2 ufficiale e non accetta più l’header di richiestaX-Payment della v1. Durante l’integrazione è necessario notare tre punti:
- L’header di richiesta è
PAYMENT-SIGNATURE, e il valore è un JSON envelope codificato in base64. - Il livello superiore dell’envelope deve essere
x402Version: 2, e utilizzare l’oggettoacceptedper dichiarare loschemee ilnetworkselezionati questa volta. - Il
networkutilizza l’identificatore CAIP-2 (ad esempioeip155:8453), e non può essere scritto con abbreviazioni comebase.
PAYMENT-REQUIRED, il cui valore è la codifica base64 dello stesso contenuto della challenge, per consentire al client di leggere i requisiti di pagamento senza analizzare il body.
Interfacce principali
GET /supported
Visualizza le reti e gli scheme supportati:
- Il
networkutilizza l’identificatore CAIP-2, non abbreviazioni comebaseosolana. /supportedindica che il Facilitator possiede le capacità di verifica e regolamento corrispondenti.- Sia Base sia Solana supportano
exact;uptoè attualmente fornito solo su Base. - I
signerssono gli indirizzi utilizzati dal Facilitator per inviare le transazioni di regolamento. - Se una specifica API consente queste opzioni dipende comunque dagli
acceptsdella 402 di tale API.
POST /verify
Verifica se il PAYMENT-SIGNATURE inviato dal client soddisfa un determinato payment requirement.
Body della richiesta:
paymentRequirements della v2 sono scheme, network, asset, amount, payTo, maxTimeoutSeconds ed extra, e il campo dell’importo è amount. Gli accepts[] della risposta 402 dell’API restituiscono inoltre maxAmountRequired affinché il client possa leggere il limite massimo, ma questo non fa parte dei campi del body della richiesta al Facilitator.
Risposta di successo:
PAYMENT-RESPONSE del pagamento degli ordini di produzione contiene il risultato del settlement. Il risultato dell’esecuzione del programma per il pagamento di un ordine Base:
success=Trueindica che il settlement del Facilitator è riuscito.transactionè l’hash della transazione on-chain, e anche ilpay_iddell’ordine viene scritto con lo stesso valore.- Nell’explorer è possibile vedere il trasferimento di
1200000atomic USDC su Base. errorReason=Noneindica che questo settlement non ha restituito errori di business.
isValid è false. Il lato business dovrebbe leggere invalidReason, invece di controllare solo il codice di stato HTTP.
POST /settle
Regola on-chain un’autorizzazione già verificata.
Il body della richiesta è sostanzialmente identico a quello di /verify. La differenza di upto è: paymentRequirements.amount viene riscritto con l’importo effettivo di regolamento durante il settle; il limite della firma viene registrato dal Facilitator nella fase di verify, e durante il settle viene verificato che l’importo effettivo non superi tale limite.
Risposta di successo:
upto è 0, transaction potrebbe essere una stringa vuota, a indicare che non è necessario inviare una transazione on-chain.
Come l’Ace Data Cloud Gateway utilizza il Facilitator
Il flusso dell’API Gateway di Ace Data Cloud è il seguente:- Il client richiede l’API per la prima volta, senza
AuthorizationePAYMENT-SIGNATURE. - Il Gateway calcola il prezzo stimato della richiesta e restituisce 402 e
accepts. - Dopo la firma, il client riprova con
PAYMENT-SIGNATURE. - Il Gateway decodifica
PAYMENT-SIGNATUREe seleziona il payment requirement corrispondente. - Il Gateway chiama il Facilitator
/verify. - Dopo il successo di
/verify, il Gateway consente il passaggio della richiesta all’API di destinazione. - Dopo la risposta dell’API di destinazione, il Gateway chiama il Facilitator
/settlenella fase/record. - Il Gateway scrive l’hash della transazione on-chain nei metadata del record di utilizzo.
exact regola l’importo firmato nel passaggio 7; upto scrive amount in base all’utilizzo reale nel passaggio 7, quindi regola l’importo effettivo.
Come integrare la propria API
Se desideri che la tua API supporti X402, puoi implementarla secondo questa struttura:- Preparare
paymentRequirementsper ogni interfaccia a pagamento, includendo rete, importo, indirizzo del destinatario, indirizzo dell’asset e domain della firma. - Se la richiesta non contiene
PAYMENT-SIGNATURE, restituire HTTP 402 eaccepts. - Se la richiesta contiene
PAYMENT-SIGNATURE, decodificare Base64 per ottenerepaymentPayload. - Chiamare il Facilitator
/verify. - Dopo una verifica riuscita, eseguire la logica di business.
- Dopo il successo della logica di business, chiamare il Facilitator
/settle. - Salvare
payer,transaction,amount,networkper la riconciliazione.
paymentRequirements generati per chiamare /verify e /settle, non fidarsi dell’importo, dell’indirizzo del destinatario o dell’indirizzo dell’asset ritrasmessi dal client.
Protezione dai replay
Il Facilitator registra i nonce. L’autorizzazione con lo stesso nonce non può essere verificata e regolata ripetutamente. Questo significa:- Il client dovrebbe firmare un nuovo envelope per ogni richiesta;
- Se
/settleha già inviato la transazione ma non ha temporaneamente ricevuto conferma, è possibile riprovare/settlecon lo stesso nonce per una riconciliazione idempotente; - Non memorizzare nella cache lo stesso
PAYMENT-SIGNATUREper poi usarlo in più chiamate API.

