ponscli

Неофициальный интерфейс командной строки для лаунчпада Pons в Robinhood Chain (chain ID 4663), созданный для разработчиков и агентов. Не связан с Pons или Robinhood; он читает публичные контракты в публичной сети.

• По умолчанию — только чтение. CLI никогда не видит приватный ключ. Подпись — это явное согласие, поэтому агент не может случайно потратить средства.

• Структурированный вывод везде. --json есть в каждой команде и включается автоматически, когда stdout не является терминалом. Ошибки тоже структурированы и имеют стабильные коды выхода.

• Значения протокола читаются из сети. Комиссии, налоговые окна и список одобренных парных токенов запрашиваются в реальном времени, а не зашиты в код. Значения в сети отличаются от исходного кода контракта.

• Двухуровневый RPC. Бесплатные эндпоинты поочерёдно используются в Tier 1; платный эндпоинт в Tier 2 подключается только после полного исчерпания Tier 1. Без платных учётных данных пакетная работа деградирует, а не превращает сбой в счёт.

• Два бинарника. pons — для людей, pons-mcp — для моделей, на одном и том же ядре, поэтому цена, которую видит агент, совпадает с ценой, которую выводит CLI.

Установка

npm install -g ponscli
pons --version

Или вообще без установки. Пакет называется ponscli, а бинарник — pons, поэтому npx нужно явно указать, что запускать:

npx -p ponscli pons info 0x44D6…20f4

Две версии Node важны, и это не одна и та же версия. CLI работает на 20.11 или новее; CI проверяет это при каждом пуше, устанавливая собранный tarball именно на эту версию. Для сборки нужна 20.19 или новее, потому что этого требует дерево зависимостей линтера. Из клона npm install собирает проект в рамках установки, а npm run dev -- <command> запускает его из исходников.

Related MCP server: r0x-os

Быстрый старт

Для чтения не нужны ключ, кошелёк и конфигурация.

pons info 0x44D6…20f4             # price, reserves, graduation phase, live snipe tax
pons pairs                        # every quote asset a launch may be priced in
pons watch 0x44D6…20f4            # follow one launch's trades as they happen
pons tx 0x2e8d…f58e               # receipt, decoded logs, and why a failure failed
pons doctor                       # probe every RPC endpoint with real calls

Для торговли нужен ключ. Ничего не подписывается, пока вы этого не скажете.

pons wallet create                          # generate a key into an encrypted keystore
pons buy  0x44D6…20f4 0.05                  # price it, simulate it, print it. Nothing is sent
pons buy  0x44D6…20f4 0.05 --dry-run        # the same, said explicitly
pons buy  0x44D6…20f4 0.05 --confirm        # sign and broadcast
pons sell 0x44D6…20f4 50% --slippage 200

Всё машиночитаемо при передаче через конвейер, и это режим по умолчанию:

pons info 0x44D6…20f4 | jq .graduation

Команды

Полный справочник, включая то, с каким контрактом работает каждая команда: docs/commands.md.

Чтение, ключ не требуется

Торговля, с RPC и ключом

Запуск

Комиссии

Кошелёк и настройка

Два поколения

Pons запускал токены через две фабрики, и обе поддерживаются. Вам никогда не нужно указывать, какую вы имеете в виду: опрашиваются оба реестра, и ответ определяет всё дальнейшее.

Фабрика V1 выведена из эксплуатации. launchEnabled() возвращает false с 2026-08-12, и транзакция, установившая это значение, — последнее, что фабрика когда-либо эмитировала; после неё ни один адрес не был включён в белый список, поэтому pons launch --generation v1 отказывается работать, ничего не создав. С токенами V1 дело обстоит иначе. Тысячи из них всё ещё содержат ликвидность, а выборка из сорока пулов показала 223 свопа менее чем за шесть дней — именно поэтому чтение и торговля ими полностью поддерживаются.

Торговля

Каждая операция записи сначала строит Plan: что будет отправлено, кому, что ожидается получить взамен и о чём стоит предупредить. Этот же Plan симулируется и подписывается, так что эти три составляющие не могут разойтись.

Четыре особенности, о которых стоит знать:

• Вам не нужно выбирать площадку. В записи о запуске указано, где торгуется токен. --route curve|v4|v3 переопределяет этот ответ, а не ищет маршрут.

