upstox / upstox-python

Official Python SDK for accessing Upstox API

MIT License

38 stars 43 forks

Star Watch

Code Issues 12 Pull requests 6 Actions Projects Security

master Go to file

AlokGaira [Feature ] : Updated README.md. … Sep 21, 2017 49

View code

README.md

Python SDK for Upstox API

The official Python library for communicating with the Upstox APIs.

Upstox Python library provides an easy to use wrapper over the HTTPs APIs.

The HTTP calls have been converted to methods and JSON responses are
wrapped into Python-compatible objects.

Websocket connections are handled automatically with the library

Installation
This module is installed via pip:

pip install upstox

To force upgrade existing installations:

 pip uninstall upstox
pip --no-cache-dir install --upgrade upstox

Prerequisites
Python 2.x or 3.x

Also, you need the following modules:

• future
• websocket_client
• requests

The modules can also be installed using pip

Getting started with API

Overview
There are two classes in the library: Session, and Upstox. The Session class is
used to retrieve an access token from the server. An access token is valid for
24 hours. With an access token, you can instantiate an Upstox object. Ideally
you only need to create a Session object once every day. After you have the
access token, you can store it separately for re-use.

REST Documentation
The original REST API that this SDK is based on is available online. Upstox API
REST documentation

Sample Program
An interactive Python program to test your connectivity and show
functionality is available on Gist.

Using the API

Get an access token

1. Import Upstox
 from upstox_api.api import *

2. Create a Session object with your api_key , redirect_uri and

api_secret

s = Session ('your_api_key')
s.set_redirect_uri ('your_redirect_uri')
s.set_api_secret ('your_api_secret')

3. Get the login URL so you can login with your Upstox UCC ID and
password.

print (s.get_login_url())
## this will return a URL such as https://api.upstox.com/index/dialog/authorize?apiKey={

 

4. Login to the URL and set the code returned by the login response in your
Session object

s.set_code ('your_code_from_login_response')

5. Retrieve your access token

access_token = s.retrieve_access_token()
print ('Received access_token: %s' % access_token)

Establish a session
1. Once you have your access_token , you can create an Upstox object with
your access_token and api_key .

u = Upstox ('your_api_key', access_token)

2. You can run commands here to check your connectivity

print (u.get_balance()) # get balance / margin limits

print (u.get_profile()) # get profile
 print (u.get_holdings()) # get holdings
print (u.get_positions()) # get positions

Get master contracts

Getting master contracts allow you to search for instruments by symbol name
and place orders. Master contracts are stored as an OrderedDict by token
number and by symbol name. Whenever you get a trade update, order
update, or quote update, the library will check if master contracts are loaded.
If they are, it will attach the instrument object directly to the update.

u.get_master_contract('NSE_EQ') # get contracts for NSE EQ

u.get_master_contract('NSE_FO') # get contracts for NSE FO
u.get_master_contract('NSE_INDEX') # get contracts for NSE INDEX
u.get_master_contract('BSE_EQ') # get contracts for BSE EQ
u.get_master_contract('BCD_FO') # get contracts for BCD FO
u.get_master_contract('BSE_INDEX') # get contracts for BSE INDEX
u.get_master_contract('MCX_INDEX') # get contracts for MCX INDEX
u.get_master_contract('MCX_FO') # get contracts for MCX FO

Search for symbols

Symbols can be retrieved in multiple ways. Once you have the master contract
loaded for an exchange, you can search for an instrument in many ways.

Search for a single instrument by it's name:

tatasteel_nse_eq = u.get_instrument_by_symbol('NSE_EQ', 'TATASTEEL')

reliance_nse_eq = u.get_instrument_by_symbol('NSE_EQ', 'RELIANCE')
ongc_bse_eq = u.get_instrument_by_symbol('BSE_EQ', 'ONGC')
mcxagri_mcx_index = u.get_instrument_by_symbol('MCX_INDEX', 'MCXAGRI')
india_vix_nse_index = u.get_instrument_by_symbol('NSE_INDEX', 'INDIA_VIX'
sensex_nse_index = u.get_instrument_by_symbol('BSE_INDEX', 'SENSEX')

 

Search for a single instrument by it's token number (generally useful only for
BSE Equities):

ongc_bse_eq = u.get_instrument_by_token('BSE_EQ', 500312)

reliance_bse_eq = u.get_instrument_by_token('BSE_EQ', 500325)
acc_nse_eq = u.get_instrument_by_token('NSE_EQ', 22)
Search for multiple instruments by matching the name

