Brokerage Calculator

This document explains how to use the Brokerage Calculator API within the Firstock trading platform.

Overview

The Brokerage Calculator API allows you to calculate the total brokerage, taxes, and final charges for a trade across multiple asset classes like equities, and derivatives.
It provides real-time estimation of trading costs based on your input parameters such as order type, quantity, price, and exchange.

This helps traders and investors to accurately predict the net profitability or cost of a trade before execution.

Key benefits:

• Real-time Cost Estimation: Instantly calculate total charges before placing trades.
• Trade Planning: Helps in determining breakeven points and potential profitability.
• Supports Multiple Asset Classes: Equity, and derivatives markets.
• Improved Transparency: Provides clear breakup of all transaction costs.

Endpoint & Method

URL:

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

Headers:

Body:

Below is the general JSON body for the Get Security Info API request. All Mandatory fields must be included.

Request:

{
    "userId": "AB1234",
    "jKey": "137dea860c50cbe7077dd8455569cac08f3b6fdd5512b48bde71c3110e4b8788",
    "exchange": "NFO",
    "tradingSymbol": "RELIANCE27FEB25F",
    "transactionType": "B",
    "Product": "M",
    "quantity": "500",
    "price": "125930",
    "strike_price": "0",
    "inst_name": "FUTSTK",
    "lot_size": "1"

}

Example cURL Request

curl --location 'https://api.firstock.in/V1/brokerageCalculator' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "AB1234",
    "jKey": "137dea860c50cbe7077dd8455569cac08f3b6fdd5512b48bde71c3110e4b8788",
    "exchange": "NFO",
    "tradingSymbol": "RELIANCE27FEB25F",
    "transactionType": "B",
    "Product": "M",
    "quantity": "500",
    "price": "125930",
    "strike_price": "0",
    "inst_name": "FUTSTK",
    "lot_size": "1"

}'

Response Structure

Success Response:

If your request is valid and the security is found, you will receive a 200 OK status with a JSON object containing:

• status: Typically "success".
• message: A short note (e.g., "Fetched security info successfully").
• data: An object detailing the security’s info.

Key Fields in data:

• instrumentName: The instrument category (e.g., "EQ", "OPTIDX", "FUTSTK", etc.).
• segment: The market segment (e.g., "EQT", "FNO", etc.).
• symbolName: The system-recognized name for the instrument.
• tradingSymbol: The display-oriented name (may differ from the input if the system has a specific format).
• token: Numeric identifier used within Firstock’s system.
• priceFactor, pricePrecision, tickSize: Information about how prices are calculated or displayed.

Failure Response:

If any required field is missing, invalid, or the session token (jKey) is expired, you may receive a 400 or 401 status code with an error object:

• Invalid or missing jKey.
• Empty or incorrect tradingSymbol or exchange.
• Security not found (the symbol may not exist or be spelled incorrectly).

Response

        {
          "status": "success",
          "message": "Brokerage Data",
          "data": {
            "exchange": "NSE",
            "instrumentName": "UNDIND",
            "lotSize": "1",
            "mult": "1",
            "priceFactor": "(1 / 1 ) * (1 / 1)",
            "pricePrecision": "2",
            "segment": "EQT",
            "symbolName": "NIFTY",
            "tickSize": "0.00",
            "token": "26000",
            "tradingSymbol": "Nifty 50"
          }         
    }
        

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

Usage & Best Practices

• Verification Before Trading
  • Use this API to confirm the correct segment, instrumentName, or lotSize before placing F&O orders.
• Session Management
  • Maintain a valid jKey. If INVALID_JKEY or similar errors arise, re-login or refresh tokens as needed.
• Error Handling
  • If status is "failed", review the error.field and error.message to correct any missing or invalid parameters.
• Reference Data
  • Consider storing or caching common results if you repeatedly request the same symbol (e.g., “NIFTY”) to reduce API overhead.
• Integration with Other APIs
  • Combine with Order Margin, Place Order, or Get Quotes for a seamless workflow once you have the correct details for a symbol.

Conclusion

The Get Security Info API is a crucial tool for validating an instrument’s internal details—such as segment, instrumentName, lotSize, and token—before you proceed with more advanced operations. Make sure to maintain a valid session (jKey), handle errors gracefully, and use this data to ensure you’re interacting with the correct instrument.