X402 Facilitator Integration

https://facilitator.acedata.cloud

​

v2 Wire Vereinbarung

• Der Anforderungsheader ist PAYMENT-SIGNATURE, der Wert ist ein base64-kodiertes JSON-Envelope.
• Die oberste Ebene des Envelopes muss x402Version: 2 sein und das accepted-Objekt muss das gewählte scheme und network deklarieren.
• network verwendet die CAIP-2 Kennung (z. B. eip155:8453), Abkürzungen wie base sind nicht zulässig.

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

​

Kernschnittstellen

​

GET /supported

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

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

• network verwendet die CAIP-2 Kennung, nicht Abkürzungen wie base, skale.
• /supported zeigt an, dass der Facilitator über die entsprechenden Validierungs- und Abrechnungsfähigkeiten verfügt.
• Base, SKALE und Solana unterstützen exact; upto wird derzeit nur auf Base angeboten.
• signers sind die Adressen, die der Facilitator zur Einreichung von Abrechnungstransaktionen verwendet.
• Ob eine bestimmte API diese Optionen zulässt, hängt weiterhin von den accepts der API 402 ab.

​

POST /verify

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

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

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

• success=True zeigt an, dass die Abrechnung des Facilitators erfolgreich war.
• transaction ist der Hash der On-Chain-Transaktion, die pay_id der Bestellung wird ebenfalls in denselben Wert geschrieben.
• Im Explorer kann die Überweisung von 1200000 atomic USDC auf Base USDC eingesehen werden.
• errorReason=None zeigt an, dass bei dieser Abrechnung kein geschäftlicher Fehler zurückgegeben wurde.

​

POST /settle

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

​

Wie Ace Data Cloud Gateway den Facilitator verwendet

1. Der Client fordert zum ersten Mal die API an, ohne Authorization und PAYMENT-SIGNATURE.
2. Gateway berechnet den geschätzten Preis der Anfrage und gibt 402 und accepts zurück.
3. Der Client signiert und versucht es erneut mit PAYMENT-SIGNATURE.
4. Gateway dekodiert PAYMENT-SIGNATURE und wählt die passende Zahlungsanforderung aus.
5. Gateway ruft Facilitator /verify auf.
6. Nach erfolgreichem /verify lässt Gateway die Anfrage an die Ziel-API weiter.
7. Nach der Rückgabe der Ziel-API ruft Gateway in der Phase /record Facilitator /settle auf.
8. Gateway schreibt den On-Chain-Transaktionshash in die verwendete Aufzeichnungsmetadaten. exact in Schritt 7 den Betrag der Signatur abrechnen; upto in Schritt 7 den amount basierend auf dem tatsächlichen Verbrauch schreiben und dann den tatsächlichen Betrag abrechnen.

​

Eigene API-Anbindung

1. Bereite für jede kostenpflichtige Schnittstelle paymentRequirements vor, die Netzwerk, Betrag, Empfangsadresse, Vermögensadresse und Signatur-Domain enthält.
2. Wenn die Anfrage kein PAYMENT-SIGNATURE hat, gib HTTP 402 und accepts zurück.
3. Wenn die Anfrage ein PAYMENT-SIGNATURE hat, dekodiere es in Base64, um paymentPayload zu erhalten.
4. Rufe den Facilitator /verify auf.
5. Führe die Geschäftslogik nach erfolgreicher Validierung aus.
6. Rufe nach erfolgreichem Geschäft den Facilitator /settle auf.
7. Speichere payer, transaction, amount, network zur Abrechnung.

​

Replay-Schutz

• Der Client sollte bei jeder Anfrage ein neues Envelope signieren;
• Wenn /settle eine Transaktion eingereicht hat, aber vorübergehend nicht bestätigt ist, kann /settle mit demselben nonce erneut versucht werden, um eine idempotente Abrechnung durchzuführen;
• Verwende dasselbe PAYMENT-SIGNATURE nicht im Cache für mehrere API-Aufrufe.

​

Häufige Fehler