all_tata_companies_on_bse = u.search_instruments('BSE_EQ', 'tata')

Instrument object

Instruments are represented by instrument objects. These are named-tuples

that are created by the get_master_contract function. They are used when
placing an order and searching for an instrument. The structure of an
instrument tuple is as follows:

Instrument = namedtuple('Instrument', ['exchange', 'token', 'parent_token'

'name', 'closing_price', 'expiry'
'tick_size', 'lot_size', 'instrument_type'

 

All instruments have the fields mentioned above. Wherever a field is not
applicable for an instrument (for example, equity instruments don't have strike
prices), that value will be None

Quote update
Once you have master contracts loaded, you can easily subscribe to quote
updates.

Two types of feed data available

You can either subscribe for a full quote update or an LTP quote update. Using
the LiveFeedType object, you can specify whether you want the full feed
( LiveFeedType.Full ) or just the LTP feed ( LiveFeedType.LTP )

Get current market price

u.get_live_feed(u.get_instrument_by_symbol('NSE_EQ', 'ACC'), LiveFeedType

u.get_live_feed(u.get_instrument_by_symbol('BSE_EQ', 'RELIANCE'), LiveFeedType

 

Subscribe to a live feed

Start getting live feed via socket

 def event_handler_quote_update(message):
print("Quote Update: %s" % str(message))

u.set_on_quote_update(event_handler_quote_update)

u.subscribe(u.get_instrument_by_symbol('NSE_EQ', 'TATASTEEL'), LiveFeedType

u.subscribe(u.get_instrument_by_symbol('BSE_EQ', 'RELIANCE'), LiveFeedType

u.start_websocket(True)

 

Unsubscribe to a live feed

Unsubscribe to an existing live feed

u.unsubscribe(u.get_instrument_by_symbol('NSE_EQ', 'TATASTEEL'), LiveFeedType

u.unsubscribe(u.get_instrument_by_symbol('BSE_EQ', 'RELIANCE'), LiveFeedType

 

Get historical data

Get historical OHLC data for any symbol

u.get_ohlc(u.get_instrument_by_symbol('NSE_EQ', 'RELIANCE'), OHLCInterval

 

Place an order
Place limit, market, SL, SL-M, AMO, OCO/BO, CO orders

print (u.get_profile())
u.get_master_contract('nse_eq') # get contracts for NSE EQ

# TransactionType.Buy, OrderType.Market, ProductType.Delivery

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, #transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), #instrument
1, # quantity
OrderType.Market, # order_type
ProductType.Delivery, # product_type
0.0, # price 
 
 None, # trigger_price 

0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None )# trailing_ticks
)

# TransactionType.Buy, OrderType.Market, ProductType.Intraday

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.Market, # order_type
ProductType.Intraday, # product_type
0.0, # price
None, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None )# trailing_ticks
)

# TransactionType.Buy, OrderType.Market, ProductType.CoverOrder

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.Market, # order_type
ProductType.CoverOrder, # product_type
0.0, # price
7.5, # trigger_price Here the trigger_price is taken as stop loss (provid
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks
)

# TransactionType.Buy, OrderType.Market, ProductType.OneCancelsOther

# OCO Order can't be of type market

# TransactionType.Buy, OrderType.Limit, ProductType.Delivery 

 
 

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%4%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.Limit, # order_type
ProductType.Delivery, # product_type
8.0, # price
None, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks
)

# TransactionType.Buy, OrderType.Limit, ProductType.Intraday

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%5%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.Limit, # order_type
ProductType.Intraday, # product_type
8.0, # price
None, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks

# TransactionType.Buy, OrderType.Limit, ProductType.CoverOrder

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%6%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.Limit, # order_type
ProductType.CoverOrder, # product_type
8.0, # price
8.0, # trigger_price Here the trigger_price is taken as stop loss (pro
0, # disclosed_quantity 
 
 DurationType.DAY, # duration 

None, # stop_loss
None, # square_off
None) # trailing_ticks 20 * 0.05
)

# TransactionType.Buy, OrderType.Limit, ProductType.OneCancelsOther

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%7%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.Limit, # order_type
ProductType.OneCancelsOther, # product_type
8.0, # price
None, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
1.0, # stop_loss
1.0, # square_off
20) # trailing_ticks 20 * 0.05
)

###############################

