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

# XHuoAPI x402 Zahlungsintegrationsleitfaden

> x402 集成指南 - XHuoAPI

x402 ist ein auf dem HTTP 402 Payment Required Standard basierendes On-Chain-Zahlungsprotokoll, das es dem Aufrufer ermöglicht, die On-Chain-Abrechnung gleichzeitig mit der Initiierung von API-Anfragen durchzuführen. Es eignet sich hervorragend für Abrechnungszenarien zwischen automatisierten Programmen, KI-Agenten und Mikrodiensten. Mit diesem Leitfaden kannst du die Zahlung für XHuoAPI-Bestellungen programmatisch in deinem System durchführen und ein „Anfrage-zu-Zahlung“-Erlebnis realisieren.

Offizielle Referenzdokumente:

* x402 Übersichtsdokument: [https://docs.cdp.coinbase.com/x402/docs/overview](https://docs.cdp.coinbase.com/x402/docs/overview)
* x402 Open-Source-Beispiel: [https://github.com/coinbase/x402](https://github.com/coinbase/x402)

Dieses Dokument richtet sich an Entwickler, die die Zahlungsfähigkeit der XHuoAPI-Plattform x402 in ihr Geschäft integrieren möchten. Es beschreibt den vollständigen Prozess von der Vorbereitung der Umgebung bis zur Durchführung der Zahlungsanfrage und bietet Beispielcodes für Axios, Fetch, Python requests und httpx. Kernpunkte:

* Die Zahlungsabwicklung erfolgt im **Base Mainnet**, die Vermögenswerte verwenden **USDC**;
* Es muss der **EVM Private Key** der Wallet verwendet werden, um den `X-PAYMENT` Signatur-Header zu generieren;
* Alle APIs befinden sich unter der Domain `https://api.xhuoapi.ai`, der `Authorization` Header muss das **Platform Token** enthalten.

***

## I. Vorbereitungen

### 1. Bestellungen einsehen und Zahlungsinformationen aufzeichnen

Melde dich im Dashboard [https://api.xhuoapi.ai](https://api.xhuoapi.ai) an. In der Bestellliste oder auf der Bestelldetailseite kannst du die zu zahlende Bestellung sehen. Die Bestelldetails zeigen:

* Bestell-ID (z. B. `7744945e-5e77-4dcc-a9c4-528692d17b34`);
* Empfangsadresse `pay_to` (wird auch in der 402-Antwort zurückgegeben, es wird empfohlen, sich an die Seiteninformationen zu halten).

Bitte notiere die Bestell-ID und bestätige die `pay_to` Adresse, da diese für die spätere Signatur benötigt wird, um sicherzustellen, dass die Mittel an diese Adresse gesendet werden.

### 2. Zahlungsmittel und -mittel vorbereiten

* Bereite eine EVM-Wallet vor, die das Base Mainnet unterstützt, und exportiere den zu verwendenden Private Key;
* Lade ausreichend **USDC** (Zahlungsbetrag in der kleinsten Einheit mit 6 Dezimalstellen) auf das Base Mainnet;
* Der x402 Facilitator übernimmt die Netzwerkgebühren, die Zahlungsmittel-Wallet muss nur genügend USDC behalten;
* Der Private Key wird nur für lokale Signaturen verwendet, bitte bewahre ihn sicher auf und vermeide es, ihn im Browser oder in unsicheren Umgebungen offenzulegen.

### 3. Platform Token erstellen

Das Platform Token wird verwendet, um die Plattform-APIs aufzurufen, und funktioniert ähnlich wie das Benutzer-Token, das nach der Anmeldung im Browser verwendet wird, läuft jedoch nicht ab. Bitte folge diesen Schritten zur Erstellung:

1. Öffne die Dashboard-Seite [https://api.xhuoapi.ai/console/platform-tokens](https://api.xhuoapi.ai/console/platform-tokens);
2. Klicke auf „Token erstellen“, fülle die Hinweisinformationen gemäß den Anweisungen aus und generiere es;
3. Kopiere das generierte Token (z. B. `platform-v1-xxxx`) und bewahre es sicher als `platform_token` auf.

![platform-token](https://cdn.xhuoapi.ai/6g86oz.png)

Bei allen zukünftigen API-Aufrufen muss der Header Folgendes enthalten:

```
Authorization: Bearer {platform_token}
```

### 4. Grundlegende Informationen anfordern

* API Basis-Domain: `https://api.xhuoapi.ai`
* Zahlungsanforderungspfad: `/api/v1/orders/{order_id}/pay/`
* Anfragen und Antworten verwenden JSON, kodiert in UTF-8.

***

## II. Übersicht des Zahlungsprozesses

1. **Zahlungsanforderung initiieren**: Erste `POST`-Anfrage ohne `X-PAYMENT`-Header, die die Plattform dazu bringt, 402 Payment Required zurückzugeben;
2. **Zahlungsanforderungen lesen**: Analysiere das `accepts`-Array in der 402-Antwort, um sicherzustellen, dass `network` auf `base`, `asset` auf USDC und `payTo` mit der Bestellseite übereinstimmt;
3. **`X-PAYMENT` generieren**: Verwende den Private Key der Zahlungsmittel-Wallet, die Anforderungen im Antwortkörper, die von Facilitator zurückgegebenen EIP-712-Daten usw., um die Signatur zu generieren (normalerweise mithilfe des offiziellen SDK);
4. **Mit Signatur erneut versuchen**: Füge den `X-PAYMENT`-Header zur Anfrage am gleichen Pfad hinzu, die Plattform validiert und gibt bei Erfolg 200 zurück;
5. **Ergebnisse analysieren**: Lese den Antwort-Header `X-PAYMENT-RESPONSE`, um die On-Chain-Transaktionshash, den tatsächlich abgebuchten Betrag und andere Informationen für die Abrechnung zu erhalten.

***

## III. Integrationsbeispiele

### 1. Erste Anfrage (Auslösen von 402)

```http theme={null}
POST https://api.xhuoapi.ai/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json

{
  "pay_way": "X402"
}
```

Typische 402-Antwort (Feldreihenfolge kann leicht variieren):

```json theme={null}
{
  "error": "Zahlung für diese Bestellung erforderlich.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}
```

Erläuterung der Schlüsselparameter:

* `network`: muss `base` (Base Mainnet) sein;
* `asset`: Base USDC Vertragsadresse (Beispiel für den offiziellen Hauptnetzvertrag);
* `maxAmountRequired`: die für diese Zahlung erforderliche USDC-Atomareinheit (1 USDC = 1.000.000 atomare Einheiten);
* `payTo`: Plattform-Empfangsadresse, sollte mit der Bestelldetailseite übereinstimmen;
* `extra`: EIP-712-Dateninformationen, die für die Signatur benötigt werden.

### 2. `X-PAYMENT` generieren

Eine gängige Methode ist die Verwendung des offiziellen SDK (z. B. `x402-js`, `x402-fetch`, `x402.clients` usw.):

1. Konvertiere den Private Key der Zahlungsmittel-Wallet in ein Kontoobjekt;
2. Notiere die `accepts`-Daten aus der 402-Antwort und wähle die Zahlungsoption mit `network == "base"`;
3. Rufe die Signaturfunktion des SDK auf, um den Base64-kodierten `X-PAYMENT`-String zu generieren (keine direkte Verbindung des Clients zum Facilitator erforderlich; das Backend der Plattform kümmert sich um die Aufrufe des Facilitators zur Verifizierung/Abwicklung);
4. Es wird empfohlen, zu überprüfen, ob `maxAmountRequired` im akzeptablen Bereich liegt, andernfalls den Benutzer aufzufordern, Guthaben aufzuladen.

Wenn du es manuell implementieren möchtest, konsultiere bitte die offiziellen x402-Dokumente und konstruiere die EIP-712-Struktur gemäß den bereitgestellten `extra.eip712`-Dateninformationen, bevor du die Signatur durchführst.

### 3. Mit Signatur erneut versuchen

```http theme={null}
POST https://api.xhuoapi.ai/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json
X-PAYMENT: {base64_signed_payload}

{
  "pay_way": "X402"
}
```

Wenn die Zahlung erfolgreich ist, beträgt der Antwortstatus 200, der Antwortkörper gibt die aktualisierten Bestellinformationen zurück und enthält:

```
X-PAYMENT-RESPONSE: eyJ0cmFuc2FjdGlvbiI6IjB4...==
```

`X-PAYMENT-RESPONSE` kann mit der Dekodierungsfunktion des SDK verwendet werden, um die On-Chain-Transaktionshash, das Zahlungsnetzwerk, die Adresse des Zahlers und andere Daten zu erhalten, die für die Buchhaltung oder Anzeige verwendet werden können.

***

## IV. Mehrsprachige Beispielcodes

Die folgenden Beispiele gehen davon aus, dass sie über Umgebungsvariablen oder Konfigurationsdateien injiziert werden:

* `ACE_PLATFORM_TOKEN`：Plattform-Token；
* `ACE_X402_ORDER_ID`：Bestell-ID；
* `ACE_X402_PRIVATE_KEY`：Zahlungs-Wallet-Privatschlüssel (mit `0x` Präfix).

### 1. Axios (TypeScript)

```ts theme={null}
import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { buildPaymentHeader, decodePaymentResponse } from "x402-js";

const baseURL = "https://api.xhuoapi.ai";
const orderId = process.env.ACE_X402_ORDER_ID!;
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const privateKey = process.env.ACE_X402_PRIVATE_KEY as Hex;

const account = privateKeyToAccount(privateKey);
const api = axios.create({
  baseURL,
  headers: {
    Authorization: `Bearer ${platformToken}`,
    "Content-Type": "application/json",
  },
});

async function payOrder() {
  const payPath = `/api/v1/orders/${orderId}/pay/`;

  const initial = await api.post(
    payPath,
    { pay_way: "X402" },
    { validateStatus: () => true }
  );
  if (initial.status !== 402) {
    throw new Error(`unerwarteter Status ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("keine Basisanforderung zurückgegeben");
  }

  const paymentHeader = await buildPaymentHeader({
    account,
    requirement,
  });

  const final = await api.post(
    payPath,
    { pay_way: "X402" },
    { headers: { "X-PAYMENT": paymentHeader } }
  );

  if (final.status >= 400) {
    throw new Error(`x402-Zahlung fehlgeschlagen: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("x402 Quittung", receipt);
}

payOrder().catch(console.error);
```

### 2. Fetch (JavaScript)

```ts theme={null}
import { wrapFetchWithPayment, decodePaymentResponse } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.ACE_X402_PRIVATE_KEY!);
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const orderId = process.env.ACE_X402_ORDER_ID!;
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

async function payOrder() {
  const url = `https://api.xhuoapi.ai/api/v1/orders/${orderId}/pay/`;

  const response = await fetchWithPayment(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${platformToken}`,
    },
    body: JSON.stringify({ pay_way: "X402" }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`x402-Zahlung fehlgeschlagen: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("x402 Quittung", receipt);
}

payOrder().catch(console.error);
```

### 3. Python requests

```python theme={null}
import os
from eth_account import Account
from x402.clients.requests import x402_requests
from x402.clients.base import decode_x_payment_response

order_id = os.environ["ACE_X402_ORDER_ID"]
platform_token = os.environ["ACE_PLATFORM_TOKEN"]
account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

session = x402_requests(
    account,
    payment_requirements_selector=lambda accepts, **_: next(
        req for req in accepts if req.network == "base" and req.scheme == "exact"
    ),
)

response = session.post(
    f"https://api.xhuoapi.ai/api/v1/orders/{order_id}/pay/",
    json={"pay_way": "X402"},
    headers={"Authorization": f"Bearer {platform_token}"},
)

response.raise_for_status()
receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
if receipt_header:
    print("x402 Quittung:", decode_x_payment_response(receipt_header))
```

### 4. Python httpx (asynchron)

```python theme={null}
import asyncio
import os
from eth_account import Account
from x402.clients.httpx import x402HttpxClient
from x402.clients.base import decode_x_payment_response

async def pay_order() -> None:
    order_id = os.environ["ACE_X402_ORDER_ID"]
    platform_token = os.environ["ACE_PLATFORM_TOKEN"]
    account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

    async with x402HttpxClient(
        account=account,
        base_url="https://api.xhuoapi.ai",
        headers={"Authorization": f"Bearer {platform_token}"},
        payment_requirements_selector=lambda accepts, **_: next(
            req for req in accepts if req.network == "base"
        ),
    ) as client:
        response = await client.post(
            f"/api/v1/orders/{order_id}/pay/",
            json={"pay_way": "X402"},
        )
        response.raise_for_status()
        receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
        if receipt_header:
            print("x402 Quittung:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())
```

> Beispiel zeigt nur die wesentlichen Aufrufe, in der Produktionsumgebung bitte Fehlerbehandlung, Wiederholungsstrategien, Protokollierung und Sicherheitskontrollen ergänzen.

***

## Fünf, Überprüfung nach erfolgreicher Zahlung

* **Konsole Überprüfung**: Besuchen Sie die Bestelldetailseite `https://api.xhuoapi.ai/console/orders/{order_id}`, wenn die Seite „Zahlung erfolgreich“ anzeigt oder der Bestellstatus auf bezahlt/abgeschlossen geändert wurde, bedeutet dies, dass die On-Chain-Abwicklung abgeschlossen ist.
* **API Überprüfung**: Rufen Sie `GET https://api.xhuoapi.ai/api/v1/orders/{order_id}/` auf und fügen Sie `Authorization: Bearer {platform_token}` hinzu, überprüfen Sie das `state`-Feld in der Antwort ( `PAID` oder `FINISHED` bedeutet Zahlung erfolgreich).
* **Rückgabe-Header**: Lesen Sie im Antworttext der erfolgreichen Zahlung den `X-PAYMENT-RESPONSE`, um den On-Chain-Transaktionshash als endgültigen Beleg zu entschlüsseln; es wird empfohlen, diese Informationen im Systemprotokoll zu speichern, um die Abrechnung zu erleichtern.

***

## Sechs, häufige Probleme und deren Lösung

* **Gibt weiterhin 402 zurück**: Stellen Sie sicher, dass die Zahlungsadresse im Base-Hauptnetz über genügend USDC verfügt, überprüfen Sie, ob `maxAmountRequired` das Wallet-Guthaben oder benutzerdefinierte Limits überschreitet.
* **Signatur fehlgeschlagen**: Stellen Sie sicher, dass der Privatschlüssel mit `0x` Präfix versehen ist; verwenden Sie beim Signieren strikt die `extra` (EIP-712-Domain) und `payTo` aus der Antwort, ändern Sie nicht die Reihenfolge der Felder.
* **Netzwerk stimmt nicht überein**: In `accepts` können mehrere Anforderungen vorhanden sein, wählen Sie die Option `network === "base"`.
* **Fehlender `X-PAYMENT-RESPONSE`**: Dies bedeutet, dass keine tatsächliche Zahlung abgebucht wurde, Sie können basierend auf dem Fehler im Antworttext erneut anfordern; bei On-Chain-Staus bitte später erneut versuchen.
* **Plattform-Token ungültig**: Stellen Sie sicher, dass das Token nicht gelöscht wurde und mit `platform-v1-` beginnt; wenn die Schnittstelle 401 zurückgibt, können Sie es im Dashboard neu generieren.

***

## Sieben, weitere Hilfe

* Online-Dokumentation und häufige Fragen: Dokumente im oberen Navigationsbereich des Plattform-Dashboards.
* Ticket einreichen und Kundensupport: [https://api.xhuoapi.ai/support](https://api.xhuoapi.ai/support)
* Community-Austausch: Discord [https://discord.gg/f9GRuKCmRc](https://discord.gg/f9GRuKCmRc), X (Twitter) [https://x.com/XHuoAPI](https://x.com/XHuoAPI)
* Weitere Kanäle: E-Mail `office@xhuoapi.ai`, `office@germey.tech`; Firmenadresse 651 N Broad St, Suite 201, Middletown, Delaware, USA; WeChat-Kundendienst bitte auf der Support-Seite den neuesten QR-Code einsehen.
* Feedback und Vorschläge: Wir freuen uns über Ihre Verbesserungsvorschläge über einen der oben genannten Kanäle.