Full API Documentation

Welcome to the NIN Trade API — a powerful, clean, and developer-first trading API built for the next generation of fintech innovation. This API allows you to integrate everything from market data, order management, positions, margin reporting, and analytics into your apps with clarity and performance.

🌐 Base URL

https://api.nin.in/trade/v1

All requests must be made over HTTPS.

📘 Contents

🔐 Authentication

All endpoints require authentication via OAuth 2.0 Bearer Token.

🔁 Token Generation (POST /auth/token)

POST /auth/token

Request Body:

{
  "api_key": "string",
  "api_secret": "string"
}

Response:

{
  "access_token": "abcdef1234567890",
  "expires_in": 86400
}

Headers to Include in All Authenticated Requests:

Authorization: Bearer <access_token>

📈 Instruments

List Instruments (GET /instruments)

GET /instruments

Query Parameters:

exchange: NSE / BSE / MCX
search: partial name or symbol (optional)

Response:

[
  {
    "symbol": "RELIANCE",              // string: Trading symbol
    "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
    "quantity": 100,                    // integer: Held quantity
    "avg_price": 2450.0,                // float: Average buy price
    "last_price": 2500.0,               // float: Current market price
    "pnl": 5000.0,                        // float: Profit or loss
    "exchange": "NSE",                  // string: Exchange code
    "instrument_token": 738561,          // integer: Unique token
    "tick_size": 0.05,                   // float: Min price step
    "lot_size": 1,                       // integer: Quantity lot size
    "instrument_type": "EQ"             // string: Instrument category
  },
 ...
]

Download Instruments CSV (GET /instruments/csv)

GET /instruments/csv

Description: Download the full instruments list in CSV format. Useful for bulk analysis or mapping tokens.

Example (cURL):

curl -o instruments.csv \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://api.nin.in/trade/v1/instruments/csv"

Example (Python):

import requests

url = "https://api.nin.in/trade/v1/instruments/csv"
headers = {"Authorization": "Bearer <ACCESS_TOKEN>"}
resp = requests.get(url)

with open("instruments.csv", "wb") as f:
    f.write(resp.content)

Sample CSV Output:

instrument_token,symbol,nin_symbol,name,exchange,instrument_type,segment,tick_size,lot_size
738561,RELIANCE,RELIANCE.NS,Reliance Industries Ltd,NSE,EQ,NSE_EQ,0.05,1

🧾 Orders

Place Order (POST /orders)

POST /orders

Request Body:

{
  "symbol": "RELIANCE",                 // string: Trading symbol
  "exchange": "NSE",                   // string: Exchange code
  "transaction_type": "BUY",           // string: BUY or SELL
  "order_type": "LIMIT",               // string: MARKET, LIMIT, SL, SL-M
  "quantity": 100,                      // integer: Number of shares
  "price": 2500,                        // float: Limit price | For MARKET type, pass 0
  "product": "CNC",                    // string: CNC, MIS, NRML
  "validity": "DAY",                   // string: DAY or IOC
}

Response:

{
  "order_id": "ORD123456789",         // string: Unique order ID
  "status": "OPEN"                    // string: Current order status
}

For SL and SL-M, include trigger_price

Modify Order (PUT /orders/{id})

PUT /orders/{order_id}

Description: Update the parameters of an open order (price, quantity, etc.) before it's filled.

Request Body:

{
  "price": 2480,               // float: New price (for LIMIT orders)
  "quantity": 50               // integer: New quantity (if reduced)
}

Response:

{
  "order_id": "ORD123456789",   // string: Order ID
  "status": "MODIFIED"           // string: Result status
}

⚠️ You can only modify open and pending orders. Not applicable for market orders already executed.

Cancel Order (DELETE /orders/{id})

DELETE /orders/{order_id}

Description: Cancel an open order before execution.

Response:

{
  "order_id": "ORD123456789",   // string: Order ID
  "status": "CANCELLED"          // string: Final status
}

Cancelling a filled or already cancelled order will return a 400 error.

Order Status (GET /orders/{id})

GET /orders/{order_id}

Response:

{
  "order_id": "ORD123456789",
  "status": "FILLED",
  "symbol": "RELIANCE",
  "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
  "filled_quantity": 100,
  "average_price": 2498.25,
  "placed_at": "2025-05-05T09:16:22Z"
}

Use this to track order fulfillment and final pricing.

List All Orders (GET /orders)

GET /orders

