ODIN B2C Rest API (1.1.0)

Download OpenAPI specification:Download

Download Postman Collection:Download

Download NodeJS SDK:Download

Download Python SDK:Download

Cloud Rest API allows the developer to create a custom trading application for Web or Mobile communicating with ODIN Order Management System (OMS). This REST based API allows user to develop the following functionalities for Trading Application / Portal.

Salient Features:
  • User Authentication and Profile management
  • Order Management
  • Portfolio information management
  • Scrip Master Details

This step-by- step guide will assist you through the entire flow of API implementation; right from authentication, to handle the request and response structure of the API.

Getting Started

Cloud Rest API is a set of REST APIs that provide the platform along with required data to build a Trading Platform, the API specifications is used for communicating with ODIN API Gateway. API specifications are based on the REST protocol that covers the functionalities which are need to develop a trading application like Login / Logout, Order Management (Place Order, Modify Order, Cancel order), Reports like Order Book, Trade Book, Position, Holding & Limit, etc. The REST API supports JSON based request and responses along with data compression.

Basic Flow to Implement the APIs:

STEP 1:Make a Login API call using login credential to obtain the access token.
STEP 2: Use access token obtained from Login API in all the subsequent API calls.
STEP 3: Setting obtained access token and content-type is shown below.

Header:
Content-Type: application/json
Authorization: Bearer eyJ1c2VySUQiOiJSVVBFU0giLCJpYXQiOjE1NTIxMjIwOTEsImV4cCI6MTU1MjIwODQ5MX0

Response Structure

All GET and DELETE request parameters go as query parameters, and POST and PUT request parameters as json (application/json) parameters, responses from the API are always JSON. Any non-alphanumeric character should be URL encoded in query string and path parameters.

Successful Request

All responses from the API server are in JSON format with the content-type application/json unless explicitly stated otherwise. A successful 200 OK response always has a JSON response body with a status as success. The data key contains the full response payload.

HTTP/1.1 200 OK 
Content-Type: application/json
{
"status": "success",
"code": "",
"message": "",
"data": "{}"
}


Failed Request

A failed response is preceded by the corresponding 40x or 50x HTTP header. The status key in the response contains the value error. The message key contains a textual description of the error and code contains the unique error code. The errors key contains fields breakdown of validation errors for POST & Put requests.
HTTP/1.1 500 Server error 
Content-Type: application/json
{
"status": "error",
"code": "",
"message": "",
"errors": "[]"
}

Data types
Values in JSON responses are of types string, integer, number, or bool.
Timestamp (datetime) strings in the responses are represented in the default date format yyyy-mm-dd HH:mm:ss e.g., 2016-01-25 13:33:42.

Exceptions and Errors

The HTTP Status Codes used by the RESTful API.

HTTP Error CodeDescription
400Bad Request - Missing or bad request parameters or values. Error message will indicate which one and why.
401Unauthorized - The access token provided is expired, revoked, malformed, or invalid. Client should refresh relogin and then try again.
404Not Found - Request resource was not found.
405 Method Not Allowed - Request method (GET, POST etc.) is not allowed on the requested endpoint
500 Internal Server Error - API is not working as expected. The request is probably valid but needs to be requested again later.
503Service Unavailable - The API endpoint is down.

Scrip Master Details

Kindly use below scrip master API for ODIN Scrip master :
https://odinscripmaster.s3.ap-south-1.amazonaws.com/scripfiles/NSE_EQ.json
replace exchange name, like NSE_FO.json, etc...with the list below.
Another version file is at https://odinscripmaster.s3.ap-south-1.amazonaws.com/scripfiles/v2/NSE_EQ.json

Exchange SegmentCode
NSE EquityNSE_EQ
NSE DerivativesNSE_FO
BSE EquityBSE_EQ
BSE DerivativesBSE_FO
MCX COMMODITYMCX_FO
NCDEX COMMODITYNCDEX_FO
MSE CURRENCYMSE_CUR
NSE CURRENCYNSE_CUR
BSE CURRENCYBSE_CUR
BSE COMMODITYBSE_COMM
NSE COMMODITYNSE_COMM

User

This collection of API's would help in user authentication flow including password/MPIN validation, forget & reset etc.

Login

This API needs to be used for signing-in to the application using login credentials. A successful sign-in would return an ‘access token’ and a 'broadcast_access_token' in the response.
'access_token' needs to be included in all subsequent API invocations as part of http header 'Authorization' token.
'broadcast_access_token' would be required for establishing a connection with the feed endpoint ('broadCastSocket' received in the response). Kindly refer Price Feed API for further details.
The response will also have the details like exchanges allowed, product types allowed and other key information required for trading.

login_typepasswordsecond_auth_typesecond_auth
PASSWORDpasswordREGISTERNot Required
TOKENregister_tokenOTP/TOTP/FINGERPRINTOTP value/TOTP value/Registered UDID
PASSWORDpasswordOTP/TOTP/FINGERPRINTOTP value/TOTP value/Registered UDID
MPINMPIN RegisteredOTP/TOTP/FINGERPRINTOTP value/TOTP value/Registered UDID
TP_TOKENSSO TOKENNot RequiredNot Required

