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. 1. Use the API Key and Secret Key provided by the vendor to login using Session Login API
2. 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. 3. User will then need to connect to the socket by using this token to ws://IP:PORT/token= this endpoint
4. 4. User will need to add Authorization in request header and pass this bearer token to access the API’s
5. 5. A user session will be created and all the socket events will be sent to the connected users
6. 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.

RESPONSES

200:-

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:-

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:-

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:-

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:-

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

RESPONSES

200:-

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

RESPONSES

200:-

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

RESPONSES

200:-

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

RESPONSES

200:-

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

ExchangeSegment

BalanceList

LimitObject

RMSSubLimits

MarginAvailable

MarginUtilized

LimitsAssigned

BadRequestRes

EntrySucessRes

ModifySucessRes

CancelSucessRes

OrderBookSucessRes

TradeSucessRes

PositionSucessRes

ChildPosition

DataTypes/Enums

Some of the ENUMS, strings highlighted below to be used in appropriate requests

Data Types:-

Below are the user defined data types:-