AceDataCloud x402 Руководство по интеграции платежей

x402 — это протокол платежей на основе стандарта HTTP 402 Payment Required, который позволяет вызывающей стороне завершать расчет на блокчейне одновременно с отправкой API-запроса. Он идеально подходит для сценариев по оплате за вызовы между автоматизированными программами, AI Agent и микросервисами. С помощью этого руководства вы сможете программно осуществлять оплату заказов AceDataCloud в своей системе, реализуя опыт «запроса и оплаты». Официальные материалы:

Обзор документа x402: https://docs.cdp.coinbase.com/x402/docs/overview
Примеры с открытым исходным кодом x402: https://github.com/coinbase/x402

Этот документ предназначен для разработчиков, которым необходимо интегрировать платежные возможности платформы AceDataCloud x402 в свой бизнес, и описывает полный процесс от подготовки окружения до завершения вызова платежа, а также предоставляет примеры кода на Axios, Fetch, Python requests и httpx. Основные моменты:

Платежная цепочка завершается в Base основной сети, актив используется USDC;
Необходимо использовать EVM приватный ключ кошелька для генерации заголовка подписи X-PAYMENT;
Все API находятся на домене https://platform.acedata.cloud, заголовок Authorization должен содержать Platform Token.

I. Подготовительные работы

1. Просмотр заказа и запись информации о получении

Войдите в консоль https://platform.acedata.cloud, в списке заказов или на странице деталей заказа вы можете увидеть заказы, которые необходимо оплатить. В деталях заказа будет отображено:

ID заказа (например, 7744945e-5e77-4dcc-a9c4-528692d17b34);
Адрес получения pay_to (также будет возвращен в ответе 402, рекомендуется ориентироваться на информацию на странице).

Пожалуйста, запишите ID заказа и подтвердите адрес pay_to, так как он потребуется для подписи в дальнейшем.

2. Подготовка платежного кошелька и средств

Подготовьте EVM-кошелек, поддерживающий основную сеть Base, и экспортируйте используемый приватный ключ;
Пополните основной сеть Base достаточным количеством USDC (сумма платежа указывается в минимальных единицах с 6 знаками после запятой);
x402 Facilitator оплатит сетевые сборы, кошелек для платежей должен содержать только достаточное количество USDC;
Приватный ключ используется только для локальной подписи, пожалуйста, храните его в безопасности, избегая его раскрытия в браузере или ненадежной среде.

3. Создание Platform Token

Platform Token используется для вызова API платформы и аналогичен токену пользователя, используемому в браузере после входа в систему, но не имеет срока действия. Пожалуйста, выполните следующие шаги для его создания:

Откройте страницу консоли https://platform.acedata.cloud/console/platform-tokens;
Нажмите «Создать токен», заполните информацию по запросу и создайте токен;
Скопируйте сгенерированный токен (например, platform-v1-xxxx) и сохраните его как platform_token.

Во всех последующих вызовах API заголовок должен содержать:

Authorization: Bearer {platform_token}

4. Запрос базовой информации

Базовый домен API: https://platform.acedata.cloud
Путь запроса на оплату: /api/v1/orders/{order_id}/pay/
Запросы и ответы используют JSON, кодировка — UTF-8.

II. Обзор процесса оплаты

Инициация запроса на оплату: первый POST запрос без заголовка X-PAYMENT, который вызывает платформу для возврата 402 Payment Required;
Чтение требований к оплате: анализируйте массив accepts в ответе 402, подтверждая, что network равен base, asset равен USDC, а payTo совпадает с данными на странице заказа;
Генерация X-PAYMENT: используйте приватный ключ платежного кошелька, требования из тела ответа, а также информацию о домене EIP-712, возвращенную Facilitator, для генерации подписи (обычно с помощью официального SDK);
Повторная попытка с подписью: добавьте заголовок X-PAYMENT в запрос по тому же пути, после успешной проверки платформа вернет 200;
Анализ результата: прочитайте заголовок ответа X-PAYMENT-RESPONSE, чтобы получить хэш транзакции на блокчейне, фактическую сумму списания и другую информацию для сверки.

III. Примеры интеграции

1. Первый запрос (инициация 402)

POST https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json

{
  "pay_way": "X402"
}

Типичный ответ 402 (порядок полей может немного изменяться):

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

Объяснение ключевых полей:

network: должно быть base (основная сеть Base);
asset: адрес контракта Base USDC (пример — официальный контракт основной сети);
maxAmountRequired: необходимая сумма USDC в атомарных единицах для данного платежа (1 USDC = 1,000,000 атомарных единиц);
payTo: адрес получения платформы, должен совпадать с данными на странице деталей заказа;
extra: информация о домене EIP-712, необходимая для подписи и т.д.

2. Генерация `X-PAYMENT`

Обычная практика — использовать официальный SDK (например, x402-js, x402-fetch, x402.clients и т.д.):

Преобразуйте приватный ключ платежного кошелька в объект аккаунта;
Запишите данные accepts из ответа 402, выберите вариант оплаты с network == "base";
Вызовите функцию подписи, предоставляемую SDK, для генерации строки X-PAYMENT в формате Base64 (не требуется прямое подключение клиента к facilitator; бэкенд платформы будет отвечать за вызов facilitator для завершения verify/settle);
Рекомендуется проверить, находится ли maxAmountRequired в допустимом диапазоне, и в случае превышения уведомить пользователя о необходимости пополнения.

