tbank-mobile-api

Неофициальный Python-клиент для мобильного API Т‑Банка (бывший Тинькофф), полученный обратной разработкой Android‑приложения (com.idamob.tinkoff.android). Предназначен для личного использования — чтения собственных счетов, выгрузки операций в инструменты учёта финансов и тому подобного.

⚠️ НЕОФИЦИАЛЬНЫЙ. Не имеет отношения к АО «Т‑Банк». Библиотека работает с недокументированным API, который может измениться в любой момент. Используйте на свой страх и риск.

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

import datetime as dt
from tbank import TBankClient
from tbank.storage import FileStorage

with TBankClient(storage=FileStorage("~/.tbank")) as client:
    # Интерактивный логин (только при первом запуске) —
    # спросит телефон, код из СМС и пароль
    if not client.is_authenticated():
        client.login_interactive()

    # Типизированный бизнес‑API
    for account in client.accounts.list():
        balance = account.balance.amount if account.balance else "n/a"
        print(f"{account.id}  {account.type}  {balance}")

    # Операции за последние 90 дней по последнему счёту
    end = dt.datetime.now(dt.UTC)
    start = end - dt.timedelta(days=90)
    for op in client.operations.list(account=account.id, start=start, end=end):
        print(f"{op.time:%Y-%m-%d}  {op.type}  {op.amount.amount}  {op.description}")

Готовые сквозные примеры лежат в examples/.

Возможности

Авторизация

• Полный интерактивный SMS-флоу: телефон → код из СМС → селфи (со скипом) → пароль → обмен кода на токены — реализован той же последовательностью запросов, что и мобильное приложение.
• OAuth 2.0 + PKCE (RFC 7636) с методом S256. Verifier сохраняется между шагами и автоматически удаляется после успешного обмена.
• 64-полевой device fingerprint с SHA-512 anti-DDoS proof (ssoData), посчитанный по той же формуле, что и в Android-приложении. Корректность хеша запинена ground-truth тестом против Java-эталона.
• Типизированный конечный автомат шагов — EntryStep, OtpStep, SelfieStep, PasswordStep, AuthComplete, UnknownStep. Можно пройти флоу через высокоуровневый client.login_interactive(...) с кастомными prompt-callable, либо вручную через client.begin_auth() и match-диспетчеризацию.
• Кастомные UI-интеграции: prompt-функции принимают типизированный step-объект, так что флоу одинаково встраивается в Telegram-бот, GUI, веб-форму или CLI.
• Refresh-токены работают неделями: long-lived refresh_token ротируется на каждом обновлении, библиотека сама применяет grant_type=refresh_token к классическому SSO-эндпоинту.
• Persistent device identity: device_id, tinkoff_device_id, stable_id генерируются один раз и переживают перезапуски процесса — банк видит вас как одно и то же устройство, повторная авторизация не требуется.
• Headless-friendly: селфи-шаг автоматически скипается с camera_unavailable (на сервере это валидная причина), пароль читается через getpass.

Бизнес-API

• Список счетов через client.accounts.list() — GET /v1/accounts_light. Возвращает типизированные Account с балансом, валютой, кредитным лимитом, флагами видимости/совместного доступа и описанием программы лояльности.
• Поддержка всех типов счетов банка: Current, Saving, CreditCard, Telecom, Deposit, Loan, SharedAccount, плюс ExternalAccount (привязанные карты других банков по open banking, для них balance is None).
• Список операций через client.operations.list(account, start, end) — GET /v1/operations. Возвращает типизированные Operation за произвольный период.
• Богатая модель транзакций: для каждой операции доступны сумма в валюте операции и валюте счёта, тип (Credit/Debit), группа (PAY/INCOME/TRANSFER), описание, мерчант с логотипом, MCC, пользовательская и банковская категории, кэшбек, маскированный номер карты, отправитель/получатель, тип платежа.
• Корректная обработка переводов между своими счетами: распознаются inner-transfer пары и проставляется inner_counterpart_id — можно строить двусторонние постинги для бухгалтерских инструментов (beancount, hledger и т.п.) без задвоения сумм.
• Распознавание валютной конвертации через op.is_conversion, когда валюта операции отличается от валюты счёта (например, покупка в USD списанная с RUB-счёта).
• Точная арифметика денег: суммы лежат в decimal.Decimal, парсинг идёт через Decimal(str(...)) — никаких float-артефактов вроде 221112.9899999....