Query Parameters:

from_date, to_date (optional): ISO 8601 filters
status: Filter by order status (e.g., OPEN, FILLED)

Response:

[
  {
    "order_id": "ORD123456789",
    "symbol": "RELIANCE",
    "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
    "status": "OPEN",
    "quantity": 100,
    "price": 2500,
    "order_type": "LIMIT",
    "placed_at": "2025-05-05T09:15:00Z"
  },
  ...
]

Returns a paginated list of all orders placed by the user.

GTT Order (POST /orders/gtt)

POST /orders/gtt

Description: Place a Good-Till-Triggered (GTT) order which gets sent to the exchange when your trigger price is hit.

Request Body:

{
  "symbol": "RELIANCE",
  "exchange": "NSE",
  "trigger_price": 2450.0,       // float: Price to trigger this GTT
  "order": {
    "transaction_type": "BUY",
    "order_type": "LIMIT",
    "quantity": 100,
    "price": 2435.0,
    "product": "CNC",
    "validity": "DAY"
  }
}

Response:

{
  "gtt_id": "GTT123456",
  "status": "ACTIVE"
}

GTT orders remain active for 1 year unless triggered or cancelled.

💼 Portfolio

Holdings (GET /portfolio/holdings)

[
  {
    "symbol": "RELIANCE",
    "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
    "quantity": 100,
    "avg_price": 2450.0,
    "last_price": 2500.0,
    "pnl": 5000.0
  },
  ...
]

Positions (GET /portfolio/positions)

Returns intraday and overnight positions with realized_pl and unrealized_pl.

📡 Live Data

Quote (GET /marketdata/quote)

LTP Only (GET /marketdata/ltp)

Market Depth (GET /marketdata/depth)

{
  "bids": [[2490.00, 100]],            // array of [price, qty]: Top bid levels
  "asks": [[2500.00, 75]]              // array of [price, qty]: Top ask levels
}

📊 Historical Data

OHLC Candles (GET /marketdata/history)

Query: symbol, exchange, interval, from, to

Intervals: 1min, 5min, 15min, 1hour, 1day

🏦 Margin

Get Margin (GET /margin)

{
  "available_cash": 80000,            // float: Available funds
  "collateral": 20000,                // float: Collateral margin
  "used_margin": 50000,               // float: Utilized margin
  "net": 100000                        // float: Net margin available
}

Margin Calculator (POST /margin/calculate)

Send hypothetical order to get margin required.

❌ Errors & Status Codes

Status

Meaning

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Rate Limit Exceeded

500

Server Error

📚 Annexures & Definitions

📊 Pagination & Filtering

🔠 Query Parameter Types

Parameter

Type

Description

limit

integer

Max number of records to return

offset

integer

Record index to start from (for pagination)

sort

string

Format: field:direction (e.g. time:desc)

from_date

datetime

Start date in ISO 8601 format

to_date

datetime

End date in ISO 8601 format

Orders & Instruments endpoints support:

limit (default: 50, max: 100)
offset (for pagination)
sort (e.g. created_at:desc)
from_date, to_date (ISO 8601 for filtering)

Example:

GET /orders?limit=25&offset=0&sort=created_at:desc

⏱️ Rate Limits

Endpoint Group

Limit

Window

Market Data

60 req/min

per token

Orders

30 req/min

per token

Portfolio

20 req/min

per token

Exceeding limits will return HTTP 429 with Retry-After header.

⚠️ WebSocket Error Handling

WebSocket clients may receive:

{
  "type": "error",
  "message": "Invalid token or malformed subscription"
}

Handle with reconnect logic or alert user accordingly.

📣 Webhooks (Optional)

Enable real-time updates for:

✅ Order Status Changes
💸 Margin Call Alerts

Webhook Payload Example:

{
  "event": "ORDER_UPDATE",            // string: Event type
  "order_id": "ORD12345",             // string: Order identifier
  "status": "FILLED",                 // string: Final status
  "filled_quantity": 100              // integer: Executed quantity
}

Use secure HTTPS URLs with HMAC signature (SHA256).

🧪 Environments

Type

URL Prefix

Sandbox

https://sandbox.api.nin.in/

Live

https://api.nin.in/

Sandbox allows safe order testing with virtual funds.

🛡️ Security & Retry Tips

🔁 Retry only 5xx errors with backoff.
🚫 Never log raw access_token.
🔄 Refresh token every 24 hrs (or use a refresh token model).

