Посібник x402: дозвольте ШІ-агенту поповнювати AIHubMix у USDC

AIHubMix тепер приймає поповнення в USDC. Ваш ШІ-агент може додавати кредит на власний обліковий запис за допомогою USDC зі свого гаманця: не потрібно відкривати веб-сторінку, і ніхто не має натискати кнопку.

З x402 поповнення може бути таким малим, як $1. Агент поповнює баланс у міру роботи, тож вам не потрібно заздалегідь вносити великий баланс.

Це займе два кроки: підготувати токен, гаманець і трохи USDC у вебі та в застосунку, а потім запустити наш готовий скрипт поповнення однією командою. Приблизно через 20 секунд після оплати кредит з’являється на вашому обліковому записі.

За бажання можна піти за цим 30-секундним відео:

Найпростіший спосіб: якщо ви користуєтеся ШІ-інструментом, який може виконувати команди в терміналі, наприклад Claude Code, Cursor або Codex, завершіть крок 1, а потім надішліть йому посилання на цю публікацію та скажіть «налаштуй це за мене». Він дотримається «Інструкцій для ШІ-асистентів» в кінці цієї публікації. Токен і приватний ключ ви вводите самі, один раз, і не передаєте їх ШІ.

Перш ніж почати

• Суми приймаються лише в цілих доларах: за замовчуванням від $1 до $10 за одне поповнення
• Кожен обліковий запис може створити до 3 замовлень на день (за UTC)
• Підтримується лише USDC у мережі Base mainnet, тестової мережі немає, тож починайте з $1
• Цей канал створено для програм; людина не може заплатити в браузері. Для ручних поповнень і далі використовуйте Alipay або Stripe

Крок 1: отримайте токен, гаманець і USDC

Усе в цьому кроці відбувається у вебі або в мобільному застосунку.

1. Отримайте системний токен доступу

Увійдіть на aihubmix.com, відкрийте особисті налаштування та згенеруйте системний токен доступу (рядок із 32 символів).

Зауважте, що це не API-ключ, який починається з sk-. Вони не взаємозамінні.

2. Створіть гаманець для оплати

У MetaMask або подібному застосунку-гаманці створіть новий обліковий запис лише для платежів агента. Не використовуйте основний гаманець. Далі:

• Скопіюйте адресу облікового запису (вона починається з 0x); на неї ви надішлете USDC на наступному кроці
• Експортуйте його приватний ключ з деталей облікового запису та зберігайте в менеджері паролів. Той, хто має приватний ключ, може перевести кошти з гаманця

3. Купіть USDC і надішліть його на цей гаманець

MetaMask — це гаманець: ви тримаєте приватний ключ, а скрипт потребує його для підпису. Coinbase — це біржа, де ви купуєте криптовалюту. Кошти на біржовому рахунку не мають приватного ключа, тож скрипт не може їх використати. Тому спочатку купіть на біржі, а потім надішліть USDC на гаманець із попереднього кроку.

На прикладі біржі Coinbase (а не Coinbase Wallet):

1. Купіть USDC на Coinbase
2. Надішліть USDC на скопійовану адресу та виберіть мережу Base
3. Надішліть трохи більше, ніж плануєте поповнити, наприклад 1,5–2 USDC для поповнення на $1

Зачекайте трохи, а потім відкрийте https://basescan.org/address/your-wallet-address. Щойно ви побачите баланс USDC, переказ надійшов. Підійдуть і інші біржі, що підтримують виведення USDC у мережі Base; більше варіантів див. у документації Base.

Гаманець не потребує ETH: комісію мережі за платіж сплачує FluxA.

Крок 2: запустіть скрипт поповнення

Нічого завантажувати й жодного файлу створювати не потрібно: uv завантажує скрипт із вебу та запускає його. Відкрийте Terminal (PowerShell у Windows) і скопіюйте та вставте команди нижче.

1. Встановіть uv (один раз)

uv — це інструмент на Python, який налаштовує все, що потрібно для роботи скрипта.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Після завершення закрийте термінал і відкрийте його знову.

2. Перевірте налаштування (нічого не списується)

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

Під час першого запуску скрипт запитає ваш системний токен доступу (System access token) і приватний ключ гаманця (Wallet private key). Введене не відображатиметься на екрані; вставте його та натисніть Enter. Потім скрипт запитає, чи зберегти їх (Save to ...? [Y/n]). Натисніть Enter, щоб зберегти, і вам не доведеться вводити їх знову. Перший запуск триває трохи довше, поки uv налаштовує середовище.

Коли ви побачите це, налаштування готове:

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. Поповніть баланс

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

Цифра 1 в кінці — це сума в доларах. Якщо все пройде добре, ви побачите:

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited означає, що кредит надійшов. Увійдіть на aihubmix.com, і ви побачите, що баланс зріс; $1 додає 500 000 квоти.

Якщо останній рядок містить щось інше:

