Position & PnL API

Endpoints for accessing portfolio positions and profit/loss analytics.

Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/positions`	Get current positions
`GET`	`/api/v1/positions/summary`	Get portfolio summary
`GET`	`/api/v1/positions/pnl/summary`	Get PnL summary
`GET`	`/api/v1/positions/pnl/daily`	Get daily PnL breakdown
`GET`	`/api/v1/positions/pnl/attribution`	Get PnL attribution

Get Positions

Retrieve current portfolio positions with mark-to-market valuation.

GET /api/v1/positions

Query Parameters

Parameter	Type	Required	Description
`as_of_date`	date	❌	Position date (default: today)
`include_zero`	boolean	❌	Include zero-quantity positions (default: false)

Example Request

curl http://localhost:8000/api/v1/positions

Response

{
  "positions": [
    {
      "instrument_id": 1,
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "asset_class": "EQUITY",
      "quantity": 100.0,
      "avg_cost": 180.25,
      "current_price": 185.50,
      "cost_basis": 18025.00,
      "market_value": 18550.00,
      "unrealized_pnl": 525.00,
      "unrealized_pnl_pct": 2.91,
      "realized_pnl": 150.00,
      "position_currency": "USD",
      "as_of_date": "2024-01-15"
    },
    {
      "instrument_id": 9,
      "symbol": "BTC-USD",
      "name": "Bitcoin",
      "asset_class": "CRYPTO",
      "quantity": 0.5,
      "avg_cost": 40000.00,
      "current_price": 42500.00,
      "cost_basis": 20000.00,
      "market_value": 21250.00,
      "unrealized_pnl": 1250.00,
      "unrealized_pnl_pct": 6.25,
      "realized_pnl": 0.00,
      "position_currency": "USD",
      "as_of_date": "2024-01-15"
    }
  ],
  "as_of_date": "2024-01-15",
  "base_currency": "USD"
}

Get Portfolio Summary

Retrieve a high-level portfolio summary with aggregated metrics.

GET /api/v1/positions/summary

Query Parameters

Parameter	Type	Required	Description
`as_of_date`	date	❌	Summary date (default: today)

Example Request

curl http://localhost:8000/api/v1/positions/summary

Response

{
  "as_of_date": "2024-01-15",
  "base_currency": "USD",
  "position_count": 8,
  "total_market_value": 125000.00,
  "total_cost_basis": 120000.00,
  "total_unrealized_pnl": 5000.00,
  "total_realized_pnl": 2500.00,
  "total_pnl": 7500.00,
  "return_pct": 6.25
}

Response Fields

Field	Description
`position_count`	Number of active positions
`total_market_value`	Sum of all position market values
`total_cost_basis`	Sum of all position cost bases
`total_unrealized_pnl`	Sum of unrealized P&L
`total_realized_pnl`	Sum of realized P&L from closed trades
`total_pnl`	Total P&L (realized + unrealized)
`return_pct`	Percentage return on cost basis

Get PnL Summary

Retrieve profit and loss summary with period comparisons.

GET /api/v1/positions/pnl/summary

Query Parameters

Parameter	Type	Required	Description
`as_of_date`	date	❌	PnL date (default: today)

Example Request

curl http://localhost:8000/api/v1/positions/pnl/summary

Response

{
  "as_of_date": "2024-01-15",
  "base_currency": "USD",
  "portfolio_value": 125000.00,
  "total_pnl": 7500.00,
  "total_unrealized_pnl": 5000.00,
  "total_realized_pnl": 2500.00,
  "daily_pnl": 450.00,
  "mtd_pnl": 3200.00,
  "ytd_pnl": 7500.00,
  "return_pct": 6.25
}

Response Fields

Field	Description
`portfolio_value`	Current portfolio market value
`daily_pnl`	Today's P&L change
`mtd_pnl`	Month-to-date P&L
`ytd_pnl`	Year-to-date P&L
`return_pct`	Total return percentage

Get Daily PnL

Retrieve daily PnL breakdown over a date range.

GET /api/v1/positions/pnl/daily

Query Parameters

Parameter	Type	Required	Description
`start_date`	date	❌	Start date (default: 30 days ago)
`end_date`	date	❌	End date (default: today)

Example Request

curl "http://localhost:8000/api/v1/positions/pnl/daily?start_date=2024-01-01&end_date=2024-01-15"

Response

{
  "daily_pnl": [
    {
      "date": "2024-01-01",
      "total_pnl": 250.00,
      "unrealized_pnl": 200.00,
      "realized_pnl": 50.00,
      "cumulative_pnl": 250.00,
      "portfolio_value": 120250.00
    },
    {
      "date": "2024-01-02",
      "total_pnl": 175.00,
      "unrealized_pnl": 175.00,
      "realized_pnl": 0.00,
      "cumulative_pnl": 425.00,
      "portfolio_value": 120425.00
    }
  ],
  "start_date": "2024-01-01",
  "end_date": "2024-01-15",
  "total_return": 7500.00,
  "return_pct": 6.25
}

Get PnL Attribution

Retrieve PnL breakdown by instrument showing top gainers and losers.

GET /api/v1/positions/pnl/attribution

Query Parameters

Parameter	Type	Required	Description
`pnl_date`	date	❌	Attribution date (default: today)
`top_n`	integer	❌	Number of top gainers/losers (default: 10)

Example Request

curl http://localhost:8000/api/v1/positions/pnl/attribution

Response

{
  "date": "2024-01-15",
  "total_pnl": 7500.00,
  "top_gainers": [
    {
      "symbol": "BTC-USD",
      "name": "Bitcoin",
      "pnl": 2500.00,
      "pnl_pct": 12.5,
      "contribution_pct": 33.33
    },
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "pnl": 1800.00,
      "pnl_pct": 5.2,
      "contribution_pct": 24.00
    }
  ],
  "top_losers": [
    {
      "symbol": "TSLA",
      "name": "Tesla Inc.",
      "pnl": -350.00,
      "pnl_pct": -2.1,
      "contribution_pct": -4.67
    }
  ],
  "gainer_count": 6,
  "loser_count": 2
}

Response Fields

Field	Description
`top_gainers`	Instruments with highest positive P&L
`top_losers`	Instruments with negative P&L
`pnl`	Absolute P&L amount
`pnl_pct`	P&L as percentage of position
`contribution_pct`	Contribution to total portfolio P&L
`gainer_count`	Total number of positions with gains
`loser_count`	Total number of positions with losses

Response Schemas

PositionResponse

{
  "instrument_id": "integer",
  "symbol": "string",
  "name": "string | null",
  "asset_class": "EQUITY | FX | CRYPTO | BOND | DERIVATIVE",
  "quantity": "number",
  "avg_cost": "number",
  "current_price": "number | null",
  "cost_basis": "number | null",
  "market_value": "number | null",
  "unrealized_pnl": "number | null",
  "unrealized_pnl_pct": "number | null",
  "realized_pnl": "number | null",
  "position_currency": "string",
  "as_of_date": "string (YYYY-MM-DD)"
}

PortfolioSummaryResponse

{
  "as_of_date": "string (YYYY-MM-DD)",
  "base_currency": "string",
  "position_count": "integer",
  "total_market_value": "number",
  "total_cost_basis": "number",
  "total_unrealized_pnl": "number",
  "total_realized_pnl": "number",
  "total_pnl": "number",
  "return_pct": "number"
}

PnLSummaryResponse

{
  "as_of_date": "string (YYYY-MM-DD)",
  "base_currency": "string",
  "portfolio_value": "number",
  "total_pnl": "number",
  "total_unrealized_pnl": "number",
  "total_realized_pnl": "number",
  "daily_pnl": "number",
  "mtd_pnl": "number",
  "ytd_pnl": "number",
  "return_pct": "number"
}

Python Example

import requests
from datetime import date, timedelta

API_BASE = "http://localhost:8000/api/v1"

# Get current positions
positions = requests.get(f"{API_BASE}/positions").json()
print(f"Portfolio has {len(positions['positions'])} positions")

for pos in positions['positions']:
    print(f"  {pos['symbol']}: {pos['quantity']} @ ${pos['current_price']}")
    print(f"    Unrealized P&L: ${pos['unrealized_pnl']:.2f} ({pos['unrealized_pnl_pct']:.2f}%)")

# Get portfolio summary
summary = requests.get(f"{API_BASE}/positions/summary").json()
print(f"\nTotal Portfolio Value: ${summary['total_market_value']:,.2f}")
print(f"Total P&L: ${summary['total_pnl']:,.2f} ({summary['return_pct']:.2f}%)")

# Get PnL attribution
attribution = requests.get(f"{API_BASE}/positions/pnl/attribution").json()
print("\nTop Gainers:")
for gainer in attribution['top_gainers'][:3]:
    print(f"  {gainer['symbol']}: +${gainer['pnl']:,.2f}")

# Get daily PnL for the month
today = date.today()
start = today.replace(day=1)
daily = requests.get(
    f"{API_BASE}/positions/pnl/daily",
    params={"start_date": start.isoformat(), "end_date": today.isoformat()}
).json()

print(f"\nMTD Return: ${daily['total_return']:,.2f}")

Notes

FIFO Cost Basis: Position cost basis is calculated using First-In-First-Out (FIFO) method.
Mark-to-Market: Unrealized P&L is calculated using the latest available market price.
Multi-Currency: All values are converted to the base currency (default: USD) for aggregation.
Historical Data: Use the as_of_date parameter to view historical positions and P&L.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Position & PnL API

Endpoints

Get Positions

Query Parameters

Example Request

Response

Get Portfolio Summary

Query Parameters

Example Request

Response

Response Fields

Get PnL Summary

Query Parameters

Example Request

Response

Response Fields

Get Daily PnL

Query Parameters

Example Request

Response

Get PnL Attribution

Query Parameters

Example Request

Response

Response Fields

Response Schemas

PositionResponse

PortfolioSummaryResponse

PnLSummaryResponse

Python Example

Notes

FilesExpand file tree

positions.md

Latest commit

History

positions.md

File metadata and controls

Position & PnL API

Endpoints

Get Positions

Query Parameters

Example Request

Response

Get Portfolio Summary

Query Parameters

Example Request

Response

Response Fields

Get PnL Summary

Query Parameters

Example Request

Response

Response Fields

Get Daily PnL

Query Parameters

Example Request

Response

Get PnL Attribution

Query Parameters

Example Request

Response

Response Fields

Response Schemas

PositionResponse

PortfolioSummaryResponse

PnLSummaryResponse

Python Example

Notes