Positions API

Monitor your complete portfolio positions in real-time with comprehensive profit & loss analytics, mark-to-market calculations, and advanced position tracking across all exchanges.

Overview

The Positions API delivers institutional-grade portfolio monitoring capabilities with real-time position tracking, detailed P&L breakdowns, and comprehensive risk analytics. Essential for portfolio management platforms, algorithmic trading systems, and advanced trading applications requiring precise position data.

Key Features

Real-Time Portfolio Monitoring: Live position tracking with current market valuations
Advanced P&L Analytics: Comprehensive realized and unrealized profit/loss calculations
Multi-Session Tracking: Intraday, carry-forward, and historical position analysis
Risk Management Metrics: Break-even calculations and exposure analysis
Cross-Exchange Support: Unified view across NSE, BSE, NFO, BFO, and MCX

Endpoint Reference

Get Portfolio Positions

Retrieve your complete position book with detailed analytics and market data.

Endpoint Details

Method: GET
URL: /user/positions
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/positions' \
--header 'appID: <YOUR_APP_ID>' \
--header 'token: <YOUR_TOKEN>'

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

const positions = await response.json();

import requests

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

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

positions = response.json()

Response Schema

Success Response

{
    "data": [
        {
            "symbol": "BANKNIFTY27MAR24C46900",
            "exchange": "NFO",
            "token": "66696",
            "product": "I",
            "qty": "0",
            "avgPrice": "0.00",
            "ltp": "0.05",
            "realisedPnL": "2699.25",
            "unrealisedMarkToMarket": "0.00",
            "dayBuyQty": "90",
            "dayBuyAvgPrice": "84.76",
            "dayBuyAmount": "7628.25",
            "daySellQty": "90",
            "daySellAvgPrice": "114.75",
            "daySellAmount": "10327.50",
            "breakEvenPrice": "0.00",
            "lotSize": "15",
            "tickSize": "0.05",
            "pricePrecision": "2"
        }
    ],
    "status": "success"
}

Response Fields

Core Position Data

Field	Type	Description
`symbol`	string	Trading instrument identifier
`exchange`	string	Exchange code (NSE, NFO, BSE, BFO, MCX)
`token`	string	Unique instrument token
`product`	string	Product type (`I` = Intraday, `C` = Delivery, `M` = Normal)
`qty`	string	Current net position quantity
`avgPrice`	string	Average price of current position
`ltp`	string	Last traded price

Profit & Loss Metrics

Field	Type	Description
`realisedPnL`	string	Realized profit/loss from closed positions
`unrealisedMarkToMarket`	string	Unrealized profit/loss from open positions
`breakEvenPrice`	string	Price at which position breaks even

Intraday Trading Activity

Field	Type	Description
`dayBuyQty`	string	Total quantity bought during trading session
`dayBuyAvgPrice`	string	Average purchase price for the day
`dayBuyAmount`	string	Total amount spent on purchases
`daySellQty`	string	Total quantity sold during trading session
`daySellAvgPrice`	string	Average selling price for the day
`daySellAmount`	string	Total amount received from sales

Carry Forward Positions

Field	Type	Description
`carryForwardBuyQty`	string	Quantity carried from previous sessions
`carryForwardBuyAvgPrice`	string	Average price of carried positions
`carryForwardSellQty`	string	Sold quantity from carried positions
`carryForwardSellAvgPrice`	string	Average selling price of carried positions

Open Order Data

Field	Type	Description
`openBuyQty`	string	Pending buy order quantities
`openBuyAvgPrice`	string	Average price of pending buy orders
`openSellQty`	string	Pending sell order quantities
`openSellAvgPrice`	string	Average price of pending sell orders

Contract Specifications

Field	Type	Description
`lotSize`	string	Contract lot size
`tickSize`	string	Minimum price movement
`pricePrecision`	string	Decimal places for price display
`multiplier`	string	Contract multiplier
`priceFactor`	string	Price adjustment factor

