Glossary & Constants¶

Order ID Prefixes¶

See Smart Orders (GTT) for the parent/child relationship these prefixes describe.

Core Request Enums¶

exchange and segment are not freely combinable: COMMODITY is only valid with MCX, and MCX is only valid with COMMODITY. product is per segment — EQUITY takes CNC/INTRADAY, DERIVATIVE and COMMODITY take MARGIN/INTRADAY.

The segment and product query parameters on Portfolio Positions are case-insensitive — commodity and COMMODITY are both accepted, as are margin and MARGIN.

Commodity (MCX) Trading¶

Everything specific to MCX commodity trading, in one place: the account and contract checks, the trading sessions, the off-market queue, and the size, value and price rules. The endpoints themselves are documented under Order Management and Smart Orders; this section covers only what differs for segment: "COMMODITY" with exchange: "MCX".

Commodity orders use the same endpoints with segment: "COMMODITY" and exchange: "MCX". Order ids come back with the COM- prefix. Smart orders on MCX are described under Commodity (MCX) Smart Orders.

Example Request

curl --location 'https://api.indstocks.com/order' \
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "txn_type": "BUY",
  "exchange": "MCX",
  "segment": "COMMODITY",
  "product": "MARGIN",
  "order_type": "LIMIT",
  "limit_price": 8632,
  "validity": "DAY",
  "security_id": "565899",
  "qty": 100,
  "algo_id": "99999",
  "remarks": "crude-breakout/sig-118"
}'

Here 565899 is a CRUDEOIL futures contract with a lot size of 100 and a tick size of ₹1, so qty: 100 is one lot.

Response Payload (Success)

{
    "status": "success",
    "data": {
        "order_id": "COM-2013",
        "order_status": "INITIATED"
    }
}

order_status is the order's state when the response is built — for example INITIATED, PENDING, or O-PENDING for an order queued while MCX is shut. An order that the exchange or RMS rejects during placement still returns HTTP 200, with order_status: "FAILED" and the reason:

{
    "status": "success",
    "data": {
        "order_id": "COM-2016",
        "order_status": "FAILED",
        "reason": "Your order value exceeds the maximum limit set by the exchange. Please reduce the order quantity and try again."
    }
}

Account and Contract Checks¶

These checks run before the order is placed. A failed check returns 400 with error_type: RequestValidationException and the message shown.

MCX Trading Sessions¶

MCX runs two sessions on a trading day: a morning session 09:00–17:00 IST and an evening session 17:00–23:55 IST (23:30 IST while US daylight saving is in effect). Either session can be absent on a given day.

While a session is open, INTRADAY orders are refused once the intraday cutoff has passed — 23:45 IST (23:20 IST under US DST), or 16:50 IST on a day that has no evening session. The message is intraday order not allowed after cut-off time. The same cutoff applies to modifying an INTRADAY order. After the session closes, INTRADAY orders are accepted again and queued for the next session.

Orders Placed While MCX Is Shut¶

An order placed while MCX is shut is accepted and saved in INDstocks' own queue with status O-PENDING. This includes the 15-minute pre-open window before a session starts. INDstocks releases the order to the exchange after the next session opens. It is never sent to the exchange as a broker AMO.

• At release the order goes through the normal margin and order-rate checks. It can still end as FAILED — for example on a margin shortfall. Check the result with Get Order Details or Get Order Book.
• A MARKET order is priced when you place it: the last traded price at that moment plus or minus the protection buffer (see Market Orders Are Converted to Limit Orders). It is released at that limit price, even if the market opens away from it. We advise placing a LIMIT order instead, so you control the price the order is released at.

Order Size and Value¶

/order places exactly one exchange order for the whole qty:

• qty must be a whole multiple of the lot size — Qty should be multiple of 100.
• qty must not exceed the contract's freeze quantity — Qty should be less than freeze qty 10000.
• The order value must not exceed ₹3.5 crore, the exchange's per-order cap. Value is qty × price × general factor, where the general factor converts the quoted price into the contract's rupee value. The price is the limit price, or for a MARKET order the converted limit price. Over the cap: Order value 36000000.00 exceeds maximum allowed commodity order value of 35000000.00.

The value is checked again at the final price, after MARKET conversion; for an option, that check adds the strike price to the premium. A request that would then need more than one exchange order is refused with Qty requires slicing; use the smart order endpoint with slice_order=true. To place a larger quantity, send it to /smart/order with slice_order: true.

Price Rules¶

• limit_price must be a multiple of the tick size — Limit Price should be multiple of 1.00.
• limit_price must be inside the contract's circuit limits for the day — Limit price must be within range 8102.00 - 9338.00. An out-of-range limit is rejected.
• If the contract's circuit limits are not available, the order is rejected with commodity live circuit bounds are unavailable.
• On an option, the price must not exceed 1,00,000 — Max Value of option allowed is 100000.

