Vai al contenuto principale
Il Facilitator è il componente di regolamento lato server nel flusso X402. Il client è responsabile della firma, mentre il Gateway o il tuo server è responsabile della chiamata a /verify e /settle del Facilitator. L’indirizzo del Facilitator di produzione di Ace Data Cloud è:
Repository del codice sorgente: https://github.com/AceDataCloud/FacilitatorX402

Convenzioni wire v2

Il flusso X402 di Ace Data Cloud utilizza interamente l’x402 v2 ufficiale e non accetta più l’header di richiesta X-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’oggetto accepted per dichiarare lo scheme e il network selezionati questa volta.
  • Il network utilizza l’identificatore CAIP-2 (ad esempio eip155:8453), e non può essere scritto con abbreviazioni come base.
Struttura dell’envelope:
Oltre al body JSON, la risposta 402 include anche un header di risposta 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:
Esempio di risposta:
Spiegazione dei risultati:
  • Il network utilizza l’identificatore CAIP-2, non abbreviazioni come base o solana.
  • /supported indica che il Facilitator possiede le capacità di verifica e regolamento corrispondenti.
  • Sia Base sia Solana supportano exact; upto è attualmente fornito solo su Base.
  • I signers sono gli indirizzi utilizzati dal Facilitator per inviare le transazioni di regolamento.
  • Se una specifica API consente queste opzioni dipende comunque dagli accepts della 402 di tale API.

POST /verify

Verifica se il PAYMENT-SIGNATURE inviato dal client soddisfa un determinato payment requirement. Body della richiesta:
I campi 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:
Dopo la decodifica, l’header di risposta 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:
Spiegazione dei risultati:
  • success=True indica che il settlement del Facilitator è riuscito.
  • transaction è l’hash della transazione on-chain, e anche il pay_id dell’ordine viene scritto con lo stesso valore.
  • Nell’explorer è possibile vedere il trasferimento di 1200000 atomic USDC su Base.
  • errorReason=None indica che questo settlement non ha restituito errori di business.
Anche la verifica fallita restituisce solitamente HTTP 200, ma 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:
Se l’importo effettivo di 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:
  1. Il client richiede l’API per la prima volta, senza Authorization e PAYMENT-SIGNATURE.
  2. Il Gateway calcola il prezzo stimato della richiesta e restituisce 402 e accepts.
  3. Dopo la firma, il client riprova con PAYMENT-SIGNATURE.
  4. Il Gateway decodifica PAYMENT-SIGNATURE e seleziona il payment requirement corrispondente.
  5. Il Gateway chiama il Facilitator /verify.
  6. Dopo il successo di /verify, il Gateway consente il passaggio della richiesta all’API di destinazione.
  7. Dopo la risposta dell’API di destinazione, il Gateway chiama il Facilitator /settle nella fase /record.
  8. 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:
  1. Preparare paymentRequirements per ogni interfaccia a pagamento, includendo rete, importo, indirizzo del destinatario, indirizzo dell’asset e domain della firma.
  2. Se la richiesta non contiene PAYMENT-SIGNATURE, restituire HTTP 402 e accepts.
  3. Se la richiesta contiene PAYMENT-SIGNATURE, decodificare Base64 per ottenere paymentPayload.
  4. Chiamare il Facilitator /verify.
  5. Dopo una verifica riuscita, eseguire la logica di business.
  6. Dopo il successo della logica di business, chiamare il Facilitator /settle.
  7. Salvare payer, transaction, amount, network per la riconciliazione.
Il server deve usare i propri 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 /settle ha già inviato la transazione ma non ha temporaneamente ricevuto conferma, è possibile riprovare /settle con lo stesso nonce per una riconciliazione idempotente;
  • Non memorizzare nella cache lo stesso PAYMENT-SIGNATURE per poi usarlo in più chiamate API.

Errori comuni