t-invest-skill — CLI + скилл для доступа к Т-Инвестициям

Даёт ИИ-агенту доступ к вашему брокерскому счёту Т-Инвестиций: данные, аналитику и операции по вашей команде — через T-Invest API. Вы спрашиваете обычным языком — «как мой портфель?», «почём я брал Сбер?», «какая доходность у моих облигаций?» — а агент сам вызывает встроенный CLI и отвечает по реальным данным счёта, а не по памяти. Вручную запускать CLI не нужно.

Это инструмент доступа к данным и операциям, а не инвестиционный советник: он не оказывает инвестиционного консультирования и не даёт индивидуальных инвестиционных рекомендаций (см. Дисклеймер).

Что умеет

• Портфель: позиции и P/L, реальная доходность (XIRR с учётом пополнений и выводов), структура (классы активов, секторы, валюты, страны, концентрация), календарь пассивного дохода (купоны + дивиденды), свободные деньги, операции с комиссиями.
• Рынок и бумаги: котировки, история цены с бенчмарком (IMOEX), стакан, лента обезличенных сделок, техиндикаторы (RSI/SMA/MACD), расписание торгов, карточки любых активов, облигации с расчётом YTM и дюрации, дивиденды, фундаментал, прогнозы аналитиков.
• Скринеры: облигации (по YTM / сроку / риску) и акции (по фундаменталу) по всему справочнику с локальным кэшем.
• Информация: новости, сделки инсайдеров, календарь отчётностей, сигналы стратегий, вотчлист.
• Торговля: заявки и стоп-заявки — в песочнице свободно, на боевом счёте с обязательным подтверждением каждой сделки; в режиме «только чтение» мутации заблокированы кодом.

Доходность к погашению и дюрация облигаций, XIRR-доходность счёта считаются самим CLI — T-Invest API готовых значений не отдаёт. Для флоатеров, амортизации и бессрочных выпусков YTM честно возвращается пустым с указанием причины.

Установка

Нужно: Node.js ≥ 20 (единственная внешняя зависимость — весь код вшит в один файл, npm-пакеты и сборка не требуются) и агент, умеющий читать SKILL.md и запускать shell-команды.

Быстро — одной командой (Linux / macOS / WSL). Скачает скилл и распакует его в каталоги скиллов (~/.agents/skills/ — общий для агентов, ~/.claude/skills/ — Claude Code), а также создаст шаблон ~/.config/tinvest/.env (без токенов):

curl -fsSL https://raw.githubusercontent.com/nyxandro/t-invest-skill/main/install.sh | bash

Повторный запуск обновляет скилл и НЕ трогает уже вписанные токены. Скилл сам подскажет (в session status), когда в репозитории появится новая версия.

Вручную. Скилл — это папка с SKILL.md, scripts/, references/. Скачай .skill (кнопка в шапке или Releases) — это ZIP-архив — и распакуй в каталог скиллов своего агента (~/.agents/skills/ у большинства, ~/.claude/skills/ у Claude Code; сам файл-архив не подхватывается):

unzip t-invest.skill -d ~/.agents/skills/     # или -d ~/.claude/skills/ для Claude Code
# → <каталог>/t-invest/{SKILL.md, scripts/tinvest.cjs, references/}

После установки скилл подхватывается автоматически (перезапусти сессию агента).

Токены и режимы

CLI работает в трёх режимах, у каждого — собственный токен:

Токены выпускаются в личном кабинете Т-Инвестиций → «Токены T-Invest API» (уровень доступа под режим — по таблице выше; пошагово — в инструкции по выпуску токена). Кладутся в единственный файл ~/.config/tinvest/.env:

mkdir -p ~/.config/tinvest
cat > ~/.config/tinvest/.env <<'EOF'
T_INVEST_TOKEN_SANDBOX=      # песочница
T_INVEST_TOKEN_READONLY=     # боевой счёт, уровень «Только просмотр»
T_INVEST_TOKEN_FULL=         # боевой счёт, уровень «Торговля» (НЕ «Торговля и переводы»)
EOF
chmod 600 ~/.config/tinvest/.env

