Extend information for bonds

[Tim55667757]

Add to --info bonds payment schedule, the number of payments in total and already redeemed coupons, and also calculate the ACI, current yield, yield to maturity and coupon value.

See also: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons

[Tim55667757]

Implemented since v1.4.*

When requesting information about bonds (with the --info or -i key), more data is now calculated and displayed: bond payment calendar, total number of payments and already redeemed coupons, coupons yield (average coupon daily yield * 365), current price yield (average daily yield * 365), ACI and coupon's size. To request the necessary information, the RequestBondCoupons() (returns a dictionary of processed data received from the server) and ExtendBondsData() (returns an extended pandas dataframe containing more information about bonds) methods were implemented to extend bonds data with more information. The ShowInstrumentInfo() method has been improved to display more information on bonds and the payment calendar. To receive extended information about bonds in XLSX-format now you can use --bonds-xlsx (-b) key.

[Tim55667757]

Debug build run: https://app.travis-ci.com/github/Tim55667757/TKSBrokerAPI/builds/257466833
PyPI dev-build: https://pypi.org/project/tksbrokerapi/1.4.dev84/

Get extended bonds data

TKSBrokerAPI v1.4.* contains a new console command --bonds-xlsx (-b). This action get all available bonds if only key present or list of bonds with FIGIs or tickers and transform it to the wider pandas dataframe with more information about bonds: main info, current prices, bonds payment calendar, coupon yields, current yields and some statistics etc.

Also, at the end data exports to XLSX-file, for the further used by datascientists or stock analytics. Default ext-bonds.xlsx or you can change it with the --output key.

❗ WARNING: this is too long operation if a lot of bonds requested from broker server (~90-120 extended data bonds per minute, depends on speed limit rate).

Which mean headers in XLSX-file, see here: "Main bond information" and "Coupon information".

Headers in XLSX-file or pandas dataframe:

• actualDateTime — the date and time at which the extended data on the bond was received;
• figi — FIGI identifier of the instrument;
• ticker — instrument ticker;
• classCode — Class Code (exchange section where instrument is traded);
• isin — ISIN identifier of the instrument;
• lot — lot of the instrument (you can trade operation only with volumes of the instrument multiple of this parameter);
• currency — settlement currency (for buying and selling an instrument);
• shortEnabledFlag — availability flag for short operations;
• name — human-understandable name of the instrument;
• exchange — trading platform (MOEX — Moscow Exchange, SPBEX — St. Petersburg Exchange, OTC — over-the-counter transactions);
• couponQuantityPerYear — number of coupon payments per year;
• maturityDate — bond maturity date in UTC time zone;
• nominal — current nominal price of a bond;
• stateRegDate — bond state registration date in UTC time zone;
• placementDate — bond placement date in UTC time zone;
• placementPrice — bond placement price;
• aciValue — current accumulated coupon income;
• countryOfRisk — country risk code (the country in which the company keep its main business);
• countryOfRiskName — name of the country risk (the country in which the company keep its main business);
• sector — sector of the economy;
• issueKind — bond issue kind (documentary or non_documentary);
• issueSize — actual issue size;
• issueSizePlan — planned issue size;
• tradingStatus — current instrument trading status at the moment of actualDateTime;
• otcFlag — flag of an over-the-counter security;
• buyAvailableFlag — buy available flag;
• sellAvailableFlag — sell available flag;
• floatingCouponFlag — flag of floating coupon bond;
• perpetualFlag — flag of a perpetual bond;
• amortizationFlag — flag of a bond with debt amortization;
• apiTradeAvailableFlag — flag of the ability to trade the instrument through the API (including through the TKSBrokerAPI);
• realExchange — real platform for settlements;
• forIisFlag — availability indicator for individual investment account;
• first1minCandleDate — date and time of the first available minute candle of the instrument in the UTC time zone;
• first1dayCandleDate — date of the first available daily candle of the instrument in the UTC time zone;
• type — instrument type (Currencies, Shares, Bonds, Etfs and Futures);
• step — minimal step of changes;
• nominalCurrency — nominal currency;
• aciCurrency — currency of coupon payments for bonds;
• klong — risk rate coefficient for a long position;
• kshort — risk rate coefficient for a short position;
• dlong — risk rate of minimum margin per long;
• dshort — risk rate of minimum margin per short;
• dlongMin — risk rate of start margin per long;
• dshortMin — risk rate of start margin per short;
• limitUpPercent — the upper limit of the prices set by the stock exchange for a bond, as a percentage of the nominal price;
• limitDownPercent — the lower limit of the prices set by the stock exchange for a bond, as a percentage of the nominal price;
• lastPricePercent — last bond price, as a percentage of the nominal price;
• closePricePercent — last day close price, as a percentage of the nominal price;
• changes — the difference between the last price of a bond and the closing price of the previous trading day, measured as a percentage;
• limitUp — the upper limit of the prices set by the exchange for a bond in the settlement currency;
• limitDown — the lower limit of the prices set by the exchange for a bond in the settlement currency;
• lastPrice — last bond price in the settlement currency;
• closePrice — last day close price in the settlement currency;
• changesDelta — the difference between the last price of a bond and the closing price of the previous trading day in the settlement currency;
• sumCoupons — the sum of all declared coupons for payment on the bond during the entire period of its validity;
• periodDays — the total number of days for all coupon periods of the bond;
• couponsYield — annual coupon yield on a bond (average daily yield, assuming all coupons paid, multiplied by 365 days);
• daysToMaturity — number of days remaining until full redemption of the bond;
• sumLastCoupons — amount of remaining coupon payments (in the currency of aciCurrency coupon payments);
• lastPayments — the amount of payments remaining on the current date actualDateTime sumLastCoupons, reduced by the ACI value aciValue;
• currentYield — current yield at the time of actualDateTime (the current price is taken, the average daily yield is calculated and multiplied by 365 days);
• calendar — bond payments calendar is a python list of dictionaries, which contains all coupons data, where fields mean:
  • couponDate — coupon payment date;
  • couponNumber — coupon number;
  • fixDate — date of fixing the register, before which, inclusive, you need to have to buy a bond to receive payments;
  • payCurrency — the currency in which the coupon will be paid (usually the same as aciCurrency);
  • payOneBond — pay one bond in payment currency payCurrency;
  • couponType — coupon type (Constant, Floating, Discount, Mortgage, Fixed, Variable and Other);
  • couponStartDate — start date of coupon period in UTC time zone;
  • couponEndDate — end date of coupon period in UTC time zone;
  • couponPeriod — days count in coupon period.

