Kotak API

Brokerage API Document
Field Value Description

Wtoken WTOKEN Wtoken of scrip (Optional)
Order price in decimal value (Keep 4 decimal
Price PRICE places for Commodity, Currency and 2
decimal places for all other segments)
Quantity QTY Quantity of the scrip in multiples of lots
display_segment EQ Segment type
DERIVATIVE
COMMODITIES
CURRENCY
lot_size LOT_SIZE Size of Lot

display_fno_eq OPT OPT for Option contract
FUT
FUT for Future contract, Blank string for
Equity contract
order_type ID
DLV ID for Intraday order.DLV for Delivery order
order_action Buy Buy for Buy order
Sell Sell for Sell order
market_exchange NSE Exchange of contract
BSE
MCX
NCDEX
Display name of construct which contains

Script SCRIPT_NAME scrip name, strike price, opt/fut, expiry date
(Optional)
Description of Result items Array
{
"percentage_static_rates": {
"brokerage": "0.49%",
"transaction_charges": "0.00345%",
"stt_ctt": "0.1%",
"sebi_tax": "0.0001%",
"stamp_duty": "0.015%",
"gst": "18%"
},
"value_static_rates": {
"brokerage": 88.2,
"transaction_charges": 0.62,
"stt_ctt": 18,
"sebi_tax": 0.02,
"stamp_duty": 3,
"gst": 15.99,
"total_charges": 125.83
},
"display_rates": {
"brokerage_str": "0.49% or Rs. 21 per order whichever is higher",
"transaction_charges_str": "0.62",
"stt_ctt_str": "18",
"sebi_tax_str": "0.02",
"stamp_duty_str": "3",
"gst_str": "15.99",
"total_charges_str": "125.83"
}
}
Response of Success example
{
"result_items": [
{
"percentage_static_rates": [ "2.5%", "0.00345%", "0.1%", "0.0001%",
"0.015%", "18%" ],
"value_static_rates": [ 986.88, 1.36, 39.48, 0.04, 6, 177.89, 1211.65 ],
"display_rates": [ "2.5% or Rs. 21 per order whichever is higher",
"1.36", "39.48", "0.04", "6", "177.89", "1211.65" ]
},
{
"percentage_static_rates": [ "2.5%", "0.00345%", "0.1%", "0.0001%",
"0.015%", "18%" ],
"value_static_rates": [ 986.88, 1.36, 39.48, 0.04, 6, 177.89, 1211.65 ],
"display_rates": [ "2.5% or Rs. 21 per order whichever is higher",
"1.36", "39.48", "0.04", "6", "177.89", "1211.65" ]
},
{
"error": "inactive_segment",
"error_description": "As per our records, in your account the segment
selected for this stock is inactive and hence we are unable to show charges
related to this order. You can activate the segment by visiting the profile
section."
}
],
"sum_total_charges": [ 1973.76, 2.72, 78.96, 0.08, 12, 355.78, 2423.3 ],
"result_count": {
"success": 2,
"error": 1,
"error_message": "We are unable to calculate the charges for this order
since the trading segment you have selected for one of the scrips / contracts
is possibly inactive. You can still continue placing your order (for other
scrips) and check your charges in your contract note or you can check
individual scrip-wise charges by entering the order information on the
individual scrip order page"
}
}
Documentation
Margin API:
Margin API takes consumer key, session token and access token as header
inputs, with no data body, to return complete margin details associated
with the client, classified segment-wise.
Complete Margin Details
https://tradeapi.kotaksecurities.com/apim/margin/1.0/margin
Request type: GET
Request body parameters:
Headers = {
'accept': 'application/json',
'consumerKey': '\<your consumer key\>',
'sessionToken': '\<your session token\>',
'Authorization': '\<your access token\>',
Order API:
The order API is concerned with all order placements, modifications, and
cancellations. The following types of orders are available at this time. Their
respective endpoints are listed as follows:
TYPES:
Normal
Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/
normal
MTF Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/

mtf
SOR Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/

sor
MIS Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/

mis
For each of the above endpoints, the request type determines whether
the request is an order placement, modification or cancellation (POST,
PUT, and DELETE respectively). For order placement, an input parameter
labelled 'instrument token' is listed. This refers to a unique number that
dictates to the server the instrument listing that the order is placed in.
Each listing on each exchange has a unique token. These values change
over time, and the latest list can be obtained via the scrip master
generation URL.
Place (places a new order)

Request type: POST
Headers = {
'Content-Type': 'application/json',
Data:
Attribute Name Datatype Description

"instrumentToken" Number Numeric token assigned to each scrip
"transactionType" String "BUY" or "SELL"
"quantity" Number Quantity of shares
"price" Number 0 for market order, non-zero for limit
"validity" String "GFD" or "IOC"
"variety" String "REGULAR" or "AMO"
"disclosedQuantity" Number Input disclosed quantity
"triggerPrice" Number Price at which order will be triggered
"tag" String "string"
Modify (modify an existing pending order using order ID to identify it)

Request type: PUT
Headers = {
Data:

"orderId" String Order ID of the order to be modified
"quantity" Number Quantity of shares
"price" Number 0 for market order, non-zero for limit
"validity" String "GFD" or "IOC"
"disclosedQuantity" Number Input disclosed quantity
"triggerPrice" Number Price at which order will be triggered
Cancel (cancel an existing pending order using order ID)

Request type: DELETE
Headers = {
*NOTE: for Order cancellation, the ORDER ID is to be added to the API

request URL, instead of the header.
For example, to cancel a NORMAL order type, the url will be:
https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/normal/\
<order ID\>
Positions API:
Positions API takes consumer key, session token and access token as
header inputs, with no data body, to return positions associated with the
client
Todays Position (gets the day's positions)
https://tradeapi.kotaksecurities.com/apim/positions/1.0/positions/todays
Request type: GET
Headers = {
Open Positions (gets currently open positions)

https://tradeapi.kotaksecurities.com/apim/positions/1.0/positions/open
Request type: GET
Headers = {
Stock Positions (gets stock positions for client eligible to be sold)

https://tradeapi.kotaksecurities.com/apim/positions/1.0/positions/stocks
Request type: GET
Headers = {
Quotes API:
Quotes APIs take consumer key, session token and access token as
header inputs, with no data body, to return instantaneous quotes for any
particular scrip associated with the instrument token passed into the url.
The instrument token for the scrip can be retrieved using the scrip master
generation URL.
Depth (returns the disclosed depth of existing orders for the scrip)
https://tradeapi.kotaksecurities.com/apim/quotes/v1.0/depth/
instruments/ \<instrument token\>
Request type: GET
Headers = {
OHLC Quote (open-high-low-close information for the scrip)

https://tradeapi.kotaksecurities.com/apim/quotes/v1.0/ohlc/instruments/
\<instrument token\>
Request type: GET
Headers = {
LTP Quote (last traded price for the scrip)

https://tradeapi.kotaksecurities.com/apim/quotes/v1.0/ltp/instruments/ \
<instrument token\>
Request type: GET
Headers = {
Full Details Quote (general quote details for the scrip)

https://tradeapi.kotaksecurities.com/apim/quotes/v1.0/instruments/ \
<instrument token\>
Request type: GET
Headers = {
Reports API:
Reports API takes consumer key, session token and access token as
header inputs, with no data body, to return order book associated with
the client, or if order ID is specified, the order status history.
Order Details (returns the general details of all orders placed by the
client)
https://tradeapi.kotaksecurities.com/apim/reports/1.0/orders
Request type: GET
Headers = {
Expanded Order Details (when order ID is specified in the API URL, it

returns the history of the order associated with the order ID instead of the
general book)
https://tradeapi.kotaksecurities.com/apim/reports/1.0/orders/\<order ID\
>
Request type: GET
Headers = {
Trade Details (returns the general details of all trades made by the client)
https://tradeapi.kotaksecurities.com/apim/reports/1.0/trades
Request type: GET
Headers = {
Expanded Trade Details (when order ID is specified in the API URL, it

returns the history of the trade associated with the order ID instead of the
general book)
https://tradeapi.kotaksecurities.com/apim/reports/1.0/trades/ \<order ID\
>
Request type: GET
Headers = {
Session API:
The first step to logging in is to generate the One-Time Token, which will
later be required for the 2-factor authentication function. For this you
must input your user ID and password associated with your Kotak
securities account as data, along with your access token, consumer key, IP
address, and app ID as header inputs (latter two being optional inputs for
clients):
Generate OTT
https://tradeapi.kotaksecurities.com/apim/session/1.0/session/login/
userid
Request type: POST
Headers = {
'ip': '\<ip address\>',
'appId': '\<your app ID\>',
Data:

userid String Your trading account user ID
password String Your trading account password
Once the OTT is generated by the function above, it is used as header
input for the 2-Factor Authentication function, along with your access
token, consumer key, IP address, and app ID as header inputs (latter two
being optional inputs for clients). One can choose between two possible
2FA functions, the first of which (as shown below) requires only your user
ID as input data (meaning no manual intervention is required). The other
option requires your user ID and your access code as input data. The
access code can be generated on any Kotak securities login portal (for
example, website), or by the GET request of the same end-point. Once the
access code is generated, it remains valid throughout the day. both
options are listed below:
Generate Session Token(2 Factor Authentication) (without access

code, requires no change in inputs)
https://tradeapi.kotaksecurities.com/apim/session/1.0/session/2FA/
oneTimeToken
Request type: POST
Headers = {
'oneTimeToken': '\<Your One Time Token(output from previous function)\>',

}
Data:

Once the above function is executed you will have your validated session
token iin your response body that can be used as header input for all
subsequent API requests.
Generate Session Token(2 Factor Authentication) (with access code,

needs to be updated daily)
https://tradeapi.kotaksecurities.com/apim/session/1.0/session/2FA/
accesscode
Request type: POST
Headers = {
'oneTimeToken': '\<Your One Time Token(output from previous function)\>',
Data:
Attribute
Datatype Description
Name
Your Kotak securities access code (sent to
accessCode String
mobile)
Once the above function is executed you will have your validated session
token iin your response body that can be used as header input for all
subsequent API requests.
Tokens Api
Generate access tokens using grant_type parameter
grant_type=password
URL
https://tradeapi.kotaksecurities.com/token
Method
POST
Request header
Authorization : Basic base64(client-key:client-secret)
Request body (application/x-www-form-urlencoded)
grant_type=password
username=<your_username>
password=<your_password>
Sample CURL
curl -k -X POST https://tradeapi.kotaksecurities.com/token --header

"Authorization: Basic Base64(consumer-key:consumer-secret)" --header
'Content-Type: application/x-www-form-urlencoded' --data-urlencod
"grant_type=password" --data-urlencod
"username=<username>&password=<password>"
Sample Response
{
"access_token": "4e125cd8-4e05-3ba4-b48c-eb1fe1c40743",
"refresh_token": "ad51d5e6-b3c3-39e4-adf3-5b4f17786adb",
"scope": "default",
"token_type": "Bearer",
"expires_in": 3600
----------------------------------------------
grant_type=refresh_token
URL
Method
POST
Request header
grant_type=refresh_token
refresh_token=<refresh_token>
Sample CURL
'Content-Type: application/x-www-form-urlencoded' --data-urlencode
'grant_type=refresh_token' --data-urlencode
'refresh_token=<refresh_token>'
Sample Response
"access_token": "803a74b0-47e2-34e7-b1af-66eb01ad4d7b",
"refresh_token": "d668eb08-0751-33fc-8bc1-f6ebfb557418",
"scope": "default",
"expires_in": 3600
----------------------------------------------
grant_type=client_credentials
URL
Method
POST
Request header

grant_type=client_credentials
Sample CURL

'Content-Type: application/x-www-form-urlencoded' --data-urlencod
"grant_type=client_credentials"
Sample Response
"access_token": "77c74dea-c463-3892-8667-36a0c7c7e890",
"scope": "am_application_scope default",
"expires_in": 3600
----------------------------------------------
ks_api_client
No description provided
 API version: 1.0.1

 Package version: 1.1.0
Requirements.
Python 2.7 and 3.4+
Installation & Usage
pip install
If the python package is hosted on a repository, you can install directly using:
pip install -e
"git+https://github.com/paramatrixtech/ksapi.git#egg=ks_api_client&subdirectory=./
python"
(you may need to run pip with root permission: sudo pip install -e
"git+https://github.com/paramatrixtech/ksapi.git#egg=ks_api_client&subdirectory=./
python")
Then import the package:
import ks_api_client
Setuptools
Install via Setuptools.
python setup.py install --user

(or sudo python setup.py install to install the package for all users)
Then import the package:
import ks_api_client
Getting Started
Please follow the installation procedure and then run the following:
from ks_api_client import ks_api

# Defining the host is optional and defaults to https://sbx.kotaksecurities.com/apim
# See configuration.py for a list of all supported configuration parameters.
client = ks_api.KSTradeApi(access_token = "", userid = "", consumer_key = "",ip =
"127.0.0.1", app_id = "", \
hosts=["https://tradeapi.kotaksecurities.com/apim"],
proxy_url = '', proxy_user = '', \
proxy_pass = '', consumer_secret = "")
# Get session for user

client.login(password = "")
#Generated session token

client.session_2fa(access_code = "")
# Place an order
client.place_order(order_type = "O", instrument_token = 727, transaction_type =
"BUY",\
quantity = 1, price = 0, disclosed_quantity = 0, trigger_price =
0,\
validity = "GFD", variety = "REGULAR", tag = "string", product =
"NORMAL", smart_order_routing="string")
client.place_order(order_type = "N", instrument_token = 727, transaction_type =

"BUY",\
quantity = 1, price = 0, disclosed_quantity = 0, trigger_price =
0,\
validity = "GFD", variety = "REGULAR", tag = "string")
# Modify an order
client.modify_order(order_id = "", price = 0, quantity = 1, disclosed_quantity = 0,
trigger_price = 0, validity = "GFD")
# Cancel an order
client.cancel_order(order_id = "")
# Get Report Orders

client.order_report()
# Get Report Orders for order id

client.order_report(order_id = "")
# Get FNO Report Orders for order id

client.order_report(order_id = "", is_fno = "Y")
# Get Trade Report

client.trade_report()
# Get Trade Report for order id

client.trade_report(order_id = "")
# Get FNO Trade Report for order id

client.trade_report(order_id = "", is_fno = "Y")
# Get Margin required

order_info = [
{"instrument_token": 727, "quantity": 1, "price": 1300, "amount": 0,
"trigger_price": 1190},
{"instrument_token": 1374, "quantity": 1, "price": 1200, "amount": 0,
"trigger_price": 1150}
]
client.margin_required(transaction_type = "BUY",order_info = order_info)
# Get Margin
client.margin()
# Get Positions
client.positions(position_type = "TODAYS")
# Get Quote details

client.quote(instrument_token = 110)
# Get Historical data

client.history("historicalprices",{"exchange":"bse","cocode":"476","fromdate":"01-
jan-2014","todate":"08-oct-2015"})
client.history("historicalprices-unadjusted",
{"exchange":"bse","co_code":"476","date":"16-Jun-2016"})
client.history("NSEFNO_HistoricalContinuousChart",{"symbol":"HDFC","expiry type":
"near"})
client.history("LiveorEODHistorical",
{"exchange":"BSE","co_code":"5400","period":"Y","cnt":"3"})
# Subscribe to instrument token's stream.

def callback_method(message):
print(message)
print("Your logic/computation will come here.")
client.subscribe(input_tokens="745,754", callback=callback_method)
# Unsubscribe from streaming service.

client.unsubscribe()
#Terminate user's Session

client.logout()
Documentation for API Endpoints

All URIs are relative to https://sbx.kotaksecurities.com/apim
Class Method Description
ks_api.KSTradeAp
SessionApi Initialise Session
i
SessionApi login Login using Userid

Class Method Description
SessionApi session_2fa Generate final Session Token
OrderApi place_order Place a New order
OrderApi modify_order Modify an existing order
OrderApi cancel_order Cancel an order
ReportsApi order_report Get order report
ReportsApi trade_report Get trade report
Get Margin Required for an order by amount or

MarginApi margin_required
quantity.
MarginApi margin Get all calculated margins.
PositionsApi positions Get's Open position.
QuoteApi quote Get Quote details
HistoricalApi history Get historical data.
StreamingAp Subscribe to streaming api of specified instrument

subscribe
i tokens.
StreamingAp
unsubscribe Unsubscribe from streaming api.
i
SessionApi logout Invalidate Session Token

Kotak API

Uploaded by

Copyright:

Available Formats

Kotak API

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Kotak API

Uploaded by

Copyright:

Available Formats

Brokerage API Document

Field Value Description

lot_size LOT_SIZE Size of Lot

Display name of construct which contains

Complete Margin Details

Request type: GET

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

MTF Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/

SOR Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/

MIS Order: https://tradeapi.kotaksecurities.com/apim/orders/1.0/order/

Place (places a new order)

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

Attribute Name Datatype Description

Modify (modify an existing pending order using order ID to identify it)

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

Attribute Name Datatype Description

Cancel (cancel an existing pending order using order ID)

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

*NOTE: for Order cancellation, the ORDER ID is to be added to the API

Todays Position (gets the day's positions)

Request type: GET

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

Open Positions (gets currently open positions)

Request type: GET

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

Stock Positions (gets stock positions for client eligible to be sold)

Request type: GET

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

Request type: GET

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',

'Authorization': '\<your access token\>',

OHLC Quote (open-high-low-close information for the scrip)

Request type: GET

Request body parameters:

'consumerKey': '\<your consumer key\>',

'sessionToken': '\<your session token\>',