When building algorithmic trading systems, it is essential to have an account open with a modern broker that provides APIs for placing and querying trades programmatically. This allows us to control the broking account, which is conventionally operated manually using the broker's website, using our Python script, which would be part of our larger algorithmic trading system. This chapter demonstrates various essential recipes that introduce the essential broker API calls needed for developing a complete algorithmic trading system.

This chapter covers the following recipes:

• Setting up Python connectivity with the broker
• Querying a list of instruments
• Fetching an instrument
• Querying a list of exchanges
• Querying a list of segments
• Knowing other attributes supported by the broker
• Placing a simple REGULAR order
• Placing a simple BRACKET order
• Placing a simple DELIVERY order
• Placing a simple INTRADAY order
• Querying margins and funds
• Calculating the brokerage charged
• Calculating the government taxes charged

Let's get started!

You will need the following to successfully execute the recipes in this chapter:

• Python 3.7+
• The Pythonpyalgotrading package ($ pip install pyalgotrading)

The first thing you need to set up connectivity with the broker is API keys. The broker provides unique keys to each customer, typically as anapi-key andapi-secret key pair. These API keys are chargeable, usually on a monthly subscription basis. You need to get your copies ofapi-key andapi-secret from the broker's website before you start this recipe. Please refer toAppendix I for more details.

How to do it…

We execute the following steps to complete this recipe:

1. Import the necessary modules:

>>> from pyalgotrading.broker.broker_connection_zerodha import BrokerConnectionZerodha

2. Get theapi_key andapi_secret keys from the broker. These are unique to you and will be used by the broker to identify your Demat account:

>>> api_key = "<your-api-key>"
>>> api_secret = "<your-api-secret>"
>>> broker_connection = BrokerConnectionZerodha(api_key, api_secret)

You will get the following result:

Installing package kiteconnect via pip...
Please login to this link to generate your request token: https://kite.trade/connect/login?api_key=<your-api-key>&v=3

3. Get the request token from the preceding URL:

>>> request_token = "<your-request-token>"
>>> broker_connection.set_access_token(request_token)

How it works...

Instep 1, you import theBrokerConnectionZerodha class frompyalgotrading. TheBrokerConnectionZerodha class provides an abstraction around the broker-specific APIs. Forstep 2, you need your API key and API secret from the broker. If you do not have them, please refer toAppendix I for detailed instructions with screenshots on getting this keys. Instep 2, you assign your API key and API secret to the newapi_key andapi_secret variables and use them to createbroker_connection, an instance of theBrokerConnectionZerodha class. If you are running this for the first time andkiteconnect is not installed,pyalgotrading will automatically install it for you. (kiteconnect is the official Python package that talks to the Zerodha backend;BrokerConnectionZerodha is a wrapper on top ofkiteconnect.)Step 2 generates a login URL. Here, you need to click on the link and log in with your Zerodha credentials. If the authentication process is successful, you will see a link in your browser's address bar that looks similar to the following:

https://127.0.0.1/?request_token=&action=login&status=success

For example, the full link would be as follows:

https://127.0.0.1/?request_token=H06I6Ydv95y23D2Dp7NbigFjKweGwRP7&action=login&status=success

Copy the alphanumeric-token,H06I6Ydv95y23D2Dp7NbigFjKweGwRP7, and paste it intorequest_token as part ofstep 3. Thebroker_connection instance is now ready to perform API calls.

Once thebroker_connection handle is ready, it can be used to query the list containing all the financial instruments provided by the broker.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the previous recipe in this chapter to set up this object.

How to do it…

We execute the following steps to complete this recipe:

1. Display all the instruments:

>>> instruments = broker_connection.get_all_instruments()
>>> instruments

You will get an output similar to the following. The exact output may differ for you:

  instrument_token exchange_token tradingsymbol name last_price expiry strike tick_size lot_size instrument_type segment exchange
