Holdings API

Retrieve comprehensive portfolio holdings data for authenticated users, including position details, profit/loss calculations, and collateral information.

Overview

The Holdings API provides complete visibility into a user's equity positions across multiple exchanges, enabling portfolio management and risk assessment capabilities. Holdings are consolidated by instrument, with support for multi-exchange trading symbols.

Endpoint Reference

Get User Holdings

Retrieve all current holdings for the authenticated user account.

Endpoint Details

Method: GET
URL: /user/holdings
Authentication: Required (appID + token)

Request Headers

Header	Type	Required	Description
`appID`	string	✓	Your application identifier
`token`	string	✓	User authentication token

Request Example

cURLJavaScriptPython

curl --location 'https://edge.arrow.trade/user/holdings' \
--header 'appID: <YOUR_APP_ID>' \
--header 'token: <YOUR_TOKEN>'

const response = await fetch('https://edge.arrow.trade/user/holdings', {
  method: 'GET',
  headers: {
    'appID': '<YOUR_APP_ID>',
    'token': '<YOUR_TOKEN>'
  }
});

const holdings = await response.json();

import requests

headers = {
    'appID': '<YOUR_APP_ID>',
    'token': '<YOUR_TOKEN>'
}

response = requests.get(
    'https://edge.arrow.trade/user/holdings',
    headers=headers
)

holdings = response.json()

Response Schema

Success Response

The API returns a structured response containing an array of holding objects. Each holding represents a consolidated position across multiple exchanges where the instrument is traded.

{
  "data": [
    {
      "symbols": [
        {
          "symbol": "IDEA-EQ",
          "exchange": "NSE",
          "token": "14366"
        },
        {
          "symbol": "IDEA",
          "exchange": "BSE",
          "token": "532822"
        }
      ],
      "avgPrice": "6.53",
      "qty": "752",
      "usedQty": "0",
      "t1Qty": "0",
      "depositoryQty": "0",
      "collateralQty": "",
      "brokerCollateralQty": "0.00",
      "authorizedQty": "0",
      "unPledgedQty": "0",
      "nonPOAQty": "0",
      "haircut": "26.97",
      "effectiveQty": "752",
      "sellableQty": "752",
      "ltp": "",
      "pnl": "",
      "close": ""
    },
    {
      "symbols": [
        {
          "symbol": "YESBANK-EQ",
          "exchange": "NSE",
          "token": "11915"
        },
        {
          "symbol": "YESBANK",
          "exchange": "BSE",
          "token": "532648"
        }
      ],
      "avgPrice": "19.42",
      "qty": "2",
      "usedQty": "0",
      "t1Qty": "0",
      "depositoryQty": "0",
      "collateralQty": "",
      "brokerCollateralQty": "0.00",
      "authorizedQty": "0",
      "unPledgedQty": "0",
      "nonPOAQty": "0",
      "haircut": "17.88",
      "effectiveQty": "2",
      "sellableQty": "2",
      "ltp": "",
      "pnl": "",
      "close": ""
    }
  ],
  "status": "success"
}

Response Fields

Root Object

Field	Type	Description
`data`	array	Array of consolidated holding objects
`status`	string	Response status indicator

Holding Object

Field	Type	Description
`symbols`	array	Array of symbol objects representing the instrument across different exchanges
`avgPrice`	string	Average acquisition price across all positions
`qty`	string	Total quantity held across all exchanges
`effectiveQty`	string	Effective tradeable quantity
`sellableQty`	string	Quantity available for sale
`usedQty`	string	Quantity currently utilized
`t1Qty`	string	T+1 settlement quantity
`depositoryQty`	string	Quantity held in depository
`collateralQty`	string	Quantity pledged as collateral
`brokerCollateralQty`	string	Broker-pledged quantity
`authorizedQty`	string	Authorized quantity for trading
`unPledgedQty`	string	Unpledged quantity
`nonPOAQty`	string	Non-POA (Power of Attorney) quantity
`haircut`	string	Risk haircut percentage
`ltp`	string	Last traded price (may be empty)
`pnl`	string	Unrealized profit/loss amount (may be empty)
`close`	string	Previous day's closing price (may be empty)

Symbol Object

Each holding contains a symbols array with objects representing the instrument on different exchanges:

Field	Type	Description
`symbol`	string	Exchange-specific trading symbol
`exchange`	string	Exchange identifier (NSE, BSE, etc.)
`token`	string	Unique instrument token for the exchange

Sample Portfolio Analysis

Based on the example response, here's a portfolio breakdown:

Portfolio Summary

Total Holdings: 2 consolidated positions
Exchanges: NSE, BSE (multi-exchange support)
P&L Status: Market data pending

Individual Holdings

IDEA (Vodafone Idea)YESBANK (Yes Bank)

Exchanges: NSE (IDEA-EQ), BSE (IDEA)
Total Quantity: 752 shares
Avg Price: ₹6.53
Haircut: 26.97%
Status: Fully sellable

Exchanges: NSE (YESBANK-EQ), BSE (YESBANK)
Total Quantity: 2 shares
Avg Price: ₹19.42
Haircut: 17.88%
Status: Fully sellable

Key Features

Multi-Exchange Consolidation

Holdings are consolidated across exchanges, providing a unified view of your positions. Each holding includes all exchanges where the instrument is available for trading.

Real-time Market Data

Market data fields (ltp, pnl, close) may be populated during market hours. When empty, these fields indicate that real-time data is not currently available.

Risk Management

The haircut field indicates the risk percentage applied to the holding for margin calculations, helping assess portfolio risk exposure.

Error Handling

The API follows standard HTTP status codes and returns structured error responses:

{
  "status": "error",
  "message": "Authentication failed",
  "code": "AUTH_ERROR"
}

Common Issues

401 Unauthorized: Invalid or expired token
403 Forbidden: Insufficient permissions
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server-side processing error

Rate Limits

Tier	Requests per minute	Burst limit
Basic	60	10
Premium	300	50
Enterprise	1000	100

Integration Notes

Best Practices

Holdings are consolidated across exchanges - use the symbols array to identify specific exchange tokens
Handle empty market data fields (ltp, pnl, close) gracefully
Cache holdings data appropriately to minimize API calls
Implement proper error handling and retry logic
Use the haircut field for risk assessment calculations

Data Freshness

Holdings data is updated in real-time during market hours. Market data fields may be empty outside trading hours or during system maintenance. Position quantities and average prices are always available.