tksbrokerapi.TKSBrokerAPI

Technologies · Knowledge · Science

TKSBrokerAPI is the trading platform for automation and simplifying the implementation of trading scenarios, as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI Platform may be used in two ways: from the console, it has a rich keys and commands, or you can use it as Python module with python import.

TKSBrokerAPI allows you to automate routine trading operations and implement your trading scenarios, or just receive the necessary information from the broker. It is easy enough to integrate into various CI/CD automation systems.

See also:

Open account for trading: https://tinkoff.ru/sl/AaX1Et1omnH
TKSBrokerAPI Platform documentation: https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html
CLI examples: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Usage-examples
Used constants are in the TKSEnums module: https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSEnums.html
About Tinkoff Invest API: https://tinkoff.github.io/investAPI/
Tinkoff Invest API documentation: https://tinkoff.github.io/investAPI/swagger-ui/
How to implement trading scenario in Python: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Module-import

Using the TKSBrokerAPI Platform, you can implement any trading scenario in Python. Many system used for making trading decisions about buying or selling (technical analysis, neural networks, parsing reports or tracking other traders’ transactions), but you still need to perform trading operations: place orders, open and close transactions. The TKSBrokerAPI module will act as an intermediary between the code with the trading logic and services infrastructure of the Tinkoff Investments broker, as well as perform routine tasks on your behalf in brokerage account.

The scheme of trade scenario automation with TKSBrokerAPI is very simple:

You come up with a brilliant trading algorithm.
Write it down step by step in the form of some kind of plan or trading scenario.
Automate scenario as a Python script using TKSBrokerAPI.
TKSBrokerAPI takes care of all the work with the Tinkoff Investments broker infrastructure.
Profit!

But where to get this "brilliant trading algorithm"? The TKSBrokerAPI Platform will also help you solve the problem of obtaining primary, "raw" data on trading instruments (shares, bonds, funds, futures and currencies) from the broker server, for their future analysis in any analytical tool convenient for you. To do this, the methods of the TKSBrokerAPI module provide the ability to extend and save data in classic formats: XLSX and CSV (for analysis in spreadsheet editors), Markdown (for readability), and Pandas DataFrame (for data scientists and stock analysts).

The "raw" data can be anything that can be obtained from the broker's server. After extends, this data can be used to build, for example, a consolidated payment calendar for bonds and calculate their coupon and current yields, or you can generate analytics about the status of the user's portfolio and the distribution of assets by types, companies, industries, currencies, and countries. In addition, you can download historical data on the prices of any instrument as OHLCV-candlesticks.

How data is extended and used in TKSBrokerAPI Platform:

You request the data you need from the Tinkoff Investments broker server:
- in this module, almost all methods return "raw" data from the server in the form of a Python dictionary.
Then they are processed and extended:
- with various statistics, parameters and some analytical reports.
After that, the data is stored in a form suitable for further analysis:
- most of the methods return extended data in the form of a Python dictionary or Pandas DataFrame;
- if you launched the TKSBrokerAPI platform in the console, then the data will be saved in XLSX, CSV or Markdown formats.
Next, you can load the data into analytical system and use various data analysis methods to find and highlight dependencies, correlations, make predictions and suggest hypothesis.
Further, based on data analysis, you come up with the same "brilliant trading algorithm".
Automate the trading scenario (according to the previous scheme).
Profit!

packageDir = 'D:\\work\\projects\\TKSBrokerAPI'

uLogger = <Logger TKSBrokerAPI-UniLogger (DEBUG)>

CPU_COUNT = 20

CPU_USAGES = 19

class RateLimiter:

RateLimiter(methodLimits: dict[str, int])

Initialize RateLimiter with given method limits (requests per minute).

Parameters

methodLimits: dict[str, int] with per-method RPM limits.

methodLimits

Per-method RPM limits.

counters

Number of requests sent per method in the current window.

timestamps

Timestamp (monotonic) of the start of current window per method.

events

Synchronization event for each method to coordinate waiting.

moreDebug

Enables more debug information in this class. False by default.

def CheckRateLimit(self, methodName: str) -> None:

Check if the request for the method can proceed. Wait if needed.

Parameters

methodName: str with the method name.

def HandleServerRateLimit(self, methodName: str, waitTime: int) -> None:

Handle server-enforced rate limit using cooperative waiting.

Parameters

methodName: str with the method name.
waitTime: int time in seconds to wait before retrying the request.

class TinkoffBrokerServer:

This class implements methods to work with Tinkoff broker server.

Examples to work with API: https://tinkoff.github.io/investAPI/swagger-ui/

About token: https://tinkoff.github.io/investAPI/token/

TinkoffBrokerServer( token: str, accountId: str = None, useCache: bool = True, defaultCache: str = 'dump.json', moreDebug: bool = False)

Main class init.

Parameters

token: Bearer token for Tinkoff Invest API. It can be set from environment variable TKS_API_TOKEN.
accountId: string with numeric user account ID in Tinkoff Broker. It can be found in broker's reports. Also, this variable can be set from environment variable TKS_ACCOUNT_ID.
useCache: use default cache file with raw data to use instead of iList. True by default. Cache is auto-update if new day has come. If you don't want to use cache and always updates raw data then set useCache=False.
defaultCache: path to default cache file. dump.json by default.
moreDebug: if True, enables detailed debug-level logging for API requests, data processing, history segmentation, and other internal stages. Useful for development and diagnostics. False by default.

