User Details and Authentication

Step 1: Generate API Key, Go to trade.mstock.com to generate the Api Key. Click here if you have not yet generated. This Api-key has to be passed in all the API call as headers mentioned here.

Note

mStock account is manadatory to genreate the API key. If you still do not have mstock account, Open Account.

Step 2: Using the Api key, you can now login using the user name & password with connect/login api. This will generate the OTP.

Step 3: You can use the OTP to generate the access Token, & use that with all the subsequent api calls.

Warning

Avoid api_key exposure. It's unsafe to embed it in mobile apps or client code! Never let access_token be public.

User APIs

method	path	description
POST	https://api.mstock.trade/openapi/typea/connect/login	This endpoint allows users to log in to the application
POST	https://api.mstock.trade/openapi/typea/session/token	This endpoint is used to retrieve a session token based on the provided API key, request token, and checksum.
GET	https://api.mstock.trade/openapi/typea/user/fundsummary	This endpoint used get the funds, cash and margin information for the user.
GET	https://api.mstock.trade/openapi/typea/logout	This API call will invalidate the access_token and destroys the API session.

This endpoint allows users to log in to the application by providing their username and password. Successful authentication will send the OTP to users registered mobile no that can be used for subsequent requests.

Request Headers -

X-Mirae-Version : Specifies the version of the API being used. In this case, it is set to 1.
Content-Type : For this request, it is set to application/x-www-form-urlencoded, which is used for submitting form data.

cURLNode.jsPythonJava

curl --location 'https://api.mstock.trade/openapi/typea/connect/login' \
--header 'X-Mirae-Version: 1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=XXXXX' \
--data-urlencode 'password=YYYYY'

import axios from 'axios';

const response = await axios.post(
  'https://api.mstock.trade/openapi/typea/connect/login',
  new URLSearchParams({
    'username': 'XXXXX',
    'password': 'YYYYY'
  }),
  {
    headers: {
      'X-Mirae-Version': '1'
    }
  }
);

import requests

headers = {
    'X-Mirae-Version': '1',
    'Content-Type': 'application/x-www-form-urlencoded',
}

data = {
    'username': 'XXXXX',
    'password': 'YYYYY',
}

response = requests.post('https://api.mstock.trade/openapi/typea/connect/login', headers=headers, data=data)

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newBuilder()
.followRedirects(HttpClient.Redirect.NORMAL)
.build();

HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.mstock.trade/openapi/typea/connect/login"))
.POST(BodyPublishers.ofString("username=XXXXX&password=YYYYY"))
.setHeader("X-Mirae-Version", "1")
.setHeader("Content-Type", "application/x-www-form-urlencoded")
.build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request Body -

The body of the request must be URL-encoded and include the following parameters:

Field	Type	Description
username	string	The username of the user attempting to log in. (Example: XXXXX)
password	string	The password associated with the username. (Example: XYZ@123)

Note -

Generated JWT token will be valid till 12:00 AM of generated day.

Response Structure -

The response of the request will be based on authentication outcome.

Success (HTTP Status 200): On successful login, the server returns a JSON object containing the authentication token and any relevant user information.

{
    "status": "success",
    "data": {
        "ugid": "xxxxxx-xxxxx-4b04-8086-a8b37f62953d",
        "is_kyc": "true",
        "is_activate": "true",
        "is_password_reset": "true",
        "is_error": "false",
        "cid": "XXXXX",
        "nm": "XXXXX",
        "flag": 0
    }
}

Failure (HTTP Status 400): If the version is incorrect, the server will return an error message.

{
    "status": "error",
    "message": "Please provide valid api version.",
    "data": null
}

Failure (HTTP Status 500): If the login credentials are incorrect, the server will return an error message.

{
    "status": "error",
    "message": "Invalid username or password (YYYY)",
    "data": null
}

Generate Session

This endpoint is used to retrieve a session token based on the provided API key, request token, and checksum. The session token is essential for authenticating subsequent API requests

Request Headers -

X-Mirae-Version : Specifies the version of the API being used. In this case, it is set to 1.
Content-Type : For this request, it is set to application/x-www-form-urlencoded, which is used for submitting form data.

cURL Command -

cURLNode.jsPythonJava