🧠 Glossary: Instrument Fields

📌 Data Types Reference

Type

Description

string

UTF-8 encoded text

integer

Whole number

float

Decimal number

boolean

true or false

datetime

ISO 8601 format, e.g., 2025-05-05T09:15:00Z

Field

Description

instrument_token

Unique ID used internally for streaming & orders

tick_size

Minimum price movement allowed

lot_size

Number of units per order (e.g., 1 for equity)

segment

Segment type (e.g., NSE_EQ, BSE_EQ, NFO_OPT)

Order Types

MARKET
LIMIT
SL
SL-M

Products

CNC: Delivery
MIS: Intraday
NRML: Futures & Options

Validity

DAY: Valid till end of day
IOC: Immediate or Cancel

📶 WebSocket Streams

NIN provides real-time streaming over WebSocket for:

📈 Live market quotes
🧾 Order status updates (for authenticated users)
🔄 LTP, depth, and volume changes

🔗 Connection URL

wss://stream.nin.in/quotes

🔒 Authenticated WebSocket sessions must include a valid bearer token in the Authorization header (for private streams).

📩 Subscription Format

{
  "action": "subscribe",
  "tokens": [738561, 256265]
}

🔕 Unsubscribe Format

{
  "action": "unsubscribe",
  "tokens": [738561]
}

📊 Tick Message Format

{
  "instrument_token": 738561,     // integer: NSE/BSE instrument ID
  "last_price": 2500.00,          // float: Latest price
  "volume": 120000,               // integer: Traded volume
  "change": 15.5,                 // float: Change from previous close
  "percent_change": 0.62,         // float: Percentage change
  "timestamp": "2025-05-05T10:15:30Z"  // datetime: Server time
}

🧾 Order Update Message (Authenticated Users Only)

{
  "type": "order_update",
  "order_id": "ORD123456789",
  "status": "FILLED",
  "filled_quantity": 100,
  "average_price": 2498.25,
  "symbol": "RELIANCE",
  "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
  "timestamp": "2025-05-05T10:16:05Z"
}

Maintain the connection using ping/pong or keepalive every 30s. Use a WebSocket client that supports automatic reconnect on network drop.

📞 Support

PreviousHow to get API Keys?NextOpenAPI Reference (Trade)

Last updated 15 days ago

🌐 Base URL

https://api.nin.in/trade/v1

All requests must be made over HTTPS.

📘 Contents

🔐 Authentication

All endpoints require authentication via OAuth 2.0 Bearer Token.

🔁 Token Generation (POST /auth/token)

POST /auth/token

Request Body:

{
  "api_key": "string",
  "api_secret": "string"
}

Response:

{
  "access_token": "abcdef1234567890",
  "expires_in": 86400
}

Headers to Include in All Authenticated Requests:

Authorization: Bearer <access_token>

📈 Instruments

List Instruments (GET /instruments)

GET /instruments

Query Parameters:

exchange: NSE / BSE / MCX
search: partial name or symbol (optional)

Response:

[
  {
    "symbol": "RELIANCE",              // string: Trading symbol
    "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
    "quantity": 100,                    // integer: Held quantity
    "avg_price": 2450.0,                // float: Average buy price
    "last_price": 2500.0,               // float: Current market price
    "pnl": 5000.0,                        // float: Profit or loss
    "exchange": "NSE",                  // string: Exchange code
    "instrument_token": 738561,          // integer: Unique token
    "tick_size": 0.05,                   // float: Min price step
    "lot_size": 1,                       // integer: Quantity lot size
    "instrument_type": "EQ"             // string: Instrument category
  },
 ...
]

Download Instruments CSV (GET /instruments/csv)

GET /instruments/csv

Description: Download the full instruments list in CSV format. Useful for bulk analysis or mapping tokens.

Example (cURL):

curl -o instruments.csv \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://api.nin.in/trade/v1/instruments/csv"

Example (Python):

import requests

url = "https://api.nin.in/trade/v1/instruments/csv"
headers = {"Authorization": "Bearer <ACCESS_TOKEN>"}
resp = requests.get(url)

with open("instruments.csv", "wb") as f:
    f.write(resp.content)

Sample CSV Output:

instrument_token,symbol,nin_symbol,name,exchange,instrument_type,segment,tick_size,lot_size
738561,RELIANCE,RELIANCE.NS,Reliance Industries Ltd,NSE,EQ,NSE_EQ,0.05,1