moreDebug

Enables more debug information in this class, such as net request and response headers in all methods. False by default.

rateLimiter

RateLimiter object to work with given method limits (requests per minute) from TKS_METHOD_LIMITS.

version

Current TKSBrokerAPI Platform version: major.minor, but the build number define at the build-server only.

Latest version: https://pypi.org/project/tksbrokerapi/

aliases

Some aliases instead official tickers.

See also: SendAPIRequest().

retry

How many times retry after first request if a 5xx server errors occurred. If set to 0, then only first main request will be sent without retries. This allows you to reduce the number of calls to the server API for all methods.

3 times of retries by default.

See also: SendAPIRequest().

pause

Sleep time in seconds between retries, in all network requests 3 seconds by default.

See also: SendAPIRequest().

headers

Headers which send in every request to broker server. Please, do not change it! Default: {"Content-Type": "application/json", "accept": "application/json", "Authorization": "Bearer {your_token}", "x-app-name": "Tim55667757.TKSBrokerAPI"}.

See also: SendAPIRequest().

body

Request body which send to broker server. Default: None.

See also: SendAPIRequest().

useHTMLReports

If True then TKSBrokerAPI generate also HTML reports from Markdown. False by default.

See also: Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.

historyFile

Full path to the output file where history candles will be saved or updated. Default: None, it mean that returns only Pandas DataFrame.

Parameters

url: url with REST request.
reqType: send "GET" or "POST" request. "GET" by default.
methodName: optional manual override for REST method name (used for throttling).
_internalBody: DO NOT use this variable in your scripts! This is debug variable for internal used only.

Returns

response JSON (dictionary) from broker.

def Listing(self) -> dict:

Gets JSON with raw data about shares, currencies, bonds, ETFs, and futures from broker server.

Returns

Dictionary with all available broker instruments: currencies, shares, bonds, ETFs, and futures.

def DumpInstrumentsAsXLSX(self, forceUpdate: bool = False) -> None:

Creates XLSX-formatted dump file with raw data of instruments to further used by data scientists or stock analytics.

See also: DumpInstruments(), Listing().

Parameters

forceUpdate: if True then at first updates data with Listing() method, otherwise just saves exist iList as XLSX-file (default: dump.xlsx) .

def DumpInstruments(self, forceUpdate: bool = True) -> str:

Receives and returns actual raw data about shares, currencies, bonds, etfs and futures from broker server using Listing() method. If iListDumpFile string is not empty then also save information to this file.

See also: DumpInstrumentsAsXLSX(), Listing().

Parameters

forceUpdate: if True then at first updates data with Listing() method, otherwise just saves exist iList as JSON-file (default: dump.json).

Returns

serialized JSON formatted str with full data of instruments, also saved to the --output JSON-file.

def ShowInstrumentInfo(self, iJSON: dict, show: bool = True, onlyFiles=False) -> str:

Show information about one instrument defined by json data and prints it in Markdown format.

Parameters

iJSON: json data of instrument, example: iJSON = self.iList["Shares"][self._ticker]
show: if True then also printing information about instrument and its current price.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

multilines text in Markdown format with information about one instrument.

def SearchByTicker(self, requestPrice: bool = False, show: bool = False) -> dict:

Search and return raw broker's information about instrument by its ticker. Variable ticker must be defined!

Parameters

requestPrice: if False then do not request current price of instrument (because this is long operation).
show: if False then do not run ShowInstrumentInfo() method and do not print info to the console.

Returns

JSON formatted data with information about instrument.

def SearchByFIGI(self, requestPrice: bool = False, show: bool = False) -> dict:

Search and return raw broker's information about instrument by its FIGI. Variable figi must be defined!

Parameters

