Place Order

This document provides a detailed overview of the Place Order API for the Firstock trading platform.

Overview

The Place Order API allows authenticated clients to create new orders. Depending on the specified parameters (e.g., price type, product type), it can handle multiple order scenarios, such as limit orders, market orders, and stop-loss orders.

Key benefits:

• Versatile Order Types: Supports market, limit, and SL-based orders.
• Broad Exchange Coverage: Place trades on NSE, BSE, NFO, and more.
• Seamless Integration: Easily incorporate order placement into your trading application’s workflow.

Endpoint & Method

URL:

Headers:

Body:

Below is the general JSON body for the Place Order API request. Fields marked as Mandatory must be included.

https://api.firstock.in/V1/placeOrder

Request:

{
  "userId": "{{userId}}",
  "jKey": "{{jKey}}",
  "exchange": "NSE",
  "retention": "DAY",
  "customer_firm": "C",
  "product": "C",
  "priceType": "MKT",
  "tradingSymbol": "IDEA-EQ",
  "transactionType": "B",
  "price": "0",
  "trgprc": "0",
  "quantity": "1",
  "remarks": "Test"
}

Example cURL Request

curl --location 'https://api.firstock.in/V1/placeOrder' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "{{userId}}",
    "jKey": "{{jKey}}",
    "exchange": "NSE",
    "retention": "DAY",
    "customer_firm": "C",
    "product": "C",
    "priceType": "MKT",
    "tradingSymbol": "IDEA-EQ",
    "transactionType": "B",
    "price": "0",
    "trgprc": "0",
    "quantity": "1",
    "remarks": "Test"
}'

Note: If a trading Symbol consists of a special symbol, please use the URL encoding. example: L&TFH-EQ should be sent as L%26TFH-EQ

Response Structure

Success Response:

If the order is placed successfully, you will receive a 200 OK status with a JSON object containing:

• status: Typically "success".
• message: Brief description of the outcome (e.g., "Order details").
• data: An object with information about the newly placed order.

Key Fields in the data object:

• orderNumber: A unique identifier for this order.
• requestTime: Timestamp when the order was processed.

Failure Response:
If the request is malformed or any required field is missing/invalid, you may receive a 400 or 401 status code with details such as:

• status: "failed".
• code: Error code (e.g., "400", "401").
• name: A brief descriptor (e.g., "BADREQUEST").
• error: An object indicating which field caused the issue and why.

Response

                    {
    "status": "success",
     "message": "Order details",                 
    "data": {
      "orderNumber": "25042100011119",
      "requestTime": "17:50:52 21-04-2025"  
      }
  }
                

                    {
    "status": "failed",
    "code": "400",
    "name": "BAD_REQUEST",
    "error": {
      "field": "exchange",
      "message": "required field is empty or missing: exchange"
    }
  }
                

Usage & Best Practices

• Order Number Tracking

  • Store the orderNumber returned upon success. You’ll need it to modify, cancel, or check the status of the order later.

• Price & Trigger Price

  • If placing a market order, ensure price = 0 and priceType = "MKT".
  • If placing a stop-loss order, set trgprc to the desired trigger price and priceType to "SL-LMT" or "SL-MKT".

• Quantity & Product Types

  • Double-check the product type ("C", "I", "M", etc.) to match your trading strategy.

  • Ensure the quantity is correct (consider lot sizes for F&O instruments).

• Error Handling

  • On failure, use the field and message in the response to debug. Missing or incorrect fields (like exchange or tradingSymbol) are common mistakes.

• User Session

  • The jKey must be valid. If you receive an error like "INVALIDJKEY", your session may have expired; prompt a re-login.

• Exchange Restrictions

  • Some symbols are only valid on specific exchanges. Validate against your symbol master files or the provided symbol lists to avoid errors.

Conclusion

The Place Order API is a core feature for building trading applications on the Firstock platform. By combining the correct parameters for price type, product type, and quantity, you can execute various trading strategies across multiple exchanges. For advanced features like stop-loss orders or bracket orders, adjust the relevant fields (priceType, trgprc) accordingly. If you encounter persistent errors, consult the official Firstock documentation or support.