Position Categories

By Status

Category	Criteria	Description
Active Positions	`qty` ≠ "0"	Currently holding instruments with market exposure
Closed Positions	`qty` = "0"	Completed trades with realized P&L only
Profitable Trades	`realisedPnL` > 0	Positions closed with gains
Loss-Making Trades	`realisedPnL` < 0	Positions closed with losses

By Product Type

Product	Code	Characteristics	Settlement
Intraday	`I`	Same-day square-off mandatory	Auto-squared at market close
Delivery	`C`	Physical settlement for equity	T+2 settlement cycle
Normal	`M`	Standard F&O positions	Mark-to-market daily

P&L Calculation Methods

Realized P&L Formula

Closed Position P&L

Formula: Realized P&L = Total Sell Amount - Total Buy Amount

Example: - Buy: 90 lots @ ₹84.76 = ₹7,628.25 - Sell: 90 lots @ ₹114.75 = ₹10,327.50 - Realized P&L: ₹2,699.25

Unrealized P&L Formula

Open Position P&L

Formula: Unrealized P&L = (Current LTP - Average Price) × Quantity

Example: - Position: 15 lots @ ₹16.60 average - Current LTP: ₹17.45 - Unrealized P&L: (₹17.45 - ₹16.60) × 15 = ₹12.75

Break-Even Calculation

Break-Even Analysis

Formula: Break-Even Price = Total Cost ÷ Total Quantity

Represents the price needed to exit without profit or loss.

Position Examples

Profitable Closed Position

{
    "symbol": "BANKNIFTY27MAR24C46900",
    "exchange": "NFO",
    "product": "I",
    "qty": "0",
    "avgPrice": "0.00",
    "ltp": "0.05",
    "realisedPnL": "2699.25",
    "unrealisedMarkToMarket": "0.00",
    "dayBuyQty": "90",
    "dayBuyAvgPrice": "84.76",
    "dayBuyAmount": "7628.25",
    "daySellQty": "90",
    "daySellAvgPrice": "114.75",
    "daySellAmount": "10327.50"
}

Active Position with Unrealized Gains

{
    "symbol": "BANKNIFTY03APR24C48500",
    "exchange": "NFO",
    "product": "M",
    "qty": "15",
    "avgPrice": "16.60",
    "ltp": "17.45",
    "realisedPnL": "0.00",
    "unrealisedMarkToMarket": "12.75",
    "breakEvenPrice": "16.60",
    "lotSize": "15"
}

Loss-Making Position

{
    "symbol": "BANKNIFTY27MAR24C47300",
    "exchange": "NFO",
    "product": "I",
    "qty": "0",
    "avgPrice": "0.00",
    "ltp": "0.05",
    "realisedPnL": "-493.50",
    "dayBuyAmount": "895.50",
    "daySellAmount": "402.00"
}

Portfolio Analytics

Key Performance Indicators

Calculate comprehensive portfolio metrics using position data:

Metric	Calculation	Purpose
Total Realized P&L	Sum of all `realisedPnL` values	Overall closed trade performance
Total Unrealized P&L	Sum of all `unrealisedMarkToMarket`	Current open position value
Net Portfolio P&L	Realized + Unrealized P&L	Complete portfolio assessment
Win Rate	Profitable positions ÷ Total closed positions	Trading success ratio
Average Win	Total profits ÷ Number of winning trades	Average gain per winning trade
Average Loss	Total losses ÷ Number of losing trades	Average loss per losing trade

Risk Assessment Metrics

Metric	Description	Calculation
Position Concentration	Largest position as % of portfolio	Max position value ÷ Total portfolio
Exchange Distribution	Risk spread across exchanges	Positions by NSE/NFO/BSE/BFO/MCX
Product Mix Analysis	Intraday vs Delivery vs Normal	Position count by product type
Sector Exposure	Industry-wise position distribution	Group by underlying asset sectors

Implementation Examples