Modifying and Cancelling¶

• Modify Order and Cancel Order with segment: "COMMODITY" accept only COM- order ids. Any other id is rejected with invalid order_id <id>.
• Only a PENDING or O-PENDING order can be modified. The new qty and limit_price must pass the size, value and price rules above. The response carries the order's status after the change.
• A PENDING, O-PENDING or PARTIALLY FILLED order can be cancelled. A PARTIALLY FILLED order that has a linked stop-loss/target leg is refused, because cancelling it could also remove the protection for the filled part.
• Cancelling an order that has a linked smart-order leg also cancels that leg. The response reports the leg in child_order_details.
• The cancel response carries the status read after the request. If the exchange has not yet confirmed the cancellation, the response adds reason: "Cancellation requested; completion is not confirmed".

{
    "status": "success",
    "data": {
        "order_id": "COM-2014",
        "order_status": "CANCELLED",
        "child_order_details": {
            "order_id": "GTT-91822",
            "order_status": "CANCELLED"
        }
    }
}

Reading Commodity Orders¶

Commodity orders appear in Get Order Book alongside equity and derivative orders, and Get Order Details, Get Trades and Get Trade Book take segment: "COMMODITY". Open commodity positions come from Get Positions with segment=commodity, and margin from the Margin Calculator with segment: "COMMODITY".

Smart Orders¶

Send segment: "COMMODITY" with exchange: "MCX" to /smart/order. The fields, account checks, trading sessions, off-market queue, and the size, value and price rules are the same as for Commodity (MCX) Orders. This section covers what is specific to smart orders.

Example Request — LIMIT order with stop-loss and target (Commodity)

curl --location 'https://api.indstocks.com/smart/order' \
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "txn_type": "BUY",
  "exchange": "MCX",
  "segment": "COMMODITY",
  "product": "MARGIN",
  "order_type": "LIMIT",
  "validity": "DAY",
  "security_id": "565899",
  "qty": 100,
  "limit_price": 8632,
  "sl_trigger_price": 8550,
  "sl_limit_price": 8545,
  "tgt_trigger_price": 8750,
  "tgt_limit_price": 8755,
  "algo_id": "99999"
}'

Response Payload (Success)

{
  "status": "success",
  "data": {
    "order_data": [
      {
        "order_id": "COM-2017",
        "order_status": "CREATED",
        "child_order_details": {
          "order_id": "GTT-91822",
          "order_status": "CREATED"
        }
      }
    ]
  }
}

Commodity Rules¶

Order IDs in the Response¶

Slicing Large Commodity Orders¶

slice_order: true works the same way on MCX as elsewhere — see Slicing Large Orders for the rules, the split and the validations. Two things are specific to commodity:

• A slice must fit the contract's freeze quantity and ₹3.5 crore of order value. The value cap usually binds first, so the slice is smaller than the freeze quantity alone would allow.
• order_data holds one entry per slice — INITIATED for a COM- slice, CREATED for the GTT- slices of a TRIGGER order. A COM- slice receives its stop-loss/target leg after the response; read it from child_order_id on Get Order Details. The GTT- slices of a TRIGGER order carry their leg in the response.

Modifying and Cancelling Commodity Smart Orders¶

Use segment: "COMMODITY" with a COM- or GTT- order id. Any other id, or a GTT- id that does not belong to a commodity order, is rejected with Order ID is missing or invalid.

• qty is optional on both and keeps the current quantity when left out.
• INTRADAY orders cannot be modified after the intraday cutoff.
• Cancelling a COM- parent also cancels its linked GTT- leg, reported in child_order_details. A PARTIALLY FILLED order cannot be cancelled through this endpoint.
• The cancel response carries the status read after the request. If the cancellation is not yet confirmed, it adds reason: "Cancellation requested; completion is not confirmed".

Instrument Code Formats¶

Two different formats are used depending on whether you're calling REST or WebSocket:

The bare form is used wherever the segment is already given by another parameter — security_id on the order endpoints, and underlying-scrip on the Option Chain, where segment carries that information instead.

WebSocket segment prefixes:

The underlying instrument identifier (SECURITY_ID / scrip code / token) is the same number in both formats — only the segment prefix and separator differ. Look up the right SECURITY_ID for a symbol via the Instruments API.

Order Status Values¶

The full list of order statuses (QUEUED, INITIATED, SUCCESS, CANCELLED, etc.) is maintained in one place: Orders — Order Status Types.

WebSocket Message Fields¶

See the WebSockets guide for full subscription payloads and response shapes.

TOTP Authentication¶

Limits at a glance

See Getting Your Access Token — Method 2 and TOTP limits and lockouts.