> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# X402 Facilitator Integration

> Platform API guide - Ace Data Cloud

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:

```text theme={null}
https://facilitator.acedata.cloud
```

Källkodsförråd: [https://github.com/AceDataCloud/FacilitatorX402](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:

```json theme={null}
{
  "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:

```bash theme={null}
curl https://facilitator.acedata.cloud/supported
```

Exempel på svar:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```text theme={null}
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:

```json theme={null}
{
  "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:

1. Klienten gör första API-begäran 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 en matchande betalningskrav.
5. Gateway anropar Facilitator `/verify`.
6. Efter att `/verify` har lyckats, släpper Gateway begäran till mål-API:t.
7. Efter att mål-API:t har returnerat, anropar Gateway Facilitator `/settle` under `/record`-steget.
8. 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:

1. För varje betalningsgränssnitt förbered `paymentRequirements`, som innehåller nätverk, belopp, mottagaradress, tillgångsadress och signaturdomän.
2. Om begäran inte har `PAYMENT-SIGNATURE`, returnera HTTP 402 och `accepts`.
3. Om begäran har `PAYMENT-SIGNATURE`, avkoda Base64 för att få `paymentPayload`.
4. Anropa Facilitator `/verify`.
5. Vid lyckad verifiering, utför affärslogik.
6. Vid affärssuccé, anropa Facilitator `/settle`.
7. 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.