Если необходимо реализовать вручную, обратитесь к официальной документации x402, чтобы построить структуру EIP-712 на основе информации о домене, предоставленной в extra.eip712, и затем выполнить подпись.

3. Повторная попытка с подписью

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

Если платеж успешен, статус ответа будет 200, а тело ответа вернет обновленную информацию о заказе и дополнительно:

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

X-PAYMENT-RESPONSE можно декодировать с помощью функции SDK, чтобы получить хэш транзакции на блокчейне, платежную сеть, адрес плательщика и другие данные для учета или отображения.

IV. Примеры кода на нескольких языках

Следующие примеры предполагают, что переменные окружения или конфигурационные файлы были внедрены:

ACE_PLATFORM_TOKEN：Токен платформы；
ACE_X402_ORDER_ID：ID заказа；
ACE_X402_PRIVATE_KEY：Приватный ключ платежного кошелька (с префиксом 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(`неожиданный статус ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("нет базового требования");
  }

  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 не удался: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("чек 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(`платеж x402 не удался: ${response.status} ${errorBody}`);
  }

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

4. Python httpx（异步）

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("чек x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())

Пример только демонстрирует ключевые вызовы, в производственной среде необходимо добавить обработку исключений, стратегии повторных попыток, журналы и контроль безопасности.

Пять, проверка после успешной оплаты

Проверка в консоли：Перейдите на страницу деталей заказа https://platform.acedata.cloud/console/orders/{order_id}. Если на странице отображается «Оплата успешна» или статус заказа изменился на оплаченный/завершенный, это означает, что расчет в цепочке завершен.
Проверка API：Вызовите GET https://platform.acedata.cloud/api/v1/orders/{order_id}/ с заголовком Authorization: Bearer {platform_token} и проверьте поле state в ответе (значения PAID или FINISHED означают успешную оплату).
Заголовок ответа：В ответе на успешный платеж прочитайте X-PAYMENT-RESPONSE, из которого можно извлечь хэш транзакции в цепочке как окончательное подтверждение; рекомендуется сохранить эту информацию в системных журналах для сверки.

Шесть, устранение распространенных проблем

По-прежнему возвращает 402：Убедитесь, что адрес платежа имеет достаточное количество USDC в основной сети, проверьте, не превышает ли maxAmountRequired баланс кошелька или пользовательский лимит.
Ошибка подписи：Убедитесь, что приватный ключ имеет префикс 0x; при подписании строго используйте extra (домен EIP-712) и payTo из ответа, не изменяйте порядок полей.
Несоответствие сети：В accepts может быть несколько требований, выберите вариант с network === "base".
Отсутствует X-PAYMENT-RESPONSE：Это означает, что платеж не был фактически списан, можно повторно инициировать запрос на основе ошибки в теле ответа; если возникли проблемы с сетью, попробуйте позже.
Недействительный токен платформы：Убедитесь, что токен не был удален и начинается с префикса platform-v1-; если интерфейс возвращает 401, можно заново сгенерировать его в консоли.

Семь, дополнительная помощь

Онлайн-документация и часто задаваемые вопросы: навигация «Документация» в верхней части консоли платформы.
Подать заявку и поддержка клиентов: https://platform.acedata.cloud/support
Сообщество: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
Другие каналы: электронная почта office@acedata.cloud, office@germey.tech; адрес компании 131 Continental Dr, Suite 305, Newark, DE 19713, USA; для поддержки WeChat смотрите последние QR-коды на странице поддержки.
Обратная связь и предложения: мы будем рады услышать ваши требования по улучшению через любой из вышеуказанных каналов.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Прокси

Продвинутый

AceDataCloud x402 Руководство по интеграции платежей

I. Подготовительные работы

1. Просмотр заказа и запись информации о получении

2. Подготовка платежного кошелька и средств

3. Создание Platform Token

4. Запрос базовой информации

II. Обзор процесса оплаты

III. Примеры интеграции

1. Первый запрос (инициация 402)

2. Генерация `X-PAYMENT`

3. Повторная попытка с подписью

IV. Примеры кода на нескольких языках

1. Axios（TypeScript）

2. Fetch（JavaScript）

3. Python requests

4. Python httpx（异步）

Пять, проверка после успешной оплаты

Шесть, устранение распространенных проблем

Семь, дополнительная помощь

​I. Подготовительные работы

​1. Просмотр заказа и запись информации о получении

​2. Подготовка платежного кошелька и средств

​3. Создание Platform Token

​4. Запрос базовой информации

​II. Обзор процесса оплаты

​III. Примеры интеграции

​1. Первый запрос (инициация 402)

​2. Генерация X-PAYMENT

​3. Повторная попытка с подписью

​IV. Примеры кода на нескольких языках

​1. Axios（TypeScript）

​2. Fetch（JavaScript）

​3. Python requests

​4. Python httpx（异步）

​Пять, проверка после успешной оплаты

​Шесть, устранение распространенных проблем

​Семь, дополнительная помощь

I. Подготовительные работы

1. Просмотр заказа и запись информации о получении

2. Подготовка платежного кошелька и средств

3. Создание Platform Token

4. Запрос базовой информации

II. Обзор процесса оплаты

III. Примеры интеграции

1. Первый запрос (инициация 402)

2. Генерация `X-PAYMENT`

3. Повторная попытка с подписью

IV. Примеры кода на нескольких языках

1. Axios（TypeScript）

2. Fetch（JavaScript）

3. Python requests

4. Python httpx（异步）

Пять, проверка после успешной оплаты

Шесть, устранение распространенных проблем

Семь, дополнительная помощь