0 267556358 1045142 EURINR20AUGFUT EURINR 0.0 2020-08-27 0.0 0.0025 1 FUT BCD-FUT BCD
1 268660998 1049457 EURINR20DECFUT EURINR 0.0 2020-12-29 0.0 0.0025 1 FUT BCD-FUT BCD
2 266440966 1040785 EURINR20JULFUT EURINR 0.0 2020-07-29 0.0 0.0025 1 FUT BCD-FUT BCD
3 266073606 1039350 EURINR20JUNFUT EURINR 0.0 2020-06-26 0.0 0.0025 1 FUT BCD-FUT BCD
4 265780742 1038206 EURINR20MAYFUT EURINR 0.0 2020-05-27 0.0 0.0025 1 FUT BCD-FUT BCD
... ... ... ... ... ... ... ... ... ... ... ... ...
64738 978945 3824 ZODJRDMKJ ZODIAC JRD-MKJ 0.0 0.0 0.0500 1 EQ NSE NSE
64739 2916865 11394 ZOTA ZOTA HEALTH CARE 0.0 0.0 0.0500 1 EQ NSE NSE
64740 7437825 29054 ZUARI-BE ZUARI AGRO CHEMICALS 0.0 0.0 0.0500 1 EQ NSE NSE
64741 979713 3827 ZUARIGLOB ZUARI GLOBAL 0.0 0.0 0.0500 1 EQ NSE NSE
64742 4514561 17635 ZYDUSWELL ZYDUS WELLNESS 0.0 0.0 0.0500 1 EQ NSE NSE

64743 rows × 12 columns

2. Print the total number of instruments:

>>> print(f'Total instruments: {len(instruments)}')

We get the following output (your output may differ):

Total instruments: 64743

How it works…

The first step fetches all the available financial instruments using theget_all_instruments() method ofbroker_connection. This method returns apandas.DataFrame object. This object is assigned to a new variable,instruments, which is shown in the output ofstep 1. This output may differ for you as new financial instruments are frequently added and existing ones expire regularly. The final step shows the total number of instruments provided by the broker.

Instruments, also known asfinancial instruments orsecurities, are assets that can be traded in an exchange. In an exchange, there can easily be tens of thousands of instruments. This recipe demonstrates how to fetch an instrument based on itsexchange andtrading symbol.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the first recipe in this chapter to set up this object.

How to do it…

Fetch an instrument for a specific trading symbol and exchange:

>>> broker_connection.get_instrument(segment='NSE', tradingsymbol='TATASTEEL')

You'll get the following output:

segment: NSE
exchange: NSE
tradingsymbol: TATASTEEL
broker_token: 895745
tick_size: 0.05
lot_size: 1
expiry:
strike_price: 0.0

How it works…

Thebroker_connection object provides a handy method,get_instrument, for fetching any financial instrument. It takessegment andtradingsymbol as attributes before returning an instrument. The return object is an instance of theInstrument class.

Anexchange is a marketplace where instruments are traded. Exchanges ensure that the trading process is fair and happens in an orderly fashion at all times. Usually, a broker supports multiple exchanges. This recipe demonstrates how to find the list of exchanges supported by the broker.

Getting ready

Make sure theinstruments object is available in your Python namespace. Refer to the second recipe of this chapter to learn how to set up this object.

How to do it…

Display the exchanges supported by the broker:

>>> exchanges = instruments.exchange.unique()
>>> print(exchanges)

You will get the following output:

['BCD' 'BSE' 'NSE' 'CDS' 'MCX' 'NFO']

How it works…

instruments.exchange returns apandas.Series object. Itsunique() method returns anumpy.ndarray object consisting of unique exchanges supported by the broker.

A segment is essentially a categorization of instruments based on their types. The various types of segments that are commonly found at exchanges include cash/equities, futures, options, commodities, and currency. Each segment may have a different operating time. Usually, a broker supports multiple segments within multiple exchanges. This recipe demonstrates how to find the list of segments supported by the broker.

Getting ready

Make sure theinstruments object is available in your Python namespace. Refer to the second recipe of this chapter to learn how to set up this object.

How to do it…

Display the segments supported by the broker:

>>> segments = instruments.segment.unique()
>>> print(segments)

You will get the following output:

['BCD-FUT' 'BCD' 'BCD-OPT' 'BSE' 'INDICES' 'CDS-FUT' 'CDS-OPT' 'MCX-FUT' 'MCX-OPT' 'NFO-OPT' 'NFO-FUT' 'NSE']

How it works…

