> ## 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 Guía de Integración de Pagos

> x402 集成指南 - XHuoAPI

x402 es un protocolo de pago en cadena basado en el estándar HTTP 402 Payment Required, que permite a los llamadores completar la liquidación en cadena al iniciar una solicitud API, siendo muy adecuado para escenarios de facturación por llamada entre programas automatizados, Agentes de IA y microservicios. A través de esta guía, puedes realizar el pago de pedidos de XHuoAPI de manera programática en tu propio sistema, logrando una experiencia de "pago al solicitar".

Referencias de documentación oficial:

* Documentación general de x402: [https://docs.cdp.coinbase.com/x402/docs/overview](https://docs.cdp.coinbase.com/x402/docs/overview)
* Ejemplo de código abierto de x402: [https://github.com/coinbase/x402](https://github.com/coinbase/x402)

Este documento está dirigido a desarrolladores que necesitan integrar la capacidad de pago de la plataforma XHuoAPI x402 en sus negocios, presentando el proceso completo desde la preparación del entorno hasta la finalización de la llamada de pago, y proporcionando ejemplos de código en Axios, Fetch, Python requests y httpx. Puntos clave:

* La cadena de pago se completa en **Base Mainnet**, utilizando **USDC** como activo;
* Debe utilizarse la **clave privada EVM** de una billetera con fondos para generar el encabezado de firma `X-PAYMENT`;
* Todas las API se encuentran bajo el dominio `https://api.xhuoapi.ai`, y el encabezado `Authorization` debe incluir el **Token de Plataforma**.

***

## I. Preparativos

### 1. Verificar el pedido y registrar la información de pago

Inicia sesión en la consola [https://api.xhuoapi.ai](https://api.xhuoapi.ai), donde podrás ver los pedidos que requieren pago en la lista de pedidos o en la página de detalles del pedido. Los detalles del pedido mostrarán:

* ID del pedido (por ejemplo, `7744945e-5e77-4dcc-a9c4-528692d17b34`);
* Dirección de pago `pay_to` (también se devolverá en la respuesta 402, se recomienda basarse en la información de la página).

Por favor, registra el ID del pedido y confirma la dirección `pay_to`, ya que necesitarás asegurarte de que los fondos se envíen a esa dirección al firmar más adelante.

### 2. Preparar la billetera de pago y los fondos

* Prepara una billetera EVM que soporte la red Base y exporta la clave privada que se utilizará;
* Carga suficiente **USDC** en la red Base (la unidad de pago es la unidad mínima de 6 decimales);
* El facilitador de x402 pagará las tarifas de red, la billetera de pago solo necesita mantener suficiente USDC;
* La clave privada se utiliza únicamente para la firma local, por favor, mantenla segura y evita exponerla en navegadores o entornos no confiables.

### 3. Crear el Token de Plataforma

El Token de Plataforma se utiliza para llamar a la API de la plataforma, similar a la funcionalidad del Token de usuario que se utiliza en el navegador después de iniciar sesión, pero no caduca. Sigue estos pasos para crear uno:

1. Abre la página de la consola [https://api.xhuoapi.ai/console/platform-tokens](https://api.xhuoapi.ai/console/platform-tokens);
2. Haz clic en "Crear Token", completa la información de referencia según las indicaciones y genera el token;
3. Copia el Token generado (por ejemplo, `platform-v1-xxxx`) y guárdalo como `platform_token`.

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

En todas las llamadas a la API posteriores, el encabezado debe incluir:

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

### 4. Solicitar información básica

* Dominio base de la API: `https://api.xhuoapi.ai`
* Ruta de solicitud de pago: `/api/v1/orders/{order_id}/pay/`
* Tanto las solicitudes como las respuestas utilizan JSON, codificado en UTF-8.

***

## II. Resumen del Proceso de Pago

1. **Iniciar la solicitud de pago**: Primera solicitud `POST` sin el encabezado `X-PAYMENT`, lo que activa la respuesta 402 Payment Required de la plataforma;
2. **Leer los requisitos de pago**: Analiza el array `accepts` en la respuesta 402, confirmando que `network` sea `base`, `asset` sea USDC, y que `payTo` coincida con la página del pedido;
3. **Generar `X-PAYMENT`**: Utiliza la clave privada de la billetera de pago, los requisitos del cuerpo de respuesta, y la información del dominio EIP-712 devuelta por el facilitador para generar la firma (normalmente se completa con la ayuda del SDK oficial);
4. **Reintentar con la firma**: Agrega el encabezado `X-PAYMENT` a la solicitud en la misma ruta, y tras la verificación exitosa de la plataforma, se devuelve un 200;
5. **Analizar el resultado**: Lee el encabezado de respuesta `X-PAYMENT-RESPONSE`, donde puedes obtener el hash de la transacción en cadena, el monto real deducido y otra información para la conciliación.

***

## III. Ejemplo de Integración

### 1. Primera solicitud (activar 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"
}
```

Respuesta típica 402 (el orden de los campos puede variar ligeramente):

```json theme={null}
{
  "error": "Payment required for this order.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}
```

Descripción de campos clave:

* `network`: debe ser `base` (Base Mainnet);
* `asset`: dirección del contrato de USDC en Base (ejemplo de contrato en la red principal oficial);
* `maxAmountRequired`: unidad atómica de USDC requerida para este pago (1 USDC = 1,000,000 unidades atómicas);
* `payTo`: dirección de pago de la plataforma, debe coincidir con la página de detalles del pedido;
* `extra`: información del dominio EIP-712 necesaria para la firma, etc.

### 2. Generar `X-PAYMENT`

La práctica común es utilizar el SDK oficial (como `x402-js`, `x402-fetch`, `x402.clients`, etc.):

1. Convierte la clave privada de la billetera de pago en un objeto de cuenta;
2. Registra los datos `accepts` de la respuesta 402, eligiendo la opción de pago donde `network == "base"`;
3. Llama a la función de firma proporcionada por el SDK para generar la cadena `X-PAYMENT` codificada en Base64 (no es necesario que el cliente se conecte directamente al facilitador; el backend de la plataforma se encargará de llamar al facilitador para completar la verificación/liquidación);
4. Se recomienda verificar si `maxAmountRequired` está dentro del rango aceptable, y si excede, notificar al usuario que debe recargar.

Si necesitas implementarlo manualmente, consulta la documentación oficial de x402 y construye la estructura EIP-712 según la información del dominio proporcionada en `extra.eip712` antes de firmar.

### 3. Reintentar 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"
}
```

Si el pago es exitoso, el estado de respuesta será 200, y el cuerpo de respuesta devolverá la información actualizada del pedido, junto con:

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

`X-PAYMENT-RESPONSE` se puede decodificar utilizando la función de decodificación del SDK para obtener el hash de la transacción en cadena, la red de pago, la dirección del pagador y otros datos, que se pueden utilizar para la contabilización o visualización en el negocio.

***

## IV. Ejemplos de Código en Múltiples Lenguajes

Los siguientes ejemplos suponen que se inyectan a través de variables de entorno o archivos de configuración:

* `ACE_PLATFORM_TOKEN`：Token de la plataforma；
* `ACE_X402_ORDER_ID`：ID del pedido；
* `ACE_X402_PRIVATE_KEY`：Clave privada de la billetera de pago (con prefijo `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(`estado inesperado ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("no se devolvió ningún requisito base");
  }

  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(`el pago x402 falló: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("recibo 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(`el pago x402 falló: ${response.status} ${errorBody}`);
  }

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

### 4. Python httpx（asíncrono）

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

asyncio.run(pay_order())
```

> Ejemplo solo muestra llamadas clave, en producción se debe agregar manejo de excepciones, estrategias de reintento, registro y control de seguridad.

***

## Cinco, verificación después del pago exitoso

* **Verificación en consola**: Acceda a la página de detalles del pedido `https://api.xhuoapi.ai/console/orders/{order_id}`, si la página muestra "pago exitoso" o el estado del pedido ha cambiado a pagado/completado, significa que la liquidación en la cadena se ha completado.
* **Verificación de API**: Llame a `GET https://api.xhuoapi.ai/api/v1/orders/{order_id}/` y lleve `Authorization: Bearer {platform_token}`, verifique el campo `state` en la respuesta (`PAID` o `FINISHED` indica que el pago fue exitoso).
* **Cabecera de respuesta**: En la respuesta del pago exitoso, lea `X-PAYMENT-RESPONSE`, se puede analizar el hash de la transacción en la cadena como comprobante final; se recomienda guardar esta información en el registro del sistema para conciliación.

***

## Seis, solución de problemas comunes

* **Aún devuelve 402**: Confirme que la dirección de pago tiene suficiente USDC en la red principal de Base, verifique si `maxAmountRequired` excede el saldo de la billetera o el límite personalizado.
* **Fallo en la firma**: Asegúrese de que la clave privada tenga el prefijo `0x`; al firmar, use estrictamente el `extra` (dominio EIP-712) y `payTo` de la respuesta, no cambie el orden de los campos.
* **Red no coincide**: Puede haber múltiples requisitos en `accepts`, elija la opción `network === "base"`.
* **Falta `X-PAYMENT-RESPONSE`**: Indica que el pago no se ha deducido realmente, puede reiniciar según el error en el cuerpo de la respuesta; si hay congestión en la cadena, intente nuevamente más tarde.
* **Token de plataforma inválido**: Confirme que el token no ha sido eliminado y comienza con el prefijo `platform-v1-`; si la interfaz devuelve 401, puede regenerarlo en la consola.

***

## Siete, más ayuda

* Documentación en línea y preguntas frecuentes: Navegación en la parte superior de la consola de la plataforma "Documentación".
* Envío de tickets y soporte al cliente: [https://api.xhuoapi.ai/support](https://api.xhuoapi.ai/support)
* Interacción comunitaria: Discord [https://discord.gg/f9GRuKCmRc](https://discord.gg/f9GRuKCmRc), X (Twitter) [https://x.com/XHuoAPI](https://x.com/XHuoAPI)
* Otros canales: Correo electrónico `office@xhuoapi.ai`, `office@germey.tech`; dirección de la empresa 651 N Broad St, Suite 201, Middletown, Delaware, EE. UU.; para soporte de WeChat, consulte el código QR más reciente en la página de soporte.
* Comentarios y sugerencias: Bienvenido a informarnos sobre necesidades de mejora a través de cualquiera de los canales anteriores.