Orders

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

type endpoint  
POST /orders/:variety Place an order of a particular variety
PUT /orders/:variety/:order_id Modify an open or pending order
DELETE /orders/:variety/:order_id Cancel an open or pending order
GET /orders Retrieve the list of all orders (open and executed) for the day
GET /orders/:order_id Retrieve the history of a given order
GET /trades Retrieve the list of all executed trades for the day
GET /orders/:order_id/trades Retrieve the trades generated by an order

Glossary of constants

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

param values  
variety regular Regular order
  amo After Market Order
  bo Bracket Order ?
  co Cover Order ?
order_type MARKET Market order
  LIMIT Limit order
  SL Stoploss order ?
  SL-M Stoploss-market order ?
product CNC Cash & Carry for equity ?
  NRML Normal for futures and options ?
  MIS Margin Intraday Squareoff for futures and options ?
validity DAY Regular order
  IOC Immediate or Cancel

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 idefinitely 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 etc. See the list of varieties here.

curl https://api.kite.trade/orders/regular \
    -H "X-Kite-Version: 3" \
    -H "Authorization: token api_key:access_token" \
    -d "tradingsymbol=ACC" \
    -d "exchange=NSE" \
    -d "transaction_type=BUY" \
    -d "order_type=MARKET" \
    -d "quantity=1" \
    -d "product=MIS" \
    -d "validity=DAY" 
{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}

Regular order parameters

These parameters are common across different order varieties.

parameter  
tradingsymbol Tradingsymbol of the instrument
exchange Name of the exchange
transaction_type BUY or SELL
order_type Order type (MARKET, LIMIT etc.)
quantity Quantity to transact
product Margin product to use for the order (margins are blocked based on this) ?
price The min or max price to execute the order at (for LIMIT orders)
trigger_price The price at which an order should be triggered (SL, SL-M)
disclosed_quantity Quantity to disclose publicly (for equity trades)
validity Order validity
tag An optional tag to apply to an order to identify it (alphanumeric, max 8 chars)

Bracket order (BO) parameters

Bracket orders ? require these additional parameters. They also support the LIMIT and SL order types.

parameter  
squareoff Price difference at which the order should be squared off and profit booked (eg: Order price is 100. Profit target is 102. So squareoff = 2)
stoploss Stoploss difference at which the order should be squared off (eg: Order price is 100. Stoploss target is 98. So stoploss = 2)
trailing_stoploss Incremental value by which stoploss price changes when market moves in your favor by the same incremental value from the entry price (optional)

Note

For bracket orders, for example, if target = 2, then the target order (second leg) is placed 2 points away from the execution price of the first leg, and not the price you specify in the price field.

Response attributes

attribute  
order_idstring Unique order ID

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.

curl --request PUT https://api.kite.trade/orders/regular/151220000000000 \
    -H "X-Kite-Version: 3" \
    -H "Authorization: token api_key:access_token" \
    -d "order_type=MARKET" \
    -d "quantity=3" \
    -d "validity=DAY"
{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}

Regular order parameters

parameter  
order_type
quantity
price
trigger_price
disclosed_quantity
validity

Bracket order (BO) parameters

parameter  
parent_order_id Required, but not modifiable
quantity Only modifable on the first-leg order
price
trigger_price

Cover order (CO) parameters

parameter  
order_id
price
trigger_price For LIMIT Cover orders

Cancelling orders

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

curl --request DELETE \
    "https://api.kite.trade/orders/regular/151220000000000" \
    -H "X-Kite-Version: 3" \
    -H "Authorization: token api_key:access_token" \
{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}

Cancelling and exiting Bracket orders (BO)

As a bracket order is a two-legged order, it can only be "cancelled" when the entry order (first leg) is open. This works like cancelling any other order. However, if the entry order is executed and the second leg is open, the order can only be exited. The API call for cancellation and exiting is the same.

For cancelling or exiting bracket orders, the parent_order_id parameter should be sent.