instruments.segment returns apandas.Series object. Its unique method returns anumpy.ndarray object consisting of unique segments supported by the broker.

For placing an order, the following attributes are needed: order transaction type, order variety, order type, and order code. Different brokers may support different types of order attributes. For example, some brokers may support just regular orders, while others may support regular and bracket orders. The value for each of the attributes supported by the broker can be queried using the broker specific constants provided by thepyalgotrading package.

How to do it…

We execute the following steps to complete this recipe:

1. Import the necessary class from thepyalgotrading module:

>>> from pyalgotrading.broker.broker_connection_zerodha import BrokerConnectionZerodha

2. List the order transaction types:

>>> list(BrokerConnectionZerodha.ORDER_TRANSACTION_TYPE_MAP.keys())

We'll get the following output:

[<BrokerOrderTransactionTypeConstants.BUY: 'BUY'>,
 <BrokerOrderTransactionTypeConstants.SELL: 'SELL'>]

3. List the order varieties:

>>> list(BrokerConnectionZerodha.ORDER_VARIETY_MAP.keys())

We'll get the following output:

[<BrokerOrderVarietyConstants.MARKET: 'ORDER_VARIETY_MARKET'>,
 <BrokerOrderVarietyConstants.LIMIT: 'ORDER_VARIETY_LIMIT'>,
 <BrokerOrderVarietyConstants.STOPLOSS_LIMIT: 'ORDER_VARIETY_STOPLOSS_LIMIT'>,
 <BrokerOrderVarietyConstants.STOPLOSS_MARKET: 'ORDER_VARIETY_STOPLOSS_MARKET'>]

4. List the order types:

>>> list(BrokerConnectionZerodha.ORDER_TYPE_MAP.keys())

We'll get the following output:

[<BrokerOrderTypeConstants.REGULAR: 'ORDER_TYPE_REGULAR'>,
 <BrokerOrderTypeConstants.BRACKET: 'ORDER_TYPE_BRACKET'>,
 <BrokerOrderTypeConstants.COVER: 'ORDER_TYPE_COVER'>,
 <BrokerOrderTypeConstants.AMO: 'ORDER_TYPE_AFTER_MARKET_ORDER'>]

5. List the order codes:

>>> list(BrokerConnectionZerodha.ORDER_CODE_MAP.keys())

We'll get the following output:

[<BrokerOrderCodeConstants.INTRADAY: 'ORDER_CODE_INTRADAY'>,
 <BrokerOrderCodeConstants.DELIVERY: 'ORDER_CODE_DELIVERY_T0'>]

How it works…

Instep 1, we import theBrokerConnectionZerodha class frompyalgotrading. This class holds the order attributes mapping betweenpyalgotrading and broker specific constants as dictionary objects. The next steps fetch and print these mappings. Step 2 shows that your broker supports bothBUY andSELL order transaction types.

Step 3 shows that your broker supportsMARKET,LIMIT,STOPLOSS_LIMIT, andSTOPLOSS_MARKET order varieties.Step 4 shows that your broker supportsREGULAR,BRACKET,COVER, andAFTER_MARKET order types.Step 5 shows that your broker supportsINTRADAY andDELIVERY order codes.

This recipe demonstrates how to place aREGULAR order on the exchange via the broker.REGULAR orders are the simplest types of orders. After trying out this recipe, check your broking account by logging into the broker's website; you will find that an order has been placed there. You can match the order ID with the one that's returned in the last code snippet shown in this recipe.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the first recipe of this chapter to learn how to set up this object.

How to do it…

We execute the following steps to complete this recipe:

1. Import the necessary constants frompyalgotrading:

>>> from pyalgotrading.constants import *

2. Fetch an instrument for a specific trading symbol and exchange:

>>> instrument = broker_connection.get_instrument(segment='NSE',
                                        tradingsymbol='TATASTEEL')

3. Place a simple regular order– aBUY,REGULAR,INTRADAY,MARKET order:

>>> order_id = broker_connection.place_order(
                   instrument=instrument,
                   order_transaction_type= \
                       BrokerOrderTransactionTypeConstants.BUY,
                   order_type=BrokerOrderTypeConstants.REGULAR,
                   order_code=BrokerOrderCodeConstants.INTRADAY,
                   order_variety= \
                       BrokerOrderVarietyConstants.MARKET,
                   quantity=1)
