X402 Facilitator Integration

Facilitator är serverkomponenten för avräkning i X402-länken. Klienten ansvarar för signering, Gateway eller din server ansvarar för att anropa Facilitator’s /verify och /settle. Ace Data Clouds produktionsadress för Facilitator är:

https://facilitator.acedata.cloud

Källkodsförråd: https://github.com/AceDataCloud/FacilitatorX402

v2 wire överenskommelse

Ace Data Clouds X402-länk använder nu officiellt x402 v2 och accepterar inte längre v1:s X-Payment begärningshuvud. Vid anslutning behöver tre punkter beaktas:

Begärningshuvudet är PAYMENT-SIGNATURE, värdet är en base64-kodad JSON envelope.
Envelope-toppnivån måste vara x402Version: 2 och använda accepted-objektet för att deklarera det valda scheme och network.
network använder CAIP-2 identifiering (t.ex. eip155:8453), får inte skrivas som base eller liknande förkortningar.

Envelope-struktur:

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

402-svaret, förutom JSON-kroppen, kommer också att ha ett PAYMENT-REQUIRED svarshuvud, vars värde är en base64-kodning av samma utmaningsinnehåll, vilket underlättar för klienten att läsa betalningskravet utan att behöva analysera kroppen.

Kärninterface

`GET /supported`

Visa stödda nätverk och scheme:

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

Exempel på svar:

{
  "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"]
  }
}

Resultatförklaring:

network använder CAIP-2 identifiering, inte base, skale eller liknande förkortningar.
/supported indikerar att Facilitator har motsvarande verifierings- och avräkningskapacitet.
Base, SKALE och Solana stöder exact; upto erbjuds för närvarande endast på Base.
signers är adresser som Facilitator använder för att skicka avräkningstransaktioner.
Huruvida ett specifikt API tillåter dessa alternativ beror fortfarande på det API:s 402 accepts.

`POST /verify`

Verifiera om den PAYMENT-SIGNATURE som skickats av klienten uppfyller ett visst betalningskrav. Begärningskropp:

{
  "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": { "...": "..." }
  }
}

v2:s paymentRequirements fält är scheme, network, asset, amount, payTo, maxTimeoutSeconds och extra, beloppet anges i fältet amount. API 402-svaret kommer också att returnera maxAmountRequired i accepts[] för att klienten ska kunna läsa gränsen, men det tillhör inte Facilitator-begärningskroppen. Framgångsrikt svar:

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

Betalningssvarshuvudet PAYMENT-RESPONSE för produktionsorder innehåller avräkningsresultatet efter avkodning. Resultatet av betalningen för Base-order:

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

Resultatförklaring:

success=True indikerar att Facilitator-avräkningen lyckades.
transaction är hash för transaktionen på kedjan, orderns pay_id skrivs också med samma värde.
På explorer kan man se en överföring av 1200000 atomic USDC.
errorReason=None indikerar att denna avräkning inte returnerade några affärsfel.

Verifieringsfel returnerar också vanligtvis HTTP 200, men isValid är false. Affärssidan bör läsa invalidReason, snarare än att bara titta på HTTP-statuskoden.

`POST /settle`

Avräkna den redan verifierade auktoriseringen på kedjan. Begärningskroppen är i stort sett densamma som för /verify. Skillnaden för upto är: paymentRequirements.amount skrivs om till det faktiska avräkningsbeloppet; signeringsgränsen registreras av Facilitator under verifieringssteget, och vid avräkning kontrolleras det faktiska beloppet så att det inte överskrider den gränsen. Framgångsrikt svar:

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

Om det faktiska beloppet för upto är 0, kan transaction vara en tom sträng, vilket indikerar att ingen kedjetransaktion behöver göras.

Hur Ace Data Cloud Gateway använder Facilitator

Ace Data Cloud API Gateway:s flöde är som följer:

Klienten gör första API-begäran utan Authorization och PAYMENT-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-SIGNATURE och väljer en matchande betalningskrav.
Gateway anropar Facilitator /verify.
Efter att /verify har lyckats, släpper Gateway begäran till mål-API:t.
Efter att mål-API:t har returnerat, anropar Gateway Facilitator /settle under /record-steget.
Gateway skriver kedjetransaktionshashen i metadata för användningsloggen. exact i steg 7 avräknar signaturbeloppet; upto i steg 7 skriver in amount baserat på verklig användning, och avräknar det faktiska beloppet.

Hur man ansluter sin egen API

Om du vill att din egen API ska stödja X402 kan du implementera enligt denna struktur:

För varje betalningsgränssnitt förbered paymentRequirements, som innehåller nätverk, belopp, mottagaradress, tillgångsadress och signaturdomän.
Om begäran inte har PAYMENT-SIGNATURE, returnera HTTP 402 och accepts.
Om begäran har PAYMENT-SIGNATURE, avkoda Base64 för att få paymentPayload.
Anropa Facilitator /verify.
Vid lyckad verifiering, utför affärslogik.
Vid affärssuccé, anropa Facilitator /settle.
Spara payer, transaction, amount, network för avstämning.

Servern måste använda sina egna genererade paymentRequirements för att anropa /verify och /settle, lita inte på belopp, mottagaradress eller tillgångsadress som skickas tillbaka av klienten.

Återspelningsskydd

Facilitator kommer att registrera nonce. Samma nonce kan inte verifieras och avräknas flera gånger. Detta innebär:

Klienten bör signera en ny envelope varje gång den gör en begäran;
Om /settle har skickat en transaktion men ännu inte bekräftats, kan samma nonce användas för att försöka /settle för idempotent avstämning;
Lagra inte samma PAYMENT-SIGNATURE för att användas vid flera API-anrop.

Vanliga fel

Fel	Vanliga orsaker
`Authorization nonce already processed`	Samma `PAYMENT-SIGNATURE` har använts flera gånger.
`Authorization destination mismatch`	`to` i klientens signatur stämmer inte överens med `payTo` i betalningskravet.
`invalid_upto_evm_payload_invalid_signature`	`upto` typed data:s chainId, facilitator, Permit2-domän eller signaturadress stämmer inte.
`PERMIT2_ALLOWANCE_REQUIRED`	Plånboken har ännu inte godkänt tillräcklig USDC-allowance för Permit2.
`Payer has insufficient USDC balance`	Betalningsplånboken har otillräckligt med USDC.
`Solana signer private key not configured`	Facilitator behöver signera som avgiftsbetalare, men servern saknar Solana signer-konfiguration.

Getting Started

AI Samtal

AI Bild

AI Video

AI Ljud

Web & Data

CAPTCHA

Identitet

Coding

Fler guider

X402 Facilitator Integration

v2 wire överenskommelse

Kärninterface

`GET /supported`

`POST /verify`

`POST /settle`

Hur Ace Data Cloud Gateway använder Facilitator

Hur man ansluter sin egen API

Återspelningsskydd

Vanliga fel

​v2 wire överenskommelse

​Kärninterface

​GET /supported

​POST /verify

​POST /settle

​Hur Ace Data Cloud Gateway använder Facilitator

​Hur man ansluter sin egen API

​Återspelningsskydd

​Vanliga fel

v2 wire överenskommelse

Kärninterface

`GET /supported`

`POST /verify`

`POST /settle`

Hur Ace Data Cloud Gateway använder Facilitator

Hur man ansluter sin egen API

Återspelningsskydd

Vanliga fel