🧾 Orders

Place Order (POST /orders)

POST /orders

Request Body:

{
  "symbol": "RELIANCE",                 // string: Trading symbol
  "exchange": "NSE",                   // string: Exchange code
  "transaction_type": "BUY",           // string: BUY or SELL
  "order_type": "LIMIT",               // string: MARKET, LIMIT, SL, SL-M
  "quantity": 100,                      // integer: Number of shares
  "price": 2500,                        // float: Limit price | For MARKET type, pass 0
  "product": "CNC",                    // string: CNC, MIS, NRML
  "validity": "DAY",                   // string: DAY or IOC
}

Response:

{
  "order_id": "ORD123456789",         // string: Unique order ID
  "status": "OPEN"                    // string: Current order status
}

For SL and SL-M, include trigger_price

Modify Order (PUT /orders/{id})

PUT /orders/{order_id}

Description: Update the parameters of an open order (price, quantity, etc.) before it's filled.

Request Body:

{
  "price": 2480,               // float: New price (for LIMIT orders)
  "quantity": 50               // integer: New quantity (if reduced)
}

Response:

{
  "order_id": "ORD123456789",   // string: Order ID
  "status": "MODIFIED"           // string: Result status
}

⚠️ You can only modify open and pending orders. Not applicable for market orders already executed.

Cancel Order (DELETE /orders/{id})

DELETE /orders/{order_id}

Description: Cancel an open order before execution.

Response:

{
  "order_id": "ORD123456789",   // string: Order ID
  "status": "CANCELLED"          // string: Final status
}

Cancelling a filled or already cancelled order will return a 400 error.

Order Status (GET /orders/{id})

GET /orders/{order_id}

Response:

{
  "order_id": "ORD123456789",
  "status": "FILLED",
  "symbol": "RELIANCE",
  "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
  "filled_quantity": 100,
  "average_price": 2498.25,
  "placed_at": "2025-05-05T09:16:22Z"
}

Use this to track order fulfillment and final pricing.

List All Orders (GET /orders)

GET /orders

Query Parameters:

from_date, to_date (optional): ISO 8601 filters
status: Filter by order status (e.g., OPEN, FILLED)

Response:

[
  {
    "order_id": "ORD123456789",
    "symbol": "RELIANCE",
    "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
    "status": "OPEN",
    "quantity": 100,
    "price": 2500,
    "order_type": "LIMIT",
    "placed_at": "2025-05-05T09:15:00Z"
  },
  ...
]

Returns a paginated list of all orders placed by the user.

GTT Order (POST /orders/gtt)

POST /orders/gtt

Description: Place a Good-Till-Triggered (GTT) order which gets sent to the exchange when your trigger price is hit.

Request Body:

{
  "symbol": "RELIANCE",
  "exchange": "NSE",
  "trigger_price": 2450.0,       // float: Price to trigger this GTT
  "order": {
    "transaction_type": "BUY",
    "order_type": "LIMIT",
    "quantity": 100,
    "price": 2435.0,
    "product": "CNC",
    "validity": "DAY"
  }
}

Response:

{
  "gtt_id": "GTT123456",
  "status": "ACTIVE"
}

GTT orders remain active for 1 year unless triggered or cancelled.

💼 Portfolio

Holdings (GET /portfolio/holdings)

[
  {
    "symbol": "RELIANCE",
    "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
    "quantity": 100,
    "avg_price": 2450.0,
    "last_price": 2500.0,
    "pnl": 5000.0
  },
  ...
]

Positions (GET /portfolio/positions)

Returns intraday and overnight positions with realized_pl and unrealized_pl.

📡 Live Data

Quote (GET /marketdata/quote)

LTP Only (GET /marketdata/ltp)

Market Depth (GET /marketdata/depth)

{
  "bids": [[2490.00, 100]],            // array of [price, qty]: Top bid levels
  "asks": [[2500.00, 75]]              // array of [price, qty]: Top ask levels
}

📊 Historical Data

OHLC Candles (GET /marketdata/history)

Query: symbol, exchange, interval, from, to

Intervals: 1min, 5min, 15min, 1hour, 1day

🏦 Margin

Get Margin (GET /margin)

{
  "available_cash": 80000,            // float: Available funds
  "collateral": 20000,                // float: Collateral margin
  "used_margin": 50000,               // float: Utilized margin
  "net": 100000                        // float: Net margin available
}