Качество кода

• Полная типизация, проходит mypy --strict. Включает py.typed marker — если ваш проект на mypy, он автоматически подхватит типы.
• Frozen-dataclasses со slots для всех value objects: модели иммутабельные, безопасны в многопоточной работе, дружат с hashing/equality.
• Forward-compat через raw: каждая модель сохраняет полный оригинальный JSON в атрибуте .raw, так что вы можете дотянуться до любого ещё не смоделированного поля без даунгрейда на нетипизированный доступ.
• Аккуратная обработка неизвестных значений: новые типы счетов или шагов авторизации приходят на сервере — библиотека не падает, а возвращает строку или UnknownStep соответственно.
• Иерархия исключений с конкретными подклассами для транспортных ошибок, HTTP-ответов, rate limit'а, истечения SSO-сессии, провала refresh'а и т.п. — можно ловить точечно.
• 95 unit-тестов покрывают парсеры моделей, fingerprint (включая ground-truth для anti-DDoS hash), PKCE, storage, step-машину и cookie helpers.

Транспорт и эксплуатация

• Авторефреш токенов: библиотека проактивно обновляет access_token за 60 секунд до истечения и автоматически повторяет запрос один раз при ответе 401. Можно отключить через auto_refresh=False.
• Per-host rate limit — по умолчанию не более одного запроса в секунду к одному хосту, чтобы не упереться в антифрод. Настраивается параметром rate_limit_interval (или 0 для отключения).
• Контекст-менеджер: with TBankClient(...) as client: корректно закрывает HTTP connection pool на выходе.
• Подключаемое хранилище через интерфейс Storage. В коробке идут FileStorage (атомарные записи через tmp+rename, права 0o600 на файлы, защита от path traversal) и MemoryStorage (для тестов). Свой бэкенд легко обёртывает Keychain, Vault, БД и прочее.
• Кастомизация устройства через DeviceProfile — по умолчанию библиотека маскируется под Pixel 7 на Android 14, можно подменить на любой другой плотно прописанный профиль.
• Опциональный per-request лог обмена в JSON-файлы (с автоматической редакцией паролей, refresh-токенов, code_verifier) — удобно для отладки протокола и сравнения с реальными captures.
• HTTP-клиент инжектируем: можно передать свой httpx.Client-обёртку для шеринга пула соединений между несколькими TBankClient или для моков в тестах.

Установка

pip install tbank-mobile-api

Требуется Python 3.11+.

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

Библиотека хранит access_token и refresh_token в подключённой реализации Storage. По умолчанию это FileStorage, который кладёт их в JSON‑файл на диск. Защитите каталог:

chmod 700 ~/.tbank

Если ваша модель угроз требует более серьёзной защиты, реализуйте собственный Storage‑бэкенд, оборачивающий macOS Keychain, Linux Secret Service или keyring.

refresh_token живёт долго — мобильное приложение использует его, чтобы держать сессию активной неделями простоя. Если есть подозрение, что он утёк, удалите локальный state/tokens.json и пройдите авторизацию заново с другого доверенного устройства — старая сессия будет инвалидирована во вкладке Активные сессии в приложении.

Юридическая оговорка

Этот код — clean‑room реализация сетевого протокола, который использует мобильное приложение Т‑Банка. Он не содержит ни одной строки копирайтного кода самого приложения. Библиотека предоставлена для:

• агрегации ваших собственных банковских данных в личных бюджетных инструментах;
• учебного изучения реального мобильного API;
• интероперабельности там, где официального API нет.

Библиотеку нельзя использовать для:

• несанкционированного доступа к чужим счетам;
• автоматизированного массового создания аккаунтов;
• скрейпинга на высоких скоростях;
• любых действий, нарушающих условия использования Т‑Банка.

Вы сами отвечаете за то, как вы используете свой банковский аккаунт и этот код.

Лицензия

MIT. См. LICENSE.

---

© Nikita Samoylov