Saltar al contenido principal
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 AceDataCloud de manera programática en tu propio sistema, logrando una experiencia de “pago al solicitar”. Referencias de documentación oficial: Este documento está dirigido a desarrolladores que necesitan integrar la capacidad de pago de la plataforma AceDataCloud 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://platform.acedata.cloud, 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://platform.acedata.cloud, 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://platform.acedata.cloud/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 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://platform.acedata.cloud
  • 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)

POST https://platform.acedata.cloud/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): 
{
  "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

POST https://platform.acedata.cloud/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）

import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { buildPaymentHeader, decodePaymentResponse } from "x402-js";

const baseURL = "https://platform.acedata.cloud";
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）

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://platform.acedata.cloud/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

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://platform.acedata.cloud/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）

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://platform.acedata.cloud",
        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://platform.acedata.cloud/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://platform.acedata.cloud/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://platform.acedata.cloud/support
  • Interacción comunitaria: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
  • Otros canales: Correo electrónico office@acedata.cloud, 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.