Tinkoff Broker API

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/modules/tinkoff/tinkoff.service.ts
• backend/src/modules/tinkoff/tinkoff.resolver.ts
• backend/src/modules/tinkoff/tinkoff.module.ts
• backend/src/modules/algorithmTesting/algorithmTesting.resolver.ts
• frontend/src/graphql.ts
• readme.md

The Tinkoff Broker API integration serves as the core data provider for the Technical Analysis terminal. It enables the application to fetch historical market data, subscribe to real-time price updates via WebSockets, and search for financial instruments. This module acts as the bridge between the Tinkoff Invest OpenAPI and the project's internal services, providing standardized candle data for strategy testing and visualization.

Sources: readme.md:1-5, backend/src/modules/tinkoff/tinkoff.service.ts:15-25

Core Architecture

The system is built using NestJS and GraphQL, organized into a provider service and a resolver. The TinkoffService manages the low-level communication with the Tinkoff Invest SDK, while the TinkoffResolver exposes this functionality through a GraphQL API for the frontend and other backend modules like AlgorithmTesting.

Data Flow Overview

The following diagram illustrates how market data flows from the external Tinkoff API through the backend services to the end-user interface.

Tinkoff Service Implementation

The TinkoffService initializes the OpenAPI client using credentials retrieved from the ConfigService. It is responsible for mapping external data structures to the internal Candle type and managing complex historical data requests that require period splitting.

Sources: backend/src/modules/tinkoff/tinkoff.service.ts:15-25

Historical Candle Retrieval

The candles method handles requests for historical data across various resolutions. For intervals like "day" or "hour", it automatically segments the request into smaller sub-periods to comply with API limitations. For "minute" intervals, it performs recursive fetching to reach the desired history depth.

Sources: backend/src/modules/tinkoff/tinkoff.service.ts:38-125

Feature	Description
SDK Instance	Wraps @tinkoff/invest-openapi-js-sdk for API and WebSocket connections.
Mapping	Transforms TinkoffCandle or CandleStreaming into a unified Candle object.
Period Management	Calculates startDate using subPeriodLength and date-fns.
Deduplication	Filters out duplicate candles based on time stamps.

Sources: backend/src/modules/tinkoff/tinkoff.service.ts:27-45, backend/src/modules/tinkoff/tinkoff.service.ts:145-155

GraphQL API and Real-time Subscriptions

The TinkoffResolver provides the public interface for interacting with the broker API. It supports standard queries for historical data and search, as well as GraphQL Subscriptions for real-time market data.

Real-time Subscription Flow

When a client subscribes to realtimeCandles, the resolver creates a unique subscription to the Tinkoff WebSocket. Streamed candles are mapped and published via a PubSub mechanism.

API Operations

Operation	Type	Input Parameters	Return Type
candles	Query	figi, interval, to (optional)	[Candle]
searchInstrument	Query	ticker	[Instrument]
candle	Subscription	figi, interval	CandleSubscriptionData

Sources: backend/src/modules/tinkoff/tinkoff.resolver.ts:48-75, frontend/src/graphql.ts:100-130

Integration with Algorithm Testing

The Tinkoff API module is consumed by the AlgorithmTestingResolver to facilitate strategy backtesting and live signal monitoring. It initializes candle storage for every instrument in the user's watch list and manages active WebSocket connections for algorithm execution.

Signal Processing Logic

1. Initialization: Fetches initial candles for the watch list via TinkoffService.candles.
2. Streaming: Subscribes to new candles.
3. Analysis: Updates local candlesStorage and executes the algorithm function.
4. Action: If the algorithm returns a signal (isShort or isLong), the system manages trades via AlgorithmTestingService.

Sources: backend/src/modules/algorithmTesting/algorithmTesting.resolver.ts:35-85

Configuration and Environment

The module requires a TINKOFF_SECRET token for authentication. This is configured in the .env file of the backend. The service uses the production endpoints for both REST and WebSocket communication.

Config Key	Description	Default / Example
apiURL	Base URL for REST API	https://api-invest.tinkoff.ru/openapi
socketURL	Base URL for WebSockets	wss://api-invest.tinkoff.ru/openapi/md/v1/md-openapi/ws
TINKOFF_SECRET	User's API token	Obtained from Tinkoff dashboard

Sources: backend/src/modules/tinkoff/tinkoff.service.ts:18-22, readme.md:14-16

Summary

The Tinkoff Broker API module provides the essential data infrastructure for the technical analysis platform. By abstracting the complexities of the Tinkoff OpenAPI SDK into a clean NestJS service and GraphQL interface, it enables seamless data retrieval and real-time streaming. This foundation allows the AlgorithmTesting module and frontend charts to focus on strategy execution and visualization without handling the nuances of financial API rate limits or message mapping.

Sources: backend/src/modules/tinkoff/tinkoff.module.ts:1-12, backend/src/modules/tinkoff/tinkoff.service.ts:15-30