Hoppa till huvudinnehåll
Facilitator är serverns avvecklingskomponent i X402-kedjan. Klienten ansvarar för signering, och Gateway eller din server ansvarar för att anropa Facilitators /verify och /settle. Ace Data Clouds Facilitator-adress för produktion är:
Källkodsrepo: https://github.com/AceDataCloud/FacilitatorX402

v2 wire-konventioner

Ace Data Clouds X402-kedja använder nu helt och hållet den officiella x402 v2 och accepterar inte längre X-Payment-begärandehuvudet från v1. Tre saker att notera vid integrering:
  • Begärandehuvudet är PAYMENT-SIGNATURE, och värdet är ett base64-kodat JSON envelope.
  • Envelope på toppnivå måste vara x402Version: 2 och använda objektet accepted för att deklarera det valda scheme och network för detta tillfälle.
  • network använder CAIP-2-identifierare (såsom eip155:8453) och får inte skrivas som förkortningar såsom base.
Envelope-struktur:
Utöver JSON body kommer 402-svaret även att innehålla ett PAYMENT-REQUIRED-svarshuvud, vars värde är base64-kodningen av samma challenge-innehåll, så att klienten kan läsa betalningskraven utan att parsa body.

Kärn-API:er

GET /supported

Visa nätverk och scheme som stöds:
Exempel på svar:
Förklaring av resultatet:
  • network använder CAIP-2-identifierare, inte förkortningar såsom base eller solana.
  • /supported innebär att Facilitator har motsvarande verifierings- och avvecklingskapacitet.
  • Både Base och Solana stöder exact; upto erbjuds för närvarande endast på Base.
  • signers är de adresser som Facilitator använder för att skicka avvecklingstransaktioner.
  • Huruvida ett specifikt API tillåter dessa alternativ avgörs fortfarande av API:ets 402 accepts.

POST /verify

Verifiera om klientens PAYMENT-SIGNATURE uppfyller ett visst payment requirement. Begärandetext:
Fälten i v2 paymentRequirements är scheme, network, asset, amount, payTo, maxTimeoutSeconds och extra, och beloppsfältet är amount. accepts[] i API:ets 402-svar returnerar även maxAmountRequired för att klienten ska kunna läsa det övre gränsvärdet, men det tillhör inte fälten i Facilitators begärandetext. Svar vid framgång:
Efter avkodning innehåller svarshuvudet PAYMENT-RESPONSE för betalning av produktionsordrar settlement-resultatet. Programmets körningsresultat för betalning av Base-ordern:
Förklaring av resultatet:
  • success=True innebär att Facilitator settlement lyckades.
  • transaction är transaktionshashen på kedjan, och orderns pay_id skrivs också till samma värde.
  • I explorer kan du se Base USDC-överföringen på 1200000 atomic USDC.
  • errorReason=None innebär att denna settlement inte returnerade något affärsfel.
Verifieringsfel returnerar vanligtvis också HTTP 200, men isValid är false. Affärssidan bör läsa invalidReason i stället för att endast titta på HTTP-statuskoden.

POST /settle

Avveckla en redan verifierad auktorisering på kedjan. Begärandetexten är i princip densamma som för /verify. Skillnaden för upto är: paymentRequirements.amount skrivs om till det faktiska avvecklingsbeloppet vid settle; signeringsgränsen registreras av Facilitator i verify-steget, och vid settle kontrolleras att det faktiska beloppet inte överstiger denna gräns. Svar vid framgång:
Om det faktiska beloppet för upto är 0 kan transaction vara en tom sträng, vilket innebär att ingen transaktion på kedjan behöver skickas.

Hur Ace Data Cloud Gateway använder Facilitator

Flödet för Ace Data Cloud API Gateway är följande:
  1. Klienten begär API:et för första gången utan Authorization och PAYMENT-SIGNATURE.
  2. Gateway beräknar det uppskattade priset för begäran och returnerar 402 och accepts.
  3. Klienten signerar och försöker igen med PAYMENT-SIGNATURE.
  4. Gateway avkodar PAYMENT-SIGNATURE och väljer ett matchande payment requirement.
  5. Gateway anropar Facilitator /verify.
  6. Efter att /verify har lyckats släpper Gateway igenom begäran till mål-API:et.
  7. Efter att mål-API:et har returnerat anropar Gateway Facilitator /settle i /record-steget.
  8. Gateway skriver transaktionshashen på kedjan till användningspostens metadata.
exact avvecklar det signerade beloppet i steg 7; upto skriver in amount baserat på den faktiska användningen i steg 7 och avvecklar sedan det faktiska beloppet.

Hur du integrerar ditt eget API

Om du vill att ditt eget API ska stödja X402 kan du implementera det enligt denna struktur:
  1. Förbered paymentRequirements för varje betalt gränssnitt, inklusive nätverk, belopp, mottagaradress, tillgångsadress och signatur domain.
  2. Om begäran saknar PAYMENT-SIGNATURE, returnera HTTP 402 och accepts.
  3. Om begäran har PAYMENT-SIGNATURE, Base64-avkoda den för att få paymentPayload.
  4. Anropa Facilitator /verify.
  5. Kör affärslogiken efter lyckad verifiering.
  6. Anropa Facilitator /settle efter att affärslogiken har lyckats.
  7. Spara payer, transaction, amount, network för avstämning.
Servern måste använda sina egen-genererade paymentRequirements för att anropa /verify och /settle, lita inte på beloppet, mottagaradressen eller tillgångsadressen som klienten skickar tillbaka.

Skydd mot återspelning

Facilitator registrerar nonce. Auktoriseringar med samma nonce kan inte verifieras och avräknas upprepade gånger. Detta innebär:
  • Klienten bör signera ett nytt envelope vid varje begäran;
  • Om /settle redan har skickat in transaktionen men ännu inte har bekräftats, kan du försöka igen med samma nonce för /settle för idempotent avstämning;
  • Cacha inte samma PAYMENT-SIGNATURE för användning vid flera API-anrop.

Vanliga fel