@makshuk/tinkoff-invest-api

Node.js SDK для работы с Tinkoff Invest API.

• Установка
• Использование
  • Подключение
  • Unary-запросы
  • Стримы
  • Универсальный счет
  • Кеширование свечей
  • Хелперы
• Отладка
• История изменений
• Лицензия

Установка

npm i @makshuk/tinkoff-invest-api

Использование

Подключение

import { TinkoffInvestApi } from "@makshuk/tinkoff-invest-api";

// создать клиента с заданным токеном доступа
const api = new TinkoffInvestApi({ token: "<your-token>" });

Как получить токен доступа описано тут.

Unary-запросы

import { PortfolioRequest_CurrencyRequest } from "@makshuk/tinkoff-invest-api/dist/generated/operations.js";
import { CandleInterval } from "@makshuk/tinkoff-invest-api/dist/generated/marketdata.js";

// получить список счетов
const { accounts } = await api.users.getAccounts({});

// получить портфель по id счета
const portfolio = await api.operations.getPortfolio({
  accountId: accounts[0].id,
  currency: PortfolioRequest_CurrencyRequest.RUB,
});

// получить 1-минутные свечи за последние 5 мин для акций Тинкофф Групп
const { candles } = await api.marketdata.getCandles({
  figi: "BBG00QPYJ5H0",
  instrumentId: "BBG00QPYJ5H0",
  interval: CandleInterval.CANDLE_INTERVAL_1_MIN,
  ...api.helpers.fromTo("-5m"), // <- удобный хелпер для получения { from, to }
});

Стримы

Для работы со стримом сделана обертка api.stream:

import { SubscriptionInterval } from "@makshuk/tinkoff-invest-api/dist/generated/marketdata.js";

// подписка на свечи
const unsubscribe = await api.stream.market.candles(
  {
    instruments: [
      {
        figi: "BBG00QPYJ5H0",
        instrumentId: "BBG00QPYJ5H0",
        interval: SubscriptionInterval.SUBSCRIPTION_INTERVAL_ONE_MINUTE,
      },
    ],
    waitingClose: false,
  },
  (candle) => console.log(candle),
);

// отписаться
await unsubscribe();

// обработка дополнительных событий
api.stream.market.on("error", (error) => console.log("stream error", error));
api.stream.market.on("close", (error) =>
  console.log("stream closed, reason:", error),
);

// получить список текущих подписок
const data = await api.stream.market.getMySubscriptions();

// закрыть соединение
await api.stream.market.cancel();

Примечание: со стримом можно работать и напрямую через api.marketdataStream. Но там AsyncIterable, которые менее удобны (имхо)

По умолчанию стрим автоматически переподключается при потере соединения. Чтобы это отключить, установите api.stream.market.options.autoReconnect = false.

Стримы доступны по следующим сущностям:

• .candles(request, handler)
• .trades(request, handler)
• .orderBook(request, handler)
• .lastPrice(request, handler)
• .info(request, handler)

Универсальный счет

Для бесшовной работы со счетами в бою и песочнице сделан универсальный интерфейс TinkoffAccount.

import {
  TinkoffAccount,
  RealAccount,
  SandboxAccount,
} from "@makshuk/tinkoff-invest-api";
import {
  OrderDirection,
  OrderType,
} from "@makshuk/tinkoff-invest-api/dist/generated/orders.js";

// создать экземпляр счета: боевого или в песочнице
const account: TinkoffAccount = process.env.USE_REAL_ACCOUNT
  ? new RealAccount(api, "<real-account-id>")
  : new SandboxAccount(api, "<sandbox-account-id>");

// получить портфель
const protfolio = await account.getPortfolio();

// получить список заявок
const { orders } = await account.getOrders();

// создать лимит-заявку на покупку 1 лота по цене 100
const order = await account.postOrder({
  figi: "BBG00QPYJ5H0",
  quantity: 1,
  price: api.helpers.toQuotation(100),
  direction: OrderDirection.ORDER_DIRECTION_BUY,
  orderType: OrderType.ORDER_TYPE_LIMIT,
  orderId: "<random-id>",
});

Все методы универсального счета можно посмотреть тут.

Кеширование свечей

Кеширование свечей позволяет сократить кол-во запросов к API, а также удобно получать нужное кол-во свечей за любой период времени (в исходном API есть ограничения на диапазоны дат запроса). Для загрузки свечей с учетом кеша используется класс CandlesLoader:

import { TinkoffInvestApi, CandlesLoader } from "@makshuk/tinkoff-invest-api";
import { CandleInterval } from "@makshuk/tinkoff-invest-api/dist/generated/marketdata.js";

const api = new TinkoffInvestApi({ token: "<your-token>" });

// создать инстанс загрузчика свечей
const candlesLoader = new CandlesLoader(api, { cacheDir: ".cache" });

// загрузить минимум 100 последних свечей (в понедельник будут использованы данные пятницы, итп)
const { candles } = await candlesLoader.getCandles({
  figi: "BBG004730N88",
  instrumentId: "BBG004730N88",
  interval: CandleInterval.CANDLE_INTERVAL_15_MIN,
  minCount: 100, // <- этот параметр позволяет задать кол-во свечей в результате
});

.cache
  candles
    <figi>
      1_min
        2022-05-01.json
        2022-05-02.json
      5_min
        2022-05-01.json
        2022-05-02.json
      15_min
        2022-05-01.json
        2022-05-02.json
      hour
        2022-05-01.json
        2022-05-02.json
      day
        2020.json
        2021.json
        2022.json

Хелперы

Для более удобной работы есть несколько хелперов:

import { Helpers } from '@makshuk/tinkoff-invest-api';

/**
 * Переводит число в Quotation.
 * Пример: 123.4 -> { units: 123, nano: 400000000 }
 */
Helpers.toQuotation(value: number): Quotation;

/**
 * Переводит число в MoneyValue.
 * Пример: (123.4, 'rub') -> { units: 123, nano: 400000000, currency: 'rub' }
 */
Helpers.toMoneyValue(value: number, currency: string): MoneyValue;

/**
 * Переводит MoneyValue в строку.
 * Пример: { units: 123, nano: 400000000, currency: 'rub' } -> '123.4 rub'
 */
Helpers.toMoneyString(value: MoneyValue | undefined): string;

/**
 * Переводит Quotation или MoneyValue в число.
 * Пример: { units: 123, nano: 400000000 } -> 123.4
 */
Helpers.toNumber(value: Quotation | MoneyValue): number;

/**
 * Возвращает интервал времени в формате { from, to } по заданному смещению и базовой дате.
 * Для смещения можно использовать кол-во миллисекунд или строку в формате из https://github.com/vercel/ms.
 * Пример: получить { from, to } за последние 5 минут -> fromTo('-5m')
 */
Helpers.fromTo(offset: string | number, base?: Date): { from: Date; to: Date; };

/**
 * Переводит значения констант в человеко-читаемые строки.
 * Например: CandleInterval.CANDLE_INTERVAL_1_MIN -> '1_MIN'
 */
Helpers.toHuman<T extends Enums>(value: T, values: getEnumType<T>): string;

Отладка

Для отладки используется модуль debug. Чтобы вывести отладочную информацию, нужно указать переменную окружения DEBUG:

DEBUG=tinkoff-invest-api:* node robot.js

История изменений

7.0.1

• Исправлена опечатка при получении лимитов (issue #14, PR #26, @devoln)

7.0.0

• Обновление версии протокола до 1.24 (issue #24, @Jokky)

Лицензия

MIT @ makshuk