To get second factor authentication details of user, "REGISTER" can be used in second_auth_type field, which validates password field and return register_token that can be used as "TOKEN" login type with second factor after registration.

header Parameters
Content-Type
string
Example: application/json
x-api-key
string
Example: {{x-api-key}}
Request Body schema: application/json
user_id
required
string

User Id (UCC) provided to the user.

login_type
string
Default: "PASSWORD"
Enum: "PASSWORD" "MPIN" "FINGERPRINT" "TP_TOKEN"

Whether user has logged in with password, MPIN, fingerprint or SSO token and respectively need to pass value in "password" field. In case authentication is handled in a separate application, e.g. Super app in which for trading functionality ODIN APIs are used, then TP_TOKEN will be used. In this case the third party token which is shared will be verified using two way authentication.

password
required
string

Password/MPIN/UDID/SSO-Token to validate

second_auth_type
string
Enum: "OTP" "TOTP" "FINGERPRINT" "REGISTER"

This is the secondary type of authorization selected by the User at the time of signing in apart from Password. During the first login attempt "REGISTER" will be used to register the mode of second factor authentication. Developer can give all three (OTP, TOTP and Fingerprint) or any one of the option.

second_auth
string

User shall enter credentials as per the secondary authentication type selected by them.

api_key
required
string

API key provided by 63moons for a particular period.

source
required
string
Enum: "WEBAPI" "MOBILEAPI"

Application from which the User has logged in. "WEBAPI" for Browser Based Applications and "MOBILEAPI" for Mobile Applications.

UDID
string

Unique Device Id of the device on which the application is being accessed.

version
string

Application version of the android application to be logged in the system.

iosversion
string

Application version of the iOS application to be logged in the system.

build_version
string

Internal build version of the application to be logged in the system.

object

Responses

Request samples

Content type
application/json
{
  • "user_id": "{{user_id}}",
  • "login_type": "PASSWORD",
  • "password": "{{password}}",
  • "second_auth_type": "OTP",
  • "second_auth": "123456",
  • "api_key": "{{api_key}}",
  • "source": "{{source}}",
  • "UDID": "a1b23cd4e5f6g78h",
  • "version": "2.0.0",
  • "iosversion": "",
  • "build_version": "22.11.01",
  • "deviceinfo": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "code": "s-101",
  • "message": "User logged in Successfully.",
  • "data": {
    }
}

Logout

This call would logout the user from the system and end the active session.

header Parameters
Authorization
string
Example: {{access_token}}
Content-Type
string
Example: application/json
x-api-key
string
Example: {{x-api-key}}

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "code": "s-101",
  • "message": "Successfully Logged out."
}

Validate Session

This call will help validate if the session token passed is active in the system or not.

header Parameters
Authorization
string
Example: {{access_token}}
x-api-key
string
Example: {{x-api-key}}

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "code": "s-101",
  • "message": "Session verified.",
  • "data": "{\"status\":\"false\",\"message\":\"TRUE\",\"dropped\":\"true\"}"
}

Balance

This API can be used to retrieve the latest balance with broker for allowed segments.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "code": "s-101",
  • "message": "Success message",
  • "data": {
    }
}

Order

This section provided to information of API calls to do the order management i.e. place fresh order, modify or cancel already submitted valid orders. Retrieve the order and trade book. Using Order API, various type of orders Intraday, Delivery, Bracket Order, Cover order, etc. can be placed. Order type here is used as Product Type in System. Kindly refer to the respective API call for more detail. Global Constants
Here are some of the constants enum values used for placing order.

Params Values Description
exchange (segment id) NSE_EQ (1), NSE_FO (2), BSE_EQ (8), BSE_FO (4), MCX_FO (16), NCDEX_FO (64), NSE_CUR (2048), NSE_COMM (32768), BSE_CUR (268435456), BSE_COMM (16384), MSE_CUR (1024), NSE_OTS (536870912) Exchange segment
product_type INTRADAY It consists of one leg only. Open orders will be squared off automatically before market close.
DELIVERY Order position will be carried over to next day under holding.
BTST Buy today sell tomorrow. It will be squared off automatically before next day market close.
COVER It consists of two legs. MAIN_LEG which is market order and SL_LEG which will be square off stop loss order of MAIN_LEG. Open orders will be squared off automatically before market close.
BRACKET It consists of three leg order. MAIN_LEG which is placed as Market or Limit, SL_LEG which is square off stop loss order and PROFIT_LEG which is square off order. Open orders will be squared of automatically before market close.
MTF Margin Trading or Margin Trading Facility (MTF) is a facility provided by brokers to their clients in which the client does not have to pay full amount for carrying overnight positions.
order_typeRLRegular limit order.
RL-MKT Regular market order.
SL Stoploss limit order.
SL-MKT Stoploss market order.
validity DAY Order valid for the same day.
IOC Order valid only for immediate execution else cancelled.
GTD Order valid for specified number of days.
GTC Order valid until user cancels the order.
EOS Order valid for the specific session.
EOSESS Order valid till end of session for BSE.
EOTODY Order valid till end of day for BSE.
order_status PENDING Order is pending or partially executed at exchange.
EXECUTED Order is fully executed at exchange.
CANCELLED Order is cancelled at exchange.
OMSXMITTED Order is received by OMS but not submitted to exchange.
OMSREJECT Order is rejected by OMS.
ORDERERROR Order is not valid, rejected by exchange.
ADMINREJECT Order is rejected by OMS Admin.
EXXMITTED Order is submitted to exchange, but confirmation is not received.
AMOACCEPTED AMO order is received by OMS.
AMOWITHDRAWN AMO order is cancelled.