Margin Calculator (POST /margin/calculate)

Send hypothetical order to get margin required.

❌ Errors & Status Codes

Status

Meaning

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Rate Limit Exceeded

500

Server Error

📚 Annexures & Definitions

📊 Pagination & Filtering

🔠 Query Parameter Types

Parameter

Type

Description

limit

integer

Max number of records to return

offset

integer

Record index to start from (for pagination)

sort

string

Format: field:direction (e.g. time:desc)

from_date

datetime

Start date in ISO 8601 format

to_date

datetime

End date in ISO 8601 format

Orders & Instruments endpoints support:

limit (default: 50, max: 100)
offset (for pagination)
sort (e.g. created_at:desc)
from_date, to_date (ISO 8601 for filtering)

Example:

GET /orders?limit=25&offset=0&sort=created_at:desc

⏱️ Rate Limits

Endpoint Group

Limit

Window

Market Data

60 req/min

per token

Orders

30 req/min

per token

Portfolio

20 req/min

per token

Exceeding limits will return HTTP 429 with Retry-After header.

⚠️ WebSocket Error Handling

WebSocket clients may receive:

{
  "type": "error",
  "message": "Invalid token or malformed subscription"
}

Handle with reconnect logic or alert user accordingly.

📣 Webhooks (Optional)

Enable real-time updates for:

✅ Order Status Changes
💸 Margin Call Alerts

Webhook Payload Example:

{
  "event": "ORDER_UPDATE",            // string: Event type
  "order_id": "ORD12345",             // string: Order identifier
  "status": "FILLED",                 // string: Final status
  "filled_quantity": 100              // integer: Executed quantity
}

Use secure HTTPS URLs with HMAC signature (SHA256).

🧪 Environments

Type

URL Prefix

Sandbox

https://sandbox.api.nin.in/

Live

https://api.nin.in/

Sandbox allows safe order testing with virtual funds.

🛡️ Security & Retry Tips

🔁 Retry only 5xx errors with backoff.
🚫 Never log raw access_token.
🔄 Refresh token every 24 hrs (or use a refresh token model).

🧠 Glossary: Instrument Fields

📌 Data Types Reference

Type

Description

string

UTF-8 encoded text

integer

Whole number

float

Decimal number

boolean

true or false

datetime

ISO 8601 format, e.g., 2025-05-05T09:15:00Z

Field

Description

instrument_token

Unique ID used internally for streaming & orders

tick_size

Minimum price movement allowed

lot_size

Number of units per order (e.g., 1 for equity)

segment

Segment type (e.g., NSE_EQ, BSE_EQ, NFO_OPT)

Order Types

MARKET
LIMIT
SL
SL-M

Products

CNC: Delivery
MIS: Intraday
NRML: Futures & Options

Validity

DAY: Valid till end of day
IOC: Immediate or Cancel

📶 WebSocket Streams

NIN provides real-time streaming over WebSocket for:

📈 Live market quotes
🧾 Order status updates (for authenticated users)
🔄 LTP, depth, and volume changes

🔗 Connection URL

wss://stream.nin.in/quotes

🔒 Authenticated WebSocket sessions must include a valid bearer token in the Authorization header (for private streams).

📩 Subscription Format

{
  "action": "subscribe",
  "tokens": [738561, 256265]
}

🔕 Unsubscribe Format

{
  "action": "unsubscribe",
  "tokens": [738561]
}

📊 Tick Message Format

{
  "instrument_token": 738561,     // integer: NSE/BSE instrument ID
  "last_price": 2500.00,          // float: Latest price
  "volume": 120000,               // integer: Traded volume
  "change": 15.5,                 // float: Change from previous close
  "percent_change": 0.62,         // float: Percentage change
  "timestamp": "2025-05-05T10:15:30Z"  // datetime: Server time
}

🧾 Order Update Message (Authenticated Users Only)

{
  "type": "order_update",
  "order_id": "ORD123456789",
  "status": "FILLED",
  "filled_quantity": 100,
  "average_price": 2498.25,
  "symbol": "RELIANCE",
  "nin_symbol": "RELIANCE.NS",         // string: NIN Trade Trading symbol
  "timestamp": "2025-05-05T10:16:05Z"
}

Maintain the connection using ping/pong or keepalive every 30s. Use a WebSocket client that supports automatic reconnect on network drop.

📞 Support

Dev Portal:
Contact:

Ready to trade? Start building with NIN today at