Shoonya API Python Wrapper

The shoonyaapi-py library is a Python wrapper and connector designed to interface with the Shoonya Order Management System (OMS). It provides programmatic access to both the Shoonya REST API and its WebSocket services.

For comprehensive details regarding the underlying API endpoints, parameters, and authentication requirements, refer to the official Shoonya API documentation at https://www.shoonya.com/api-documentation.

Scrip masters (symbol lists) can be downloaded directly from the following URLs:

• NSE: https://api.shoonya.com/NSE_symbols.txt.zip
• NFO: https://api.shoonya.com/NFO_symbols.txt.zip
• CDS: https://api.shoonya.com/CDS_symbols.txt.zip
• MCX: https://api.shoonya.com/MCX_symbols.txt.zip
• BSE: https://api.shoonya.com/BSE_symbols.txt.zip
• BFO: https://api.shoonya.com/BFO_symbols.txt.zip

To use the API, initialize the ShoonyaApiPy class and call the login method with your credentials. You can enable debug logging to inspect the raw requests and responses sent to the server.

from api_helper import ShoonyaApiPy
import logging

# enable debug to see request and responses
logging.basicConfig(level=logging.DEBUG)

api = ShoonyaApiPy()

# credentials
user        = '< user id>'
u_pwd       = '< password >'
factor2     = 'OTP/TOTP'
vc          = 'vendor code'
app_key     = 'API key'
imei        = 'uniq identifier'

ret = api.login(userid=user, password=u_pwd, twoFA=factor2, vendor_code=vc, api_secret=app_key, imei=imei)
print(ret)

To build and install the package on your server, use the following command to install the required dependencies:

pip install -r requirements.txt

To receive live market updates, you must first connect to the WebSocket using api.start_websocket() and then use the api.subscribe() method.

Note: Both market data feeds and order updates are received through the same WebSocket connection; you only need to connect once.

feed_opened = False

def event_handler_feed_update(tick_data):
    print(f"feed update {tick_data}")

def open_callback():
    global feed_opened
    feed_opened = True

# 1. Start the websocket with callbacks
api.start_websocket(order_update_callback=None, 
                     subscribe_callback=event_handler_feed_update, 
                     socket_open_callback=open_callback)

# 2. Wait for connection to open
while not feed_opened:
    pass

# 3. Subscribe to tokens (single or list)
api.subscribe('NSE|13')
api.subscribe(['NSE|22', 'BSE|522032'])

Call get_trade_book() to get a list of all executed trades for the account. The response is a JSON array of objects containing trade execution details like fill price, fill quantity, and time.

ret = api.get_trade_book()
print(ret)

Call get_order_book() to retrieve a list of all orders placed for the account. The response is a JSON array of objects containing order details such as status, price, quantity, and exchange information.

ret = api.get_order_book()
print(ret)

Use api.searchscrip() to find the exchange-provided token for a specific scrip or to search for matching scrips using a partial string.

Naming Conventions for Search Text:

• Futures: SymbolName + ExpDate + 'F' (e.g., for instruments starting with FUT). Note: For MCX, the 'F' should be ignored.
• Put Options: SymbolName + ExpDate + 'P' + StrikePrice (for OPT instruments with type PE).
• Call Options: SymbolName + ExpDate + 'C' + StrikePrice (for OPT instruments with type C).

# Search for scrips matching 'REL' on NSE
api.searchscrip(exchange='NSE', searchtext='REL')

Use the login method to connect to the broker. This must be called successfully before any other operations can be performed. For TOTP automation, you can use the pyotp library to generate the required twoFA token.

Parameters:

• userid: User Id of the login user.
• password: Shoonya login password.
• twoFA: OTP or TOTP generated from the Shoonya app.
• vendor_code: Vendor code provided by the Noren team.
• api_secret: Prism Generated API key.
• imei: MAC address for desktop login, or IMEI for mobile.

Response: On success, the response contains stat: "Ok" and a susertoken. The susertoken must be sent in the jKey field of subsequent requests and used for WebSocket connections.

# Example login
ret = api.login(userid=uid, password=pwd, twoFA=factor2, vendor_code=vc, api_secret=app_key, imei=imei)

Use position_product_conversion() to change the product type of an existing position (e.g., converting an intraday position to carry forward or vice versa).

Important: For the tsym (trading symbol) field, use URL encoding to avoid errors with special characters (e.g., M&M should be encoded).

ret = api.get_positions()
# converts the first position from existing product to intraday
p = ret[0]
ret = api.position_product_conversion(p['exch'], p['tsym'], p['netqty'], 'I', p['prd'], 'B', 'DAY')