# Exit / cancel a bracket order.
curl --request DELETE \
    "https://api.kite.trade/orders/bo/151220000000000?parent_order_id=151210000000000" \
    -H "X-Kite-Version: 3" \
    -H "Authorization: token api_key:access_token" \
{
  "status": "success",
  "data": {
    "order_id": "151220000000000"
  }
}
parameter  
parent_order_id

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.

curl "https://api.kite.trade/orders" \
    -H "X-Kite-Version: 3" \
    -H "Authorization: token api_key:access_token"
{
  "status": "success",
  "data": [{
    "order_id": "151220000000000",
    "parent_order_id": "151210000000000",
    "exchange_order_id": null,
    "placed_by": "AB0012",
    "variety": "regular",
    "status": "REJECTED",

    "tradingsymbol": "ACC",
    "exchange": "NSE",
    "instrument_token": 22,
    "transaction_type": "BUY",
    "order_type": "MARKET",
    "product": "NRML",
    "validity": "DAY",

    "price": 0.0,
    "quantity": 75,
    "trigger_price": 0.0,

    "average_price": 0.0,
    "pending_quantity": 0,
    "filled_quantity": 0,
    "disclosed_quantity": 0,
    "market_protection": 0,

    "order_timestamp": "2015-12-20 15:01:43",
    "exchange_timestamp": null,

    "status_message": "RMS:Margin Exceeds, Required:0, Available:0",
    "tag": null
  }]
}

Response attributes

attribute  
order_idstring Unique order ID
parent_order_idstring Order ID of the parent order (only applicable in case of multi-legged orders like BO and CO)
exchange_order_idnull, string Exchange generated order ID. Orders that don't reach the exchange have null IDs
placed_bystring ID of the user that placed the order. This may different from the user's ID for orders placed outside of Kite, for instance, by dealers at the brokerage using dealer terminals
varietystring Order variety (regular, amo, bo, co etc.)
statusstring Current status of the order. Most common values or COMPLETE, REJECTED, CANCELLED, and OPEN. There may be other values as well.
tradingsymbolstring Exchange tradingsymbol of the of the instrument
exchangestring Exchange
instrument_tokenstring The numerical identifier issued by the exchange representing the instrument. Used for subscribing to live market data over WebSocket
transaction_typestring BUY or SELL
order_type Order type (MARKET, LIMIT etc.)
productstring> Margin product to use for the order (margins are blocked based on this) ?
validitystring Order validity
pricefloat Price at which the order was placed (LIMIT orders)
quantityint Quantity ordered
trigger_pricefloat Trigger price (for SL, SL-M, CO orders)
average_pricefloat Average price at which the order was executed (only for COMPLETE orders)
peding_quantityint Pending quantity to be filled
filled_quantityint Quantity that's been filled
disclosed_quantityint Quantity to be disclosed (may be different from actual quantity) to the public exchange orderbook. Only for equities
order_timestampstring Timestamp at which the order was registered by the API
exchange_timestampstring Timestamp at which the order was registered by the exchange. Orders that don't reach the exchange have null timestamps
status_messagenull, string Textual description of the order's status. Failed orders come with human readable explanation

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.

status  
PUT ORDER REQUEST RECEIVED Order request has been received by the backend
VALIDATION PENDING Order pending validation by the RMS (Risk Management System)
OPEN PENDING Order is pending registration at the exchange
MODIFY VALIDATION PENDING Order's modification values are pending validation by the RMS
MODIFY PENDING Order's modification values are pending registration at the exchange
CANCEL PENDING Order's cancellation request is pending registration at the exchange
AMO REQ RECEIVED Same as PUT ORDER REQUEST RECEIVED, but for AMOs

Tagging orders

Often, it may be necessary to tag and filter orders based on various critera, for intance, 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 (BO and CO)

Bracket and 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

