> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# X402 Інтеграційний посібник

> Platform API guide - Ace Data Cloud

X402 є протоколом на основі HTTP `402 Payment Required` для ланцюгових платежів. Завдяки можливостям X402 від Ace Data Cloud, викликач може не створювати API Token, не попередньо поповнювати баланс рахунку, а безпосередньо здійснювати ланцюгові платежі за допомогою USDC у кожному запиті API.

Цей набір документів організовано за реальним порядком інтеграції: спочатку виконайте мінімальний запит, потім інтегруйте SDK, а після цього зрозумійте мережу, схеми оплати, оплату замовлень та Facilitator. Рекомендується читати за таблицею зверху вниз.

| Посібник | Сценарій використання | Посилання |
| - | - | - |
| Швидкий старт | Спочатку зрозумійте 402, `accepts` та `PAYMENT-SIGNATURE` процеси з мінімальним запитом | [X402 Швидкий старт](https://platform.acedata.cloud/documents/x402-quickstart) |
| TypeScript SDK | Викликати Ace Data Cloud API в браузері, Node.js або фронтенд-додатках | [Інтеграція TypeScript SDK](https://platform.acedata.cloud/documents/x402-typescript-sdk) |
| Python SDK | Викликати API в Python сервісах, скриптах, агенті або конвеєрах даних | [Інтеграція Python SDK](https://platform.acedata.cloud/documents/x402-python-sdk) |
| Оплата замовлень | Використовувати X402 для оплати замовлень в консолі Ace Data Cloud | [Посібник з оплати замовлень](https://platform.acedata.cloud/documents/x402-order-payment) |
| Мережа та способи оплати | Ознайомитися з активами, підписами та сценаріями використання Base, SKALE, Solana | [Мережа та способи оплати](https://platform.acedata.cloud/documents/x402-networks) |
| `exact` та `upto` | Розрізняти API з фіксованою ціною та API з постоплатою | [Опис схем оплати](https://platform.acedata.cloud/documents/x402-metered-upto) |
| Опис цін | Ознайомитися з відношенням цін X402 до одиничної вартості Credits та реальними цінами на послуги | [Опис цін X402](https://platform.acedata.cloud/documents/x402-pricing) |
| Facilitator | Зрозуміти зв'язок між `verify`, `settle` та API для збору платежів на сервері | [Інтеграція Facilitator](https://platform.acedata.cloud/documents/x402-facilitator) |
| E2E та усунення несправностей | Перевірити публічні точки входу, запустити інструменти для розширеної перевірки, виявити поширені проблеми з 402, підписами та розрахунками | [E2E перевірка та усунення несправностей](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) |

## Рекомендований шлях інтеграції

Якщо ви просто хочете викликати Ace Data Cloud API, спочатку використовуйте офіційний SDK:

* TypeScript: `@acedatacloud/sdk` + `@acedatacloud/x402-client`
* Python: `acedatacloud` + `acedatacloud-x402`

Публічні адреси вихідного коду та пакетів:

| Проект | Адреса |
| - | - |
| Ace Data Cloud SDK | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) |
| X402 Client | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) |
| X402 Facilitator | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) |
| npm SDK | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) |
| npm X402 Client | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) |
| PyPI SDK | [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/) |
| PyPI X402 Client | [https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/) |

SDK автоматично виконає перший запит без аутентифікації, розпарсить `402 Payment Required`, викличе обробник платежів, повторить ці кроки з `PAYMENT-SIGNATURE`. Вам лише потрібно підготувати гаманець з USDC та вибрати мережу, яку ви хочете використовувати.

Якщо ви хочете, щоб ваш API також підтримував X402 для збору платежів, вам потрібно прочитати документацію Facilitator, щоб зрозуміти зв'язок між `paymentRequirements`, `paymentPayload`, `/verify` та `/settle`.

## Статус підтримки

Ace Data Cloud X402 вже пройшов верифікацію в публічному API, офіційному SDK, Facilitator та ланцюгових шляхах розрахунків. У таблиці нижче підсумовано поточний статус за найбільш використовуваними можливостями під час інтеграції розробниками.

| Можливість | Статус | Опис |
| - | - | - |
| Можливості Facilitator | Доступно | `https://facilitator.acedata.cloud/.well-known/x402` повертає платіжні мережі та кінцеві точки протоколу. |
| API 402 `accepts` | Доступно | Неплатежні запити повертають доступні вимоги до платежів для Base, SKALE та Solana. |
| TypeScript SDK | Доступно | `@acedatacloud/sdk` та `@acedatacloud/x402-client` автоматично обробляють 402, підписи та повтори. |
| Python SDK | Доступно | `acedatacloud` та `acedatacloud-x402` автоматично обробляють 402, підписи та повтори. |
| Base `exact` | Верифіковано в ланцюгу | Підходить для API з фіксованою сумою та оплати замовлень. |
| Base `upto` | Верифіковано в ланцюгу | Підходить для API з постоплатою, таких як чат, наразі є єдиною мережею, що пропонує `upto`. |
| SKALE `exact` | Верифіковано в ланцюгу | Підходить для сценаріїв EVM з низькими витратами на газ. |
| Solana `exact` | HTTP paid retry верифіковано | Верифіковано API paid retry та відповіді моделі; для підтвердження підпису в ланцюгу рекомендується використовувати власний Solana RPC для звірки. |
| Оплата замовлень | Верифіковано в ланцюгу | Оплата замовлень Base `exact` завершена в ланцюгових розрахунках та оновила статус замовлення. |

Наступний вихід призначений лише для ілюстрації формату повернення верифікованих шляхів. Під час фактичної інтеграції завжди орієнтуйтеся на `accepts`, повернуті поточним API.

```text theme={null}
пакети
@acedatacloud/sdk@2026.504.2 імпорт ок
@acedatacloud/x402-client@2026.531.3 імпорт ок
acedatacloud==2026.4.26.1 імпорт ок
acedatacloud-x402==2026.5.31.3 імпорт ок

API 402
статус 402
приймає eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact

TypeScript SDK
контент ADC_TS_SDK_X402_OK

Python SDK
контент ADC_PY_SDK_X402_OK

Base exact
контент ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
експлорер https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3

SKALE exact
контент ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
експлорер https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
контент ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
експлорер https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
підписаний ліміт 95215 атомних USDC
значення переказу 3 атомних USDC

Solana exact
HTTP 402 -> HTTP 200
контент ADC_SOLANA_E2E_OK
підпис чеку не підтверджено в цьому запуску

Оплата замовлення
замовлення 78481793-304e-47f7-bc0c-8231aec9cc1e стан Завершено спосіб оплати X402
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
експлорер https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
```

说明：

* npm та PyPI пакети вже успішно встановлені та імпортовані в чистому середовищі.
* Неплатеж API запит повертає 402, `приймає` містить доступні способи оплати для Base, SKALE та Solana.
* `приймає[].мережа` є CAIP-2 ідентифікатором, клієнт повинен відповідати CAIP-2 рядку при виборі мережі.
* TypeScript SDK та Python SDK можуть автоматично обробляти 402 та завершувати повторну оплату.
* Base `exact`, SKALE `exact`, Base `upto` та оплата замовлення мають відкриті адреси експлорера.
* Ліміт підпису для Base `upto` становить `95215` атомних USDC, фактичне врегулювання становить `3` атомних USDC, що відображає особливість розрахунку за фактичним використанням.
* Solana `exact` підтвердив HTTP 402 -> HTTP 200 та вихід моделі. Оскільки публічні RPC запити можуть бути обмежені, для точного звіряння рекомендується використовувати власний Solana RPC або записи розрахунків платформи для підтвердження підпису транзакції.

## Уваги при підключенні

Розробники при підключенні повинні спочатку звертати увагу на реальні вимоги до оплати, які повертаються в поточному запиті, а не копіювати приклади сум або адреси з документації:

* `приймає[].maxAmountRequired` є максимальною сумою, яку можна підписати в поточному запиті.
* `приймає[].актив` є контрактом або mint USDC, який буде використано в цьому запиті.
* `приймає[].extra.chainId`, `приймає[].extra.facilitatorAddress` та `приймає[].extra.verifyingContract` братимуть участь у підписанні EVM типізованих даних.
* `upto` вимагає, щоб гаманець спочатку надав дозвіл Permit2 для USDC цільової мережі; без дозволу буде повернуто `PERMIT2_ALLOWANCE_REQUIRED`.
* Якщо ви чітко хочете використовувати розрахунок за фактичним використанням, передайте в TypeScript SDK `preferScheme: 'upto'`, в іншому випадку SDK вибере першу доступну вимогу, повернуту сервером для цієї мережі.

## Доступні для публічної перевірки області

Перед підключенням можна перевірити ці публічні входи та поведінку SDK:

* API запити без `Authorization` або `PAYMENT-SIGNATURE` повернуть `402 Payment Required`, а `приймає` в відповіді є єдиною підставою для підпису цього запиту.
* TypeScript SDK та Python SDK обидва надають обробник платежів, рівень передачі SDK після отримання 402 викликає обробник та повторює запит.
* `https://facilitator.acedata.cloud/.well-known/x402`: повертає мережі, схеми та кінцеві точки протоколу, підтримувані Facilitator; ціна API все ще базується на 402, що повертається в реальному часі для цільового запиту.
* `https://facilitator.acedata.cloud/supported`: повертає мережі та схеми, підтримувані Facilitator.
* Репозиторій X402Client містить інструменти для верифікації на високому рівні, які можуть бути використані для підтвердження підписів, повторних спроб та поведінки врегулювання; вихід інструменту не замінює `приймає`, повернуте онлайн API.

`upto` належить до розрахунку за фактичним використанням, підходить для API, де реальне використання, таке як доповнення чату, виклики моделей тощо, стає відомим лише після відповіді. Наразі лише Base надає `upto`; якщо перевірка підпису не вдалася, перевірте, чи відповідають chain id, адреса посередника, spender, контракт USDC та дозволи Permit2 відповіді 402.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.