Portfolio P&L Calculator

JavaScriptPython

function calculatePortfolioMetrics(positions) {
    const metrics = positions.reduce((acc, position) => {
        const realized = parseFloat(position.realisedPnL) || 0;
        const unrealized = parseFloat(position.unrealisedMarkToMarket) || 0;

        acc.totalRealized += realized;
        acc.totalUnrealized += unrealized;
        acc.totalPositions += 1;

        if (realized > 0) acc.winningTrades += 1;
        if (realized < 0) acc.losingTrades += 1;

        return acc;
    }, {
        totalRealized: 0,
        totalUnrealized: 0,
        totalPositions: 0,
        winningTrades: 0,
        losingTrades: 0
    });

    return {
        ...metrics,
        netPnL: metrics.totalRealized + metrics.totalUnrealized,
        winRate: metrics.winningTrades / (metrics.winningTrades + metrics.losingTrades)
    };
}

def calculate_portfolio_metrics(positions):
    total_realized = sum(float(pos.get('realisedPnL', 0)) for pos in positions)
    total_unrealized = sum(float(pos.get('unrealisedMarkToMarket', 0)) for pos in positions)

    winning_trades = sum(1 for pos in positions if float(pos.get('realisedPnL', 0)) > 0)
    losing_trades = sum(1 for pos in positions if float(pos.get('realisedPnL', 0)) < 0)

    return {
        'total_realized': total_realized,
        'total_unrealized': total_unrealized,
        'net_pnl': total_realized + total_unrealized,
        'win_rate': winning_trades / (winning_trades + losing_trades) if (winning_trades + losing_trades) > 0 else 0
    }

Position Filter Examples

JavaScript

// Filter active positions
const activePositions = positions.filter(pos => parseFloat(pos.qty) !== 0);

// Filter profitable closed trades
const profitableTrades = positions.filter(pos => 
    parseFloat(pos.qty) === 0 && parseFloat(pos.realisedPnL) > 0
);

// Filter by exchange
const nfoPositions = positions.filter(pos => pos.exchange === 'NFO');

// Filter by product type
const intradayPositions = positions.filter(pos => pos.product === 'I');

Data Integration

Market Data Updates

The Positions API provides near real-time data with the following characteristics:

Market Phase	Update Frequency	Data Freshness
Live Trading Hours	Real-time (< 1 second)	Current market prices
Pre-Market Session	Previous close data	Last trading day values
Post-Market Hours	Closing prices	End-of-day settlements

Cross-API Integration

Complete Portfolio View

Combine Positions API with other endpoints for comprehensive portfolio management:

Orders API: Link positions to originating orders
Trade Book: Detailed execution history
Holdings API: Long-term equity positions
Margin API: Available margin calculations

Error Handling

Standard HTTP status codes with structured error responses:

{
    "status": "error",
    "message": "Position data temporarily unavailable",
    "code": "DATA_UNAVAILABLE"
}

Common Scenarios

Empty Portfolio: data: [] - Normal for new accounts
401 Unauthorized: Invalid or expired authentication token
429 Rate Limited: Too many requests, implement throttling
500 Server Error: Temporary data service issues

Rate Limits

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

Integration Guidelines

Best Practices

Efficient Polling: Request positions data at appropriate intervals (every 1-5 seconds during market hours)
Data Caching: Cache position data to minimize API calls while maintaining freshness
P&L Monitoring: Implement real-time P&L tracking for risk management
Position Reconciliation: Cross-verify with order and trade data for accuracy
Error Recovery: Build robust error handling for market data interruptions

Performance Optimization

Filter positions client-side to reduce processing overhead
Implement incremental updates where possible
Use WebSocket feeds for real-time price updates when available
Monitor API response times and implement fallback mechanisms

Risk Management

Monitor unrealized P&L for position sizing decisions
Set up alerts for significant position movements
Implement automated stop-loss mechanisms based on position data
Regular reconciliation with broker statements for accuracy