Page 1 of 16
Primus Web API
(To obtain your API key please mail us at [email protected] )
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 16
Index
1. Profile ................................................................................................................................ 4
Request .................................................................................................................................. 4
Response ............................................................................................................................... 4
2. Place Normal Order .......................................................................................................... 5
Request .................................................................................................................................. 5
Response ............................................................................................................................... 5
3. Modify Normal Order ........................................................................................................ 6
Request .................................................................................................................................. 6
Response ............................................................................................................................... 6
4. Cancel Normal Order ........................................................................................................ 7
Request .................................................................................................................................. 7
Response ............................................................................................................................... 7
5. Scripinfo. ........................................................................................................................... 8
Request .................................................................................................................................. 8
Response ............................................................................................................................... 8
6. Search Script. ................................................................................................................... 9
Request .................................................................................................................................. 9
Response ............................................................................................................................... 9
7. Orderbook ........................................................................................................................10
Request .................................................................................................................................10
Response ..............................................................................................................................10
8. TradeBook ........................................................................................................................11
Request .................................................................................................................................11
Response ..............................................................................................................................11
9. OrderHistory ....................................................................................................................12
Request .................................................................................................................................12
Response ..............................................................................................................................12
10. PositionBook .................................................................................................................13
Request .................................................................................................................................13
Response ..............................................................................................................................13
Page 3 of 16
11. Demat Holdings .............................................................................................................14
Request .................................................................................................................................14
Response ..............................................................................................................................14
12. Cash Positions ...............................................................................................................15
Request .................................................................................................................................15
Response ..............................................................................................................................15
13. Glossary .........................................................................................................................16
Page 4 of 16
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":"[email protected]",
"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":"[email protected]\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 5 of 16
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,SL-M
"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 6 of 16
3. Modify Normal Order
Request
Method URL
PUT
/
api
/v1/orders
Sample Request Parameters (Possible values in comment)
{
"oms_order_id":"200327000000027"// fixed value as per order response
"instrument_token":"11536", // fixed value as per order request
"exchange":"NSE", // fixed value as per order request
"product":"MIS", // fixed value as per order request
"validity":"DAY", // fixed value as per order request
"order_type":"LIMIT", // can be LIMIT ,MARKET ,SL ,SL-M
"price":2073, // can be changed
"trigger_price":0, // can be changed if SL or SL-M
"quantity":1, // can be changed
"disclosed_quantity":0, // can be changed
"client_id":"XYZ" // fixed value
}
Response
Status Sample Response
200
{
"data":{
"oms_order_id":[
"200327000000027"
]
},
"message":"Order modification request submitted",
"status":"success"
}
Page 7 of 16
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":[
"200327000000027"
]
},
"message":"Order modification request submitted",
"status":"success"
}
Page 8 of 16
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 9 of 16
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 10 of 16
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 11 of 16
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 12 of 16
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 13 of 16
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 14 of 16
11. Demat Holdings
Request
Method URL
GET
/api/
v1/
holdings?client_id=
<clientID>
Response
Status Sample Response
200
{
"data": [
{
}
],
"message": "",
"status": "success"
}
Page 15 of 16
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 16 of 16
13. 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 Modified date: 18/04/2020