An example of the generated XLSX file, with extended bond data, can be viewed here: ./docs/media/ext-bonds.xlsx.

Command to generate extended data for multiple bonds

$ tksbrokerapi -v 10 --bonds-xlsx RU000A1002C2 RU000A102CK5 RU000A101YV8 BBG00JS9D851 --output ext-bonds--2022-11-05.xlsx

TKSBrokerAPI.py     L:4451 DEBUG   [2022-11-05 17:54:31,756] >>> TKSBrokerAPI module started at: [2022-11-05 14:54:31] UTC, it is [2022-11-05 17:54:31] local time
TKSBrokerAPI.py     L:4465 DEBUG   [2022-11-05 17:54:31,757] TKSBrokerAPI major.minor.build version used: [1.4.dev0]
TKSBrokerAPI.py     L:4466 DEBUG   [2022-11-05 17:54:31,757] Host CPU count: [8]
TKSBrokerAPI.py     L:210  DEBUG   [2022-11-05 17:54:31,757] Bearer token for Tinkoff OpenAPI set up from environment variable `TKS_API_TOKEN`. See https://tinkoff.github.io/investAPI/token/
TKSBrokerAPI.py     L:223  DEBUG   [2022-11-05 17:54:31,757] Main account ID [2000096541] set up from environment variable `TKS_ACCOUNT_ID`
TKSBrokerAPI.py     L:272  DEBUG   [2022-11-05 17:54:31,757] Broker API server: https://invest-public-api.tinkoff.ru/rest
TKSBrokerAPI.py     L:430  DEBUG   [2022-11-05 17:54:31,780] Local cache with raw instruments data is used: [dump.json]
TKSBrokerAPI.py     L:431  DEBUG   [2022-11-05 17:54:31,780] Dump file was last modified [2022-11-05 09:56:11] UTC
TKSBrokerAPI.py     L:1365 DEBUG   [2022-11-05 17:54:31,780] Requested instruments without duplicates of tickers or FIGIs: ['RU000A1002C2', 'RU000A102CK5', 'RU000A101YV8', 'BBG00JS9D851']
TKSBrokerAPI.py     L:1388 DEBUG   [2022-11-05 17:54:31,781] Unique list of FIGIs: ['BBG00N6MD6M2', 'BBG00Y5TNGR6', 'TCS00A101YV8', 'BBG00JS9D851']
TKSBrokerAPI.py     L:3833 DEBUG   [2022-11-05 17:54:31,781] Requesting raw bonds calendar from server, transforming and extending it. Wait, please...
TKSBrokerAPI.py     L:1134 DEBUG   [2022-11-05 17:54:31,782] Requesting current prices: ticker [RU000A1002C2], FIGI [BBG00N6MD6M2]. Wait, please...
TKSBrokerAPI.py     L:3787 DEBUG   [2022-11-05 17:54:31,919] Requesting bond payment calendar, ticker: [RU000A1002C2], FIGI: [BBG00N6MD6M2], from: [2019-02-01T00:00:00Z], to: [2024-01-26T00:00:00Z]. Wait, please...
TKSBrokerAPI.py     L:3802 DEBUG   [2022-11-05 17:54:32,094] Records about bond payment calendar successfully received
TKSBrokerAPI.py     L:3941 DEBUG   [2022-11-05 17:54:32,103] 25.0% bonds processed [1 / 4]...
TKSBrokerAPI.py     L:1134 DEBUG   [2022-11-05 17:54:32,105] Requesting current prices: ticker [RU000A102CK5], FIGI [BBG00Y5TNGR6]. Wait, please...
TKSBrokerAPI.py     L:3787 DEBUG   [2022-11-05 17:54:32,221] Requesting bond payment calendar, ticker: [RU000A102CK5], FIGI: [BBG00Y5TNGR6], from: [2020-11-20T00:00:00Z], to: [2027-11-20T00:00:00Z]. Wait, please...
TKSBrokerAPI.py     L:3802 DEBUG   [2022-11-05 17:54:32,365] Records about bond payment calendar successfully received
TKSBrokerAPI.py     L:3941 DEBUG   [2022-11-05 17:54:32,376] 50.0% bonds processed [2 / 4]...
TKSBrokerAPI.py     L:1134 DEBUG   [2022-11-05 17:54:32,378] Requesting current prices: ticker [RU000A101YV8], FIGI [TCS00A101YV8]. Wait, please...
TKSBrokerAPI.py     L:3787 DEBUG   [2022-11-05 17:54:32,469] Requesting bond payment calendar, ticker: [RU000A101YV8], FIGI: [TCS00A101YV8], from: [2020-07-29T00:00:00Z], to: [2023-07-26T00:00:00Z]. Wait, please...
TKSBrokerAPI.py     L:3802 DEBUG   [2022-11-05 17:54:32,619] Records about bond payment calendar successfully received
TKSBrokerAPI.py     L:3941 DEBUG   [2022-11-05 17:54:32,625] 75.0% bonds processed [3 / 4]...
TKSBrokerAPI.py     L:1134 DEBUG   [2022-11-05 17:54:32,627] Requesting current prices: ticker [XS1760786340], FIGI [BBG00JS9D851]. Wait, please...
TKSBrokerAPI.py     L:3787 DEBUG   [2022-11-05 17:54:32,717] Requesting bond payment calendar, ticker: [XS1760786340], FIGI: [BBG00JS9D851], from: [2018-01-30T00:00:00Z], to: [2111-01-01T00:00:00Z]. Wait, please...
TKSBrokerAPI.py     L:3802 DEBUG   [2022-11-05 17:54:32,845] Records about bond payment calendar successfully received
TKSBrokerAPI.py     L:3941 DEBUG   [2022-11-05 17:54:32,853] 100.0% bonds processed [4 / 4]...
TKSBrokerAPI.py     L:3961 INFO    [2022-11-05 17:54:32,953] XLSX-file with extended bonds data for further used by data scientists or stock analytics: [ext-bonds--2022-11-05.xlsx]
TKSBrokerAPI.py     L:4810 DEBUG   [2022-11-05 17:54:32,953] All operations were finished success (summary code is 0).
TKSBrokerAPI.py     L:4817 DEBUG   [2022-11-05 17:54:32,953] >>> TKSBrokerAPI module work duration: [0:00:01.197099]
TKSBrokerAPI.py     L:4818 DEBUG   [2022-11-05 17:54:32,953] >>> TKSBrokerAPI module finished: [2022-11-05 14:54:32 UTC], it is [2022-11-05 17:54:32] local time