• Нижняя граница фиксируется, когда вы её принимаете. План перестраивается на основе актуального состояния сети непосредственно перед отправкой, и принятая вами нижняя граница переносится в перестроенный план, а не пересчитывается по новой цене. Сделка не может быть подписана ниже одобренной вами границы, а если цена ушла за неё, ничего не отправляется вовсе.

• Продажа в кривую, достигшую порога, перенаправляется, а не завершается ошибкой. Кривая прекращает торговлю, как только собрала достаточно средств, и вызвать pons graduate <token> может любой.

• При продаже V1 WETH разворачивается за вас. Пулы V1 хранят WETH, а не ETH, поэтому при продаже выручка остаётся на роутере и разворачивается в той же транзакции. Продажа очевидным способом тоже сработала бы, но оставила бы вас с WETH.

Запуск

pons launch --name "My Token" --symbol MINE --desc "..."      # plan it and simulate it. Nothing is sent
pons launch --name "My Token" --symbol MINE --dry-run         # the same, said explicitly
pons launch --name "My Token" --symbol MINE \
  --pair USDG --creator-tax 250 --dev-buy 100 --confirm       # launch, quoted in USDG

Запуск — единственное, что здесь нельзя отменить. Прежде чем построить транзакцию, команда печатает всё, на что вы соглашаетесь: адрес, по которому будет создан токен, предложение, куда он выйдет после завершения кривой, распределение комиссий и действие налога на снайперские покупки. Она также локально проверяет всё, что фабрика отклонила бы в сети.

• Адрес известен до отправки. Оба поколения разворачиваются через CREATE2 на основе соли, которую вы выбираете, поэтому pons launch заранее печатает адреса токена и кривой и отклоняет уже занятую соль. --salt принимает сырое 32-байтовое значение, так что работает и подобранный ванити-адрес.

• Условия закреплены. previewLaunchEconomics возвращает дайджест, охватывающий предложение, комиссию кривой, уровень комиссии пула и долю комиссии протокола, и он передаётся вместе с запуском. Если владелец протокола изменит любой из этих параметров, пока ваша транзакция находится в обработке, запуск откатится, а не будет молча переоценён.

• --dev-buy атомарен, и это необходимо. Фабрика V2 требует ровно комиссию за запуск и ничего сверх, поэтому стартовая покупка не может быть добавлена к ней; вместо этого покупка проходит через собственный роутер лаунчпада в той же транзакции. Запуск без такой покупки был полностью выкуплен в течение двух блоков в этой сети.

• --buyback обходится вам, а не держателям. Казна наполняется полностью из вашей собственной доли комиссий и высвобождается в течение пяти лет с разделением с протоколом. Это не распределение среди держателей, и план сообщает об этом как о предупреждении, а не как о сноске.

pons pairs перечисляет активы, в которых может быть номинирован запуск: нативный ETH плюс двадцать три одобренных токена — это токенизированные акции, два индексных фонда и один стейблкоин. Они возвращаются в том порядке, в котором их отображает страница создания Pons, так что оба списка совпадают строка в строку.

Безопасность

• По умолчанию — только чтение. Ни одна команда ничего не подписывает без --confirm. Три из четырёх режимов выполнения ничего не стоят, и каждый из них, кроме --unsigned, сначала проверяет вызов по развёрнутым контрактам, не требуя средств на счету.

• Хранилище ключей — это scrypt + AES-256-GCM, записывается с доступом только для владельца. Пароль берётся из скрытого ввода или PONS_PASSWORD; ключ для импорта — из PONS_PRIVATE_KEY.

• Ни то, ни другое не передаётся флагом. Аргумент виден в таблице процессов и попадает в историю оболочки. Не существует флага, который принимал бы пароль или ключ, и pons config list сообщает об этом там, где кто-то стал бы его искать.

• Учётные данные никогда не попадают в строки журнала. Платный эндпоинт несёт свой ключ в URL, а сообщения об ошибках содержат URL, поэтому URL маскируются внутри выбрасываемых ошибок, а не только в форматированном выводе.

• MCP-сервер не может подписывать. Он никогда не загружает хранилище ключей и никогда не отправляет транзакции в сеть. См. docs/agents.md.