Заполните только нужные режимы. CLI читает .env только из ~/.config/tinvest/.env (не из текущей папки) — детерминированно, из любой директории запуска; реальные переменные окружения имеют приоритет (штатный способ для CI/контейнеров). Без токена — ошибка APP_TINVEST_TOKEN_MISSING, никаких значений по умолчанию. Уровень «Торговля и переводы» не нужен: CLI переводов и выводов средств не делает.

Реальные деньги: гейт и безопасность

Само наличие full-токена не разрешает торговать. Реальные сделки открываются флагом в окружении, и каждая требует подтверждения. Лестница гейтов работает в коде, до обращения к API:

T_INVEST_ALLOW_TRADING=true   # разрешить реальные сделки (каждая — с подтверждением)
T_INVEST_STONKS_MODE=true     # ОПАСНО: сделки без подтверждений (осознанный opt-in)

Что защищает деньги:

• Подтверждение каждой сделки — агент ставит --confirm только после того, как вы явно согласовали конкретную заявку.
• Гард ликвидности — перед реальной рыночной заявкой проверяются стакан и спред; на неликвиде/широком спреде заявка блокируется и предлагается лимитная.
• Ключ идемпотентности (--order-id) — защита от дублирования заявки при повторе после сетевого сбоя.
• Аудит-журнал — каждая мутация (реальная и в песочнице) дописывается в ~/.config/tinvest/trades.log: время, режим, бумага, лоты, цена, номер заявки.

Деньги нельзя вывести со счёта: токен уровня «Торговля» и отсутствие в коде методов перевода/вывода означают, что возможны только операции с бумагами внутри самого счёта. Честная оговорка: разделение режимов и гейт торговли — защита штатных путей (флаг + подтверждение), а не криптография; владелец окружения может включить флаг сам, но это осознанное явное действие.

Как это работает

Активный режим — персистентная памятка. В начале каждого диалога скилл спрашивает, в каком режиме работать, и перезаписывает выбор (по умолчанию readonly, самый безопасный) — так новый запуск или другая сессия не наследует режим молча. Сама память нужна для удобства в пределах диалога (не передавать --mode на каждой команде) и чтобы пережить потерю контекста; источник правды — session status. Пока режим не подтверждён, команды с данными не выполняются (APP_TINVEST_SESSION_REQUIRED); переключить режим можно в любой момент (session start --mode <режим>).

Параллельные агенты (необязательно). Если под одним пользователем одновременно работают несколько агентов/сессий, задайте каждому свой TINVEST_SESSION_ID — тогда их активные режимы раздельные и не перезаписывают друг друга. Для одного агента не нужно (все делят один общий файл режима).

Кэш. Списки инструментов (сутки) и графики купонов (неделя) кэшируются в ~/.config/tinvest/cache — скринеры и структура портфеля после первого прогона работают за доли секунды. Кэш можно безопасно удалить целиком.

Диагностика. Любая ошибка выводится по-русски со стабильным кодом (APP_TINVEST_...); технические детали — при запуске с TINVEST_DEBUG=1.

Правила поведения агента (дисциплина режимов, подтверждение каждой сделки, должная осмотрительность, интерпретация полей JSON) описаны в SKILL.md и references/ внутри пакета — агент обязан им следовать.

Дисклеймер

Это инструмент доступа к данным и операциям T-Invest API. Он не является услугой инвестиционного консультирования и не предоставляет индивидуальных инвестиционных рекомендаций (ИИР). Данные и расчёты предоставляются «как есть», информационно; все инвестиционные решения и сделки — на усмотрение и под ответственность пользователя. Аналитика (доходности, скринеры, прогнозы аналитиков) — это данные и вычисления, а не рекомендации к покупке/продаже.