Position Book

This document details how to use the Position Book API on the Firstock trading platform.

Overview

The Position Book API provides a snapshot of open positions held in a user’s account. Each position entry includes details such as the net quantity, day buy/sell amounts, average price, and mark-to-market (MTM) information. This data is crucial for traders who want to monitor their current market exposure and unrealised profit or loss.

Key benefits:

• Real-Time Position Tracking: Keep tabs on both intraday and positional holdings.
• Profit/Loss Insights: Quickly gauge unrealized MTM to assess current market exposure.
• Data Consolidation: Combine position data with order and trade books for a complete trading overview.

Endpoint & Method

URL:

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

Headers:

Body:

Below is the typical JSON body for the Position Book API request. Fields marked Mandatory must be included.

Request:

{
  "userId": "{{userId}}",
  "jKey": "{{jKey}}"
}

Example cURL Request

curl --location 'https://api.firstock.in/V1/positionBook' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "{{userId}}",
    "jKey": "{{jKey}}"
}'

Response Structure

Success Response:

If the request is valid and trades exist for the given account, you will receive a 200 OK status and a JSON object containing:

• status: Typically "success".
• message: Brief description (e.g., "Fetched positions")
• data: An array of position objects, each detailing a specific position.

Key Fields per Position Entry:

• dayBuyQuantity/daySellQuantity: The total intraday buy/sell quantities.
• dayBuyAveragePrice/datSellAveragePrice: Average prices for intraday trades.
• netQuantity: Net position quantity (buys minus sells).
• netAveragePrice: Weighted average price for the net position.
• unrealizedMTOM: Mark-to-market profit/loss for the open position.
• RealizedPNL: Realized profit/loss for closed portions of the position.
• product: The product type (e.g., "C" for CNC, "M" for MIS).
• tradingSymbol: Symbol for the security.
• exchange: Exchange code ("NSE", "BSE", "NFO", etc.).

Failure Response:

If any required field is missing, invalid, or the order can’t be canceled, you may receive a 400 or 401 status code with an error structure:

• Invalid jKey: Session expired or token is incorrect.
• Missing userId: The system cannot determine which account to reference.
• No Positions: If there are truly no open positions, the API may return an empty data array (or a specific message).

Response

        {
          "status": "success",
          "message": "Fetched positions",
          "data": [ 
          {
            "RealizedPNL": "0.00",
            "datSellAveragePrice": "0.00",
            "dayBuyAmount": "2837.00",
            "dayBuyAveragePrice": "2837.00",
            "dayBuyQuantity": "1.00",
            "daySellQuantity": "0.00",
            "exchange": "EQT",
            "lotSize": "1",
            "mult": "1",
            "netAveragePrice": "2837.00",
            "netQuantity": "1.00",
            "netUploadPrice": "0.00",
            "priceFactor": "1.000000",
            "pricePrecision": "2",
            "product": "C",
            "tickSize": "0.05",
            "token": "PSB",
            "tradingSymbol": "PSB-EQ",
            "unrealizedMTOM": "0.00",
            "uploadPrice": "0.00",
            "userId": "AB1234"
          },
          {
            "RealizedPNL": "0.00",
            "datSellAveragePrice": "0.00",
            "dayBuyAmount": "2837.00",
            "dayBuyAveragePrice": "2837.00",
            "dayBuyQuantity": "1.00",
            "daySellQuantity": "0.00",
            "exchange": "NSE",
            "lotSize": "1",
            "mult": "1",
            "netAveragePrice": "2837.00",
            "netQuantity": "1.00",
            "netUploadPrice": "0.00",
            "priceFactor": "1.000000",
            "pricePrecision": "2",
            "product": "C",
            "tickSize": "0.05",
            "token": "21001",
            "tradingSymbol": "PSB-EQ",
            "unrealizedMTOM": "0.00",
            "uploadPrice": "0.00",
            "userId": "AB1234"
          }
          ]       
    }
        

                    {
    "status": "failed",
    "code": "401",
    "name": "INVALID_JKEY",
    "error": {
      "field": "jKey",
      "message": "jKey is required"
    }
  }
                

Usage & Best Practices

• Monitor Profit/Loss
  • The unrealizedMTOM field is particularly useful for real-time P/L analysis.
• Partial vs. Full Positions
  • Some entries might represent partially squared-off positions. Keep track of netQuantity to see how many shares/contracts remain.
• Intraday vs. Carry Forward
  • Pay attention to the product field. For intraday positions ("M", "MIS") vs. delivery/carry forward ("C"), the margin requirements and auto-square-off rules differ.
• Session Validity
  • Ensure jKey is current. If an error indicates INVALID_JKEY, prompt for re-login.
• Data Synchronization
  • Integrate with the Order Book, Trade Book, and RMS Limit data for a comprehensive real-time view of the user’s account status.

Conclusion

The Position Book API is vital for traders who need up-to-date information on their open positions and real-time profit/loss estimates. Integrating this endpoint into your application allows you to provide users with accurate insights into their current market exposure, helping them make informed trading decisions.