Integrazione del Facilitator X402

Il Facilitator è il componente di regolamento server-side nel link X402. Il client è responsabile della firma, il Gateway o il tuo server sono responsabili della chiamata ai metodi /verify e /settle del Facilitator. L’indirizzo del Facilitator di produzione di Ace Data Cloud è:

https://facilitator.acedata.cloud

Repository del codice sorgente: https://github.com/AceDataCloud/FacilitatorX402

Convenzioni v2 wire

Il link X402 di Ace Data Cloud utilizza completamente la versione ufficiale x402 v2 e non accetta più l’intestazione X-Payment v1. Durante l’integrazione, è necessario prestare attenzione a tre punti:

L’intestazione della richiesta è PAYMENT-SIGNATURE, il cui valore è un envelope JSON codificato in base64.
Il livello superiore dell’envelope deve essere x402Version: 2 e dichiarare l’oggetto accepted con lo scheme e il network scelti.
Il network utilizza l’identificatore CAIP-2 (ad esempio eip155:8453), non è possibile utilizzare abbreviazioni come base.

Struttura dell’envelope:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453"
  },
  "payload": { "...": "..." }
}

La risposta 402, oltre al corpo JSON, includerà anche un’intestazione di risposta PAYMENT-REQUIRED, il cui valore è la stessa sfida codificata in base64, per facilitare al client la lettura dei requisiti di pagamento senza dover analizzare il corpo.

Interfacce principali

`GET /supported`

Visualizza le reti e gli schemi supportati:

curl https://facilitator.acedata.cloud/supported

Esempio di risposta:

{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:8453" },
    {
      "x402Version": 2,
      "scheme": "upto",
      "network": "eip155:8453",
      "extra": { "facilitatorAddress": "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708" }
    },
    { "x402Version": 2, "scheme": "exact", "network": "eip155:1187947933" },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": { "feePayer": "3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq" }
    }
  ],
  "extensions": [],
  "signers": {
    "eip155:*": [
      "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708",
      "0xd0479FA9FD8C678303d477433d24C15e3723CC1C"
    ],
    "solana:*": ["3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq"]
  }
}

Spiegazione dei risultati:

Il network utilizza l’identificatore CAIP-2, non abbreviazioni come base, skale.
/supported indica che il Facilitator ha le capacità di verifica e regolamento corrispondenti.
Base, SKALE e Solana supportano exact; upto è attualmente disponibile solo su Base.
signers sono gli indirizzi utilizzati dal Facilitator per inviare le transazioni di regolamento.
Se un’API specifica consente queste opzioni, è comunque soggetta a quanto indicato in accepts della risposta 402 di quell’API.

`POST /verify`

Verifica se il PAYMENT-SIGNATURE fornito dal client soddisfa un determinato requisito di pagamento. Corpo della richiesta:

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "exact",
      "network": "eip155:8453"
    },
    "payload": { "...": "..." }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x...",
    "amount": "95215",
    "payTo": "0x...",
    "maxTimeoutSeconds": 3600,
    "extra": { "...": "..." }
  }
}

Il campo paymentRequirements della v2 include scheme, network, asset, amount, payTo, maxTimeoutSeconds e extra, il campo dell’importo è amount. La risposta API 402 includerà anche maxAmountRequired per consentire al client di leggere il limite, ma non fa parte dei campi del corpo della richiesta del Facilitator. Risposta di successo:

{
  "isValid": true,
  "invalidReason": null,
  "payer": "0x..."
}

L’intestazione di risposta PAYMENT-RESPONSE per il pagamento degli ordini di produzione decodificata contiene il risultato del regolamento. Risultato dell’esecuzione del pagamento dell’ordine su Base:

settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151', 'errorReason': None}
order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402 price 1.2
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC

Spiegazione dei risultati:

success=True indica che il regolamento del Facilitator è andato a buon fine.
transaction è l’hash della transazione sulla blockchain, l’pay_id dell’ordine è scritto anche con lo stesso valore.
Su explorer è possibile vedere il trasferimento di 1200000 atomic USDC.
errorReason=None indica che non ci sono stati errori di business in questo regolamento.

Le verifiche fallite restituiscono solitamente anche un HTTP 200, ma isValid sarà false. Il lato business dovrebbe leggere invalidReason, piuttosto che limitarsi a controllare il codice di stato HTTP.

`POST /settle`

Regola l’autorizzazione già verificata sulla blockchain. Il corpo della richiesta è sostanzialmente identico a quello di /verify. La differenza per upto è che: paymentRequirements.amount viene riscritto come l’importo effettivo del regolamento; il limite di firma è registrato dal Facilitator nella fase di verifica, e durante il regolamento si verifica che l’importo effettivo non superi tale limite. Risposta di successo:

