Руководство 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 загрузит скрипт из интернета и запустит его. Откройте терминал (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 в день недостаточно, свяжитесь с нами, чтобы увеличить лимиты

Инструкции для ИИ-ассистентов

Если вы ИИ-ассистент, помогающий пользователю настроить пополнение AIHubMix в USDC, выполните следующие шаги по порядку:

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