• Нативный перевод подписывается с фиксированным лимитом газа 100 000. Nitro списывает стоимость публикации в L1 из собственного лимита транзакции, и eth_estimateGas об этом не сообщает; при 21 000 перевод работает, пока L1 дёшев, и периодически сбоит, когда это не так.

Нашли то, что может стоить кому-то денег? Пожалуйста, сообщите об этом приватно. В SECURITY.md описано, как это сделать, что входит в область ответственности и какие гарантии даёт архитектура.

Конфигурация

Значения разрешаются по лестнице: флаг > переменная окружения > файл конфигурации > значение по умолчанию. pons config list печатает разрешённое значение вместе с уровнем, из которого оно взято, так что неожиданная настройка находится в одной команде от объяснения.

Файл конфигурации — это плоский JSON в $XDG_CONFIG_HOME/ponscli/config.json (если его нет, используется ~/.config/ponscli/config.json), доступный на запись только владельцу.

PONS_PASSWORD и PONS_PRIVATE_KEY читаются из окружения, но намеренно не являются ключами конфигурации: ни тому, ни другому не место в файле, который печатает config list и который пользователи вставляют в отчёты об ошибках.

Архитектура

Полный документ со всеми решениями и измерениями, стоящими за ними, находится в docs/architecture/ponscli.md. Кратко о структуре:

src/core/       business logic, framework-free
src/commands/   thin CLI wiring
src/mcp/        the MCP server, also thin
src/chain/      the RPC waterfall
src/abi/        generated and committed

Оба фронтенда — это оболочки над src/core/. Именно это делает pons-mcp обёрткой, а не второй реализацией.

Как маршрутизируются запросы

Уровень 1 — это round-robin по бесплатным эндпоинтам; уровень 2 — это платный эндпоинт, к которому обращаются только после того, как перепробованы все кандидаты уровня 1. Каждое правило основано на измерениях собственных эндпоинтов этой сети, а не на универсальной политике повторов. Те, что важнее всего в повседневной работе:

• Реверт — это ответ, а не ошибка. Он возвращается вам напрямую, а не повторяется на всех эндпоинтах и затем эскалируется на платный уровень.

• Ограничение частоты запросов ставит эндпоинт на паузу на 30 секунд, а не на час. Бесплатные эндпоинты — это токен-бакеты; долгая пауза стоит больше доступности, чем само троттлинг.

• Записывающие операции никогда не идут по кругу. Nonce, взятый на одной ноде и отправленный на другую, даёт nonce too low, поэтому транзакции привязываются к одному эндпоинту.

• eth_chainId — это не проверка работоспособности. Один публичный эндпоинт отвечает на него быстрее любого другого, а затем отклоняет eth_call. pons doctor зондирует реальными вызовами именно по этой причине.

ABI

src/abi/ генерируется и сохраняется в репозитории, поэтому CLI работает офлайн, а изменение интерфейса появляется в виде просматриваемого diff.

npm run abi:fetch     # regenerate from Sourcify, falling back to Blockscout
npm run abi:check     # fail if the committed files have drifted

Каждый файл фиксирует, откуда взят его ABI и как было доказано совпадение. Есть четыре класса происхождения, потому что контракты различаются:

Один файл написан вручную: erc20Errors.ts, содержащий ошибки, с которыми ревертятся сторонние котируемые активы. Котируемый актив — это чей-то чужой токен; не существует единого ABI, покрывающего двадцать три одобренных актива, и без них самый обычный сбой при запуске USDG печатается как четыре необъяснимых байта.

Для агентов

Полное руководство: docs/agents.md.

pons-mcp поставляется в этом пакете как второй исполняемый файл и обращается к тому же core/, что и CLI.

// claude_desktop_config.json, .mcp.json, or your client's equivalent
{
  "mcpServers": {
    "pons": { "command": "pons-mcp" }
  }
}

Шесть инструментов: pons_info, pons_pairs, pons_plan_buy, pons_plan_sell, pons_transaction, pons_endpoints.

Сервер не может подписывать, и флага, который это включает, не существует. Он читает сеть и собирает неподписанные транзакции; отправляет их человек. В этом вся модель безопасности, и именно поэтому сервер безопасно оставлять работающим рядом с моделью: худшее, что может сделать сбитый с толку агент, — это назвать вам плохую цену, а не потратить ваши деньги.