curl "https://api.kite.trade/orders/180111000830542" \
     -H "Authorization: token api_key:access_token"
{
  "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,
      "market_protection": 0,
      "order_id": "171222000539943",
      "order_timestamp": "2017-12-22 10:36:09",
      "order_type": "SL",
      "parent_order_id": null,
      "pending_quantity": 1,
      "placed_by": "ZQXXXX",
      "price": 130,
      "product": "MIS",
      "quantity": 1,
      "status": "PUT ORDER REQ RECEIVED",
      "status_message": null,
      "tag": null,
      "tradingsymbol": "ASHOKLEY",
      "transaction_type": "BUY",
      "trigger_price": 128,
      "validity": "DAY",
      "variety": "regular"
    },
    {
      "average_price": 0,
      "cancelled_quantity": 0,
      "disclosed_quantity": 0,
      "exchange": "NSE",
      "exchange_order_id": null,
      "exchange_timestamp": null,
      "filled_quantity": 0,
      "instrument_token": 54273,
      "market_protection": 0,
      "order_id": "171222000539943",
      "order_timestamp": "2017-12-22 10:36:09",
      "order_type": "SL",
      "parent_order_id": null,
      "pending_quantity": 1,
      "placed_by": "ZQXXXX",
      "price": 130,
      "product": "MIS",
      "quantity": 1,
      "status": "VALIDATION PENDING",
      "status_message": null,
      "tag": null,
      "tradingsymbol": "ASHOKLEY",
      "transaction_type": "BUY",
      "trigger_price": 128,
      "validity": "DAY",
      "variety": "regular"
    },
    {
      "average_price": 0,
      "cancelled_quantity": 0,
      "disclosed_quantity": 0,
      "exchange": "NSE",
      "exchange_order_id": null,
      "exchange_timestamp": null,
      "filled_quantity": 0,
      "instrument_token": 54273,
      "market_protection": 0,
      "order_id": "171222000539943",
      "order_timestamp": "2017-12-22 10:36:09",
      "order_type": "SL",
      "parent_order_id": null,
      "pending_quantity": 0,
      "placed_by": "ZQXXXX",
      "price": 130,
      "product": "MIS",
      "quantity": 1,
      "status": "REJECTED",
      "status_message": "RMS:Rule: Check circuit limit including square off order exceeds  for entity account-DH0490 across exchange across segment across product ",
      "tag": null,
      "tradingsymbol": "ASHOKLEY",
      "transaction_type": "BUY",
      "trigger_price": 128,
      "validity": "DAY",
      "variety": "regular"
    }
  ]
}

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.

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.

curl "https://api.kite.trade/trades" \
     -H "X-Kite-Version: 3" \
     -H "Authorization: token api_key:access_token"
{
    "status": "success",
    "data": [{
        "trade_id": "159918",
        "order_id": "151220000000000",
        "exchange_order_id": "511220371736111",

        "tradingsymbol": "ACC",
        "exchange": "NSE",
        "instrument_token": "22",

        "transaction_type": "BUY",
        "product": "MIS",
        "average_price": 100.98,
        "quantity": 10,

        "fill_timestamp": "2015-12-20 15:01:44",
        "exchange_timestamp": "2015-12-20 15:01:43"

    }]
}

Response attributes

attribute  
trade_idstring Exchange generated trade ID
order_idstring Unique order ID
exchange_order_idnull, string Exchange generated order ID
tradingsymbolstring Exchange tradingsymbol of the o
exchangestring Exchange
instrument_tokenstring The numerical identifier issued by the exchange representing the instrument. Used for subscribing to live market data over WebSocket
transaction_typestring BUY or SELL
productstring Margin product to use for the order (margins are blocked based on this) ?
average_pricefloat Price at which the was filled
filledint Filled quantity
fill_timestampstring Timestamp at which the trade was filled at the exchange
exchange_timestampstring Timestamp at which the order was registered by the exchange

Retrieving an order's trades

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

curl "https://api.kite.trade/orders/151220000000000/trades" \
     -H "X-Kite-Version: 3" \
     -H "Authorization: token api_key:access_token"
{
    "status": "success",
    "data": [{
        "trade_id": "159918",
        "order_id": "151220000000000",
        "exchange_order_id": "511220371736111",

        "tradingsymbol": "ACC",
        "exchange": "NSE",
        "instrument_token": "22",

        "transaction_type": "BUY",
        "product": "MIS",
        "average_price": 100.98,
        "quantity": 10,

        "fill_timestamp": "2015-12-20 15:01:44",
        "exchange_timestamp": "2015-12-20 15:01:43"

    }]
}