# TransactionType.Buy, OrderType.StopLossMarket, ProductType.Delivery

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%8%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.StopLossMarket, # order_type
ProductType.Delivery, # product_type
0.0, # price
8.0, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks
)

# TransactionType.Buy, OrderType.StopLossMarket, ProductType.Intraday


 
 print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%9%%%%%%%%%%%%%%%%%%%%%%%%%%%%%") 
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.StopLossMarket, # order_type
ProductType.Intraday, # product_type
0.0, # price
8.0, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks
)

# TransactionType.Buy, OrderType.StopLossMarket, ProductType.CoverOrder

# CO order is of type Limit and And Market Only

# TransactionType.Buy, OrderType.StopLossMarket, ProductType.OneCancelsOther

# CO order is of type Limit and And Market Only

###################################

# TransactionType.Buy, OrderType.StopLossLimit, ProductType.Delivery

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.StopLossLimit, # order_type
ProductType.Delivery, # product_type
8.0, # price
8.0, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks
)

# TransactionType.Buy, OrderType.StopLossLimit, ProductType.Intraday

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%11%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print( 
 
 u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.StopLossLimit, # order_type
ProductType.Intraday, # product_type
8.0, # price
8.0, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
None, # stop_loss
None, # square_off
None) # trailing_ticks
)

# TransactionType.Buy, OrderType.StopLossLimit, ProductType.CoverOrder

# CO order is of type Limit and And Market Only

# TransactionType.Buy, OrderType.StopLossLimit, ProductType.OneCancelsOther

print ("%%%%%%%%%%%%%%%%%%%%%%%%%%%%12%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
print(
u.place_order(TransactionType.Buy, # transaction_type
u.get_instrument_by_symbol('NSE_EQ', 'UNITECH'), # instrument
1, # quantity
OrderType.StopLossLimit, # order_type
ProductType.OneCancelsOther, # product_type
8.0, # price
8.0, # trigger_price
0, # disclosed_quantity
DurationType.DAY, # duration
1.0, # stop_loss
1.0, # square_off
20) # trailing_ticks 20 * 0.05
)
 

Cancel an order

u.cancel_order('170713000075481') #Cancel an open order (Should be a string not an int)

u.cancel_order('170713000075481,170713000075482') #Cancel multiple open orders (No space
u.cancel_all_orders() #Cancel all open orders

 
Order properties as objects
Order properties such as TransactionType, OrderType, and others have been
safely classified as objects so you don't have to write them out as strings

TransactionType

Transaction types indicate whether you want to buy or sell. Valid transaction
types are of the following:

• TransactionType.Buy - buy
• TransactionType.Sell - sell

OrderType

Order type specifies the type of order you want to send. Valid order types
include:

• OrderType.Market - Place the order with a market price

• OrderType.Limit - Place the order with a limit price (limit price
parameter is mandatory)
• OrderType.StopLossLimit - Place as a stop loss limit order
• OrderType.StopLossMarket - Place as a stop loss market order

ProductType

Product types indicate the complexity of the order you want to place. Valid
product types are:

• ProductType.Intraday - Intraday order that will get squared off before

market close
• ProductType.Delivery - Delivery order that will be held with you after
market close
• ProductType.CoverOrder - Cover order
• ProductType.OneCancelsOther - One cancels other order. Also known as
bracket order

DurationType

Duration types specify how long your order will stay on the market. Valid
duration types include:

• DurationType.DAY - Day order

 • DurationType.IOC - Immediate or cancel order

Listen to live events

You can attach handlers to the following market events:

• Quote update
• Trade update
• Order update

Upstox uses the Websocket library to provide real-time updates for these
events

1. Before starting the websocket, attach event handlers to the events you
want to be notified for

def my_generic_event_handler (event):

print ("Event: %s" % str(event))

u.set_on_order_update (my_generic_event_handler)
u.set_on_quote_update (my_generic_event_handler)

2. Start the websocket library. The first parameter, run_in_background ,

controls whether the socket will run as a daemon or not

To run it in the current thread

u.start_websocket (False)

To run it in the background, please ensure that your program doesn't exit.
Here's an example of

u.start_websocket (True)
condition = threading.Condition()
condition.acquire()
condition.wait()

Releases 2

1.5.1 Latest
 Jun 30, 2017

+ 1 release

Packages

No packages published

Contributors 2

AlokGaira

svishi Shrini

Languages

Python 100.0%