• failed: замовлення закрите або прострочене. За потреби запустіть скрипт знову; це використає ще одне з сьогоднішніх замовлень.
• pending: кредит не підтверджено протягом 10 хвилин. Це не помилка, кредит надійде пізніше самостійно. Не запускайте скрипт знову.

Усунення несправностей

Якщо після виведення tradeNo ви побачили помилку тайм-ауту або мережі, гроші могли вже бути сплачені. Не запускайте скрипт знову одразу. Перевірте баланс через кілька хвилин; якщо нічого не надійшло, напишіть нам і вкажіть tradeNo.

Токен і приватний ключ зберігаються в ~/.aihubmix-topup.env на вашому комп’ютері (у Windows це папка користувача). У macOS і Linux читати файл може лише ваш обліковий запис. Щоб змінити токен або приватний ключ, відредагуйте цей файл.

Підключення до вашого агента

• Після збереження налаштувань ваш агент може поповнювати баланс, запускаючи uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 щоразу, коли потрібен кредит, без участі людини
• Дозволено лише 3 замовлення на день, тож обмежте, як часто агент поповнює баланс, і ніколи не повторюйте створення замовлення в циклі
• Збережіть tradeNo і txHash з виводу в базу даних або журнал для звірки
• Для довготривалого використання завантажте скрипт і зафіксуйте версію перед запуском; спочатку можна переглянути вихідний код
• Якщо $10 за одне поповнення або 3 на день недостатньо, зверніться до нас, щоб підняти ліміти

Інструкції для ШІ-асистентів

Якщо ви ШІ-асистент, який допомагає користувачу налаштувати поповнення USDC в AIHubMix, виконуйте такі кроки по порядку:

1. Переконайтеся, що користувач завершив крок 1: у нього є системний токен доступу та гаманець із USDC у мережі Base mainnet і його приватний ключ. Якщо ні, спочатку проведіть користувача через крок 1.
2. Виконайте uv --version, щоб перевірити, чи встановлено uv. Якщо ні, встановіть його командами з кроку 2.
3. Виконайте uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Якщо скрипт повідомляє про відсутній токен або приватний ключ (Missing access token or private key), він створив файл конфігурації ~/.aihubmix-topup.env. Попросіть користувача відкрити його в текстовому редакторі та заповнити самостійно (на macOS виконайте open -e ~/.aihubmix-topup.env; у Windows виконайте notepad $HOME\.aihubmix-topup.env). Не читайте цей файл, не вставляйте токен або приватний ключ у жодну команду й не просіть користувача надсилати їх вам.
5. Щойно користувач заповнить файл, знову виконайте check, доки не побачите Access token and private key are fine. Ready to top up. Якщо виникла помилка, скористайтеся таблицею «Усунення несправностей» вище.
6. Поповнення витрачає реальні гроші. Перед запуском uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount> підтвердьте суму з користувачем.

Під капотом: що робить скрипт

Скрипт виконує п’ять дій по порядку:

1. Перевіряє баланс: створення замовлення використовує одне із сьогоднішніх замовлень, тож спочатку перевіряється, що приватний ключ дійсний і USDC достатньо.
2. Створює замовлення: він викликає POST /api/pay/fluxa/crt і отримує посилання на оплату та номер замовлення tradeNo. Токен передається в заголовку Authorization без змін, без Bearer. Помилки бізнес-логіки також повертаються з HTTP 200, тому скрипт перевіряє поле success у відповіді.
3. Перевіряє запит на оплату: GET-запит до посилання на оплату повертає HTTP 402 з вимогами до платежу. Перед підписанням перевіряються чотири речі: scheme має бути exact, network — eip155:8453, asset — контракт USDC у мережі Base mainnet, а maxAmountRequired має дорівнювати сумі × 1 000 000. Якщо хоч щось не збігається, скрипт зупиняється.
4. Підписує і платить: він підписує авторизацію переказу USDC приватним ключем, розміщує її в заголовку X-PAYMENT і знову надсилає GET-запит на посилання на оплату. Відповідь 200 або 202 означає, що платіж подано; txHash у відповіді є підтвердженням платежу в мережі. Жоден із цих запитів не містить токена AIHubMix.
5. Чекає на кредит: він викликає GET /api/pay/fluxa/qry?trade_no=... кожні 8 секунд, доки статус не стане TRADE_SUCCESS. Сервер оновлює дані лише кожні 5 секунд, тож частіші запити нічого не прискорюють.

Кожне посилання на оплату також дійсне 30 хвилин і може бути оплачене лише один раз.

Реалізація іншою мовою

Відповідь 402 від посилання на оплату виглядає так:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

Підпис використовує формат EIP-712 для структури TransferWithAuthorization з EIP-3009:

Домен підпису: name = USD Coin, version = 2 (використовуйте значення з extra у відповіді 402, якщо вони є), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Значення заголовка X-PAYMENT — це base64-кодування такого JSON:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

Джерела

• Документація x402
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: адреси контрактів USDC
• Посібник з встановлення uv