{"id":15647445,"url":"https://github.com/vitalets/tinkoff-invest-api","last_synced_at":"2025-07-18T19:06:14.794Z","repository":{"id":45264476,"uuid":"486218609","full_name":"vitalets/tinkoff-invest-api","owner":"vitalets","description":"Node.js SDK для работы с Tinkoff Invest API","archived":false,"fork":false,"pushed_at":"2024-12-23T08:27:59.000Z","size":9342,"stargazers_count":54,"open_issues_count":5,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-03T10:07:23.056Z","etag":null,"topics":["api","nodejs","tinkoff","tinkoff-invest"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vitalets.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["vitalets"]}},"created_at":"2022-04-27T14:08:12.000Z","updated_at":"2025-06-23T20:07:01.000Z","dependencies_parsed_at":"2024-10-03T12:19:36.970Z","dependency_job_id":"8a1ef989-d210-4335-a878-efcd753a30d9","html_url":"https://github.com/vitalets/tinkoff-invest-api","commit_stats":{"total_commits":154,"total_committers":2,"mean_commits":77.0,"dds":0.00649350649350644,"last_synced_commit":"cbdcbd1bbbaf545f5a18f94f1eeef985faef2e03"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/vitalets/tinkoff-invest-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalets%2Ftinkoff-invest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalets%2Ftinkoff-invest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalets%2Ftinkoff-invest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalets%2Ftinkoff-invest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitalets","download_url":"https://codeload.github.com/vitalets/tinkoff-invest-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalets%2Ftinkoff-invest-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265815825,"owners_count":23833021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","nodejs","tinkoff","tinkoff-invest"],"created_at":"2024-10-03T12:19:28.757Z","updated_at":"2025-07-18T19:06:14.740Z","avatar_url":"https://github.com/vitalets.png","language":"HTML","funding_links":["https://github.com/sponsors/vitalets"],"categories":[],"sub_categories":[],"readme":"# tinkoff-invest-api\nNode.js SDK для работы с [Tinkoff Invest API](https://tinkoff.github.io/investAPI/).\n\n\u003c!-- toc --\u003e\n\n- [Установка](#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0)\n- [Использование](#%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)\n  * [Подключение](#%D0%BF%D0%BE%D0%B4%D0%BA%D0%BB%D1%8E%D1%87%D0%B5%D0%BD%D0%B8%D0%B5)\n  * [Unary-запросы](#unary-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B)\n  * [Стримы](#%D1%81%D1%82%D1%80%D0%B8%D0%BC%D1%8B)\n  * [Универсальный счет](#%D1%83%D0%BD%D0%B8%D0%B2%D0%B5%D1%80%D1%81%D0%B0%D0%BB%D1%8C%D0%BD%D1%8B%D0%B9-%D1%81%D1%87%D0%B5%D1%82)\n  * [Кеширование свечей](#%D0%BA%D0%B5%D1%88%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81%D0%B2%D0%B5%D1%87%D0%B5%D0%B9)\n  * [Хелперы](#%D1%85%D0%B5%D0%BB%D0%BF%D0%B5%D1%80%D1%8B)\n- [Отладка](#%D0%BE%D1%82%D0%BB%D0%B0%D0%B4%D0%BA%D0%B0)\n- [История изменений](#%D0%B8%D1%81%D1%82%D0%BE%D1%80%D0%B8%D1%8F-%D0%B8%D0%B7%D0%BC%D0%B5%D0%BD%D0%B5%D0%BD%D0%B8%D0%B9)\n- [Лицензия](#%D0%BB%D0%B8%D1%86%D0%B5%D0%BD%D0%B7%D0%B8%D1%8F)\n\n\u003c!-- tocstop --\u003e\n\n## Установка\n```\nnpm i tinkoff-invest-api\n```\n\n## Использование\n### Подключение\n```ts\nimport { TinkoffInvestApi } from 'tinkoff-invest-api';\n\n// создать клиента с заданным токеном доступа\nconst api = new TinkoffInvestApi({ token: '\u003cyour-token\u003e' });\n```\nКак получить токен доступа описано [тут](https://tinkoff.github.io/investAPI/token/).\n\n### Unary-запросы\n```ts\nimport { PortfolioRequest_CurrencyRequest } from 'tinkoff-invest-api/dist/generated/operations.js';\nimport { CandleInterval } from 'tinkoff-invest-api/dist/generated/marketdata.js';\n\n// получить список счетов\nconst { accounts } = await api.users.getAccounts({});\n\n// получить портфель по id счета\nconst portfolio = await api.operations.getPortfolio({\n  accountId: accounts[0].id,\n  currency: PortfolioRequest_CurrencyRequest.RUB\n});\n\n// получить 1-минутные свечи за последние 5 мин для акций Тинкофф Групп\nconst { candles } = await api.marketdata.getCandles({\n  figi: 'BBG00QPYJ5H0',\n  instrumentId: 'BBG00QPYJ5H0',\n  interval: CandleInterval.CANDLE_INTERVAL_1_MIN,\n  ...api.helpers.fromTo('-5m'), // \u003c- удобный хелпер для получения { from, to }\n});\n```\n\n### Стримы\nДля работы со стримом сделана обертка `api.stream`:\n```ts\nimport { SubscriptionInterval } from 'tinkoff-invest-api/dist/generated/marketdata.js';\n\n// подписка на свечи\nconst unsubscribe = await api.stream.market.candles({\n  instruments: [\n    {\n      figi: 'BBG00QPYJ5H0',\n      instrumentId: 'BBG00QPYJ5H0',\n      interval: SubscriptionInterval.SUBSCRIPTION_INTERVAL_ONE_MINUTE\n    }\n  ],\n  waitingClose: false,\n}, candle =\u003e console.log(candle));\n\n// отписаться\nawait unsubscribe();\n\n// обработка дополнительных событий\napi.stream.market.on('error', error =\u003e console.log('stream error', error));\napi.stream.market.on('close', error =\u003e console.log('stream closed, reason:', error));\n\n// получить список текущих подписок\nconst data = await api.stream.market.getMySubscriptions();\n\n// закрыть соединение\nawait api.stream.market.cancel();\n```\n\u003e Примечание: со стримом можно работать и напрямую через `api.marketdataStream`. Но там `AsyncIterable`, которые менее удобны (имхо)\n\nПо умолчанию стрим автоматически переподключается при потере соединения ([#4](https://github.com/vitalets/tinkoff-invest-api/issues/4)). Чтобы это отключить, установите `api.stream.market.options.autoReconnect = false`.\n\nСтримы доступны по следующим сущностям:\n* `.candles(request, handler)`\n* `.trades(request, handler)`\n* `.orderBook(request, handler)`\n* `.lastPrice(request, handler)`\n* `.info(request, handler)`\n\n### Универсальный счет\nДля бесшовной работы со счетами в бою и песочнице сделан универсальный интерфейс `TinkoffAccount`.\n\n```ts\nimport { TinkoffAccount, RealAccount, SandboxAccount } from 'tinkoff-invest-api';\nimport { OrderDirection, OrderType } from 'tinkoff-invest-api/dist/generated/orders.js';\n\n// создать экземпляр счета: боевого или в песочнице\nconst account: TinkoffAccount = process.env.USE_REAL_ACCOUNT\n    ? new RealAccount(api, '\u003creal-account-id\u003e')\n    : new SandboxAccount(api, '\u003csandbox-account-id\u003e');\n\n// получить портфель\nconst protfolio = await account.getPortfolio();\n\n// получить список заявок\nconst { orders } = await account.getOrders();\n\n// создать лимит-заявку на покупку 1 лота по цене 100\nconst order = await account.postOrder({\n  figi: 'BBG00QPYJ5H0',\n  quantity: 1,\n  price: api.helpers.toQuotation(100),\n  direction: OrderDirection.ORDER_DIRECTION_BUY,\n  orderType: OrderType.ORDER_TYPE_LIMIT,\n  orderId: '\u003crandom-id\u003e',\n});\n```\n\nВсе методы универсального счета можно посмотреть [тут](https://github.com/vitalets/tinkoff-invest-api/blob/main/src/account/real.ts).\n\n### Кеширование свечей\nКеширование свечей позволяет сократить кол-во запросов к API, а также удобно получать нужное кол-во свечей за любой период времени (в исходном API есть ограничения на диапазоны дат запроса). Для загрузки свечей с учетом кеша используется класс `CandlesLoader`:\n```ts\nimport { TinkoffInvestApi, CandlesLoader } from 'tinkoff-invest-api';\nimport { CandleInterval } from 'tinkoff-invest-api/dist/generated/marketdata.js';\n\nconst api = new TinkoffInvestApi({ token: '\u003cyour-token\u003e' });\n\n// создать инстанс загрузчика свечей\nconst candlesLoader = new CandlesLoader(api, { cacheDir: '.cache' });\n\n// загрузить минимум 100 последних свечей (в понедельник будут использованы данные пятницы, итп)\nconst { candles } = await candlesLoader.getCandles({\n  figi: 'BBG004730N88',\n  instrumentId: 'BBG004730N88',\n  interval: CandleInterval.CANDLE_INTERVAL_15_MIN,\n  minCount: 100, // \u003c- этот параметр позволяет задать кол-во свечей в результате\n});\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eДля кеширования `CandlesLoader` создает на файловой системе следующую структуру:\u003c/summary\u003e\n\n```\n.cache\n  candles\n    \u003cfigi\u003e\n      1_min\n        2022-05-01.json\n        2022-05-02.json\n      5_min\n        2022-05-01.json\n        2022-05-02.json\n      15_min\n        2022-05-01.json\n        2022-05-02.json\n      hour\n        2022-05-01.json\n        2022-05-02.json\n      day\n        2020.json\n        2021.json\n        2022.json\n```\n\u003c/details\u003e\n\n### Хелперы\nДля более удобной работы есть несколько хелперов:\n```ts\nimport { Helpers } from 'tinkoff-invest-api';\n\n/**\n * Переводит число в Quotation.\n * Пример: 123.4 -\u003e { units: 123, nano: 400000000 }\n */\nHelpers.toQuotation(value: number): Quotation;\n\n/**\n * Переводит число в MoneyValue.\n * Пример: (123.4, 'rub') -\u003e { units: 123, nano: 400000000, currency: 'rub' }\n */\nHelpers.toMoneyValue(value: number, currency: string): MoneyValue;\n\n/**\n * Переводит MoneyValue в строку.\n * Пример: { units: 123, nano: 400000000, currency: 'rub' } -\u003e '123.4 rub'\n */\nHelpers.toMoneyString(value: MoneyValue | undefined): string;\n\n/**\n * Переводит Quotation или MoneyValue в число.\n * Пример: { units: 123, nano: 400000000 } -\u003e 123.4\n */\nHelpers.toNumber(value: Quotation | MoneyValue): number;\n\n/**\n * Возвращает интервал времени в формате { from, to } по заданному смещению и базовой дате.\n * Для смещения можно использовать кол-во миллисекунд или строку в формате из https://github.com/vercel/ms.\n * Пример: получить { from, to } за последние 5 минут -\u003e fromTo('-5m')\n */\nHelpers.fromTo(offset: string | number, base?: Date): { from: Date; to: Date; };\n\n/**\n * Переводит значения констант в человеко-читаемые строки.\n * Например: CandleInterval.CANDLE_INTERVAL_1_MIN -\u003e '1_MIN'\n */\nHelpers.toHuman\u003cT extends Enums\u003e(value: T, values: getEnumType\u003cT\u003e): string;\n```\n\n## Отладка\nДля отладки используется модуль [debug](https://github.com/debug-js/debug).\nЧтобы вывести отладочную информацию, нужно указать переменную окружения `DEBUG`:\n\n```\nDEBUG=tinkoff-invest-api:* node robot.js\n```\n\n## История изменений\n\n#### 7.0.1\n* Исправлена опечатка при получении лимитов ([#14](https://github.com/vitalets/tinkoff-invest-api/issues/14), [#26](https://github.com/vitalets/tinkoff-invest-api/pull/26), [@devoln](https://github.com/devoln))\n\n#### 7.0.0\n* Обновление версии протокола до 1.24 ([#24](https://github.com/vitalets/tinkoff-invest-api/issues/24), [@Jokky](https://github.com/Jokky))\n\n## Лицензия\nMIT @ [Vitaliy Potapov](https://github.com/vitalets)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitalets%2Ftinkoff-invest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitalets%2Ftinkoff-invest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitalets%2Ftinkoff-invest-api/lists"}