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 Mainnet, активи використовують 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 Mainnet, та експортуйте приватний ключ, який буде використовуватися;
Поповніть Base Mainnet достатньою кількістю 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 Mainnet);
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 для завершення перевірки/розрахунку);
Рекомендується перевірити, чи 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-; якщо API повертає 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-код на сторінці підтримки.
Відгуки та пропозиції: ми будемо раді дізнатися про ваші потреби в покращенні через будь-який з вищезазначених каналів.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

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 (асинхронний)

П’ять, перевірка після успішної оплати

Шість, усунення поширених проблем

Сім, більше допомоги