/verify och /settle.
Ace Data Clouds Facilitator-adress för produktion är:
v2 wire-konventioner
Ace Data Clouds X402-kedja använder nu helt och hållet den officiella x402 v2 och accepterar inte längreX-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: 2och använda objektetacceptedför att deklarera det valdaschemeochnetworkför detta tillfälle. networkanvänder CAIP-2-identifierare (såsomeip155:8453) och får inte skrivas som förkortningar såsombase.
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:
networkanvänder CAIP-2-identifierare, inte förkortningar såsombaseellersolana./supportedinnebär att Facilitator har motsvarande verifierings- och avvecklingskapacitet.- Både Base och Solana stöder
exact;uptoerbjuds 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:
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:
PAYMENT-RESPONSE för betalning av produktionsordrar settlement-resultatet. Programmets körningsresultat för betalning av Base-ordern:
success=Trueinnebär att Facilitator settlement lyckades.transactionär transaktionshashen på kedjan, och ordernspay_idskrivs också till samma värde.- I explorer kan du se Base USDC-överföringen på
1200000atomic USDC. errorReason=Noneinnebär att denna settlement inte returnerade något affärsfel.
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:
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:- Klienten begär API:et för första gången utan
AuthorizationochPAYMENT-SIGNATURE. - Gateway beräknar det uppskattade priset för begäran och returnerar 402 och
accepts. - Klienten signerar och försöker igen med
PAYMENT-SIGNATURE. - Gateway avkodar
PAYMENT-SIGNATUREoch väljer ett matchande payment requirement. - Gateway anropar Facilitator
/verify. - Efter att
/verifyhar lyckats släpper Gateway igenom begäran till mål-API:et. - Efter att mål-API:et har returnerat anropar Gateway Facilitator
/settlei/record-steget. - 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:- Förbered
paymentRequirementsför varje betalt gränssnitt, inklusive nätverk, belopp, mottagaradress, tillgångsadress och signatur domain. - Om begäran saknar
PAYMENT-SIGNATURE, returnera HTTP 402 ochaccepts. - Om begäran har
PAYMENT-SIGNATURE, Base64-avkoda den för att fåpaymentPayload. - Anropa Facilitator
/verify. - Kör affärslogiken efter lyckad verifiering.
- Anropa Facilitator
/settleefter att affärslogiken har lyckats. - Spara
payer,transaction,amount,networkför avstämning.
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
/settleredan har skickat in transaktionen men ännu inte har bekräftats, kan du försöka igen med samma nonce för/settleför idempotent avstämning; - Cacha inte samma
PAYMENT-SIGNATUREför användning vid flera API-anrop.

