Introduction
Purpose:-
This API document serves as a comprehensive guide for anyone who is
looking to integrate their application with our interactive gateway
API’s. This documentation will provide you with the necessary
information to leverage the functionalities offered by our API
efficiently.
Scope:-
The primary purpose of this documentation is to provide the
knowledge and resources to successfully integrate the API’s with
their system. It aims to provide clear explanations of API
endpoints, parameters, authentication methods, response formats, and
best practices to facilitate seamless integration and optimal usage.
This documentation covers all aspects of the Interactive Gateway
API’s, including its endpoints, request and response formats,
authentication mechanisms and any additional features or
functionalities.
Target Audience:-
This documentation is intended for anyone who is willing to develop
their trading system. Whether you’re a seasoned developer familiar
with technology or a newcomer looking to explore integration
possibilities, this documentation will provide you with the guidance
and resources you need.
Assumptions:-
The documentation assumes that readers have a basic understanding of
web technologies, HTTP protocols, and basic API concepts.
Note: - All the validations are expected to be done by the
integration partner. Before submitting data to the server, it is
important to ensure all required form controls are filled out, in
the correct format.
Rate Limit
Below are the rate limits defined for Interactive API calls
Steps
Here are the steps to integrate the system :-
-
1. Use the API Key and Secret Key provided by the vendor to login
using Session Login API
-
2. On successful login , user will get an bearer token which need
to be stored to access rest of the API’s and to connect the socket
-
3. User will then need to connect to the socket by using this
token to ws://IP:PORT/token= this
endpoint
-
4. User will need to add Authorization in request header and pass
this bearer token to access the API’s
-
5. A user session will be created and all the socket events will
be sent to the connected users
-
6. At last, user can call logout API which will expire the user
token and disconnect the user from socket
Session Login
The API consumer sends a login request to the Interactive API server
with Secret Key & App Key. Upon successful validation, the user will
get a login response.
Endpoint: interactive/user/session
Method: POST
Extract the token to be used in subsequent request Headers. Also,
note some of the ENUMS/string will be used that are mentioned in
Appendix section To be saved as variables and these can be used in
the subsequent request message bodies.
Field Name |
Data Type |
Possible Values |
Description |
secretKey |
string |
|
Secret Key to validate |
appKey |
string |
|
The API App Key |
source |
string |
|
Login source of user |
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
Valid/Invalid User |
result |
LoginSuccessRes |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Body
{
“secretKey” : “Koiejemlfjoi+lkmdclemclelclcewQ”,
“appKey” : “Hujnk3iidm3”,
“source” : “API”
}
Sample Response Body
{
“type” : “sucess”,
“code” : “s-user-0001”,
“description” : “Valid User”,
“result” : {
“enums” : “socketEvent: [joined,error,success,order,trade,logout], orderSide: [BUY,SELL], orderSource: [WebAPI], positionSqareOffMode: [DayWise,NetWise], positionSquareOffQuantityType: [Percentage, ExactQty], dayOrNet: [DAY,NET], instrumentType: [Futures,Options,Spread,Equity,Spot], exchangeSegment: [NSEFO,NSECM], productType: [CNC,MIS], orderType: [StopLimit,Limit,Market]”,
“clientCodes”: [
“APICLIENT1”
],
“exchangeSegmentArray”: [
{
“key”: “NSECM”,
“value”: “NSECM”
},
{
“key”: “NSEFO”,
“value”: “NSEFO”
}
],
“token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c”,
“userID”: “APICLIENT1”,
“isInvestorClient”: false,
“isOneTouchUser”: false
}
}
Session Logout
This call invalidates the session token and destroys the API
session. After this the user should go through the login flow again
and extract the session token from the login response before further
activities.
Endpoint: - interactive/user/session
Method: - DELETE
Authorization: - Bearer Token
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
User logout status |
result |
string |
User logout status |
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
DELETE /interactive/user/session
Authorization: Bearer {token}
Sample Response Body
{
“type”: "success",
“code”: "s-user-0001",
“description”: "successfully logout from all API.",
“result”: ""
}
Balance
API calls http://IP:Port/instancename/user/balance grouped under
this category information related to limits on equities,
derivatives, upfront margin, available exposure, and other
RMS-related balances available to the user.
Endpoint: - interactive/user/balance
Method: - GET
Authorization: - Bearer Token
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
BalanceList |
Balance List |
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
GET /interactive/user/balance
Authorization: Bearer {token}
Sample Response Body
{
"result": {
"balanceList": {
"limitHeader": null,
"limitObject": {
"rmsSubLimits": {
"cashAvailable": 1000,
"collateral": 0,
"marginUtilized": 2.12,
"netMarginAvailable": 897.88,
"mtm": 0,
"unrealizedMTM": 0,
"realizedMTM": 0
},
"marginAvailable": {
"cashMarginAvailable": 1000,
"adhocMargin": 0,
"notinalCash": 0,
"payInAmount": 1000,
"payOutAmount": 0,
"cncSellBenifit": 0,
"directCollateral": 0,
"holdingCollateral": 0,
"clientBranchAdhoc": 0,
"sellOptionsPremium": 0,
"totalBranchAdhoc": 0,
"adhocFOMargin": 0,
"adhocCurrencyMargin": 0,
"adhocCommodityMargin": 0
},
"marginUtilized": {
"grossExposureMarginPresent": 85,
"buyExposureMarginPresent": 0,
"sellExposureMarginPresent": 0,
"varELMarginPresent": 2.12,
"scripBasketMarginPresent": 0,
"grossExposureLimitPresent": 915,
"buyExposureLimitPresent": 0,
"sellExposureLimitPresent": 0,
"cncLimitUsed": 0,
"cncAmountUsed": 0,
"marginUsed": 0,
"limitUsed": 0,
"totalSpanMargin": 0,
"exposureMarginPresent": 0
},
"limitsAssigned": {
"cncLimit": 1000,
"turnoverLimitPresent": 10000,
"mtmLossLimitPresent": 900,
"buyExposureLimit": 0,
"sellExposureLimit": 0,
"grossExposureLimit": 1000,
"grossExposureDerivativesLimit": 0,
"buyExposureFuturesLimit": 0,
"buyExposureOptionsLimit": 0,
"sellExposureOptionsLimit": 0,
"sellExposureFuturesLimit": 0
},
"accountID": "APICLI201"
}
}
},
"type": "success",
"code": "s-user-0001",
"description": "OK"
}
Place Order
Read all ENUMS/strings in response and token from Login response and
provide required details as per Place Order structure. Place order
request is an asynchronous call, the user is given an
apporderID.
Execution of an order is dependent on several factors like RMS
Limits, risk checks, and so on. Orders with Limit type may remain
open for an entire course of a trading day.
Endpoint: - interactive/orders
Method: - POST
Authorization: - Bearer Token
REQUEST BODY SCHEMA
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
EntrySuccessRes |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
POST /interactive/orders
Authorization: Bearer {token}
Sample Request Body
{
"exchangeSegment": "NSECM",
"exchangeInstrumentID": 22,
"productType": "MIS",
"orderType": "LIMIT",
"orderSide": "BUY",
"timeInForce": "DAY",
"disclosedQuantity": 0,
"orderQuantity": 1,
"limitPrice": 2500.50,
"stopPrice": 0,
"orderUniqueIdentifier": "123456789"
}
Sample Response Body
{
"type": "success",
"code": "s-user-0001",
"description": "Request sent",
"result": {
"AppOrderID": “10149382024B05010100000000000003”,
"OrderUniqueIdentifier": "123456789",
"ClientID": "APICLIENT1"
}
}
Modify Order
It provides the facility to modify your open orders by allowing you
to change the limit order to market or vice versa, change the Price
or Quantity of the limit open order, change the disclosed quantity,
or stop-loss of any open stop-loss order.
Endpoint: - interactive/orders
Method: - PUT
Authorization: - Bearer Token
REQUEST BODY SCHEMA
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
ModifySucessRes |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
PUT /interactive/orders
Authorization: Bearer {token}
Sample Request Body
{
"appOrderID": “10149382024B05010100000000000003”,
"modifiedProductType": "MIS",
"modifiedOrderType": "LIMIT",
"modifiedOrderQuantity": 25,
"modifiedDisclosedQuantity": 0,
"modifiedLimitPrice": 2510.65,
"modifiedStopPrice": 0,
"modifiedTimeInForce": "DAY",
"orderUniqueIdentifier": "123456789"
}
Sample Response Body
{
"type": "success",
"code": "s-user-0001",
"description": "Request sent",
"result": {
"AppOrderID": “10149382024B05010100000000000003”,
"OrderUniqueIdentifier": "123456789",
"ClientID": "APICLIENT1"
}
}
Cancel Order
This API can be called to cancel any open order of the user by
providing the correct appOrderID matching with the chosen open order
to cancel.
Endpoint: - interactive/orders?appOrderID=
Method: - DELETE
Authorization: - Bearer Token
REQUEST IN QUERY PARAMETER
Field Name |
Data Type |
Description |
appOrderID(required) |
DT_OrderID |
It is system generated Unique Order No. |
OrderUniqueIdentifier(optional) |
DT_OrderID |
It is user specific Unique Order No. |
ClientID(optional) |
DT_ClientID |
|
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
CancelSucessRes |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
DELETE /interactive/orders?appOrderID=10149382024B05010100000000000003
Authorization: Bearer {token}
Sample Response Body
{
"type": "success",
"code": "s-user-0001",
"description": "Request sent",
"result": [
{
"AppOrderID": “10149382024B05010100000000000003”,
"ClientID": "APICLIENT1"
}
]
}
Order Book
The Order book consists of states of all the orders placed by a
user.
Endpoint: - interactive/orders
Method: - GET
Authorization: - Bearer Token
REQUEST IN QUERY PARAMETER
Field Name |
Data Type |
Description |
ClientID(optional) |
DT_ClientID |
|
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
Array < orderBookSucessRes> |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
GET /interactive/orders
Authorization: Bearer {token}
Sample Response Body
{
"result": [
{
"orderExpiryDate": "01-01-1980 00:00:00",
"cancelRejectReason": "",
"boLegDetails": 0,
"boEntryOrderId": "",
"loginID": "APICLI201",
"clientID": "APICLI201",
"appOrderID": "10149382024C05010100000000000003",
"orderReferenceID": "",
"generatedBy": "TWSAPI",
"exchangeOrderID": "1100000000113017",
"orderCategoryType": "NORMAL",
"exchangeSegment": "NSECM",
"exchangeInstrumentID": 11184,
"orderSide": "BUY",
"orderType": "Regular",
"productType": "MIS",
"timeInForce": "DAY",
"orderPrice": 85,
"orderQuantity": 1,
"orderStopPrice": 0,
"orderStatus": "Executed",
"orderAverageTradedPrice": 85,
"leavesQuantity": 0,
"cumulativeQuantity": 0,
"orderDisclosedQuantity": 0,
"orderGeneratedDateTime": "05-03-2024 20:30:09",
"exchangeTransactTime": "05-03-2024 20:30:09",
"lastUpdateDateTime": "05-03-2024 20:30:09",
"orderLegStatus": "SingleOrderLeg",
"orderUniqueIdentifier": "4571111111",
"isSpread": false,
"messageCode": 1312,
"messageVersion": 0,
"tokenID": 11184,
"applicationType": 0,
"sequenceNumber": 0
}
],
"type": "success",
"code": "s-user-0001",
"description": "Success order book"
}
Trade Book
The Order book consists of states of all the orders placed by a user.
Endpoint: - interactive/orders/trades
Method: - GET
Authorization: - Bearer Token
REQUEST IN QUERY PARAMETER
Field Name |
Data Type |
Description |
ClientID(optional) |
DT_ClientID |
|
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
Array<TradeSucessRes> |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
GET /interactive/orders/trades
Authorization: Bearer {token}
Sample Response Body
{
"result": [
{
"lastTradedPrice": 85,
"lastTradedQuantity": 1,
"lastExecutionTransactTime": "05-03-2024 20:30:09",
"executionID": "",
"executionReportIndex": 0,
"loginID": "APICLI201",
"clientID": "APICLI201",
"appOrderID": "10149382024C05010100000000000003",
"orderReferenceID": "",
"generatedBy": "TWSAPI",
"exchangeOrderID": "1100000000113017",
"orderCategoryType": "NORMAL",
"exchangeSegment": "NSECM",
"exchangeInstrumentID": 11184,
"orderSide": "BUY",
"orderType": "Regular",
"productType": "MIS",
"timeInForce": "DAY",
"orderPrice": 85,
"orderQuantity": 0,
"orderStopPrice": 0,
"orderStatus": "0",
"orderAverageTradedPrice": 85,
"leavesQuantity": 0,
"cumulativeQuantity": 0,
"orderDisclosedQuantity": 0,
"orderGeneratedDateTime": "05-03-2024 20:30:09",
"exchangeTransactTime": "",
"lastUpdateDateTime": "05-03-2024 20:30:09",
"orderLegStatus": "SingleOrderLeg",
"orderUniqueIdentifier": "4571111111",
"isSpread": false,
"messageCode": 0,
"messageVersion": 0,
"tokenID": 11184,
"applicationType": 0,
"sequenceNumber": 0
}
],
"type": "success",
"code": "s-user-0001",
"description": "Success trade book"
}
Position
Endpoint: - interactive/portfolio/positions?dayOrNet=
Method: - GET
Authorization: - Bearer Token
REQUEST IN QUERY PARAMETER
Field Name |
Data Type |
Description |
dayOrNet(required) |
string |
|
RESPONSES
200:-
Field Name |
Data Type |
Description |
type |
string |
Response for request |
code |
string |
Response code to user request |
description |
string |
|
result |
Array<PositionSucessRes> |
|
400:-
On bad request, BadRequestRes model
will be returned.
Sample Request Header
GET /interactive/portfolio/positions?dayOrNet=DAY
Authorization: Bearer {token}
Sample Response Body
{
"result": [
{
"childPositions": {
"accountID": null,
"tradingSymbol": null,
"exchangeSegment": null,
"exchangeInstrumentID": 0,
"productType": null,
"marketlot": 0,
"multiplier": 0,
"buyAveragePrice": 0,
"sellAveragePrice": 0,
"openBuyQuantity": 0,
"openSellQuantity": 0,
"quantity": 0,
"buyAmount": 0,
"sellAmount": 0,
"netAmount": 0,
"unrealizedMTM": 0,
"realizedMTM": 0,
"mtm": 0,
"bep": 0,
"sumOfTradedQuantityAndPriceBuy": 0,
"sumOfTradedQuantityAndPriceSell": 0,
"statisticsLevel": null,
"isInterOpPosition": null
},
"messageCode": 0,
"messageVersion": 0,
"tokenID": 11184,
"applicationType": 0,
"sequenceNumber": 0,
"accountID": "APICLI201",
"tradingSymbol": "IDFCFIRSTB ",
"exchangeSegment": "NSECM",
"exchangeInstrumentID": 11184,
"productType": "MIS",
"marketlot": 0,
"multiplier": 0,
"buyAveragePrice": 85,
"sellAveragePrice": 0,
"openBuyQuantity": 1,
"openSellQuantity": 0,
"quantity": 1,
"buyAmount": 85,
"sellAmount": 0,
"netAmount": 0,
"unrealizedMTM": 0,
"realizedMTM": 0,
"mtm": 0,
"bep": 0,
"sumOfTradedQuantityAndPriceBuy": 85,
"sumOfTradedQuantityAndPriceSell": 0,
"statisticsLevel": "ParentLevel",
"isInterOpPosition": "true"
}
],
"type": "success",
"code": "s-user-0001",
"description": "Success position"
}
Web socket
Once the connection is established, real-time streaming can be obtained by
listening to the socket on the relevant interactive events. You can get the related
streaming data on those events. Below are the steps you need to follow to achieve real-time streaming of interactive events:
-
• Register interactive event of socket connection.
- • Real-time interactive events.
1. Connect
User need to connect server via socket (i.e. web socket).
It is important to set path parameter value as ws://IP:PORT/token= during connection.
Token will be only available after successful login.
So make sure you login first then you can connect server via socket.
2. Orders
This event will invoke whenever an order state change occurs.
OrderResponse is order object you will receive when any of your order
state changes.
3. Trade
This event will invoke whenever a trade occurs.
TradeResponse is trade object you will receive when any of your order state changes.
Protocol Structure
LoginSuccessRes
Field Name |
Data Type |
Description |
enums |
string |
|
clientCodes |
Array<string> |
It will contain clientID’s |
exchangeSegmentArray |
Array<ExchangeSegment> |
|
token |
string |
Unique token generated to validate user |
userID |
DT_ClientID |
|
isInvestorClient |
boolean |
If true, then it is investor client else dealer. |
isOneTouchUser |
boolean |
|
ExchangeSegment
Field Name |
Data Type |
Description |
key |
string |
|
value |
string |
|
BalanceList
Field Name |
Data Type |
Description |
limitHeader |
string |
|
limitObject |
LimitObject |
limitObject |
LimitObject
RMSSubLimits
MarginAvailable
MarginUtilized
LimitsAssigned
BadRequestRes
Field Name |
Data Type |
Description |
type |
string |
Error for request |
code |
string |
Response code to user request |
description |
string |
Reason for failed request |
EntrySucessRes
Field Name |
Data Type |
Description |
AppOrderID |
DT_OrderID |
It is system generated Unique Order No. |
OrderUniqueIdentifier |
DT_OrderID |
It is user specific Unique Order No. |
ClientID |
DT_ClientID |
It is User Unique ID |
ModifySucessRes
Field Name |
Data Type |
Description |
AppOrderID |
DT_OrderID |
It is a system generated Unique Order No. |
OrderUniqueIdentifier |
DT_OrderID |
It is a user-specific Unique Order No. |
ClientID |
DT_ClientID |
It is the User Unique ID. |
CancelSucessRes
Field Name |
Data Type |
Description |
AppOrderID |
DT_OrderID |
It is a system generated Unique Order No. |
ClientID |
DT_ClientID |
It is the client Unique ID. |
OrderBookSucessRes
TradeSucessRes
PositionSucessRes
ChildPosition
Field Name |
Data Type |
Possible Values |
Description |
AccountID |
DT_ClientID |
|
|
TradingSymbol |
DT_Symbol |
“ACC” |
|
ExchangeSegment |
DT_SegmentID |
“NSECM”, “NSEFO” |
|
ExchangeInstrumentID |
DT_InstrumentID |
22 |
|
ProductType |
DT_ProductType |
productType |
|
Marketlot |
DT_Price |
|
|
Multiplier |
DT_Price |
|
|
BuyAveragePrice |
DT_Price |
|
Average buy price of position |
SellAveragePrice |
DT_Price |
|
Average sell price of position |
OpenBuyQuantity |
double |
|
Total bought quantity |
OpenSellQuantity |
double |
|
Total sold quantity |
Quantity |
double |
|
Net outstanding quantity |
BuyAmount |
DT_Price |
|
Total buy value of position in rupees |
SellAmount |
DT_Price |
|
Total sell value of position in rupees |
NetAmount |
DT_Price |
|
Outstanding position value in rupees |
UnrealizedMTM |
DT_Price |
|
It's unrealized profit or loss which has not been booked by client |
RealizedMTM |
DT_Price |
|
It's realized profit or loss which has been booked by client |
MTM |
DT_Price |
|
It's profit or loss of position |
BEP |
DT_Price |
|
It's breakeven point of position |
SumOfTradedQuantityAndPriceBuy |
DT_Price |
|
Total buy value of position in rupees |
SumOfTradedQuantityAndPriceSell |
DT_Price |
|
Total sell value of position in rupees |
statisticsLevel |
DT_Reason |
|
|
isInterOpPosition |
DT_Reason |
|
|
DataTypes/Enums
Some of the ENUMS, strings highlighted below to be used in appropriate requests
Enum/Strings |
Value |
Remarks |
orderSide |
“BUY”, “SELL” |
|
dayOrNet |
“DAY”, “NET” |
|
productType |
“MIS”, “CNC” |
|
orderType |
“StopLimit”, “Limit”, “Market” |
|
timeInForce |
“DAY”, “IOC” |
|
segmentID |
“NSECM”, “NSEFO” |
|
Data Types:-
Below are the user defined data types:-
Name |
Data Type |
Remarks |
DT_Price |
double |
|
DT_ClientID |
string |
|
DT_OrderID |
string |
|
DT_SegmentID |
string |
|
DT_ProductType |
string |
|
DT_OrderType |
string |
|
DT_OrderSide |
string |
|
DT_Quantity |
int |
|
DT_Time |
string |
|
DT_Reason |
string |
|
DT_Reason |
bool |
|
DT_TimeInForce |
string |
|
DT_MessageCode |
int |
|
DT_Symbol |
string |
|
DT_Status |
string |
|
DT_Category |
string |
|
DT_InstrumentID |
int |
|