>>> order_id

We'll get the following output:

191209000001676

How it works…

Instep 1, you import constants frompyalgotrading. Instep 2, you fetch the financial instrument withsegment = 'NSE' andtradingsymbol = 'TATASTEEL' using theget_instrument() method ofbroker_connection. Instep 3, you place aREGULAR order using theplace_order() method ofbroker_connection. The descriptions of the parameters accepted by theplace_order() method are as follows:

• instrument: The financial instrument for which the order must be placed. Should an instance of theInstrument class. You passinstrument here.
• order_transaction_type: The order transaction type. Should be an enum of typeBrokerOrderTransactionTypeConstants. You passBrokerOrderTransactionTypeConstants.BUY here.
• order_type: The order type. Should be an enum of typeBrokerOrderTypeConstants. You passBrokerOrderTypeConstants.REGULAR here.
• order_code: The order code. Should be an enum of typeBrokerOrderCodeConstants. You passBrokerOrderCodeConstants.INTRADAY here.
• order_variety: The order variety. Should be an enum of typeBrokerOrderVarietyConstants. You passBrokerOrderVarietyConstants.MARKET here.
• quantity: The number of shares to be traded for the given instrument. Should be a positive integer. We pass1 here.

If the order placement is successful, the method returns an order ID which you can use at any point in time later on for querying the status of the order.

This recipe demonstrates how to place aBRACKET order on the exchange via the broker.BRACKET orders are two-legged orders. Once the first order is executed, the broker automatically places two new orders–aSTOPLOSS order and aTARGET order. Only one of them is executed at any time; the other is canceled when the first order is completed. After trying out this recipe, check your broking account by logging into the broker's website; you will find that an order has been placed there. You can match the order ID with the one that's returned in the last code snippet shown in this recipe.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the first recipe of this chapter to learn how to set up this object.

How to do it…

We execute the following steps to complete this recipe:

1. Import the necessary modules:

>>> from pyalgotrading.constants import *

2. Fetch an instrument for a specific trading symbol and exchange:

>>> instrument = broker_connection.get_instrument(segment='NSE',
                                        tradingsymbol='ICICIBANK')

3. Fetch the last traded price of the instrument:

>>> ltp = broker_connection.get_ltp(instrument)

4. Place a simpleBRACKET order– aBUY,BRACKET,INTRADAY,LIMIT order:

>>> order_id = broker_connection.place_order(
                   instrument=instrument,
                   order_transaction_type= \
                       BrokerOrderTransactionTypeConstants.BUY,
                   order_type=BrokerOrderTypeConstants.BRACKET,
                   order_code=BrokerOrderCodeConstants.INTRADAY,
                   order_variety=BrokerOrderVarietyConstants.LIMIT,
                   quantity=1, price=ltp-1,
                   stoploss=2, target=2)
>>> order_id

We'll get the following output:

191212001268839

How it works…

This recipe demonstrates how to place aDELIVERY order on the exchange via the broker. ADELIVERY order is delivered to the user's Demat account and exists until it is explicitly squared-off by the user. Positions created by delivery orders at the end of a trading session are carried forwarded to the next trading session. They are not explicitly squared-off by the broker. After trying out this recipe, check your broking account by logging into the broker's website; you will find that an order has been placed there. You can match the order ID with the one that's returned in the last code snippet shown in this recipe.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the first recipe of this chapter to learn how to set up this object.

How to do it…

We execute the following steps to complete this recipe:

1. Import the necessary modules:

>>> from pyalgotrading.constants import *

2. Fetch an instrument for a specific trading symbol and exchange:

>>> instrument = broker_connection.get_instrument(segment='NSE',
                                        tradingsymbol='AXISBANK')

3. Place a simpleDELIVERY order– aSELL,REGULAR,DELIVERY,MARKET order:

>>> order_id = broker_connection.place_order(
                   instrument=instrument,
                   order_transaction_type= \
                       BrokerOrderTransactionTypeConstants.SELL,
                   order_type=BrokerOrderTypeConstants.REGULAR,
                   order_code=BrokerOrderCodeConstants.DELIVERY,
                   order_variety= \
                       BrokerOrderVarietyConstants.MARKET,
                    quantity=1)