requestPrice: if False then do not request current price of instrument (it's long operation).
show: if False then do not run ShowInstrumentInfo() method and do not print info to the console.

Returns

JSON formatted data with information about instrument.

def GetCurrentPrices(self, show: bool = True) -> dict:

Get and show Depth of Market with current prices of the instrument as dictionary. Result example with depth 5: {"buy": [{"price": 1243.8, "quantity": 193}, {"price": 1244.0, "quantity": 168}, {"price": 1244.8, "quantity": 5}, {"price": 1245.0, "quantity": 61}, {"price": 1245.4, "quantity": 60}], "sell": [{"price": 1243.6, "quantity": 8}, {"price": 1242.6, "quantity": 10}, {"price": 1242.4, "quantity": 18}, {"price": 1242.2, "quantity": 50}, {"price": 1242.0, "quantity": 113}], "limitUp": 1619.0, "limitDown": 903.4, "lastPrice": 1243.8, "closePrice": 1263.0}, where parameters mean:

buy: list of dicts with Sellers prices, see also: https://tinkoff.github.io/investAPI/marketdata/#order
sell: list of dicts with Buyers prices,
- price: price of 1 instrument (to get the cost of the lot, you need to multiply it by the lot of size of the instrument),
- quantity: volume value by current price in lots,
limitUp: current trade session limit price, maximum,
limitDown: current trade session limit price, minimum,
lastPrice: last deal price of the instrument,
closePrice: previous trade session close price of the instrument.

Parameters

show: if True then print DOM to log and console.

Returns

orders book dict with lists of current buy and sell prices: {"buy": [{"price": x1, "quantity": y1, ...}], "sell": [....]}. If an error occurred then returns an empty record: {"buy": [], "sell": [], "limitUp": None, "limitDown": None, "lastPrice": None, "closePrice": None}.

def ShowInstrumentsInfo(self, show: bool = True, onlyFiles=False) -> str:

This method get and show information about all available broker instruments for current user account. If instrumentsFile string is not empty then also save information to this file.

Parameters

show: if True then print results to console, if False — print only to file.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

multi-lines string with all available broker instruments.

def SearchInstruments(self, pattern: str, show: bool = True, onlyFiles=False) -> dict:

This method search and show information about instruments by part of its ticker, FIGI or name. If searchResultsFile string is not empty then also save information to this file.

Parameters

pattern: string with part of ticker, FIGI or instrument's name.
show: if True then print results to console, if False — return list of result only.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

list of dictionaries with all found instruments.

def GetUniqueFIGIs(self, instruments: list[str]) -> list:

Creating list with unique instrument FIGIs from input list of tickers (priority) or FIGIs.

Parameters

instruments: list of strings with tickers or FIGIs.

Returns

list with unique instrument FIGIs only.

def GetListOfPrices( self, instruments: list[str], show: bool = False, onlyFiles=False) -> list[dict]:

This method get, maybe show and return prices of list of instruments. WARNING! This is potential long operation!

See limits: https://tinkoff.github.io/investAPI/limits/

If pricesFile string is not empty then also save information to this file.

Parameters

instruments: list of strings with tickers or FIGIs.
show: if True then prints prices to console, if False — prints only to file pricesFile.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

list of instruments looks like [{some ticker info, "currentPrice": {current prices}}, {...}, ...]. One item is dict returned by SearchByTicker() or SearchByFIGI() methods.

def ShowListOfPrices(self, iList: list, show: bool = True, onlyFiles=False) -> str:

Show table contains current prices of given instruments.

Parameters

**iList: list of instruments looks like [{some ticker info, "currentPrice"**: {current prices}}, {...}, ...]. One item is dict returned by SearchByTicker(requestPrice=True) or by SearchByFIGI(requestPrice=True) methods.
show: if True then prints prices to console, if False — prints only to file pricesFile.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

multilines text in Markdown format as a table contains current prices.

def RequestTradingStatus(self) -> dict:

Requesting trading status for the instrument defined by figi variable.

REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetTradingStatus

Documentation: https://tinkoff.github.io/investAPI/marketdata/#gettradingstatusrequest

Returns

dictionary with trading status attributes. Response example: {"figi": "TCS00A103X66", "tradingStatus": "SECURITY_TRADING_STATUS_NOT_AVAILABLE_FOR_TRADING", "limitOrderAvailableFlag": false, "marketOrderAvailableFlag": false, "apiTradeAvailableFlag": true}

def RequestPortfolio(self) -> dict:

Requesting actual user's portfolio for current accountId.

REST API for user portfolio: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPortfolio

Documentation: https://tinkoff.github.io/investAPI/operations/#portfoliorequest

Returns

dictionary with user's portfolio.

def RequestPositions(self) -> dict:

Requesting open positions by currencies and instruments for current accountId.

REST API for open positions: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPositions

Documentation: https://tinkoff.github.io/investAPI/operations/#positionsrequest

Returns

dictionary with open positions by instruments.

def RequestPendingOrders(self) -> list:

Requesting current actual pending limit orders for current accountId.

REST API for pending (market) orders: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_GetOrders

Documentation: https://tinkoff.github.io/investAPI/orders/#getordersrequest

Returns

list of dictionaries with pending limit orders.

def RequestStopOrders(self) -> list:

Requesting current actual stop orders for current accountId.

REST API for opened stop-orders: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_GetStopOrders

Documentation: https://tinkoff.github.io/investAPI/stoporders/#getstopordersrequest

Returns

list of dictionaries with stop orders.

def Overview(self, show: bool = False, details: str = 'full', onlyFiles=False) -> dict:

Get portfolio: all open positions, orders, some statistics for current accountId. If overviewFile, overviewDigestFile, overviewPositionsFile, overviewOrdersFile, overviewAnalyticsFile and overviewBondsCalendarFile are defined, then also save information to file.

WARNING! It is not recommended to run this method too many times in a loop! The server receives many requests about the state of the portfolio, and then, based on the received data, a large number of calculations and statistics are collected.

Parameters

show: if False then only dictionary returns if True then shows more debug information.
details: how detailed should the information be?
- full — shows full available information about portfolio status (by default),
- positions — shows only open positions,
- orders — shows only sections of open limits and stop orders.
- digest — shows a short digest of the portfolio status,
- analytics — shows only the analytics section and the distribution of the portfolio by various categories,
- calendar — shows only the bonds calendar section (if these are present in portfolio).
onlyFiles: if True, then does not show the Markdown table in the console but only generates report files.

Returns

dictionary with a client's raw portfolio and some statistics.

def Deals( self, start: str = None, end: str = None, show: bool = False, showCancelled: bool = True, onlyFiles=False) -> tuple[list[dict], dict]:

Returns history operations between two given dates for current accountId. If reportFile string is not empty then also save human-readable report. Shows some statistical data of closed positions.

Parameters

start: see docstring in TradeRoutines.GetDatesAsString() method.
end: see docstring in TradeRoutines.GetDatesAsString() method.
show: if True then also prints all records to the console.
showCancelled: if False then remove information about cancelled operations from the deals report.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

original list of dictionaries with history of deals records from API ("operations" key): https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations and dictionary with custom stats: operations in different currencies, withdrawals, incomes etc.

def History( self, start: str = None, end: str = None, interval: str = 'hour', onlyMissing: bool = False, csvSep: str = ',', show: bool = True) -> pandas.core.frame.DataFrame:

This method returns last history candles of the current instrument defined by ticker or figi (FIGI id).

History returned between two given dates: start and end. Minimum requested date in the past is 1970-01-01. Warning! Broker server used ISO UTC time by default.

If historyFile is not None then method save history to file, otherwise return only Pandas DataFrame. Also, historyFile used to update history with onlyMissing parameter.

See also: LoadHistory() and ShowHistoryChart() methods.

Parameters

start: see docstring in TradeRoutines.GetDatesAsString() method.
end: see docstring in TradeRoutines.GetDatesAsString() method.
interval: this is a candle interval. Current available values are "1min", "5min", "15min", "hour", "day". Default: "hour".
onlyMissing: if True then add only last missing candles, do not request all history length from start. False by default. Warning! History appends only from last candle to current time with always update last candle!
csvSep: separator if csv-file is used, , by default.
show: if True then also prints Pandas DataFrame to the console.

Returns

Pandas DataFrame with prices history. Headers of columns are defined by default: ["date", "time", "open", "high", "low", "close", "volume"].

def LoadHistory(self, filePath: str, show: bool = True) -> pandas.core.frame.DataFrame:

Load candles history from csv-file and return Pandas DataFrame object.

See also: History() and ShowHistoryChart() methods.

Parameters

filePath: path to csv-file to open.
show: if True then also prints Pandas DataFrame to the console.

Returns

Pandas DataFrame with prices history. Headers of columns are defined by default: ["date", "time", "open", "high", "low", "close", "volume"].

def ShowHistoryChart( self, candles: Union[str, pandas.core.frame.DataFrame] = None, interact: bool = True, openInBrowser: bool = False) -> None:

Render an HTML-file with interact or non-interact candlesticks chart. Candles may be path to the csv-file.

Self variable htmlHistoryFile can be use as html-file name to save interaction or non-interaction chart. Default: index.html (both for interact and non-interact candlesticks chart).

See also: History() and LoadHistory() methods.

Parameters

candles: string to csv-file with candles in OHLCV-model or like Pandas Dataframe object.
interact: if True (default) then chain of candlesticks will render as interactive Bokeh chart. See examples: https://github.com/Tim55667757/PriceGenerator#overriding-parameters If False then chain of candlesticks will render as not interactive Google Candlestick chart. See examples: https://github.com/Tim55667757/PriceGenerator#statistics-and-chart-on-a-simple-template
openInBrowser: if True then immediately open chart in default browser, otherwise only path to html-file prints to console. False by default, to avoid issues with permissions denied to html-file.

def Trade( self, operation: str, lots: int = 1, tp: float = 0.0, sl: float = 0.0, expDate: str = 'Undefined') -> dict:

Universal method to create market order and make deal at the current price for current accountId. Returns JSON data with response. If tp or sl > 0, then in additional will open stop-orders with "TP" and "SL" flags for stopType parameter.

See also: Order() docstring. More simple methods than Trade() are Buy() and Sell().

Parameters

operation: string "Buy" or "Sell".
lots: volume, integer count of lots >= 1.
tp: float > 0, target price for stop-order with "TP" type. It used as take profit parameter targetPrice in self.Order().
sl: float > 0, target price for stop-order with "SL" type. It used as stop loss parameter targetPrice in self.Order().
expDate: string "Undefined" by default or local date in the future, it is a string with format %Y-%m-%d %H:%M:%S.

Returns

JSON with response from broker server.

def Buy( self, lots: int = 1, tp: float = 0.0, sl: float = 0.0, expDate: str = 'Undefined') -> dict:

More simple method than Trade(). Create Buy market order and make deal at the current price. Returns JSON data with response. If tp or sl > 0, then in additional will open stop-orders with "TP" and "SL" flags for stopType parameter.

See also: Order() and Trade() docstrings.

Parameters

lots: volume, integer count of lots >= 1.
tp: float > 0, take profit price of stop-order.
sl: float > 0, stop loss price of stop-order.
expDate: it's a local date in the future. String has a format like this: %Y-%m-%d %H:%M:%S.

Returns

JSON with response from broker server.

def Sell( self, lots: int = 1, tp: float = 0.0, sl: float = 0.0, expDate: str = 'Undefined') -> dict:

More simple method than Trade(). Create Sell market order and make deal at the current price. Returns JSON data with response. If tp or sl > 0, then in additional will open stop-orders with "TP" and "SL" flags for stopType parameter.

See also: Order() and Trade() docstrings.

Parameters

lots: volume, integer count of lots >= 1.
tp: float > 0, take profit price of stop-order.
sl: float > 0, stop loss price of stop-order.
expDate: it's a local date in the future. String has a format like this: %Y-%m-%d %H:%M:%S.

Returns

JSON with response from broker server.

def CloseTrades(self, instruments: list[str], portfolio: dict = None) -> None:

Close position of given instruments.

Parameters

instruments: list of instruments defined by tickers or FIGIs that must be closed.
portfolio: pre-received dictionary with open trades, returned by Overview() method. This avoids unnecessary downloading data from the server.

def CloseAllTrades(self, iType: str, portfolio: dict = None) -> None:

Close all positions of given instruments with defined type.

Parameters

iType: type of the instruments that be closed, it must be one of supported types in TKS_INSTRUMENTS list.
portfolio: pre-received dictionary with open trades, returned by Overview() method. This avoids unnecessary downloading data from the server.

def Order( self, operation: str, orderType: str, lots: int, targetPrice: float, limitPrice: float = 0.0, stopType: str = 'Limit', expDate: str = 'Undefined') -> dict:

Universal method to create market or limit orders with all available parameters for current accountId. See more simple methods: BuyLimit(), BuyStop(), SellLimit(), SellStop().

If orderType is "Limit" then create pending limit-order below current price if operation is "Buy" and above current price if operation is "Sell". A limit order has no expiration date, it lasts until the end of the trading day.

Warning! If you try to create limit-order above current price if "Buy" or below current price if "Sell" then broker immediately open market order as you can do simple --buy or --sell operations!

If orderType is "Stop" then creates stop-order with any direction "Buy" or "Sell". When current price will go up or down to target price value then broker opens a limit order. Stop-order is opened with unlimited expiration date by default, or you can define expiration date with expDate parameter.

Only one attempt without retries recommended for opens order, set self.retry = 0. If network issue occurred you can create new request.

Parameters

operation: string "Buy" or "Sell".
orderType: string "Limit" or "Stop".
lots: volume, integer count of lots >= 1.
targetPrice: target price > 0. This is open trade price for limit order.
limitPrice: limit price >= 0. This parameter only makes sense for stop-order. If limitPrice = 0, then it set as targetPrice. Broker will create limit-order with price equal to limitPrice, when current price goes to target price of stop-order.
stopType: string "Limit" by default. This parameter only makes sense for stop-order. There are 3 stop-order types "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly. Stop loss order always executed by market price.
expDate: string "Undefined" by default or local date in the future. String has a format like this: %Y-%m-%d %H:%M:%S. This date is converting to UTC format for server. This parameter only makes sense for stop-order. A limit order has no expiration date, it lasts until the end of the trading day.

Returns

JSON with response from broker server.

def BuyLimit(self, lots: int, targetPrice: float) -> dict:

Create pending Buy limit-order (below current price). You must specify only 2 parameters: lots and target price to open buy limit-order. If you try to create buy limit-order above current price then broker immediately open Buy market order, such as if you do simple --buy operation! See also: Order() docstring.

Parameters

lots: volume, integer count of lots >= 1.
targetPrice: target price > 0. This is open trade price for limit order.

Returns

JSON with response from broker server.

def BuyStop( self, lots: int, targetPrice: float, limitPrice: float = 0.0, stopType: str = 'Limit', expDate: str = 'Undefined') -> dict:

Create Buy stop-order. You must specify at least 2 parameters: lots target price to open buy stop-order. In additional you can specify 3 parameters for buy stop-order: limit price >=0, stop type = Limit|SL|TP, expiration date = Undefined|%%Y-%%m-%%d %%H:%%M:%%S. When current price will go up or down to target price value then broker opens a limit order. See also: Order() docstring.

Parameters

lots: volume, integer count of lots >= 1.
targetPrice: target price > 0. This is trigger price for buy stop-order.
limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will create limit-order with price equal to limitPrice, when current price goes to target price of buy stop-order.
stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
expDate: string "Undefined" by default or local date in the future. String has a format like this: %Y-%m-%d %H:%M:%S. This date is converting to UTC format for server.

Returns

JSON with response from broker server.

def SellLimit(self, lots: int, targetPrice: float) -> dict:

Create pending Sell limit-order (above current price). You must specify only 2 parameters: lots and target price to open sell limit-order. If you try to create sell limit-order below current price then broker immediately open Sell market order, such as if you do simple --sell operation! See also: Order() docstring.

Parameters

lots: volume, integer count of lots >= 1.
targetPrice: target price > 0. This is open trade price for limit order.

Returns

JSON with response from broker server.

def SellStop( self, lots: int, targetPrice: float, limitPrice: float = 0.0, stopType: str = 'Limit', expDate: str = 'Undefined') -> dict:

Create Sell stop-order. You must specify at least 2 parameters: lots target price to open sell stop-order. In addition, you can specify 3 parameters in sell stop-order: limit price >=0, stop type = Limit|SL|TP, expiration date = Undefined|%%Y-%%m-%%d %%H:%%M:%%S. When current price will go up or down to target price value then broker opens a limit order. See also: Order() docstring.

Parameters

lots: volume, integer count of lots >= 1.
targetPrice: target price > 0. This is trigger price in sell stop-order.
limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will create limit-order with price equal to limitPrice, when current price goes to target price of sell stop-order.
stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
expDate: string "Undefined" by default or local date in the future. String has a format like this: %Y-%m-%d %H:%M:%S. This date is converting to UTC format for server.

Returns

JSON with response from broker server.

def CloseOrders( self, orderIDs: list, allOrdersIDs: list = None, allStopOrdersIDs: list = None) -> None:

Cancel order or list of orders by its orderId or stopOrderId for current accountId.

Parameters

orderIDs: list of integers with orderId or stopOrderId.
allOrdersIDs: pre-received lists of all active pending limit orders. This avoids unnecessary downloading data from the server.
allStopOrdersIDs: pre-received lists of all active stop orders.

def CloseAllOrders(self) -> None:

Gets a list of open pending and stop orders and cancel it all.

def CloseAll(self, *args) -> None:

Close all available (not blocked) opened trades and orders.

Also, you can select one or more keywords case-insensitive: orders, shares, bonds, etfs and futures from TKS_INSTRUMENTS enum to specify trades type.

Currency positions you must close manually using buy or sell operations, CloseTrades() or CloseAllTrades() methods.

def CloseAllByTicker(self, instrument: str) -> None:

Close all available (not blocked) opened trades and orders for one instrument defined by its ticker.

This method searches opened trade and orders of instrument throw all portfolio and then use CloseTrades() and CloseOrders() methods to close trade and cancel all orders for that instrument.

Parameters

instrument: string with ticker.

def CloseAllByFIGI(self, instrument: str) -> None:

Close all available (not blocked) opened trades and orders for one instrument defined by its FIGI id.

This method searches opened trade and orders of instrument throw all portfolio and then use CloseTrades() and CloseOrders() methods to close trade and cancel all orders for that instrument.

Parameters

instrument: string with FIGI id.

@staticmethod

def ParseOrderParameters(operation, **inputParameters):

Parse input dictionary of strings with order parameters and return dictionary with parameters to open all orders.

Parameters

operation: string "Buy" or "Sell".
inputParameters: this is dict of strings that looks like this {"lots": "L_int,...", "prices": "P_float,..."} where "lots" key: one or more lot values (integer numbers) to open with every limit-order "prices" key: one or more prices to open limit-orders Counts of values in lots and prices lists must be equals!

Returns

list of dictionaries with all lots and prices to open orders that looks like this [{"lot": lots_1, "price": price_1}, {...}, ...]

def IsInPortfolio(self, portfolio: dict = None) -> bool:

Checks if instrument is in the user's portfolio. Instrument must be defined by ticker (highly priority) or figi.

Parameters

portfolio: dict with user's portfolio data. If None, then requests portfolio from Overview() method.

Returns

True if portfolio contains open position with given instrument, False otherwise.

def GetInstrumentFromPortfolio(self, portfolio: dict = None) -> dict:

Returns instrument from the user's portfolio if it presents there. Instrument must be defined by ticker (highly priority) or figi.

Parameters

portfolio: dict with user's portfolio data. If None, then requests portfolio from Overview() method.

Returns

dict with instrument if portfolio contains open position with this instrument, None otherwise.

def IsInLimitOrders(self, portfolio: dict = None) -> bool:

Checks if instrument is in the limit orders list. Instrument must be defined by ticker (highly priority) or figi.

See also: CloseAllByTicker() and CloseAllByFIGI().

Parameters

portfolio: dict with user's portfolio data. If None, then requests portfolio from Overview() method.

Returns

True if limit orders list contains some limit orders for the instrument, False otherwise.

def GetLimitOrderIDs(self, portfolio: dict = None) -> list[str]:

Returns list with all orderIDs of opened pending limit orders for the instrument. Instrument must be defined by ticker (highly priority) or figi.

See also: CloseAllByTicker() and CloseAllByFIGI().

Parameters

portfolio: dict with user's portfolio data. If None, then requests portfolio from Overview() method.

Returns

list with orderIDs of limit orders.

def IsInStopOrders(self, portfolio: dict = None) -> bool:

Checks if instrument is in the stop orders list. Instrument must be defined by ticker (highly priority) or figi.

See also: CloseAllByTicker() and CloseAllByFIGI().

Parameters

portfolio: dict with user's portfolio data. If None, then requests portfolio from Overview() method.

Returns

True if stop orders list contains some stop orders for the instrument, False otherwise.

def GetStopOrderIDs(self, portfolio: dict = None) -> list[str]:

Returns list with all orderIDs of opened stop orders for the instrument. Instrument must be defined by ticker (highly priority) or figi.

See also: CloseAllByTicker() and CloseAllByFIGI().

Parameters

portfolio: dict with user's portfolio data. If None, then requests portfolio from Overview() method.

Returns

list with orderIDs of stop orders.

def RequestLimits(self) -> dict:

Method for obtaining the available funds for withdrawal for current accountId.

See also:

REST API for limits: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetWithdrawLimits
OverviewLimits() method

Returns

dict with raw data from server that contains free funds for withdrawal. Example of dict: {"money": [{"currency": "rub", "units": "100", "nano": 290000000}, {...}], "blocked": [...], "blockedGuarantee": [...]}. Here money is an array of portfolio currency positions, blocked is an array of blocked currency positions of the portfolio and blockedGuarantee is locked money under collateral for futures.

def OverviewLimits(self, show: bool = False, onlyFiles=False) -> dict:

Method for parsing and show table with available funds for withdrawal for current accountId.

Parameters

show: if False then only dictionary returns, if True then also print withdrawal limits to log.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

dict with raw parsed data from server and some calculated statistics about it.

def RequestAccounts(self) -> dict:

Method for requesting all brokerage accounts (accountIds) of current user detected by token.

See also:

REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetAccounts
What does account fields mean: https://tinkoff.github.io/investAPI/users/#account
OverviewUserInfo() method

Returns

dict with raw data from server that contains accounts info. Example of dict: {"accounts": [{"id": "20000xxxxx", "type": "ACCOUNT_TYPE_TINKOFF", "name": "TKSBrokerAPI account", "status": "ACCOUNT_STATUS_OPEN", "openedDate": "2018-05-23T00:00:00Z", "closedDate": "1970-01-01T00:00:00Z", "accessLevel": "ACCOUNT_ACCESS_LEVEL_FULL_ACCESS"}, ...]}. If closedDate="1970-01-01T00:00:00Z" it means that account is active now.

def RequestUserInfo(self) -> dict:

Method for requesting common user information.

See also:

REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetInfo
What does user info fields mean: https://tinkoff.github.io/investAPI/users/#getinforequest
What does qualified_for_work_with field mean: https://tinkoff.github.io/investAPI/faq_users/#qualified_for_work_with
OverviewUserInfo() method

Returns

dict with raw data from server that contains user's information. Example of dict: {"premStatus": true, "qualStatus": false, "qualifiedForWorkWith": ["bond", "foreign_shares", "leverage", "russian_shares", "structured_income_bonds"], "tariff": "premium"}.

def RequestMarginStatus(self, accountId: str = None) -> dict:

Method for requesting margin calculation for defined account ID.

See also:

REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetMarginAttributes
What does margin fields mean: https://tinkoff.github.io/investAPI/users/#getmarginattributesresponse
OverviewUserInfo() method

Parameters

accountId: string with numeric account ID. If None, then used class field accountId.

Returns

dict with raw data from server that contains margin calculation. If margin is disabled then returns empty dict. Example of responses: status code 400: {"code": 3, "message": "account margin status is disabled", "description": "30051" }, returns: {}. status code 200: {"liquidPortfolio": {"currency": "rub", "units": "7175", "nano": 560000000}, "startingMargin": {"currency": "rub", "units": "6311", "nano": 840000000}, "minimalMargin": {"currency": "rub", "units": "3155", "nano": 920000000}, "fundsSufficiencyLevel": {"units": "1", "nano": 280000000}, "amountOfMissingFunds": {"currency": "rub", "units": "-863", "nano": -720000000}}.

def RequestTariffLimits(self) -> dict:

Method for requesting limits of current tariff (connections, API methods etc.) of current user detected by token.

See also:

REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetUserTariff
What does fields in tariff mean: https://tinkoff.github.io/investAPI/users/#getusertariffrequest
Unary limit: https://tinkoff.github.io/investAPI/users/#unarylimit
Stream limit: https://tinkoff.github.io/investAPI/users/#streamlimit
OverviewUserInfo() method

Returns

dict with raw data from server that contains limits of current tariff. Example of dict: {"unaryLimits": [{"limitPerMinute": 0, "methods": ["methods", "methods"]}, ...], "streamLimits": [{"streams": ["streams", "streams"], "limit": 6}, ...]}.

def RequestBondCoupons(self, iJSON: dict) -> dict:

Requesting bond payment calendar from official placement date to maturity date. If these dates are unknown then requesting dates "from": "1970-01-01T00:00:00.000Z" and "to": "2099-12-31T23:59:59.000Z". All dates are in UTC timezone.

REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons Documentation:

Parameters

iJSON: raw json data of a bond from broker server, example iJSON = self.iList["Bonds"][self._ticker] If raw iJSON is not data of bond then server returns an error [400] with message: {"code": 3, "message": "instrument type is not bond", "description": "30048"}.

Returns

dictionary with bond payment calendar. Response example {"events": [{"figi": "TCS00A101YV8", "couponDate": "2023-07-26T00:00:00Z", "couponNumber": "12", "fixDate": "2023-07-25T00:00:00Z", "payOneBond": {"currency": "rub", "units": "7", "nano": 170000000}, "couponType": "COUPON_TYPE_CONSTANT", "couponStartDate": "2023-04-26T00:00:00Z", "couponEndDate": "2023-07-26T00:00:00Z", "couponPeriod": 91}, {...}, ...]}

def ExtendBondsData( self, instruments: list[str], xlsx: bool = False) -> pandas.core.frame.DataFrame:

Requests jsons with raw bonds data for every ticker or FIGI in instruments list and transform it to the wider Pandas DataFrame with more information about bonds: main info, current prices, bond payment calendar, coupon yields, current yields and some statistics etc.

WARNING! This is too long operation if a lot of bonds requested from broker server.

Parameters

instruments: list of strings with tickers or FIGIs.
xlsx: if True then also exports Pandas DataFrame to xlsx-file bondsXLSXFile, default ext-bonds.xlsx, for further used by data scientists or stock analytics.

Returns

wider Pandas DataFrame with more full and calculated data about bonds, than raw response from broker. In XLSX-file and Pandas DataFrame fields mean: - main info about bond: https://tinkoff.github.io/investAPI/instruments/#bond - info about coupon: https://tinkoff.github.io/investAPI/instruments/#coupon

def CreateBondsCalendar( self, extBonds: pandas.core.frame.DataFrame, xlsx: bool = False) -> pandas.core.frame.DataFrame:

Creates bond payments calendar as Pandas DataFrame, and also save it to the XLSX-file, calendar.xlsx by default.

WARNING! This is too long operation if a lot of bonds requested from broker server.

See also: ShowBondsCalendar(), ExtendBondsData().

Parameters

extBonds: Pandas DataFrame object returns by ExtendBondsData() method and contains extended information about bonds: main info, current prices, bond payment calendar, coupon yields, current yields and some statistics etc. If this parameter is None then used figi or ticker as bond name and then calculate ExtendBondsData().
xlsx: if True then also exports Pandas DataFrame to file calendarFile + ".xlsx", calendar.xlsx by default, for further used by data scientists or stock analytics.

Returns

Pandas DataFrame with only bond payments calendar data. Fields mean: https://tinkoff.github.io/investAPI/instruments/#coupon

def ShowBondsCalendar( self, extBonds: pandas.core.frame.DataFrame, show: bool = True, onlyFiles=False) -> str:

Show bond payments calendar as a table. One row in input bonds dataframe contains one bond. Also, creates Markdown file with calendar data, calendar.md by default.

Parameters

extBonds: Pandas DataFrame object returns by ExtendBondsData() method and contains extended information about bonds: main info, current prices, bond payment calendar, coupon yields, current yields and some statistics etc. If this parameter is None then used figi or ticker as bond name and then calculate ExtendBondsData().
show: if True then also printing bonds payment calendar to the console, otherwise save to file calendarFile only. False by default.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

multilines text in Markdown format with bonds payment calendar as a table.

def OverviewAccounts(self, show: bool = False, onlyFiles=False) -> dict:

Method for parsing and show simple table with all available user accounts.

See also: RequestAccounts() and OverviewUserInfo() methods.

Parameters

show: if False then only dictionary with accounts data returns, if True then also print it to log.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

dict with parsed accounts data received from RequestAccounts() method. Example of dict: view = {"rawAccounts": {rawAccounts from RequestAccounts() method...}, "stat": {"accountId string": {"type": "Tinkoff brokerage account", "name": "Test - 1", "status": "Opened and active account", "opened": "2018-05-23 00:00:00", "closed": "—", "access": "Full access" }, ...}}

def OverviewUserInfo(self, show: bool = False, onlyFiles=False) -> dict:

Method for parsing and show all available user's data (accountIds, common user information, margin status and tariff connections limit).

Parameters

show: if False then only dictionary returns, if True then also print user's data to log.
onlyFiles: if True then do not show Markdown table in the console, but only generates report files.

Returns

dict with raw parsed data from server and some calculated statistics about it.

def HistoryAutoUpdater( tickersList: Union[list, str], dateStart: str = '-3', outputDir: str = None, crontabExpr: str = '*/5 10-23 * * 1-5', waitAfterIteration: int = 60, waitNext: int = 1, **kwargs) -> None:

Periodically updates history for a list of tickers using cron expression and multithreading. This method blocks execution in an infinite loop. Can be used for --auto-update mode.

Required fields for history update must be passed via **kwargs and will be forwarded to self.History().

Example: HistoryAutoUpdater( tickersList=["GAZP", "SBER"], crontabExpr="*/2 10-18,19-23 * * 0-6", timeToSleep=300, interval="hour", onlyMissing=True, show=True, csvSep="," )

Parameters

tickersList: List of ticker symbols to update.
dateStart: This is start parameter from TinkoffBrokerServer.History() method. Default is -3. See also TradeRoutines.GetDatesAsString() method.
outputDir: Output directory where history files are stored. Default is None mean current workdir.
crontabExpr: Cron-style schedule string (evaluated by pycron). Default is */5 10-23 * * 1-5. See example at https://crontab.guru/#/5_10-23__*_1-5
waitAfterIteration: Delay in seconds after each iteration completed, default is 60 seconds.
waitNext: Technical pause (in seconds) between two crontab checks, default is 1 second.
kwargs: All additional keyword arguments are passed to the History() method of the TinkoffBrokerServer() class, include token and accountId.

class Args:

If the Main () function is imported as module, then this class used to convert arguments from **kwargs as object.

Args(**kwargs)

def ParseArgs():

This function gets and parses command line keys.

def Main(**kwargs):

Main function for work with TKSBrokerAPI Platform in the console.

See examples:

in english: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md
in russian: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md