curl --location 'https://api.mstock.trade/openapi/typea/session/token' \
    --header 'X-Mirae-Version: 1' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'api_key=xxx' \
    --data-urlencode 'request_token=yyy' \
    --data-urlencode 'checksum=L'

import axios from 'axios';

const response = await axios.post(
'https://api.mstock.trade/openapi/typea/session/token',
new URLSearchParams({
    'api_key': 'xxx',
    'request_token': 'yyy',
    'checksum': 'L'
}),
{
    headers: {
    'X-Mirae-Version': '1'
    }
}
);

import requests

headers = {
    'X-Mirae-Version': '1',
    'Content-Type': 'application/x-www-form-urlencoded',
}

data = {
    'api_key': 'xxx',
    'request_token': 'yyy',
    'checksum': 'L',
}

response = requests.post('https://api.mstock.trade/openapi/typea/session/token', headers=headers, data=data)

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newBuilder()
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mstock.trade/openapi/typea/session/token"))
    .POST(BodyPublishers.ofString("api_key=xxx&request_token=yyy&checksum=L"))
    .setHeader("X-Mirae-Version", "1")
    .setHeader("Content-Type", "application/x-www-form-urlencoded")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request Body -

The body of the request must be URL-encoded and include the following parameters:

Field	Type	Description
api_key	string	The API key provided to the user (Example: ay3KxxxxxxxxxxkB/MAKg@@).
request_token	string	A token that uniquely identifies the session request (Example: 123).
checksum	string	A validation string to ensure the integrity of the request (Example: L)

n.Tasc Fields mapping with mStock API Parameters –

Field	Type	Description
api_key	string	ay3KxxxxxxxxxxkB/MAKg@@
request_token	string	OTP (123);
checksum	string	source (L)

Response Structure -

The response of the request will be based on authentication outcome.

Success (HTTP Status 200): On successful request, the server returns a JSON object containing the session token and any relevant user details

Note

In below response access_token, enctoken and refresh_token are pasted half because its size is very large.

{
    "status": "success",
    "data": {
        "user_type": "individual",
        "email": "XXXX000@gmail.com",
        "user_name": "XXXXX",
        "user_shortname": "NA",
        "broker": "MIRAE",
        "exchanges": [
            "NSE",
            "NFO",
            "CDS"
        ],
        "products": [
            "CNC",
            "NRML",
            "MIS"
        ],
        "order_types": [
            "MARKET",
            "LIMIT"
        ],
        "avatar_url": "",
        "user_id": "538",
        "api_key": "7328e5a975a5exxxxxxx",
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "public_token": "4876d509-06c1-45db-8248-33dbde85135b",
        "enctoken": "eyJhbGciOiJIUzUxMiJ9_juyp9To5lDGtr7jqmh-",
        "refresh_token": "iGcP5onq6MXJYHHvAE26qS1A2cLodotQqZE5azfsah8",
        "silo": "",
        "login_time": "2024-09-26 03:34:48",
        "meta": {
            "demat_consent": "physical"
        }
    }
}

- Failure (HTTP Status 500): If the request fails due to an invalid OTP passed, the server will return an error message.

{
    "status": "error",
    "message": "Entered OTP has been expired. Please regenerate a new one & enter the same.",
    "data": null
}

- Failure (HTTP Status 400): If the API Key is Invalid or expired.

{
    "status": "error",
    "message": "API is suspended/expired for use. Please check your API subscription and try again.",
    "error_type": "APIKeyException",
    "data": null
}

Fund Summary

This endpoint used get the funds, cash and margin information for the user.

Request Headers -

X-Mirae-Version : Specifies the version of the API being used. In this case, it is set to 1.
Authorization: A token-based authentication header. The format is token api_key:access_token

cURL Command -

cURLNode.jsPythonJava

curl --location 'https://api.mstock.trade/openapi/typea/user/fundsummary' \
    --header 'X-Mirae-Version: 1' \
    --header 'Authorization: token api_key:access_token' \

import axios from 'axios';

const response = await axios.get('https://api.mstock.trade/openapi/typea/user/fundsummary', {
headers: {
    'X-Mirae-Version': '1',
    'Authorization': 'token api_key:access_token'
}
});

import requests