>>> order_id

We'll get the following output:

191212001268956

How it works…

Instep 1, you import the constants frompyalgotrading. Instep 2, you fetch the financial instrument withsegment = 'NSE' andtradingsymbol = 'AXISBANK' using theget_instrument() method ofbroker_connection. Instep 3, you place aDELIVERY order using theplace_order() method ofbroker_connection. This method accepts the following arguments:

• instrument: The financial instrument for which the order must be placed. Should be an instance of theInstrument class. You passinstrument here.
• order_transaction_type: The order transaction type. Should be an enum of typeBrokerOrderTransactionTypeConstants. You passBrokerOrderTransactionTypeConstants.SELL here.
• order_type: The order type. Should be an enum of typeBrokerOrderTypeConstants. You passBrokerOrderTypeConstants.REGULAR here.
• order_code: The order code. Should be an enum of typeBrokerOrderCodeConstants. You passBrokerOrderCodeConstants.DELIVERY here.
• order_variety: The order variety. Should be an enum of typeBrokerOrderVarietyConstants. You passBrokerOrderVarietyConstants.MARKET here.
• quantity: The number of shares to be traded for the given instrument. Should be a positive integer. We pass1 here.

If the order placement is successful, the method returns an order ID which you can use at any point in time later on for querying the status of the order.

This recipe demonstrates how to place anINTRADAY order via the broker API. AnINTRADAY order is not delivered to the user's Demat account. Positions created by intraday orders have a lifetime of a single day. The positions are explicitly squared off by the broker at the end of a trading session and are not carried forward to the next trading session. After trying out this recipe, check your broking account by logging into the broker's website; you will find that an order has been placed there. You can match the order ID with the one that's returned in the last code snippet shown in this recipe.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the first recipe of this chapter to learn how to set up this object.

How to do it…

We execute the following steps to complete this recipe:

1. Import the necessary modules:

>>> from pyalgotrading.constants import *

2. Fetch an instrument for a specific trading symbol and exchange:

>>> instrument = broker_connection.get_instrument(segment='NSE',
                                        tradingsymbol='HDFCBANK')

3. Fetch the last traded price of the instrument:

>>> ltp = broker_connection.get_ltp(instrument)

4. Place a simpleINTRADAY order– aSELL,BRACKET,INTRADAY,LIMIT order:

>>> order_id = broker_connection.place_order(
                   instrument=instrument,
                   order_transaction_type= \
                       BrokerOrderTransactionTypeConstants.SELL,
                   order_type=BrokerOrderTypeConstants.BRACKET,
                   order_code=BrokerOrderCodeConstants.INTRADAY,
                   order_variety=BrokerOrderVarietyConstants.LIMIT,
                   quantity=1, price=ltp+1, stoploss=2, target=2)
>>> order_id

We'll get the following output:

191212001269042

How it works…

Before placing orders, it is important to ensure that you have enough margins and funds available in your broking account to place the orders successfully. A lack of sufficient funds would result in the rejection of any orders placed by the broker, which means the others would never get placed on the exchange. This recipe shows you how to find the available margins and funds in your broking account at any point in time.

Getting ready

Make sure thebroker_connection object is available in your Python namespace. Refer to the first recipe of this chapter to learn how to set it up.

How to do it…

We execute the following steps to complete this recipe:

1. Display the equity margins:

>>> equity_margins = broker_connection.get_margins('equity')
>>> equity_margins

We'll get the following output (your output may differ):

{'enabled': True,
 'net': 1623.67,
 'available': {'adhoc_margin': 0,
  'cash': 1623.67,
  'opening_balance': 1623.67,
  'live_balance': 1623.67,
  'collateral': 0,
  'intraday_payin': 0},
 'utilised': {'debits': 0,
  'exposure': 0,
  'm2m_realised': 0,
  'm2m_unrealised': 0,
  'option_premium': 0,
  'payout': 0,
  'span': 0,
  'holding_sales': 0,
  'turnover': 0,
  'liquid_collateral': 0,
  'stock_collateral': 0}}

2. Display the equity funds:

>>> equity_funds = broker_connection.get_funds('equity')
>>> equity_funds

