Orders

The order APIs let you place orders of different varities, modify and cancel pending orders, retrieve the daily order and more.

HTTP Method	Endpoint	Description	Section
POST	`/orders/:variety`	Place a new order	Placing orders
PUT	`/orders/:variety/:order_id`	Modify an existing order	Modifying orders
DELETE	`/orders/:variety/:order_id`	Cancel an order	Cancelling orders
GET	`/orders`	Retrieve all orders for the day	Retrieving orders
GET	`/orders/:order_id`	Retrieve an order's history	Retrieving an order's history
GET	`/trades`	Retrieve all trades for the day	Retrieving all trades
GET	`/orders/:order_id/trades`	Retrieve trades for a specific order	Retrieving an order's trades

Glossary of constants

Here are several of the constant enum values used for placing orders.

variety

regular
amo

order_type

LIMIT
SL - Stop-loss orders

product

CNC
NRML
MIS
MTF - Margin Trading Facility

validity

DAY
IOC
TTL

autoslice

true
false

Placing orders

Placing an order implies registering it with the OMS via the API. This does not guarantee the order's receipt at the exchange. The fate of an order is dependent on several factors including market hours, availability of funds, risk checks and so on. Under normal circumstances, order placement, receipt by the OMS, transport to the exchange, execution, and the confirmation roundtrip happen instantly.

When an order is successfully placed, the API returns an order_id. The status of the order is not known at the moment of placing because of the aforementioned reasons.

In case of non-MARKET orders that may be open indefinitely during the course of a trading day, it is not practical to poll the order APIs continuously to know the status. For this, postbacks are ideal as they sent order updates asynchronously as they happen.

Note: Successful placement of an order via the API does not imply its successful execution. To know the true status of a placed order, you should scan the order history or retrieve the particular order's current details using its order_id.

Order varieties

You can place orders of different varieties—regular orders, after market orders, cover orders, iceberg orders etc. See the list of varieties here.

Request:

curl https://api.blinkx.in/SmartApi/orders/regular \
  -H "X-Version: 3" \
  -H "Authorization: token api_key:access_token" \
  -d "tradingsymbol=ACC" \
  -d "exchange=NSE" \
  -d "transaction_type=BUY" \
  -d "order_type=LIMIT" \
  -d "quantity=1" \
  -d "product=MIS" \
  -d "validity=DAY"

Response:

{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}

Regular order parameters

These parameters are common across different order varieties.

Parameter	Description
`tradingsymbol`	Trading symbol of the instrument
`exchange`	Name of the exchange
`transaction_type`	BUY or SELL
`order_type`	Order type (LIMIT, SL)
`quantity`	Quantity to transact
`product`	Margin product type
`price`	For LIMIT orders
`trigger_price`	For SL orders
`disclosed_quantity`	Quantity to disclose publicly (for equity trades)
`validity`	Order validity (DAY, IOC, TTL)
`validity_ttl`	Order validity in minutes for TTL validity orders
`iceberg_legs`	Total number of legs for iceberg order variety
`iceberg_quantity`	Split quantity for each iceberg leg order
`auction_number`	Auction number for auction orders
`market_protection`	Market protection percentage
`autoslice`	Auto-slice large orders into smaller lots
`tag`	An optional tag to apply to an order to identify it

Modifying orders

As long as on order is open or pending in the system, certain attributes of it may be modified. It is important to sent the right value for :variety in the URL.

Request:

curl --request PUT https://api.blinkx.in/SmartApi/orders/regular/151220000000000 \
  -H "X-Version: 3" \
  -H "Authorization: token api_key:access_token" \
  -d "order_type=LIMIT" \
  -d "quantity=3" \
  -d "validity=DAY"

Response:

{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}

Regular order parameters

Parameter	Description
`order_type`	Order type (LIMIT, SL)
`quantity`	Quantity to transact
`price`	For LIMIT orders
`trigger_price`	For SL
`disclosed_quantity`	Quantity to disclose publicly
`validity`	Order validity

Cover order (CO) parameters

Parameter	Description
`order_id`	ID of the order
`price`	Price for LIMIT orders
`trigger_price`	Trigger price for stop loss

Note: For cover orders, only LIMIT order type modifications are allowed.

Cancelling orders

As long as on order is open or pending in the system, it can be cancelled.

Request:

curl --request DELETE \
  "https://api.blinkx.in/SmartApi/orders/regular/151220000000000" \
  -H "X-Version: 3" \
  -H "Authorization: token api_key:access_token"

Response:

{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}

Retrieving orders

The order history or the order book is transient as it only lives for a day in the system. When you retrieve orders, you get all the orders for the day including open, pending, and executed ones.

Request:

curl "https://api.blinkx.in/SmartApi/orders" \
  -H "X-Version: 3" \
  -H "Authorization: token api_key:access_token"

Response:

{
  "status": "success",
  "data": [
    {
      "placed_by": "XXXXXX",
      "order_id": "100000000000000",
      "exchange_order_id": "200000000000000",
      "parent_order_id": null,
      "status": "CANCELLED",
      "status_message": null,
      "status_message_raw": null,
      "order_timestamp": "2021-05-31 09:18:57",
      "exchange_update_timestamp": "2021-05-31 09:18:58",
      "exchange_timestamp": "2021-05-31 09:15:38",
      "variety": "regular",
      "modified": false,
      "exchange": "CDS",
      "tradingsymbol": "USDINR21JUNFUT",
      "instrument_token": 412675,
      "order_type": "LIMIT",
      "transaction_type": "BUY",
      "validity": "DAY",
      "product": "NRML",
      "quantity": 1,
      "disclosed_quantity": 0,
      "price": 72,
      "trigger_price": 0,
      "average_price": 0,
      "filled_quantity": 0,
      "pending_quantity": 1,
      "cancelled_quantity": 1,
      "market_protection": 0,
      "meta": {},
      "tag": null,
      "guid": "XXXXX"
    }
  ]
}

Response attributes

Attribute	Description
`order_id`	Unique order ID
`parent_order_id`	Parent order ID for multi-legged orders
`exchange_order_id`	Exchange generated order ID
`modified`	Indicates if order was modified
`placed_by`	User ID that placed the order
`variety`	Order variety
`status`	Current status of the order
`tradingsymbol`	Tradingsymbol of the instrument
`exchange`	Exchange
`instrument_token`	The numerical identifier issued by the exchange
`transaction_type`	BUY or SELL
`order_type`	Order type (LIMIT, SL)
`product`	Margin product
`validity`	Order validity
`price`	Price at which the order was placed
`quantity`	Quantity ordered
`trigger_price`	Trigger price
`average_price`	Average price at which the order was executed
`pending_quantity`	Pending quantity to be filled
`filled_quantity`	Quantity that has been filled
`disclosed_quantity`	Quantity to disclose publicly
`order_timestamp`	Timestamp at which the order was registered
`exchange_timestamp`	Timestamp at which the order was registered at the exchange
`exchange_update_timestamp`	Timestamp at which the order was last updated at the exchange
`status_message`	Textual description of the order's status
`status_message_raw`	Raw message from RMS or OMS
`cancelled_quantity`	Quantity that was cancelled
`auction_number`	Auction number (for auction orders)
`meta`	Map of arbitrary fields for internal use
`tag`	An optional tag
`guid`	Global unique identifier

Order statuses

The status field in the order response shows the current state of the order. The status values are largely self explanatory. The most common statuses are OPEN, COMPLETE, CANCELLED, and REJECTED.

An order can traverse through several interim and temporary statuses during its lifetime. For example, when an order is first placed or modified, it instantly passes through several stages before reaching its end state. Some of these are highlighted below:

PUT ORDER REQ RECEIVED
VALIDATION PENDING
OPEN PENDING
MODIFY VALIDATION PENDING
MODIFY PENDING
TRIGGER PENDING
CANCEL PENDING
AMO REQ RECEIVED

Tagging orders

Often, it may be necessary to tag and filter orders based on various criteria, for instance, to filter out all orders that came from a particular application or an api_key of yours. The tag field comes in handy here. It let's you send an arbitrary string while placing an order. This can be a unique ID, or something that indicates a particular type or context, for example. When the orderbook is retrieved, this value will be present in the tag field in the response.

Multi-legged orders (CO)

Cover orders are "multi-legged" orders, where, a single order you place (first-leg) may spawn new orders (second-leg) based on the conditions you set on the first-leg order. These orders have special properties, where the first-leg order creates a position. The position is exited when the second-leg order is executed or cancelled.

These second-leg orders will have a parent_order_id field indicating the order_id of its parent order, that is, the first-leg order. This field may be required while modifying or cancelling an open second-leg order.

Retrieving an order's history

Every order, right after being placed, goes through multiple stages internally in the OMS. Initial validation, RMS (Risk Management System) checks and so on before it goes to the exchange. In addition, an open order, when modified, again goes through these stages.

Request:

curl "https://api.blinkx.in/SmartApi/orders/171229000724687" \
  -H "Authorization: token api_key:access_token"

Response:

{
  "status": "success",
  "data": [
    {
      "average_price": 0,
      "cancelled_quantity": 0,
      "disclosed_quantity": 0,
      "exchange": "NSE",
      "exchange_order_id": null,
      "exchange_timestamp": null,
      "filled_quantity": 0,
      "instrument_token": 1,
      "order_id": "171229000724687",
      "order_timestamp": "2017-12-29 11:06:52",
      "order_type": "LIMIT",
      "parent_order_id": null,
      "pending_quantity": 1,
      "placed_by": "DA0017",
      "price": 300,
      "product": "CNC",
      "quantity": 1,
      "status": "PUT ORDER REQ RECEIVED",
      "status_message": null,
      "tag": null,
      "tradingsymbol": "SBIN",
      "transaction_type": "BUY",
      "trigger_price": 0,
      "validity": "DAY",
      "variety": "regular",
      "modified": false
    },
    {
      "average_price": 0,
      "cancelled_quantity": 0,
      "disclosed_quantity": 0,
      "exchange": "NSE",
      "exchange_order_id": null,
      "exchange_timestamp": null,
      "filled_quantity": 0,
      "instrument_token": 779521,
      "order_id": "171229000724687",
      "order_timestamp": "2017-12-29 11:06:52",
      "order_type": "LIMIT",
      "parent_order_id": null,
      "pending_quantity": 1,
      "placed_by": "DA0017",
      "price": 300,
      "product": "CNC",
      "quantity": 1,
      "status": "VALIDATION PENDING",
      "status_message": null,
      "tag": null,
      "tradingsymbol": "SBIN",
      "transaction_type": "BUY",
      "trigger_price": 0,
      "validity": "DAY",
      "variety": "regular",
      "modified": false
    }
  ]
}

Retrieving all trades

While an orders is sent as a single entity, it may be executed in arbitrary chunks at the exchange depending on market conditions. For instance, an order for 10 quantity of an instrument can be executed in chunks of 5, 1, 1, 3 or any such combination. Each individual execution that fills an order partially is a trade. An order may have one or more trades.

This API returns a list of all trades generated by all executed orders for the day.

Request:

curl "https://api.blinkx.in/SmartApi/trades" \
  -H "X-Version: 3" \
  -H "Authorization: token api_key:access_token"

Response:

{
  "status": "success",
  "data": [
    {
      "trade_id": "10000000",
      "order_id": "200000000000000",
      "exchange": "NSE",
      "tradingsymbol": "SBIN",
      "instrument_token": 779521,
      "product": "CNC",
      "average_price": 420.65,
      "quantity": 1,
      "exchange_order_id": "300000000000000",
      "transaction_type": "BUY",
      "fill_timestamp": "2021-05-31 09:16:39",
      "order_timestamp": "09:16:39",
      "exchange_timestamp": "2021-05-31 09:16:39"
    },
    {
      "trade_id": "40000000",
      "order_id": "500000000000000",
      "exchange": "CDS",
      "tradingsymbol": "USDINR21JUNFUT",
      "instrument_token": 412675,
      "product": "MIS",
      "average_price": 72.755,
      "quantity": 1,
      "exchange_order_id": "600000000000000",
      "transaction_type": "BUY",
      "fill_timestamp": "2021-05-31 11:18:27",
      "order_timestamp": "11:18:27",
      "exchange_timestamp": "2021-05-31 11:18:27"
    }
  ]
}

Response attributes

Attribute	Description
`trade_id`	Exchange generated trade ID
`order_id`	Order ID
`exchange_order_id`	Exchange order ID
`tradingsymbol`	Trading symbol
`exchange`	Exchange
`instrument_token`	Instrument token
`transaction_type`	BUY or SELL
`product`	Margin product
`average_price`	Price at which the quantity was filled
`filled`	Filled quantity
`fill_timestamp`	Timestamp at which the trade was filled
`order_timestamp`	Order timestamp
`exchange_timestamp`	Exchange timestamp

Retrieving an order's trades

This API returns the trades spawned and executed by a particular order.

Request:

curl "https://api.blinkx.in/SmartApi/orders/200000000000000/trades" \
  -H "X-Version: 3" \
  -H "Authorization: token api_key:access_token"

Response:

{
  "status": "success",
  "data": [
    {
      "trade_id": "10000000",
      "order_id": "200000000000000",
      "exchange": "MCX",
      "tradingsymbol": "GOLDPETAL21JUNFUT",
      "instrument_token": 58424839,
      "product": "NRML",
      "average_price": 4852,
      "quantity": 1,
      "exchange_order_id": "300000000000000",
      "transaction_type": "BUY",
      "fill_timestamp": "2021-05-31 16:00:36",
      "order_timestamp": "16:00:36",
      "exchange_timestamp": "2021-05-31 16:00:36"
    }
  ]
}

Glossary of constants​

variety​

order_type​

product​

validity​

autoslice​

Placing orders​

Order varieties​

Regular order parameters​

Modifying orders​

Regular order parameters​

Cover order (CO) parameters​

Cancelling orders​

Retrieving orders​

Response attributes​

Order statuses​

Tagging orders​

Multi-legged orders (CO)​

Retrieving an order's history​

Retrieving all trades​

Response attributes​

Retrieving an order's trades​

Glossary of constants

variety

order_type

product

validity

autoslice

Placing orders

Order varieties

Regular order parameters

Modifying orders

Regular order parameters

Cover order (CO) parameters

Cancelling orders

Retrieving orders

Response attributes

Order statuses

Tagging orders

Multi-legged orders (CO)

Retrieving an order's history

Retrieving all trades

Response attributes

Retrieving an order's trades