A XTS Codebase from TradeHull
Project description
TradeHull XTS Codebase Project
This project is built to interact with the XTS API using the XTS_Tradehull
library. It provides a suite of tools for trading, fetching market data, managing orders, and handling portfolio-related operations.
Features
- Fetch Market Data: Get Live Trading Price (LTP), OHLC, and historical data.
- Order Management: Place, modify, and cancel orders.
- Option Strike Selection: Fetch ATM, ITM, and OTM strike prices.
- Portfolio Management: Retrieve holdings, positions, and account balances.
- Automated Trading Tools: Telegram alerts and instrument validity checks.
Installation
To install the required dependencies:
pip install -r requirements.txt
Install XTS Package
To install the XTS package:
pip install XTS-Tradehull
Upgrade XTS Package
To update the XTS package:
pip install --upgrade XTS-Tradehull
Usage
XTS API Authentication
Initialize the TradeHull object with your XTS API credentials:
from XTS_Tradehull import Tradehull
tsl = Tradehull(interactive_key="your_interactive_key",interactive_secret="your_interactive_secret",market_key="your_market_key",market_secret="your_market_secret",client_code="your_client_code", root_url = 'root_url_provided_by_brocker'
)
Broker URLs for Web Terminals and API Access
Motilal Oswal
- Root URL:
https://moxtsapi.motilaloswal.com:3000
- Web Terminal URL:
https://moxtsapi.motilaloswal.com:3000/#!/app
- API Access URL:
https://moxtsapi.motilaloswal.com:3000/dashboard#!/login
IIFL
- Root URL:
https://ttblaze.iifl.com
- Web Terminal URL:
https://ttblaze.iifl.com/#!/app
- API Access URL:
https://ttblaze.iifl.com/dashboard#!/login
Jainam
- Root URL:
http://ctrade.jainam.in:3000
- Web Terminal URL:
http://ctrade.jainam.in:3000/#!/app
- API Access URL:
http://ctrade.jainam.in:3000/dashboard#!/login
5 Paisa
- Root URL:
https://www.5paisa.com
- Web Terminal URL:
https://trade.5paisa.com
- API Access URL:
https://api.5paisa.com/login
Bigul
- Root URL:
https://trading.bigul.co/
- Web Terminal URL:
https://trading.bigul.co/#!/app
- API Access URL:
https://trading.bigul.co/dashboard#!/login
Nirmal Bang
- Root URL:
https://xts.nirmalbang.com/
- Web Terminal URL:
https://xts.nirmalbang.com/#!/app
- API Access URL:
https://xts.nirmalbang.com/dashboard#!/login
Get Market Data
Get Live Trading Price (LTP)
Fetch the latest trading price for an instrument.
tsl.get_ltp(name: str)
Arguments:
name
(str): Trading symbol/Description (e.g., 'NIFTY', 'CRUDEOIL')
Returns:
- float: Latest trading price of the instrument
- None: If there was an error or price not available
Example:
# Get LTP for NIFTY
nifty_ltp = tsl.get_ltp("NIFTY")
# Get LTP for multi-stocks
ltp_data = tsl.get_ltp(["YESBANK-EQ","ACC-EQ"])
Get Quote Data
Fetch detailed quote data including touchline information for an instrument.
tsl.get_quote(names: str)
Arguments:
names
(str): Trading symbol/Description (e.g., 'NIFTY', 'CRUDEOIL')
Returns:
- dict: Quote data containing touchline information
- Key: Instrument name
- Value: Dictionary with quote details
- None: If there was an error
Example:
# Get quote for NIFTY
nifty_quote = tsl.get_quote("NIFTY")
# Get quote for multi-stocks
quote_data = tsl.get_quote(["YESBANK-EQ","ACC-EQ"])
Get Historical Data
Retrieve historical OHLC (Open, High, Low, Close) data for instruments.
tsl.get_historical_data(tradingsymbol: str, timeframe: str, interval: int)
Arguments:
tradingsymbol
(str): Trading symbol/Description (e.g., 'NIFTY', 'ACC-EQ')timeframe
(str): The timeframe for the data- '1minute': 1-minute candles
- '2minute': 2-minute candles
- '3minute': 3-minute candles
- '5minute': 5-minute candles
- '10minute': 10-minute candles
- '15minute': 15-minute candles
- '30minute': 30-minute candles
- '60minute': 60-minute candles
- 'day': Daily candles
interval
(int): Number of candles to fetch
Returns:
- DataFrame: Historical OHLC data
- None: If there was an error
Example:
# Get daily OHLC data for NIFTY
historical_data = tsl.get_historical_data("NIFTY", timeframe="day", interval=30)
# Get 5-minute OHLC data for equity
historical_data = tsl.get_historical_data("RELIANCE-EQ", timeframe="5minute", interval=100)
2. Order Management
Place an Order
order_id = tsl.order_placement(stock="NIFTY25MAR22000PE",quantity=75,price=100,trigger_price=0,productType="MIS",order_type="Limit",transaction_type="BUY")
Parameters:
stock
(str): Trading symbol/Description (e.g., 'NIFTY25MAR22000PE', 'ACC-EQ')quantity
(int): Number of shares/contractsprice
(float): Limit price (use 0 for market orders)trigger_price
(float): Trigger price for stop orders (use 0 for regular orders)productType
(str):- Valid values: 'MIS', 'NRML', 'CNC'
order_type
(str):- Valid values: 'Limit', 'Market', 'StopLimit', 'StopMarket'
transaction_type
(str):- Valid values: 'BUY', 'SELL'
validity_type
(str, optional):- Valid values: 'DAY', 'IOC'
- Default: 'DAY'
Supported Exchanges:
- NSEFO (NSE Futures & Options)
- NSECM (NSE Cash Market)
- BSECM (BSE Cash Market)
- NSECD (NSE Currency Derivatives)
- MCXFO (MCX Futures & Options)
- BSEFO (BSE Futures & Options)
Returns:
- str: Order ID if successful
- None: If there was an error
Example Orders:
# Limit order for options
orderid = tsl.order_placement(stock='NIFTY25MAR22000PE',quantity=75,price=0.05,trigger_price=0,productType='MIS',order_type='Limit',transaction_type='BUY')
# Market order for equity
orderid = tsl.order_placement(stock='YESBANK-EQ',quantity=1,price=0,trigger_price=0,productType='MIS',order_type='Market',transaction_type='BUY')
# Stop-limit order
orderid = tsl.order_placement(stock='ACC-EQ',quantity=1,price=2674,trigger_price=2670,productType='MIS',order_type='StopLimit',transaction_type='BUY')
Order Modification
The modify_order function allows you to modify existing orders in the market.
modified_order_id = tsl.modify_order(appOrderID="12345",
modifiedOrderType="Limit",
modifiedOrderQuantity=50,
modifiedLimitPrice=95.5,
modifiedStopPrice=0
)
Parameters:
appOrderID
(str): The unique ID of the original order to be modifiedmodifiedOrderType
(str): Type of the modified order- Valid values: 'Limit', 'Market', 'StopLimit', 'StopMarket'
modifiedOrderQuantity
(int): The new quantity for the ordermodifiedLimitPrice
(float): The new limit price for the ordermodifiedStopPrice
(float): The new trigger/stop price for the order
Default Values:
- Product Type is fixed to 'MIS'
- Validity is fixed to 'DAY'
- Disclosed Quantity is fixed to 0
Returns:
- str: Modified order ID if successful
- None: If there was an error
Example Usage:
# Modify a limit order
modified_order_id = tsl.modify_order(
appOrderID="12241210603927",
modifiedOrderType="Limit",
modifiedOrderQuantity=50,
modifiedLimitPrice=0.1,
modifiedStopPrice=0
)
# Modify Limit order to market order
modified_order_id = tsl.modify_order(
appOrderID="12241210603927",
modifiedOrderType="Market",
modifiedOrderQuantity=100,
modifiedLimitPrice=0,
modifiedStopPrice=0
)
# Modify to stop-limit order
modified_order_id = tsl.modify_order(
appOrderID="12241210603927",
modifiedOrderType="StopLimit",
modifiedOrderQuantity=75,
modifiedLimitPrice=100.5,
modifiedStopPrice=99.5
)
Order Cancellation
The cancel_order function allows you to cancel an existing order in the market.
tsl.cancel_order(OrderID="12345")
Parameters:
OrderID
(str): The unique ID of the order to be canceled
Returns:
- None: The function doesn't return any value
- Raises an exception if the cancellation fails
Example Usage:
# Cancel a specific order
tsl.cancel_order(OrderID="12241210603927")
Cancel All Orders and Close Positions
-
To cancel all the intraday open and trigger pending orders, square off all the positions
-
tsl.cancel_all_orders()
-
Sample Code:
order_details = tsl.cancel_all_orders()
-
Returns:
- dict: Dictionary containing order details of squared-off positions
- Key: Trading Symbol
- Value: Dictionary with 'orderid' and 'price' of the square-off order
- Empty dict if no orders/positions to cancel/close
3. Option Strike Selection
Get ATM Strike
tsl.get_atm(ltp: float, underlying: str, expiry: int, script_type: str)
Arguments:
ltp
(float): Last traded price of the underlyingunderlying
(str): The index name (e.g., 'NIFTY', 'BANKNIFTY')expiry
(int): The expiry to select- 0 - Current expiry
- 1 - Next expiry
- 2 - Third expiry from now
script_type
(str): Option type ('CE' or 'PE')
Returns:
- str: The option symbol for the ATM strike
- None: If there was an error
Sample Code:
atm_option = tsl.get_atm(ltp=22250, underlying="NIFTY", expiry=0, script_type="CE")
Get ITM Strike
tsl.get_itm(ltp: float, underlying: str, expiry: int, script_type: str, multiplier: int)
Arguments:
ltp
(float): Last traded price of the underlyingunderlying
(str): The index name (e.g., 'NIFTY', 'BANKNIFTY')expiry
(int): The expiry to select- 0 - Current expiry
- 1 - Next expiry
- 2 - Third expiry from now
script_type
(str): Option type ('CE' or 'PE')multiplier
(int): Number of strikes away from ATM for ITM selection
Returns:
- str: The option symbol for the ITM strike
- None: If there was an error
Sample Code:
itm_option = tsl.get_itm(ltp=18200, underlying="NIFTY", expiry=0, script_type="CE", multiplier=1)
Get OTM Strike
tsl.get_otm(ltp: float, underlying: str, expiry: int, script_type: str, multiplier: int)
Arguments:
ltp
(float): Last traded price of the underlyingunderlying
(str): The index name (e.g., 'NIFTY', 'BANKNIFTY')expiry
(int): The expiry to select- 0 - Current expiry
- 1 - Next expiry
- 2 - Third expiry from now
script_type
(str): Option type ('CE' or 'PE')multiplier
(int): Number of strikes away from ATM for OTM selection
Returns:
- str: The option symbol for the OTM strike
- None: If there was an error
Sample Code:
otm_option = tsl.get_otm(ltp=22250, underlying="NIFTY", expiry=0, script_type="PE", multiplier=2)
Order Status and Price
Get Order Status
tsl.get_order_status(order_id: str)
Arguments:
order_id
(str): The unique identifier of the order
Returns:
- str: Current status of the order (e.g., 'New', 'Completed', 'Cancelled')
- None: If there was an error
Sample Code:
orderid = '12241210603927'
order_status = tsl.get_order_status(order_id=orderid)
Get Order Executed Price
tsl.get_executed_price(order_id: str)
Arguments:
order_id
(str): The unique identifier of the order
Returns:
- float: Average traded price of the executed order
- Returns 0 if order price is None or empty
- None: If there was an error
Sample Code:
orderid = '12241210603927'
order_price = tsl.get_executed_price(order_id=orderid)
Get Order Report
Get comprehensive order details including status, execution price, and timing for multiple orders.
tsl.order_report()
Arguments:
- None
Returns:
- Tuple containing three dictionaries:
order_details
: Dictionary with order status- Key: Order ID (str)
- Value: Order status (str)
order_exe_price
: Dictionary with execution prices- Key: Order ID (str)
- Value: Average traded price
order_placed_time
: Dictionary with order timestamps- Key: Order ID (str)
- Value: Last update time
- Returns three empty dictionaries in case of error
Sample Code:
order_details, execution_prices, order_times = tsl.order_report()
Account Balance
Get Account Balance
Fetch the available cash balance from your trading account.
tsl.get_account_balance()
Returns:
- int: Available cash balance in the account
- Returns 0 if there was an error
Sample Code:
available_balance = tsl.get_account_balance()
Get Live PNL
Retrieve real-time Profit and Loss (PNL) calculation for all open positions.
tsl.get_pnl()
Returns:
- float: Total PNL across all positions
- Positive value indicates profit
- Negative value indicates loss
- 0: If no open positions exist
- None: If there was an error
Telegram Alerts
Send Telegram Alert
Send real-time alerts and notifications via Telegram bot.
tsl.send_telegram_alert(message: str, receiver_chat_id: str, bot_token: str)
Arguments:
message
(str): The text message to send- Can include trade details, alerts, or any notification text
- Supports basic text formatting
receiver_chat_id
(str): Telegram chat ID for message delivery- For individual users: Personal chat ID
- For groups: Group chat ID (bot must be added to group)
bot_token
(str): Telegram bot authorization token- Obtained from BotFather when creating a bot
- Format:
"123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ"
Returns:
- None
- Prints success/failure message to console
- Logs exceptions if any error occurs
Setup Steps:
- Create a Telegram bot via BotFather
- Get the bot token
- Add bot to desired chat/group
- Get chat ID for the target recipient
Sample Code:
# Send trade execution alert
tsl.send_telegram_alert(
message="Order executed: BUY 50 shares of RELIANCE @ 2400",
receiver_chat_id="123456789",
bot_token="123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ"
)
# Send market alert
tsl.send_telegram_alert(
message="NIFTY crossed 19000!",
receiver_chat_id="987654321",
bot_token="123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ"
)
Check Valid Instrument
Verify if a given instrument name exists in the exchange.
tsl.check_valid_instrument(name: str)
Arguments:
name
(str): Trading symbol/Description (e.g., 'NIFTY25MAR22300PE', 'ACC-EQ')
Returns:
- str: Message indicating if instrument is valid or invalid
- "instrument {name} is valid" if found
- "instrument {name} is invalid" if not found
- None: If there was an error
Example:
# Check if NIFTY option exists
result = tsl.check_valid_instrument("NIFTY25MAR22750PE")
# Check if equity exists
result = tsl.check_valid_instrument("RELIANCE-EQ")
Get Expiry Dates
Retrieve sorted list of expiry dates for futures or options of an underlying.
tsl.get_expiry_dates(underlying: str, Opt_fut: str)
Arguments:
underlying
(str): Trading symbol (e.g., 'NIFTY', 'BANKNIFTY', 'FINNIFTY', 'MIDCPNIFTY')Opt_fut
(str): Instrument type- 'Option' for options contracts
- 'Future' for futures contracts
Returns:
- list: Sorted list of expiry dates in 'YYYY-MM-DD' format
- None: If there was an error
Example:
# Get NIFTY option expiry dates
expiry_dates = tsl.get_expiry_dates(underlying="NIFTY", Opt_fut="Option")
# Get BANKNIFTY futures expiry dates
expiry_dates = tsl.get_expiry_dates(underlying="BANKNIFTY", Opt_fut="Future")
Get Lot Size
Retrieve the lot size for a given instrument.
tsl.get_lot_size(script_name: str)
Arguments:
script_name
(str): Trading symbol/Description (e.g., 'NIFTY25MAR22000PE', 'RELIANCE-EQ')
Returns:
- int: Lot size of the instrument
- 0: If invalid script name
- None: If there was an error
Example:
# Get lot size for NIFTY options
lot_size = tsl.get_lot_size("NIFTY25MAR22000PE")
# Get lot size for equity
lot_size = tsl.get_lot_size("RELIANCE-EQ")
Get Freeze Quantity
Retrieve the maximum allowed quantity (freeze quantity - 1) for a given instrument.
tsl.get_freeze_quantity(strike: str)
Arguments:
strike
(str): Trading symbol/Description (e.g., 'NIFTY25MAR22000PE', 'RELIANCE-EQ')
Returns:
- int: Maximum allowed quantity (freeze quantity - 1)
- 0: If invalid script name
- None: If there was an error
Example:
# Get freeze quantity for NIFTY options
freeze_qty = tsl.get_freeze_quantity("NIFTY25MAR22000PE")
Notes
- Ensure your API keys and client credentials are correct.
- Tokens expire periodically; refresh them as needed.
- Debugging can be enabled by modifying the log level in
XTS_Tradehull.py
.
License
This project is licensed under the MIT License.
Contact
For queries or issues, please contact: contact.tradehull@gmail.com.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
File details
Details for the file XTS_Tradehull-1.0.2-py3-none-any.whl
.
File metadata
- Download URL: XTS_Tradehull-1.0.2-py3-none-any.whl
- Upload date:
- Size: 22.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
af92e10bcab5fd4d42331a9e71de4546c5082668abd6daff3872134e4222d3e8
|
|
MD5 |
f90209cc857082e12ade9c5b944d6a41
|
|
BLAKE2b-256 |
83ce97a8bd9758726c1c16e5923cd38beb590fd7c0971d33c6c20568f4f44709
|