# Portfolio

## Get portfolio summary buckets and overall metrics

> Returns bucketed volume, open interest snapshot, win/loss trade counts, and overall metrics derived from trade history, trade history assets, and current open positions. Records marked as FULLY\_EXTERNAL are excluded. When startDate or endDate is provided, only period-scoped overall metrics are returned.

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"PortfolioResponseDto":{"type":"object","properties":{"intervals":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PortfolioIntervalsDto"}]},"overall":{"$ref":"#/components/schemas/PortfolioOverallDto"}},"required":["overall"]},"PortfolioIntervalsDto":{"type":"object","properties":{"oneDay":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBucketDto"}},"oneWeek":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBucketDto"}},"oneMonth":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBucketDto"}},"oneYear":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBucketDto"}},"all":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBucketDto"}}},"required":["oneDay","oneWeek","oneMonth","oneYear","all"]},"PortfolioBucketDto":{"type":"object","properties":{"periodStart":{"type":"string","description":"Period start ISO timestamp"},"periodEnd":{"type":"string","description":"Period end ISO timestamp"},"volume":{"type":"number","description":"Total traded volume (USD) within the bucket"},"openInterest":{"type":"number","description":"Open interest snapshot (USD). Uses current snapshot."},"winningTradesCount":{"type":"number","description":"Number of winning trades (net realized > 0) within the bucket"},"winningTradesUsd":{"type":"number","description":"Total USD from winning trades within the bucket (sum of positive net realized PnL)"},"losingTradesCount":{"type":"number","description":"Number of losing trades (net realized < 0) within the bucket"},"losingTradesUsd":{"type":"number","description":"Total USD from losing trades within the bucket (sum of absolute value of negative net realized PnL)"}},"required":["periodStart","periodEnd","volume","openInterest","winningTradesCount","winningTradesUsd","losingTradesCount","losingTradesUsd"]},"PortfolioOverallDto":{"type":"object","properties":{"totalWinningTradesCount":{"type":"number","description":"Total winning trades (net realized > 0) across the selected period"},"totalLosingTradesCount":{"type":"number","description":"Total losing trades (net realized < 0) across the selected period"},"totalWinningUsd":{"type":"number","description":"Total USD from winning trades across the selected period (sum of positive net realized PnL)"},"totalLosingUsd":{"type":"number","description":"Total USD from losing trades across the selected period (sum of absolute value of negative net realized PnL)"},"currentOpenInterest":{"type":"number","description":"Current total open interest (USD) across open positions"},"currentTotalVolume":{"type":"number","description":"Trading volume (USD) for the selected period filtered to PEAR fills"},"unrealizedPnl":{"type":"number","description":"Unrealized PnL (USD) from current open positions"},"totalTrades":{"type":"number","description":"Total trades for the selected period (open/close/reduce/increase counted as one trade each)"}},"required":["totalWinningTradesCount","totalLosingTradesCount","totalWinningUsd","totalLosingUsd","currentOpenInterest","currentTotalVolume","unrealizedPnl","totalTrades"]}}},"paths":{"/portfolio":{"get":{"description":"Returns bucketed volume, open interest snapshot, win/loss trade counts, and overall metrics derived from trade history, trade history assets, and current open positions. Records marked as FULLY_EXTERNAL are excluded. When startDate or endDate is provided, only period-scoped overall metrics are returned.","operationId":"PortfolioController_getPortfolio","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string or ms timestamp)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string or ms timestamp)","schema":{"type":"string"}}],"responses":{"200":{"description":"Portfolio data for all intervals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioResponseDto"}}}}},"summary":"Get portfolio summary buckets and overall metrics","tags":["Portfolio"]}}}}
```

## Get portfolio analytics with risk-adjusted metrics

> Returns portfolio and per-asset performance analytics including risk-adjusted metrics, rolling windows, and both realized-only and realized+unrealized variants.

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"PortfolioAnalyticsResponseDto":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/PortfolioAnalyticsConfigDto"},"portfolio":{"$ref":"#/components/schemas/PortfolioMetricsDto"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/AssetAnalyticsDto"}},"pairs":{"type":"array","items":{"$ref":"#/components/schemas/PairBreakdownDto"}},"series":{"type":"array","items":{"$ref":"#/components/schemas/SeriesPointDto"}}},"required":["config","portfolio","assets","pairs"]},"PortfolioAnalyticsConfigDto":{"type":"object","properties":{"rollingWindowDays":{"type":"number","description":"Rolling window size in days"},"startDate":{"type":"string","description":"Start date ISO string"},"endDate":{"type":"string","description":"End date ISO string"}},"required":["rollingWindowDays","startDate","endDate"]},"PortfolioMetricsDto":{"type":"object","properties":{"realizedOnly":{"description":"Metrics from closed trades only","allOf":[{"$ref":"#/components/schemas/MetricVariantDto"}]},"realizedPlusUnrealized":{"description":"Metrics including unrealized PnL from open positions","allOf":[{"$ref":"#/components/schemas/MetricVariantDto"}]},"realizedHitRate":{"type":"number","description":"Profitable closed trades / total closed trades","nullable":true},"profitFactor":{"type":"number","description":"Portfolio-level profit factor (gross profit / gross loss)","nullable":true},"avgWinSize":{"type":"number","description":"Portfolio-level average winning trade size in USD","nullable":true},"avgLossSize":{"type":"number","description":"Portfolio-level average losing trade size in USD","nullable":true},"breakevenHitRate":{"type":"number","description":"Required hit rate to break even from average win/loss sizes","nullable":true},"cushion":{"type":"number","description":"Realized hit rate minus breakeven hit rate","nullable":true}},"required":["realizedOnly","realizedPlusUnrealized","realizedHitRate","profitFactor","avgWinSize","avgLossSize","breakevenHitRate","cushion"]},"MetricVariantDto":{"type":"object","properties":{"pnlAbsolute":{"type":"number","description":"Absolute PnL in USD"},"pnlPercent":{"type":"number","description":"PnL as decimal fraction of capital base (0.12 = 12%)","nullable":true},"hitRate":{"type":"number","description":"Fraction of profitable events (0.6 = 60%)","nullable":true},"profitFactor":{"type":"number","description":"Gross profit / gross loss (absolute)","nullable":true},"avgWinSize":{"type":"number","description":"Mean positive PnL value in USD","nullable":true},"avgLossSize":{"type":"number","description":"Mean negative PnL value in USD","nullable":true},"avgReturnPerWin":{"type":"number","description":"Mean return of winning trades","nullable":true},"avgReturnPerLoss":{"type":"number","description":"Mean return of losing trades","nullable":true},"maxDrawdown":{"type":"number","description":"Maximum drawdown as decimal fraction","nullable":true},"sharpeRatio":{"type":"number","description":"Annualized Sharpe ratio (sqrt(365))","nullable":true},"sortinoRatio":{"type":"number","description":"Annualized Sortino ratio (sqrt(365))","nullable":true}},"required":["pnlAbsolute","pnlPercent","hitRate","profitFactor","avgWinSize","avgLossSize","avgReturnPerWin","avgReturnPerLoss","maxDrawdown","sharpeRatio","sortinoRatio"]},"AssetAnalyticsDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol (e.g. BTC)"},"realizedOnly":{"$ref":"#/components/schemas/MetricVariantDto"},"realizedPlusUnrealized":{"$ref":"#/components/schemas/MetricVariantDto"},"unrealizedReturnPerDay":{"type":"number","description":"Unrealized PnL / max(1, days open)","nullable":true}},"required":["asset","realizedOnly","realizedPlusUnrealized","unrealizedReturnPerDay"]},"PairBreakdownDto":{"type":"object","properties":{"key":{"type":"string","description":"Stable basket key, formatted as L:BTC,ETH|S:SOL"},"longAssets":{"description":"Long-side assets in the basket","type":"array","items":{"type":"string"}},"shortAssets":{"description":"Short-side assets in the basket","type":"array","items":{"type":"string"}},"trades":{"type":"number","description":"Closed trade count for this basket"},"wins":{"type":"number","description":"Winning closed trade count for this basket"},"losses":{"type":"number","description":"Losing closed trade count for this basket"},"hitRate":{"type":"number","description":"Winning trades / total trades","nullable":true},"avgWinSize":{"type":"number","description":"Mean positive trade PnL in USD","nullable":true},"avgLossSize":{"type":"number","description":"Mean negative trade PnL in USD","nullable":true},"expectancy":{"type":"number","description":"Average PnL per trade in USD","nullable":true},"totalPnl":{"type":"number","description":"Total realized PnL in USD for this basket"},"bookPercent":{"type":"number","description":"Basket total PnL / portfolio total realized PnL","nullable":true}},"required":["key","longAssets","shortAssets","trades","wins","losses","hitRate","avgWinSize","avgLossSize","expectancy","totalPnl","bookPercent"]},"SeriesPointDto":{"type":"object","properties":{"date":{"type":"string","description":"UTC date string (YYYY-MM-DD)"},"trades":{"type":"number","description":"Closed trades on this day"},"wins":{"type":"number","description":"Winning closed trades on this day"},"losses":{"type":"number","description":"Losing closed trades on this day"},"dayPnl":{"type":"number","description":"Realized PnL on this day in USD"},"hitRate":{"type":"number","description":"Winning trades / total trades on this day","nullable":true},"winLossRatio":{"type":"number","description":"Average winning trade size / average losing trade size on this day","nullable":true},"rollingHitRate":{"type":"number","description":"Rolling winning trades / rolling total trades","nullable":true},"rollingWinLossRatio":{"type":"number","description":"Rolling average winning trade size / rolling average losing trade size","nullable":true},"dailyReturn":{"type":"number","description":"Daily portfolio return","nullable":true},"cumulativeReturn":{"type":"number","description":"Cumulative return from start"},"equity":{"type":"number","description":"Equity value"},"drawdown":{"type":"number","description":"Current drawdown from peak"},"rollingSharpe":{"type":"number","description":"Rolling Sharpe ratio","nullable":true},"rollingSortino":{"type":"number","description":"Rolling Sortino ratio","nullable":true},"rollingVolatility":{"type":"number","description":"Rolling annualized volatility","nullable":true},"rollingFunding":{"type":"number","description":"Rolling annualized net funding rate","nullable":true}},"required":["date","trades","wins","losses","dayPnl","hitRate","winLossRatio","rollingHitRate","rollingWinLossRatio","dailyReturn","cumulativeReturn","equity","drawdown","rollingSharpe","rollingSortino","rollingVolatility","rollingFunding"]}}},"paths":{"/portfolio/analytics":{"get":{"description":"Returns portfolio and per-asset performance analytics including risk-adjusted metrics, rolling windows, and both realized-only and realized+unrealized variants.","operationId":"PortfolioController_getAnalytics","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string or ms timestamp)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string or ms timestamp)","schema":{"type":"string"}},{"name":"interval","required":false,"in":"query","description":"Display interval for date range","schema":{"enum":["1d","1w","1m","1y","all"],"type":"string"}},{"name":"rollingWindowDays","required":false,"in":"query","description":"Rolling window size in days (default 30, min 7, max 365)","schema":{"type":"number"}},{"name":"includeSeries","required":false,"in":"query","description":"Include daily/rolling time series (default true)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Portfolio analytics data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioAnalyticsResponseDto"}}}}},"summary":"Get portfolio analytics with risk-adjusted metrics","tags":["Portfolio"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pearprotocol.io/api-integration/api-specification/portfolio.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.