We'll get the following output (your output may differ):

1623.67

3. Display the commodity margins:

>>> commodity_margins = get_margins(commodity')
>>> commodity_margins

We'll get the following output (your output may differ):

{'enabled': True,
 'net': 16215.26,
 'available': {'adhoc_margin': 0,
  'cash': 16215.26,
  'opening_balance': 16215.26,
  'live_balance': 16215.26,
  'collateral': 0,
  'intraday_payin': 0},
 'utilised': {'debits': 0,
  'exposure': 0,
  'm2m_realised': 0,
  'm2m_unrealised': 0,
  'option_premium': 0,
  'payout': 0,
  'span': 0,
  'holding_sales': 0,
  'turnover': 0,
  'liquid_collateral': 0,
  'stock_collateral': 0}}

4. Display the commodity funds:

>>> commodity_funds = broker_connection.get_funds('commodity')
>>> commodity_funds

We'll get the following output (your output may differ):

0

How it works…

Thebroker_connection object provides methods for fetching the available margins and funds for your broking account:

• get_margins()
• get_funds()

The broker Zerodha keeps track of margins and funds separately forequity andcommodity products. If you are using a different broker supported bypyalgotrading, it may or may not track the funds and margins separately forequity andcommodity.

Step 1 shows how margins can be queried for theequity product using theget_margins() method of thebroker_connection object, withequity as an argument.Step 2 shows how funds can be queried for theequity product using theget_funds() method of thebroker_connection object, with theequity string as an argument.

Steps 3 and4 show how margins and funds can be queried for thecommodity product in a similar way with thecommodity string as an argument.

For every order completed successfully, the broker may charge a certain fee, which is usually a small fraction of the price at which the instrument was bought or sold. While the amount may seem small, it is important to keep track of the brokerage as it may end up eating a significant chunk of your profit at the end of the day.

The brokerage that's charged varies from broker to broker and also from segment to segment. For the purpose of this recipe, we will consider a brokerage of 0.01%.

How to do it…

We execute the following steps to complete this recipe:

1. Calculate the brokerage that's charged per trade:

>>> entry_price = 1245
>>> brokerage = (0.01 * 1245)/100
>>> print(f'Brokerage charged per trade: {brokerage:.4f}')

We'll get the following output:

Brokerage charged per trade: 0.1245

2. Calculate the total brokerage that's charged for 10 trades:

>>> total_brokerage = 10 * (0.01 * 1245) / 100
>>> print(f'Total Brokerage charged for 10 trades: \
            {total_brokerage:.4f}')

We'll get the following output:

Total Brokerage charged for 10 trades: 1.2450

How it works…

Instep 1, we start with the price at which a trade was bought or sold,entry_price. For this recipe, we have used1245. Next, we calculate 0.01% of the price, which comes to0.1245. Then, we calculate the total brokerage for 10 such trades, which comes out as10 * 0.1245 = 1.245.

For every order that's completed successfully, the government may charge a certain fee, which is a fraction of the price at which the instrument was bought or sold. While the amount may seem small, it is important to keep track of government taxes as they may end up eating a significant chunk of your profit at the end of the day.

The government charge depends on the location of the exchange, and varies from segment to segment. For the purpose of this recipe, we will consider government taxes at a rate of 0.1%.

How to do it…

We execute the following steps to complete this recipe:

1. Calculate the government taxes that are charged per trade:

>>> entry_price = 1245
>>> brokerage = (0.1 * 1245)/100
>>> print(f'Government taxes charged per trade: {brokerage:.4f}')

We'll get the following output:

Government taxes charged per trade: 1.2450

2. Calculate the total government taxes that are charged for 10 trades:

>>> total_brokerage = 10 * (0.1 * 1245) / 100
>>> print(f'Total Government taxes charged for 10 trades: \
            {total_brokerage:.4f}')

We'll get the following output:

Total Government taxes charged for 10 trades: 12.4500

How it works…

Instep 1, we start with the price at which a trade was bought or sold,entry_price. For this recipe, we have used1245. Next, we calculate 0.1% of the price, which comes to1.245. Then, we calculate the total brokerage for 10 such trades, which comes out as10 * 1.245 = 12.245.