Ответы возвращаются в базовых единицах, потому что модель может выполнять точную арифметику над 50000000000000000, а над 0.05 — нет.

Для агента, который вместо этого вызывает CLI как внешнюю команду, --json уже используется по умолчанию, когда stdout не является терминалом, а ошибка в аргументах содержит строку usage упавшей команды, чтобы вызывающий код мог исправиться:

{
  "ok": false,
  "error": {
    "code": "USAGE",
    "message": "missing required argument 'token'",
    "hint": "run 'pons info --help'",
    "details": { "command": "info", "usage": "pons info [options] <token>" }
  }
}

Агентное программирование

Этот репозиторий содержит собственную конфигурацию для агентов. CLAUDE.md — это краткое описание проекта, а AGENTS.md симлинкуется на него для Codex, Cursor, Copilot и других.

Тестирование

npm run typecheck
npm run lint
npm test
npm run build

Набор тестов полностью офлайн. Каждый тест прогоняет реальную поверхность команд через test/fakeChain.ts — таблицу адрес + ABI + функция → результат, которая также обслуживает Multicall3 и eth_getLogs, так что проверяются те же декодирование и агрегация, которые использует живой путь.

Две проверки выходят в сеть и намеренно не входят в npm test:

npm run test:sequence   # prove multi-block sequences against live mainnet state
npm run abi:check       # fail if a committed ABI has drifted from its verified source

Последовательности, без локальной ноды

Симуляция доказывает один вызов на одном блоке. Она не может доказать, что approve войдёт в блок и продажа в следующем блоке затем удастся, или что запуск подтвердится и созданная им кривая станет доступной для покупки блоком позже. Именно эти сбои доходят до пользователя.

Сеть Robinhood поддерживает eth_simulateV1, которая выполняет несколько блоков из нескольких вызовов, перенося состояние через все них, на живом состоянии мейннета. npm run test:sequence использует её, чтобы доказать шесть последовательностей, включая полный жизненный цикл запуска: создание, торговлю, проведение за порог выпуска (graduation) и посев в пул Uniswap V4. Никакой локальной ноды, никакого Foundry, ничего не потрачено.

Каждая последовательность несёт контроль, который обязан провалиться. Без него переопределение состояния могло бы делать ту работу, которую последовательность, как кажется, доказывает.

Намеренная трата реальных денег

scripts/mainnet-e2e.sh запускает токен, покупает его, продаёт его и забирает комиссии на мейннете, по-настоящему. Последовательности уже покрыты проверкой выше, так что этот скрипт добавляет единственное, чего не может симуляция: реальную транзакцию, подписанную реальным ключом, принятую реальным мемпулом, с реальной квитанцией для декодирования. Он выключен, пока вы явно об этом не попросите, спрашивает перед каждой транзакцией и никогда не должен запускаться в CI.

PONS_E2E=i-understand ./scripts/mainnet-e2e.sh

Коды возврата

Скрипты и агенты могут выбирать ветку по результату, не разбирая текст.

В случае ошибки в режиме --json в stderr записывается {"ok": false, "error": {...}}, и никогда в stdout, так что по конвейеру передаются только результаты.

Участие в разработке

Смотрите CONTRIBUTING.md, а SECURITY.md — для всего, что не должно быть публичным issue. Короткая версия: прогоните четыре проверки выше, размещайте новое поведение в src/core/ и проверяйте любое утверждение о протоколе на мейннете, прежде чем записывать его. Исходные коды контрактов устарели в нескольких важных местах.

О проекте

Написан с нуля на TypeScript с использованием viem. Ни один исходный код не скопирован из какого-либо репозитория: поверхность команд выведена из поведенческой карты chainstacklabs/pumpfun-cli, а политика RPC — из измерений, выполненных на собственных эндпоинтах этой сети.

Сам Pons находится на ponsfamily.com: веб-клиент для запуска и изучения, его аналитика и его документация. Этот CLI не является его частью, не одобрен им и обращается к тем же публичным контрактам, к которым может обратиться кто угодно.

Лицензия

MIT. См. LICENSE.