Place Order - Any Scrip

Lets you place a fresh buy order or sell order.

header Parameters
Content-Type
string
Example: application/json
Authorization
string
Example: {{access_token}}
x-api-key
string
Example: {{x-api-key}}
Request Body schema: application/json
required
object

Scrip information can be sent in 2 ways. either by sending exchange and scrip token or by sending scrip details i.e. exchange, symbol, series, expiry, strike price & option type.

transaction_type
required
string

Whether it is a Buy Order or a Sell Order.

product_type
required
string

Product type of the order. Kindly refer global constants for enum values.

order_type
required
string

Type of order. Kindly refer global constants for enum values.

quantity
required
integer

Total Quantity for which the order has to be placed.

price
number
Default: 0

Price at which the order will be placed in rupees.

trigger_price
number

Price at which order will be triggered, applicable for Stop Loss Limit (SL) or Stop Loss Market order (SL-MKT) type.

disclosed_quantity
integer

Disclosed Quantity is a part of the actual quantity that User wants to display in the Market at a time.

validity
string
Default: "DAY"

Order validity,the value will be dependant on exchange segments in which the order is being placed. Kindly refer global constants for enum values.

validity_days
integer

Number of days for which the GTD order needs to be carried forward.

is_amo
boolean
Default: false

Whether order is an AMO order or not? (AMO or After Market Orders are parked in the system and submotted to the exchange during the next trading day)

order_identifier
string <= 10 characters

An optional field to apply to an order to track it.

part_code
string

Participant Code of the Custodian.

algo_id
string

Algo id for strategy generated orders

strategy_id
string

Strategy id for strategy generated orders

vender_code
string

Vender code for inhouse application

Responses

Request samples

Content type
application/json
{
  • "scrip_info": {
    },
  • "transaction_type": "BUY",
  • "product_type": "INTRADAY",
  • "order_type": "RL-MKT",
  • "quantity": 3,
  • "price": 0,
  • "trigger_price": 0,
  • "disclosed_quantity": 0,
  • "validity": "DAY",
  • "validity_days": 0,
  • "is_amo": false,
  • "order_identifier": "",
  • "part_code": "",
  • "algo_id": "",
  • "strategy_id": "",
  • "vender_code": ""
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "code": "s-101",
  • "message": "Order Entry Sent to OMS",
  • "data": {
    }
}

Modify Order

Lets you modify an existing pending order

path Parameters
exchange
required
string
Example: NSE_EQ

Exchange segment

order_id
required
string
Example: NWSYF00005>3

Order id in URI encode form

header Parameters
Content-Type
string
Example: application/json
Authorization
string
Example: {{access_token}}
x-api-key
string
Example: {{x-api-key}}
Request Body schema: application/json
order_type
required
string

Type of order. Kindly refer global constants for enum values.

quantity
required
integer

Number of Quantity that the User wants to Modify.

traded_quantity
required
integer

Cumulative traded quantity of the order. Data to be passed in this field is available in order book response.

price
number
Default: 0

Price at which order will be placed in rupees.

trigger_price
number

Price set by the User for Stop Loss or Stop Loss Market order type which shall trigger the order and later be placed at Limit Price.

disclosed_quantity
integer

Disclosed Quantity is a part of the actual quantity that User wants to display in the Market.

validity
string
Default: "DAY"

Order validity. Kindly refer global constants for enum values.

validity_days
integer

Number of days for which the GTD order shall be carried forward.

Responses

Request samples

Content type
application/json
{
  • "order_type": "RL",
  • "quantity": 5,
  • "traded_quantity": 0,
  • "price": 310,
  • "trigger_price": 0,
  • "disclosed_quantity": 0,
  • "validity": "DAY",
  • "validity_days": 0
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "code": "s-101",
  • "message": "Order Modification Sent to OMS",
  • "data": {
    }
}

Cancel Order

This call can be used to cancel an existing pending order.

path Parameters
exchange
required
string
Example: NSE_EQ

Exchange segment

order_id
required
string
Example: NWSYF00005>3

Order id in URI encode form

header Parameters
Authorization
string
Example: {{access_token}}
Content-Type
string
Example: application/json
x-api-key
string
Example: {{x-api-key}}

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "code": "s-101",
  • "message": "Order Cancellation Sent to OMS",
  • "data": {