> ## 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 Платіжна інтеграція

> x402 集成指南 - XHuoAPI

x402 є платіжним протоколом на основі стандарту HTTP 402 Payment Required, який дозволяє викликачеві завершити ланцюговий розрахунок під час ініціювання API запиту, що робить його ідеальним для автоматизованих програм, AI Agent, мікросервісів у сценаріях оплати за викликом. За допомогою цього посібника ви можете програмно здійснити оплату замовлення XHuoAPI у своїй системі, реалізуючи досвід «запит - оплата».

Офіційні матеріали:

* Оглядова документація x402: [https://docs.cdp.coinbase.com/x402/docs/overview](https://docs.cdp.coinbase.com/x402/docs/overview)
* Відкритий приклад x402: [https://github.com/coinbase/x402](https://github.com/coinbase/x402)

Цей документ призначений для розробників, які потребують інтеграції платіжних можливостей XHuoAPI x402 у свій бізнес, і описує повний процес від підготовки середовища до завершення виклику оплати, а також надає приклади коду для Axios, Fetch, Python requests та httpx. Основні моменти:

* Платіжний ланцюг завершується в **Base Mainnet**, активи використовують **USDC**;
* Необхідно використовувати **EVM приватний ключ** гаманця для генерації заголовка підпису `X-PAYMENT`;
* Всі API розташовані на домені `https://api.xhuoapi.ai`, заголовок `Authorization` повинен містити **Platform Token**.

***

## I. Підготовчі роботи

### 1. Перегляд замовлення та запис інформації про отримання

Увійдіть до консолі [https://api.xhuoapi.ai](https://api.xhuoapi.ai), у списку замовлень або на сторінці деталей замовлення ви можете побачити замовлення, яке потрібно оплатити. Деталі замовлення покажуть:

* 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 платформи, функціонально подібний до токена користувача, що використовується в браузері після входу, але не має терміну дії. Будь ласка, дотримуйтесь наступних кроків для створення:

1. Відкрийте сторінку консолі [https://api.xhuoapi.ai/console/platform-tokens](https://api.xhuoapi.ai/console/platform-tokens);
2. Натисніть «Створити токен», заповніть інформацію про примітки відповідно до підказок і згенеруйте;
3. Скопіюйте згенерований токен (наприклад, `platform-v1-xxxx`), зберігайте його як `platform_token`.

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

Усі подальші виклики API повинні містити в заголовку:

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

### 4. Запит базової інформації

* Базовий домен API: `https://api.xhuoapi.ai`
* Шлях запиту на оплату: `/api/v1/orders/{order_id}/pay/`
* Запити та відповіді використовують JSON, кодування UTF-8.

***

## II. Огляд процесу оплати

1. **Ініціювати запит на оплату**: перший `POST` запит без заголовка `X-PAYMENT`, що викликає повернення платформи 402 Payment Required;
2. **Зчитати вимоги до оплати**: розібрати масив `accepts` у відповіді 402, підтвердити, що `network` є `base`, `asset` є USDC, `payTo` відповідає даним на сторінці замовлення;
3. **Генерувати `X-PAYMENT`**: використовуючи приватний ключ платіжного гаманця, вимоги з тіла відповіді, інформацію EIP-712, повернуту Facilitator, згенерувати підпис (зазвичай за допомогою офіційного SDK);
4. **Повторити запит з підписом**: додати заголовок `X-PAYMENT` до запиту того ж шляху, після успішної перевірки платформа повертає 200;
5. **Розібрати результати**: зчитати заголовок відповіді `X-PAYMENT-RESPONSE`, щоб отримати хеш транзакції в ланцюгу, фактичну суму списання та іншу інформацію для звірки.

***

## III. Приклад інтеграції

### 1. Перший запит (виклик 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"
}
```

Типова відповідь 402 (порядок полів може трохи змінюватися):

```json theme={null}
{
  "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` тощо):

1. Перетворити приватний ключ платіжного гаманця на об'єкт рахунку;
2. Записати дані `accepts` з відповіді 402, вибрати платіжний варіант з `network == "base"`;
3. Викликати функцію підпису, надану SDK, для генерації рядка `X-PAYMENT` у форматі Base64 (не потрібно безпосередньо підключатися до facilitator; бекенд платформи відповідатиме за виклик facilitator для завершення перевірки/розрахунку);
4. Рекомендується перевірити, чи `maxAmountRequired` знаходиться в прийнятному діапазоні, якщо перевищує, попередити користувача про поповнення.

Якщо потрібно реалізувати вручну, будь ласка, зверніться до офіційної документації x402, щоб побудувати структуру EIP-712 відповідно до інформації з `extra.eip712`, а потім підписати.

### 3. Повторний запит з підписом

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

Якщо оплата успішна, статус відповіді буде 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)

```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(`неочікуваний статус ${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)

```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(`платіж x402 не вдався: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("квитанція 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("квитанція 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("квитанція x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())
```

> Приклад лише демонструє ключові виклики, у виробничому середовищі будь ласка, додайте обробку винятків, стратегії повторних спроб, журнали та контроль безпеки.

***

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

* **Перевірка в консолі**: відвідайте сторінку деталей замовлення `https://api.xhuoapi.ai/console/orders/{order_id}`. Якщо на сторінці відображається «Оплата успішна» або статус замовлення змінився на оплачений/завершений, це означає, що розрахунок в ланцюгу завершено.
* **Перевірка API**: викличте `GET https://api.xhuoapi.ai/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://api.xhuoapi.ai/support](https://api.xhuoapi.ai/support)
* Спільнота: Discord [https://discord.gg/f9GRuKCmRc](https://discord.gg/f9GRuKCmRc), X (Twitter) [https://x.com/XHuoAPI](https://x.com/XHuoAPI)
* Інші канали: електронна пошта `office@xhuoapi.ai`, `office@germey.tech`; адреса компанії 651 N Broad St, Suite 201, Middletown, Delaware, USA; для підтримки WeChat, будь ласка, перегляньте останній QR-код на сторінці підтримки.
* Відгуки та пропозиції: ми будемо раді дізнатися про ваші потреби в покращенні через будь-який з вищезазначених каналів.