Перейти до основного вмісту
Окрім прямої оплати за API-запити, Ace Data Cloud також підтримує оплату замовлень через консоль X402. Основний протокол оплати замовлень і API-викликів однаковий: перший запит повертає 402, клієнт підписує PAYMENT-SIGNATURE, а потім повторює запит із тим самим запитом. Відмінність полягає в тому, що оплата замовлення є API платформи й потребує токена облікового запису; тоді як прямий виклик AI API x402.acedata.cloud може використовувати лише X402 і не потребує API Token.

Підготовка замовлення

Перейдіть до консолі Ace Data Cloud, виберіть замовлення, яке потрібно оплатити, і запишіть ID замовлення. Якщо у вас ще немає замовлення, ви можете створити неоплачене замовлення на сторінці тарифів. Ціна замовлення визначається відображенням на сторінці, а amount у відповіді X402 402 є остаточною основою для підпису.

Створення токена облікового запису

Запит на оплату замовлення потребує токена облікового запису. Відкрийте сторінку Token платформи і створіть token у форматі platform-v1-.... Для подальших запитів використовуйте:
Токен облікового запису відрізняється від звичайного API Token. Звичайний API Token використовується для споживання API-квоти; токен облікового запису використовується для представлення вашого облікового запису під час роботи з ресурсами платформи, наприклад для оплати замовлень.

Ініціювання 402

Спочатку надішліть запит без PAYMENT-SIGNATURE:
Статус відповіді — 402, відповідь містить accepts:
Для оплати замовлення використовується офіційний x402 v2: x402Version дорівнює 2, network використовує ідентифікатор CAIP-2, а поле суми — amount. Результат виконання програми зі створення замовлення на 10 Credits та ініціювання 402:
Наведені нижче записи транзакцій є історичними фактичними прикладами за старою політикою, суми та хеші транзакцій збережено без змін. Нові замовлення X402 більше не мають знижок за способом оплати; для підпису та оплати використовуйте amount у цій відповіді 402.
Пояснення результату:
  • Після успішного створення замовлення його статус — Pending, на цей момент ще немає ончейн-оплати.
  • Перший запит pay/ не містить PAYMENT-SIGNATURE, тому повертається HTTP 402.
  • accepts одночасно надає Base exact і Solana exact; у цьому посібнику надалі вибирається Base.
  • Ціна під час створення замовлення становила 1.26, а під час оплати за старою політикою знижок X402 фактична сума підпису та розрахунку становила 1.2 USDC, що відповідає 1200000 atomic USDC.
Зверніть увагу, що resource тут є полем, яке повертається сервером і бере участь у підписі; клієнт не повинен самостійно змінювати протокол, шлях або ID замовлення в ньому.

Підписання та повторна спроба

Для оплати замовлення можна повторно використовувати @acedatacloud/x402-client або низькорівневі функції підписання acedatacloud-x402. Нижче наведено приклад TypeScript:
Результат виконання програми після підписання та повторної спроби того самого замовлення за допомогою Base exact:
Результат ончейн-підтвердження:
Пояснення результату:
  • status 200 означає, що API оплати замовлення платформи прийняв цей PAYMENT-SIGNATURE.
  • has_x_payment_response True означає, що заголовок відповіді містить закодовану в Base64 квитанцію PAYMENT-RESPONSE.
  • settle_header.success=True і network=base означають, що Facilitator завершив settlement у Base.
  • Кінцевий статус замовлення — Finished, pay_way — X402, а в pay_id записано хеш ончейн-транзакції.
  • Подія Transfer на BaseScan показує, що адреса платника переказала 1200000 atomic USDC на адресу отримання коштів платформи, тобто 1.2 USDC.

Успішна відповідь і квитанція

Після успішної оплати замовлення тіло відповіді містить інформацію про замовлення. Платформа також передає в заголовку відповіді PAYMENT-RESPONSE закодовану в Base64 settlement response, після декодування якої поширені поля включають: Якщо вам потрібна звірка, рекомендується одночасно зберігати ID замовлення, адресу гаманця платника, transaction і кінцевий статус замовлення.

Зауваження

  • Для оплати замовлення потрібен токен облікового запису платформи, не можна завершити її лише за допомогою підпису X402-гаманця.
  • amount використовує USDC atomic units, 1200000 означає 1.2 USDC.
  • Не складайте адресу отримувача або адресу активу самостійно, орієнтуйтеся на accepts у відповіді 402.
  • Якщо той самий PAYMENT-SIGNATURE буде надіслано повторно, Facilitator застосує nonce для захисту від повторного відтворення.

Відповідь про помилку оплати

Перший HTTP 402 без PAYMENT-SIGNATURE є нормальним платіжним викликом і не означає помилку оплати. Помилки перевірки або settlement після підписання все ще зберігають стандартний рядковий error як сумісний резервний варіант, а в extensions.acedatacloud.paymentError повертається стабільна структура помилки:
Клієнт повинен насамперед локалізувати за code, а для невідомого code повертатися до загальної помилки оплати. charged — це тристанове поле: false повертається лише у разі явної відмови до settlement; відсутність поля означає, що статус списання невідомий, і її не можна тлумачити як «кошти не списано». Після переходу поточного замовлення в Failed його не можна повторити як те саме замовлення, будь ласка, виправте проблему з гаманцем і створіть нове замовлення. metadata.x402.last_error і metadata.x402.errors у списку та деталях замовлень зберігають той самий набір code, stage, retryable, charged і params; публічний опис зберігається в reason, а час виникнення — у timestamp. Наприклад, insufficient_token_balance означає недостатній баланс USDC у вибраній мережі, а invalid_signature означає недійсний платіжний підпис; повторне отримання замовлення не змінить їх на загальний payment_failed. Не записуйте та не надсилайте повний PAYMENT-SIGNATURE, підпис гаманця, authorization payload, необроблену діагностику Facilitator або RPC-відповідь. Для перевірки службою підтримки достатньо ID замовлення та публічного code помилки.

Викуп і спалювання ACE для платежів Base та Solana

Після увімкнення стратегії викупу 3% від фактично отриманої суми придатних платежів Circle USDC в основній мережі Base та USDC в основній мережі Solana використовується для купівлі й спалювання ACE, без додаткового списання з гаманця платника. Нарахування виконується один раз під час поповнення, а подальші виклики API з використанням цих Credits не нараховуються повторно; для історичних замовлень зі знижкою та замовлень зі старою стратегією нарахування не застосовується автоматично заднім числом. Платежі Base зберігають платіжну квитанцію в мережі Base, а купівля та спалювання ACE асинхронно виконуються в Solana. Для придатних платежів точно нараховується 3% від фактично отриманої суми, без фіксованого ліміту суми викупу на одну транзакцію або на день; доступні кошти, ринкові котирування та ончейн-підтвердження все ще можуть впливати на час завершення. Об’єкт ace_burn у деталях замовлення надає settlement_network, settlement_transaction і execution_network, а після завершення — swap_signature і burn_signature. Pending або Processing не означає, що спалювання вже відбулося; лише Completed означає, що остаточний ончейн-доказ було перевірено. Якщо платіж Base ще не досяг остаточного підтвердження, викуп чекатиме на підтвердження, але це не впливає на Credits, що вже надійшли.