Page 1 of 19
Primus Web API
Authentication
OUATH2 authentication protocol is used for all API calls. An oauth2 client library in any
programming language can be used.
Base url : <base_url>
OAuth2 CLIENT ID : User’s choice <ouathID>
OAuth2 CLIENT Secret: Tradelab will provide (please save it for future
usage)
==========================
Grant type: Authorization Code
Authorization endpoint: /oauth2/auth
Access token endpoint: /oauth2/token
Redirect url : User’s choice (or by default http://127.0.0.1)
Scope : orders holdings
Credentials : As Basic Auth Header (default)
Sample GET request
<base_url>/oauth2/auth?scope=orders%20hold-
ings&state=%7B%22param%22:%22value%22%7D&redi-
rect_uri=http://127.0.0.1&response_type=code&client_id=<oauthID>
After this is opened in Web Browser(once every trading Day) , Login ID ,password and 2FA of the Trading
platform needs to be entered.
After this step user will get the Access Token
Access Token needs to be sent with every API request until unless mentioned.
Authorization: Bearer {access_token}
Replace {access_token} with the access token obtained for the user.
In case the access_token got expired, 401 HTTP status will be sent in response for any request
in which case a new access token has to be obtained.
Page 2 of 19
Index
Contents
1. Profile ................................................................................................................................. 3
2. Place Normal Order ............................................................................................................ 4
3. Modify Normal Order .......................................................................................................... 5
4. Cancel Normal Order .......................................................................................................... 6
5. Scripinfo. ............................................................................................................................ 7
6. Search Script. ..................................................................................................................... 8
7. Orderbook .......................................................................................................................... 9
8. TradeBook .........................................................................................................................10
9. OrderHistory ......................................................................................................................11
10. PositionBook ...................................................................................................................12
11. Demat Holdings ...............................................................................................................13
12. Cash Positions.................................................................................................................14
13. Place Cover Order ...........................................................................................................15
14. Place Bracket Order ........................................................................................................16
15. Exit Bracket Order ...........................................................................................................17
16. Exit Cover Order ..............................................................................................................18
17. Glossary ..........................................................................................................................19
Page 3 of 19
1. Profile
Get user profile
Request
Method URL
GET
/api/v1/user/profile?client_id=
<clientID>
Response
Status Sample Response
200
{
"data":{
"account_type":"",
"bank_account_number":"1234567890",
"bank_branch_name":"",
"bank_name":"EQ-ICICI BANK LTD",
"branch":"EQ-ICICI BANK LTD",
"broker_id":"ABC",
"city":"",
"client_id":"XYZ",
"dob":"01/01/2000",
"email_id":"abc@gmail.com",
"exchange_nnf":{
"BSE":0,
"CDS":0,
"MCX":0,
"NFO":0,
"NSE":0
},
"exchanges_subscribed":[
"BSE",
"MCX",
"CDS",
"NSE",
"NFO"
],
"ifsc_code":"",
"name":"PRAVEEN KUMAR",
"office_addr":"abc@gmail.com\r\n9876543210",
"pan_number":"ABCDEFGHI",
"permanent_addr":"STATE",
"phone_number":"9876543210",
"products_enabled":[
"CNC",
"CO",
"MIS",
"NRML"
],
"role":{
"id":1,
"name":"CLIENT"
},
"sex":"",
"state":"",
"status":"Activated",
"twofa_enabled":true,
"user_type":"Non-Institutional"
},
"message":"",
"status":"success"
}
Page 4 of 19
2. Place Normal Order
Request
Method URL
POST
/
api/v1/orders
Sample Request Parameters (Possible values in comment)
{
"exchange":"NSE", // NSE,NFO,CDS,BSE,MCX
"order_type":"LIMIT", // LIMIT,MARKET,SL,SLM
"instrument_token":4717, // GAIL-EQ
"quantity":1,
"disclosed_quantity":0,
"price":89.7,
"order_side":"BUY", // BUY , SELL
"trigger_price":0,
"validity":"DAY", // DAY , IOC
"product":"MIS", // MIS (INTRADAY) , NRML ,CNC (CARRYFORWARD)
"client_id":"XYZ",
"user_order_id":10002,
"market_protection_percentage":0,
"device":"WEB"
}
Response
Status Sample Response
200
{
"data":{
"client_order_id":"200018000000003",
"user_order_id":10002
},
"message":"Order place successfully",
"status":"success"
}
Page 5 of 19
3. Modify Normal Order
Request
Method URL
PUT
/
api/v1/orders
Sample Request Parameters (Possible values in comment)
{
"oms_order_id":"200327000000027"// value as per order response
"instrument_token":"11536", // value of placeorder request
"exchange":"NSE", // value of placeorder request
"product":"MIS", //placeorder value- MIS/NRML/CNC/CO/BO
"validity":"DAY", // value of placeorder request
"order_type":"LIMIT", // placeorder value- LIMIT ,MARKET ,SL ,SLM
"price":2073, // can be changed
"trigger_price":0, // can be changed if order-type SL or SLM
"quantity":1, // can be changed other than BO or CO
"disclosed_quantity":0, // can be changed
"client_id":"XYZ" // id used to login
}
Response
Status Sample Response
200
{
"data":{
"oms_order_id":[
"200327000000027"
]
},
"message":"Order modification request submitted",
"status":"success"
}
Page 6 of 19
4. Cancel Normal Order
Request
Method URL
DELETE
/api/v1/orders/
<
omsOrderNum
>
?client_id=
<clientID>
example: /api/v1/orders/200327000000027?client_id=XYZ
Response
Status Sample Response
200
{
"data":{
"oms_order_id":"200420000000023"
},
"message":"Order cancellation request submitted for OMS Order:
200420000000023",
"status":"success"
}
Page 7 of 19
5. Scripinfo.
Request
Method URL
GET
/api/v1/contract/
<exchange>
?info=scrip&token=
<instrumentToken>
example: /api/v1/contract/NSE?info=scrip&token=4717
Response
Status Sample Response
200
{
"error":{
"code":0,
"message":""
},
"result":{
"board_lot_quantity":1,
"change_in_oi":0,
"exchange":1,
"expiry":0,
"higher_circuit_limit":88.95,
"instrument_name":"EQ",
"instrument_token":4717,
"isin":"INE129A01019",
"lower_circuit_limit":72.85,
"multiplier":1,
"open_interest":0,
"option_type":"",
"precision":2,
"series":"EQ",
"strike":0,
"symbol":"GAIL",
"tick_size":0.05,
"trading_symbol":"GAIL-EQ",
"underlying_token":4717,
"raw_expiry":0,
"freeze":274,
"instrument_type":"0",
"issue_rate":0,
"issue_start_date":"544406400",
"list_date":"544406400",
"max_order_size":0,
"price_numerator":0,
"price_denominator":0,
"comments":"",
"circuit_rating":"",
"company_name":"GAIL (INDIA) LTD",
"display_name":"GAIL EQ",
"raw_tick_size":5,
"is_index":false,
"tradable":true,
"max_single_qty":0,
"expiry_string":"",
"local_update_time":"",
"market_type":"",
"price_units":"",
"trading_units":"",
"last_trading_date":"",
"tender_period_end_date":"",
"delivery_start_date":"",
"price_quotation":0,
"general_denominator":"",
"tender_period_start_date":"",
"delivery_units":"",
"delivery_end_date":"",
"trading_unit_factor":0,
"delivery_unit_factor":0
}
}
Page 8 of 19
6. Search Script.
Request
Method URL
GET
/api/v1/search?key=<keyword>
example: /api/v1/search?key=SPICE
Response
Status Sample Response
200
{
"error":{
"code":0,
"message":""
},
"result":[
{
"company":"SPICEJET LIMITED",
"display_name":"SPICEJET EQ",
"exchange":"NSE",
"symbol":"SPICEJET",
"token":11446,
"trading_symbol":"SPICEJET-EQ"
},
{
"company":"SPICEJET LTD.",
"display_name":"SPICEJET A",
"exchange":"BSE",
"symbol":"SPICEJET LTD.",
"token":500285,
"trading_symbol":"SPICEJET-A"
},
{
"company":"SPICE ISLANDS APPARELS LTD.",
"display_name":"SPICEISL XT",
"exchange":"BSE",
"symbol":"SPICE ISLANDS APPARELS LTD.",
"token":526827,
"trading_symbol":"SPICEISL-XT"
}
]
}
Page 9 of 19
7. Orderbook
Request
Type Method URL
Pending
GET
/api/v1/orders?type=pending&client_id=
<clientID>
Completed
GET
/api/v1/orders?type=
completed
&client_id=
<clientID>
Response
Status Sample Response (Possible values in comment)
200
{
"data":{
"orders":[
{
"order_tag":"",
"validity":"DAY",
"square_off_value":null,
"exchange_order_id":"1100000000314214",
"exchange":"NSE", // NSE,NFO,CDS,BSE,MCX
"rejection_reason":"",
"amo":false,
"trade_price":0,
"order_entry_time":1585308069,
"mode":"NEW",
"is_trailing":false,
"trading_symbol":"TCS-EQ",
"segment":"",
"series":"",
"order_side":"BUY", // BUY , SELL
"product":"MIS", // MIS,CNC,NRML
"stop_loss_value":null,
"device":null,
"contract_description":{
},
"leg_order_indicator":"",
"client_id":"XYZ",
"deposit":0,
"remaining_quantity":1,
"last_activity_reference":0,
"order_status":"open", // open ,trigger pending ,completed ,rejected, cancelled
"square_off?":false,
"login_id":"XYZ",
"pro_cli":"CLIENT",
"trailing_stop_loss":null,
"market_protection_percentage":0,
"order_status_info":"",
"rejection_code":0,
"target_price_type":"absolute",
"user_order_id":"1",
"lot_size":1,
"price":"2074.00",
"average_trade_price":"00.00",
"disclosed_quantity":0,
"oms_order_id":"200327000000027",
"filled_quantity":0,
"trigger_price":"00.00",
"exchange_time":1585307852,
"nnf_id":0,
"instrument_token":"11536",
"quantity":1,
"order_type":"LIMIT", // LIMT ,MARKET ,SL,SL-M
"average_price":"00.00"
}
]
},
"message":"",
"status":"success"
}
Page 10 of 19
8. TradeBook
Request
Method URL
GET
/api/v1/trades?client_id=
<clientID>
Response
Status Sample Response
200
{
"data":{
"trades":[
{
"book_type":"",
"broker_id":"",
"client_id":"XYZ",
"disclosed_vol":0,
"disclosed_vol_remaining":0,
"exchange":"NSE",
"exchange_order_id":"1100000000503286",
"exchange_time":1587037856,
"fill_number":"50143479",
"filled_quantity":1,
"good_till_date":"",
"instrument_token":2885,
"login_id":"XYZ",
"oms_order_id":"200416000000015",
"order_entry_time":1587210656,
"order_price":1425.0,
"order_side":"BUY",
"order_type":"MKT",
"original_vol":0,
"pan":"ABCDEFGH",
"pro_cli":"--",
"product":"MIS",
"remaining_quantity":null,
"trade_number":"50143479",
"trade_price":1425.0,
"trade_quantity":1,
"trade_time":1587210656,
"trading_symbol":"RELIANCE-EQ",
"trigger_price":0,
"vol_filled_today":"Filledqty"
}
]
},
"message":"",
"status":"success"
}
Page 11 of 19
9. OrderHistory
Request
Method URL
GET
/api/v1/order/
<
omsOrderNum
>
/history?client_id=
<clientID>
example: /api/v1/order/200327000000020/history?client_id=XYZ
Response
Status Sample Response
200
{
"data": [
{
"avg_price": "2074.0",
"client_id": "XYZ",
"client_order_id": null,
"created_at": null,
"disclosed_quantity": "0",
"exchange": "NSE",
"exchange_order_id": "1100000000229456",
"exchange_time": "27-Mar-2020 16:26:50",
"fill_quantity": 1,
"last_modified": null,
"login_id": null,
"modified_at": null,
"order_id": "200327000000020",
"order_mode": null,
"order_side": "B", // B , S
"order_type": null,
"price": "2074.00",
"product": "MIS",
"quantity": 1,
"reject_reason": "--",
"remaining_quantity": null,
"segment": null,
"status": "complete",
"symbol": null,
"token": null,
"trigger_price": "0.0",
"underlying_token": null,
"validity": null
}
],
"message": "",
"status": "success"
}
Page 12 of 19
10. PositionBook
Request
Type
Method
URL
Live
(only
Day)
GET
/api/v1/positions?type=
live
&client_id=
<ClientID>
All(Live+
Historical)
GET
/api/v1/positions?type=historical&client_id=
<ClientID>
Response
Status Sample Response
200
{
"data":[
{
"average_buy_price":1476.58,
"average_price":0,
"average_sell_price":0.0,
"buy_amount":2953.15,
"buy_quantity":2,
"cf_buy_amount":0.0,
"cf_buy_quantity":0,
"cf_sell_amount":0.0,
"cf_sell_quantity":0,
"client_id":"XYZ",
"close_price":0,
"exchange":"NSE",
"instrument_token":22,
"ltp":1172.8,
"multiplier":1,
"net_amount":-2953.15,
"net_quantity":2,
"previous_close":1172.8,
"prod_type":"NRML",
"product":"NRML",
"realized_mtm":0.0,
"segment":null,
"sell_amount":0.0,
"sell_quantity":0,
"symbol":"ACC",
"token":22,
"trading_symbol":"ACC-EQ"
}
],
"message":"",
"status":"success"
}
Page 13 of 19
11. Demat Holdings
Request
Method URL
GET
/api/
v1/holdings?client_id=
<clientID>
Response
Status Sample Response
200
{
"data":{
"holdings":[
{
"branch_code":"",
"buy_avg":4.16,
"buy_avg_mtm":-5.000000000000004,
"client_id":"XYZ",
"exchange":"BSE",
"instrument_details":{
"exchange":6,
"instrument_name":"E",
"instrument_token":538743,
"trading_symbol":"MUDUNURU-XT"
},
"isin":"INE491C01027",
"ltp":3.96,
"previous_close":4.16,
"quantity":25,
"symbol":"MUDUNURU",
"t0_price":0.0,
"t0_quantity":0,
"t1_price":0.0,
"t1_quantity":0,
"t2_price":0.0,
"t2_quantity":0,
"token":538743,
"trading_symbol":"MUDUNURU",
"used_quantity":0
}
]
},
"message":"",
"status":"success"
}
Page 14 of 19
12. Cash Positions
Request
Method URL
GET
/
api/v1/funds/view?client_id=
<clientID>
&type=all
Response
Status Sample Response
200
{
"data":{
"client_id":"XYZ",
"headers":[
"Description",
""
],
"values":[
[
"Available",
"611773.30"
],
[
"Adhoc Deposit",
"0.00"
],
[
"Cash Deposit",
"1448713.90"
],
[
"Delivery",
"0.00"
],
[
"DP Collateral Benefit",
"179.37"
],
[
"DP Credit for Sale",
"0.00"
],
[
"DP Pledge Collateral",
"0.00"
],
[
"Manual Collateral",
"0.00"
],
[
"Miscellaneous Deposit",
"0.00"
],
[
"Net Margin",
"836940.60"
],
[
"Notion Deposit",
"0.00"
],
[
"Overdraft",
"0.00"
],
[
"Pay out",
"0.00"
],
[
"Pool Collateral Benefit",
"0.00"
],
[
"Pool Pledge Collateral",
"0.00"
],
[
"Premium",
"0.00"
],
[
"Sar Collateral Benefit",
"0.00"
],
[
"Sar Credit for Sale",
"0.00"
],
[
"Span Margin",
"587880.00"
],
[
"Var Margin",
"0.00"
],
Page 15 of 19
13. Place Cover Order
Note: May not be supported / enabled in all environments by default, please check with
your Broker
Request
Method URL
POST
/
api/v1/orders
Sample Request Parameters (Possible values in comment)
{
"exchange":"NSE", // NSE,NFO,CDS,BSE,MCX
"order_type":"LIMIT", // LIMIT,MARKET
"instrument_token":4717, // GAIL-EQ
"quantity":1,
"disclosed_quantity":0,
"price":89.7,
"order_side":"BUY", // BUY , SELL
"trigger_price":89,
"validity":"DAY", // DAY , IOC
"product":"CO", // CO (Cover Order)
"client_id":"XYZ",
"user_order_id":10002,
"market_protection_percentage":0,
"device":"WEB"
}
Response
Status Sample Response
200
{
"data":{
"client_order_id":"300018000000592",
"user_order_id":10002
},
"message":"Order place successfully",
"status":"success"
}
Page 16 of 19
14. Place Bracket Order
Note: May not be supported / enabled in all environments by default, please check with
your Broker
Request
Method URL
POST
/api/
v1/orders/bracket
Sample Request Parameters (Possible values in comment)
{
"exchange": "NSE", // NSE,NFO,CDS,BSE,MCX
"instrument_token": 22,
"quantity": 1,
"disclosed_quantity": 0,
"validity": "DAY",
"square_off_value": 1301, // Target Sell price (profit)
"stop_loss_value": 1290, // Stop Loss price (cover loss)
"price": 1299,
"trigger_price":1299, //0 for LIMIT,non 0 value if order_type is SL
"source": "web",
"trailing_stop_loss": 1,
"order_type": "SL", //LIMIT , SL
"product": "BO",
"order_side": "BUY", //BUY ,SELL
"is_trailing":false, //true ,false
"user_order_id": 10003,
"client_id":"XYZ"
}
Response
Status Sample Response
200
{
"data":{
"client_order_id":"300018000000593",
"user_order_id":10002
},
"message":"Order place successfully",
"status":"success"
}
Page 17 of 19
15. Exit Bracket Order
Note: May not be supported / enabled in all environments by default, please check with
your Broker
Request
Method URL
DELETE
v1/orders/bracket
Sample Request Parameters (Possible values in comment)
{
"oms_order_id": "200602000000313",
"leg_order_indicator": "200602000000311", //oms_order_id for 1
st
leg BO
"status": "trigger pending", // open or trigger pending
"client_id":"XYZ"
}
Response
Status Sample Response
200
{
"data": {},
"message": "Ok",
"status": "success"
}
Page 18 of 19
16. Exit Cover Order
Note: May not be supported / enabled in all environments by default, please check with
your Broker
Request
Method URL
DELETE
v1/orders/
cover
Sample Request Parameters (Possible values in comment)
{
"oms_order_id": "200602120000429",
"leg_order_indicator": "209102000000526", //oms_order_id for 1
st
leg CO
"client_id":"XYZ"
}
Response
Status Sample Response
200
{
"data": {},
"message": "Ok",
"status": "success"
}
Page 19 of 19
17. Glossary
Conventions
● All response are in JSON format.
● All request parameters are mandatory unless explicitly marked as [optional]
Status Codes
All status codes are standard HTTP status codes. The below ones are used in this API.
2XX - Success of some kind
4XX - Error occurred in client’s part
5XX - Error occurred in server’s part
Status Code Description
200
OK
400
Bad request
401
Authentication failure
403
Forbidden
404
Resource not found
405
Method Not Allowed
500
Internal Server Error
503
Service Unavailable
Document Modification date: 02/06/2020