headers = {
    'X-Mirae-Version': '1',
    'Authorization': 'token api_key:access_token',
}

response = requests.get('https://api.mstock.trade/openapi/typea/user/fundsummary', headers=headers)

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newBuilder()
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mstock.trade/openapi/typea/user/fundsummary"))
    .GET()
    .setHeader("X-Mirae-Version", "1")
    .setHeader("Authorization", "token api_key:access_token")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request Body -

This endpoint does not require a request body or additional parameters in the query string for the retrieval of orders

Response Structure -

The response of the request will be based on authentication outcome.

Success (HTTP Status 200): On successful request, the server returns a JSON object containing the session token and any relevant user details

Note

In below response access_token, enctoken and refresh_token are pasted half because its size is very large.

{
    "status": "success",
    "data": [
        {
            "ADDITIONAL_MARGIN": "0.0",
            "ADHOC_LIMIT": "99999999999",
            "AMOUNT_UTILIZED": "27395824.71",
            "AVAILABLE_BALANCE": "299972678840.29",
            "BANK_HOLDING": "99999999999",
            "CLEAR_BALANCE": "199999949998",
            "COLLATERALS": "74668",
            "LIMIT_SOD": "99999999999",
            "LIMIT_TYPE": "CAPITAL",
            "MF_COLLATERAL": "0.0",
            "MTF_AVAILABLE_BALANCE": "299972678840.29",
            "MTF_COLLATERAL": "0.0",
            "MTF_UTILIZE": "0.0",
            "MTM_COMBINED": "0",
            "OFS_UTILIZED": "0.0",
            "OPT_BUY_PRIMIUM_UTILIZE": "0.0",
            "PAY_OUT_AMT": "50000.0",
            "PEAK_MARGIN": "33222959.73",
            "PHYSICAL_MARGIN": "0.0",
            "REALISED_PROFITS": "0",
            "RECEIVABLES": "0",
            "SEG": "A",
            "SUM_OF_ALL": "300000024665",
            "UNCLEAR_BALANCE": "0"
        }
    ]
}

- Failure (HTTP Status 400): If the API Key is Invalid or expired.

{
    "status": "error",
    "message": "API is suspended/expired for use. Please check your API subscription and try again.",
    "error_type": "APIKeyException",
    "data": null
}

Logout

This endpoint will invalidate the access token and destroy the current API session. After logout API call use will not be able to call any other API using the invalidate JWT token and will require further login to generate new JWT token.

Request Headers -

X-Mirae-Version : Specifies the version of the API being used. In this case, it is set to 1.
Authorization : A token-based authentication header. The format is token api_key:access_token

cURLNode.jsPythonJava

curl --location 'https://api.mstock.trade/openapi/typea/logout' \
--header 'X-Mirae-Version: 1' \
--header 'Authorization: token api_key:access_token'

import axios from 'axios';

const response = await axios.post(
  'https://api.mstock.trade/openapi/typea/logout',
  {
    headers: {
      'X-Mirae-Version': '1'
      'Authorization': 'token api_key:access_token'
    }
  }
);

import requests

headers = {
    'X-Mirae-Version': '1',
    'Authorization': 'token api_key:access_token'
}

response = requests.post('https://api.mstock.trade/openapi/typea/logout', headers=headers)

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newBuilder()
.followRedirects(HttpClient.Redirect.NORMAL)
.build();

HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.mstock.trade/openapi/typea/logout"))
.GET()
.setHeader("X-Mirae-Version", "1")
.setHeader("Authorization", "token api_key:access_token")
.build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request Body -

This endpoint does not require a request body or additional parameters in the query string for the retrieval of orders.

Response Structure -

The response of the request will be based on authentication outcome.

Success (HTTP Status 200): On successful logout, the server returns the below JSON object.
```
{
    "status": "success",
    "data": "Success"
}
```

Failure (HTTP Status 400): If the version is incorrect, the server will return an error message.

{
    "status": "error",
    "message": "Please provide valid api version.",
    "data": null
}

Failure (HTTP Status 401): If access token is invalid

{
    "status": "error",
    "message": "Invalid request. Please try again.",
    "error_type": "TokenException",
    "data": null
}

User Details and Authentication

Login flow

User APIs

Login

Generate Session

Fund Summary

Logout