{
  "success": true,
  "errorReason": null,
  "transaction": "0x...",
  "network": "eip155:8453",
  "payer": "0x...",
  "amount": "3"
}

Se l’importo effettivo di upto è 0, transaction potrebbe essere una stringa vuota, indicando che non è necessaria alcuna transazione sulla blockchain.

Come utilizzare il Facilitator con Ace Data Cloud Gateway

Il flusso del Gateway API di Ace Data Cloud è il seguente:

Il client effettua la prima richiesta API, senza Authorization e PAYMENT-SIGNATURE.
Il Gateway calcola il prezzo stimato della richiesta, restituendo 402 e accepts.
Dopo la firma, il client riprova con PAYMENT-SIGNATURE.
Il Gateway decodifica PAYMENT-SIGNATURE, selezionando il requisito di pagamento corrispondente.
Il Gateway chiama il Facilitator /verify.
Dopo il successo di /verify, il Gateway consente la richiesta all’API di destinazione.
Dopo la risposta dell’API di destinazione, il Gateway chiama il Facilitator /settle nella fase di /record.
Il Gateway scrive l’hash della transazione sulla blockchain nei metadati della registrazione. exact nella fase 7 per il saldo dell’importo della firma; upto nella fase 7 scrive amount in base all’uso reale, quindi salda l’importo effettivo.

Come integrare la propria API

Se desideri che la tua API supporti X402, puoi implementare questa struttura:

Prepara paymentRequirements per ogni interfaccia a pagamento, includendo rete, importo, indirizzo di ricezione, indirizzo dell’asset e dominio di firma.
Se la richiesta non ha PAYMENT-SIGNATURE, restituisci HTTP 402 e accepts.
Se la richiesta ha PAYMENT-SIGNATURE, decodifica in Base64 per ottenere paymentPayload.
Chiama il Facilitator /verify.
Dopo una verifica riuscita, esegui la logica di business.
Dopo il successo dell’attività, chiama il Facilitator /settle.
Salva payer, transaction, amount, network per la riconciliazione.

Il server deve utilizzare i propri paymentRequirements per chiamare /verify e /settle, non fidarti degli importi, degli indirizzi di ricezione o degli indirizzi degli asset restituiti dal client.

Protezione contro la ripetizione

Il Facilitator registrerà il nonce. Le autorizzazioni con lo stesso nonce non possono essere verificate e saldate nuovamente. Questo significa:

Il client dovrebbe firmare un nuovo envelope ad ogni richiesta;
Se /settle ha inviato una transazione ma non è ancora confermata, puoi riprovare /settle con lo stesso nonce per una riconciliazione idempotente;
Non memorizzare lo stesso PAYMENT-SIGNATURE per utilizzarlo in più chiamate API.

Errori comuni

Errore	Cause comuni
`Authorization nonce already processed`	È stato riutilizzato lo stesso `PAYMENT-SIGNATURE`.
`Authorization destination mismatch`	Il `to` nella firma del client non corrisponde al `payTo` dei requisiti di pagamento.
`invalid_upto_evm_payload_invalid_signature`	Il chainId, facilitator, dominio Permit2 o indirizzo di firma dei dati tipizzati `upto` non corrispondono.
`PERMIT2_ALLOWANCE_REQUIRED`	Il portafoglio non ha ancora approvato un’adeguata allowance di USDC per Permit2.
`Payer has insufficient USDC balance`	Il portafoglio di pagamento ha un saldo USDC insufficiente.
`Solana signer private key not configured`	Il Facilitator deve firmare come fee payer, ma il server manca della configurazione del firmatario Solana.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Integrazione del Facilitator X402

Convenzioni v2 wire

Interfacce principali

`GET /supported`

`POST /verify`

`POST /settle`

Come utilizzare il Facilitator con Ace Data Cloud Gateway

Come integrare la propria API

Protezione contro la ripetizione

Errori comuni

​Convenzioni v2 wire

​Interfacce principali

​GET /supported

​POST /verify

​POST /settle

​Come utilizzare il Facilitator con Ace Data Cloud Gateway

​Come integrare la propria API

​Protezione contro la ripetizione

​Errori comuni

Convenzioni v2 wire

Interfacce principali

`GET /supported`

`POST /verify`

`POST /settle`

Come utilizzare il Facilitator con Ace Data Cloud Gateway

Come integrare la propria API

Protezione contro la ripetizione

Errori comuni