@finam/widgets-sdk

SDK для разработки виджетов для торговой платформы Финам. Позволяет виджетам взаимодействовать с платформой, получать рыночные данные и информацию об инструментах.

Установка

npm install @finam/widgets-sdk

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

import {
  subscribeWidgetState,
  setWidgetReady,
  subscribeChangeAccount,
} from '@finam/widgets-sdk';

const abortController = new AbortController(); // для отмены подписки

// Подписываемся на изменение выбранного инструмента
subscribeWidgetState({
  next: (state) => {
    console.log('Текущий инструмент:', state.security?.symbol);
  },
}, { signal: abortController.signal });

// Сигнализируем о готовности виджета
await setWidgetReady();

Тестирование виджета на стенде FT

Можно протестировать свой виджет на стенде FT. Для этого нужно добавить в localStorage следующие данные:

localStorage.setItem(
  'widgets',
  JSON.stringify([
    {
      kind: 'company.widget-example', // уникальный тип виджета
      iframeUrl: 'https://localhost:8080', // адрес html страницы с подключенным @finam/widgets-sdk
      imageUrl: 'https://localhost:8080/widget-icon.svg', // svg иконка
      title: {
        'en': 'Widget Title',
        'ru': 'Заголовок виджета'
      }, // Заголовок виджета
      requireSecurity: true, // требует ли виджет выбранный инструмент (security) для своего отображения
    },
  ]),
)

Виджет станет доступен для добавления в воркспейс после перезагрузки страницы

Требования к виджету

• должен поддерживать светлую и темную тему (текущее значение можно получить через subscribeWidgetState)
• должен поддерживать локализацию (en, ru) (текущее значение можно получить через subscribeWidgetState)
• иметь прозрачный фон, либо если это не возможно цвет фона должен соответствовать tokens.colors.bg.base.default.default из @finam/web-ui-kit

Требования к иконке

Иконка для виджета должна быть в svg формате. Цвет иконки НЕ должен быть задан, либо должен иметь значение currentColor, так как он будет устанавливаться приложением в рамках конкретного сценария использования (с помощью css свойства color).

API

API виджета

Методы для взаимодействия виджета с платформой.

subscribeWidgetState(observer, options?)

Подписка на состояние виджета. Позволяет получать уведомления об изменении состояния виджета, включая текущий выбранный инструмент.

subscribeWidgetState({
  next: (state) => {
    console.log('ID виджета:', state.id);
    console.log('Инструмент:', state.security?.symbol);
  },
});

setWidgetReady(options?)

Сигнал о готовности виджета к работе. Вызывается после инициализации виджета для уведомления хоста. Влияет на отображение лоадера.

await setWidgetReady();

requestChangeSecurity(req, options?)

Запрос на смену инструмента в виджете. Отправляет команду хосту на изменение текущего инструмента виджета.

await requestChangeSecurity({ symbol: 'AAPL@NASDAQ' });

subscribeChangeAccount(observer, options?)

Подписка на смену аккаунта. Позволяет виджету получать уведомления при смене аккаунта пользователем в хосте.

subscribeChangeAccount({
  next: () => {
    console.log('Аккаунт изменён');
  },
});

setMenuItems(req, options?)

Установка пунктов контекстного меню виджета.

await setMenuItems([
  { id: 'refresh', label: 'Обновить' },
  { id: 'settings', label: 'Настройки', disabled: true },
]);

subscribeClickMenuItems(observer, options?)

Подписка на клики по пунктам меню. Позволяет виджету получать уведомления о выборе пользователем пункта контекстного меню.

subscribeClickMenuItems({
  next: (response) => {
    console.log('Выбран пункт меню:', response.id);
  },
});

Trade API (tradeApi)

Торговый API для получения рыночных данных и информации об инструментах. Включает два модуля:

• tradeApi/marketdata — рыночные данные (котировки, свечи, стакан, сделки)
• tradeApi/assets — информация об инструментах

Модуль marketdata

Методы для работы с рыночными данными.

Котировки

• subscribeQuote(req, observer, options?) — подписка на котировки в реальном времени
• getLastQuote(req, options?) — получение последней котировки

Исторические данные

• getBars(req, options?) — получение агрегированных свечей (OHLCV)
• subscribeBars(req, observer, options?) — подписка на обновление свечей

Стакан

• getOrderBook(req, options?) — получение текущего стакана
• subscribeOrderBook(req, observer, options?) — подписка на обновления стакана

Сделки

• getLatestTrades(req, options?) — получение последних сделок
• subscribeLatestTrades(req, observer, options?) — подписка на новые сделки

Пример подписки на котировки:

import { subscribeQuote } from '@finam/widgets-sdk/tradeApi/marketdata';

subscribeQuote(
  { symbols: ['SBER@MISX', 'LKOH@MISX'] },
  {
    next: (response) => {
      response.quote.forEach((q) => {
        console.log(`${q.symbol}: bid=${q.bid?.value}, ask=${q.ask?.value}`);
      });
    },
    error: (err) => console.error('Ошибка:', err),
  }
);

Модуль assets

Методы для работы с информацией об инструментах.

Информация об инструменте

• getAsset(req, options?) — получение информации по инструменту
• subscribeAsset(req, observer, options?) — подписка на обновления информации об инструменте

Торговые параметры

• getAssetParams(req, options?) — получение торговых параметров (доступность лонга/шорта, ГО, ставки риска)
• subscribeAssetParams(req, observer, options?) — подписка на обновления торговых параметров

Биржи

• getExchanges(req, options?) — получение списка доступных бирж

Опционы

• getOptionsChain(req, options?) — получение цепочки опционов для базового актива

Расписание торгов

• getSchedule(req, options?) — получение расписания торгов для инструмента

Пример получения информации об инструменте:

import { getAsset, getAssetParams } from '@finam/widgets-sdk/tradeApi/assets';

const asset = await getAsset({ symbol: 'SBER@MOEX' });
console.log('Название:', asset.name);
console.log('Шаг цены:', asset.minStep);
console.log('Лот:', asset.lotSize);

const params = await getAssetParams({ symbol: 'SBER@M' });
console.log('Доступен лонг:', params.longable?.value);
console.log('Доступен шорт:', params.shortable?.value);
console.log('ГО лонг:', params.longInitialMargin);

Опции

SubscriptionOptions

interface SubscriptionOptions {
  signal?: AbortSignal; // Для отмены подписки
}

FetchOptions

interface FetchOptions {
  signal?: AbortSignal;       // Для отмены запроса
  timeout?: number;           // Таймаут в миллисекундах (по умолчанию 30000)
}