> ## 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 Guida all'integrazione dei pagamenti

> x402 集成指南 - XHuoAPI

x402 è un protocollo di pagamento on-chain basato sullo standard HTTP 402 Payment Required, che consente al chiamante di completare la regolazione on-chain mentre avvia una richiesta API, molto adatto per scenari di fatturazione per chiamata tra programmi automatizzati, agenti AI e microservizi. Attraverso questa guida, puoi completare in modo programmatico il pagamento degli ordini XHuoAPI nel tuo sistema, realizzando un'esperienza di "richiesta e pagamento".

Riferimenti ufficiali:

* Documentazione panoramica su x402: [https://docs.cdp.coinbase.com/x402/docs/overview](https://docs.cdp.coinbase.com/x402/docs/overview)
* Esempi open source di x402: [https://github.com/coinbase/x402](https://github.com/coinbase/x402)

Questo documento è rivolto agli sviluppatori che necessitano di integrare la capacità di pagamento x402 della piattaforma XHuoAPI nel proprio business, introducendo il processo completo dalla preparazione dell'ambiente al completamento della chiamata di pagamento, e fornendo esempi di codice per Axios, Fetch, Python requests e httpx. Punti chiave:

* Il collegamento di pagamento avviene sulla **rete principale Base**, gli asset utilizzano **USDC**;
* È necessario utilizzare la **chiave privata EVM** del wallet per generare l'intestazione di firma `X-PAYMENT`;
* Tutte le API si trovano sotto il dominio `https://api.xhuoapi.ai`, l'intestazione `Authorization` deve contenere il **Platform Token**.

***

## I. Preparativi

### 1. Controlla l'ordine e registra le informazioni di pagamento

Accedi alla console [https://api.xhuoapi.ai](https://api.xhuoapi.ai), nella lista degli ordini o nella pagina dei dettagli dell'ordine puoi vedere l'ordine da pagare. I dettagli dell'ordine mostreranno:

* ID ordine (ad esempio `7744945e-5e77-4dcc-a9c4-528692d17b34`);
* Indirizzo di pagamento `pay_to` (restituito anche nella risposta 402, si consiglia di fare riferimento alle informazioni della pagina).

Si prega di registrare l'ID ordine e confermare l'indirizzo `pay_to`, poiché sarà necessario garantire che i fondi vengano inviati a tale indirizzo durante la firma successiva.

### 2. Prepara il wallet di pagamento e i fondi

* Prepara un wallet EVM che supporti la rete principale Base e esporta la chiave privata da utilizzare;
* Ricarica sufficienti **USDC** sulla rete principale Base (l'importo del pagamento è espresso in unità minime con 6 decimali);
* x402 Facilitator coprirà le spese di rete, il wallet di pagamento deve solo mantenere un numero sufficiente di USDC;
* La chiave privata è utilizzata solo per la firma locale, si prega di conservarla in modo sicuro, evitando di esporla nel browser o in ambienti non sicuri.

### 3. Crea il Platform Token

Il Platform Token è utilizzato per chiamare le API della piattaforma, simile alla funzionalità del Token utente utilizzato nel browser dopo il login, ma non scade. Segui i seguenti passaggi per crearlo:

1. Apri la pagina della console [https://api.xhuoapi.ai/console/platform-tokens](https://api.xhuoapi.ai/console/platform-tokens);
2. Clicca su "Crea Token", compila le informazioni richieste e genera;
3. Copia il Token generato (ad esempio `platform-v1-xxxx`) e conservalo come `platform_token`.

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

Tutte le chiamate API successive devono includere nell'intestazione:

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

### 4. Richiedi informazioni di base

* Dominio base API: `https://api.xhuoapi.ai`
* Percorso della richiesta di pagamento: `/api/v1/orders/{order_id}/pay/`
* Richiesta e risposta utilizzano JSON, codificato in UTF-8.

***

## II. Panoramica del processo di pagamento

1. **Inizia la richiesta di pagamento**: prima richiesta `POST` senza intestazione `X-PAYMENT`, attiva la piattaforma per restituire 402 Payment Required;
2. **Leggi i requisiti di pagamento**: analizza l'array `accepts` nella risposta 402, conferma che `network` sia `base`, `asset` sia USDC e `payTo` corrisponda a quanto indicato nella pagina dell'ordine;
3. **Genera `X-PAYMENT`**: utilizza la chiave privata del wallet di pagamento, i requisiti nel corpo della risposta, le informazioni del dominio EIP-712 restituite dal Facilitator per generare la firma (solitamente completata con l'SDK ufficiale);
4. **Ritenta con la firma**: aggiungi l'intestazione `X-PAYMENT` alla richiesta sullo stesso percorso, la piattaforma verifica e restituisce 200 se ha successo;
5. **Analizza il risultato**: leggi l'intestazione di risposta `X-PAYMENT-RESPONSE`, puoi ottenere l'hash della transazione on-chain, l'importo effettivamente addebitato e altre informazioni per la riconciliazione.

***

## III. Esempi di integrazione

### 1. Prima richiesta (attiva 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"
}
```

Risposta tipica 402 (l'ordine dei campi potrebbe variare leggermente):

```json theme={null}
{
  "error": "Pagamento richiesto per questo ordine.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}
```

Descrizione dei campi chiave:

* `network`: deve essere `base` (rete principale Base);
* `asset`: indirizzo del contratto USDC su Base (esempio del contratto ufficiale sulla rete principale);
* `maxAmountRequired`: unità atomica di USDC necessaria per questo pagamento (1 USDC = 1.000.000 unità atomiche);
* `payTo`: indirizzo di pagamento della piattaforma, deve corrispondere a quanto indicato nella pagina dei dettagli dell'ordine;
* `extra`: informazioni del dominio EIP-712 necessarie per la firma, ecc.

### 2. Genera `X-PAYMENT`

La prassi comune è utilizzare l'SDK ufficiale (come `x402-js`, `x402-fetch`, `x402.clients`, ecc.):

1. Converti la chiave privata del wallet di pagamento in un oggetto account;
2. Registra i dati `accepts` dalla risposta 402, scegli l'opzione di pagamento con `network == "base"`;
3. Chiama la funzione di firma fornita dall'SDK per generare la stringa `X-PAYMENT` codificata in Base64 (non è necessario collegarsi direttamente al facilitator dal client; il backend della piattaforma si occuperà di chiamare il facilitator per completare la verifica/risoluzione);
4. Si consiglia di verificare se `maxAmountRequired` è entro il limite accettabile, in caso contrario avvisare l'utente di ricaricare.

Se desideri implementare manualmente, fai riferimento alla documentazione ufficiale di x402, costruendo la struttura EIP-712 secondo le informazioni del dominio fornite in `extra.eip712` e successivamente firmando.

### 3. Ritenta con la firma

```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"
}
```

Se il pagamento ha successo, lo stato della risposta sarà 200, il corpo della risposta restituirà le informazioni aggiornate sull'ordine, e includerà:

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

`X-PAYMENT-RESPONSE` può essere decodificato utilizzando la funzione di decodifica dell'SDK per ottenere l'hash della transazione on-chain, la rete di pagamento, l'indirizzo del pagatore e altri dati, utili per la registrazione o la visualizzazione nel business.

***

## IV. Esempi di codice multilingue

I seguenti esempi presumono che vengano iniettati tramite variabili d'ambiente o file di configurazione:

* `ACE_PLATFORM_TOKEN`：Token della piattaforma；
* `ACE_X402_ORDER_ID`：ID dell'ordine；
* `ACE_X402_PRIVATE_KEY`：Chiave privata del portafoglio di pagamento (con prefisso `0x`)。

### 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(`stato inaspettato ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("nessun requisito base restituito");
  }

  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(`pagamento x402 fallito: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("ricevuta x402", 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(`pagamento x402 fallito: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("ricevuta x402", 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("ricevuta x402:", decode_x_payment_response(receipt_header))
```

### 4. Python httpx（异步）

```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("ricevuta x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())
```

> L'esempio mostra solo le chiamate chiave, in un ambiente di produzione si prega di aggiungere gestione delle eccezioni, strategie di ripetizione, registrazione e controllo della sicurezza.

***

## Cinque, verifica dopo il pagamento riuscito

* **Verifica della console**：Visita la pagina dei dettagli dell'ordine `https://api.xhuoapi.ai/console/orders/{order_id}`. Se la pagina mostra "Pagamento riuscito" o lo stato dell'ordine è cambiato in pagato/completato, significa che il regolamento sulla catena è completato.
* **Verifica API**：Chiama `GET https://api.xhuoapi.ai/api/v1/orders/{order_id}/` e porta `Authorization: Bearer {platform_token}`, controlla il campo `state` nella risposta ( `PAID` o `FINISHED` indica pagamento riuscito).
* **Intestazione di ritorno**：Leggi `X-PAYMENT-RESPONSE` nella risposta di pagamento riuscito, puoi decodificare l'hash della transazione sulla catena come prova finale; si consiglia di salvare queste informazioni nei registri di sistema per la riconciliazione.

***

## Sei, risoluzione dei problemi comuni

* **Restituisce ancora 402**：Verifica che l'indirizzo di pagamento abbia abbastanza USDC sulla rete principale Base, controlla se `maxAmountRequired` supera il saldo del portafoglio o il limite personalizzato.
* **Errore di firma**：Assicurati che la chiave privata abbia il prefisso `0x`; durante la firma utilizza rigorosamente `extra` (campo EIP-712) e `payTo` nella risposta, non modificare l'ordine dei campi.
* **Rete non corrispondente**：Potrebbero esserci più requisiti in `accepts`, seleziona l'opzione `network === "base"`.
* **Manca `X-PAYMENT-RESPONSE`**：Indica che il pagamento non è stato effettivamente addebitato, puoi ripetere l'operazione in base all'errore nel corpo della risposta; se si verifica congestione sulla catena, riprova più tardi.
* **Token della piattaforma non valido**：Verifica che il token non sia stato eliminato e inizi con il prefisso `platform-v1-`; se l'interfaccia restituisce 401, puoi rigenerarlo nella console.

***

## Sette, ulteriore aiuto

* Documentazione online e domande frequenti: navigazione in alto nella console della piattaforma "Documentazione".
* Invia un ticket e supporto clienti: [https://api.xhuoapi.ai/support](https://api.xhuoapi.ai/support)
* Comunicazione nella comunità: Discord [https://discord.gg/f9GRuKCmRc](https://discord.gg/f9GRuKCmRc), X (Twitter) [https://x.com/XHuoAPI](https://x.com/XHuoAPI)
* Altri canali: email `office@xhuoapi.ai`, `office@germey.tech`; indirizzo aziendale 651 N Broad St, Suite 201, Middletown, Delaware, USA; per il supporto WeChat controlla il codice QR più recente nella pagina di supporto.
* Feedback e suggerimenti: ti invitiamo a farci sapere le tue esigenze di miglioramento attraverso uno dei canali sopra.