Portfolio
Positions, balances, and PnL snapshots
The Portfolio API provides access to a user's trading portfolio, including open positions, order history, resolved markets, watchlist management, and performance analytics. All portfolio endpoints require authentication.
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/portfolio/summary | Bearer | Get portfolio summary with total value and PnL |
| GET | /api/v1/portfolio/positions | Bearer | Get open positions |
| POST | /api/v1/portfolio/positions/:id/close | Bearer | Close a position |
| PUT | /api/v1/portfolio/positions/:id/tp-sl | Bearer | Set take-profit/stop-loss on a position |
| GET | /api/v1/portfolio/orders | Bearer | Get order history with filters |
| GET | /api/v1/portfolio/resolved | Bearer | Get resolved positions |
| POST | /api/v1/portfolio/resolved/:id/claim | Bearer | Claim winnings from a resolved position |
| GET | /api/v1/portfolio/watchlist | Bearer | Get watchlist |
| POST | /api/v1/portfolio/watchlist | Bearer | Add a market to watchlist |
| DELETE | /api/v1/portfolio/watchlist/:marketId | Bearer | Remove a market from watchlist |
| GET | /api/v1/portfolio/pnl-calendar | Bearer | Get PnL calendar data by month |
| GET | /api/v1/portfolio/chart | Bearer | Get portfolio value chart data |
Portfolio Summary
Get an overview of the user's portfolio including total value, unrealized PnL, and balance.
// GET /api/v1/portfolio/summary
// Response 200
{
"totalValue": 1250.00,
"totalPnl": 185.50,
"totalPnlPercent": 17.4,
"openPositionCount": 8,
"availableBalance": 500.00,
"invested": 750.00
}Open Positions
Get all active (open) positions for the authenticated user.
// GET /api/v1/portfolio/positions
// Response 200
{
"positions": [
{
"id": "pos-uuid-123",
"marketId": "mkt-uuid-456",
"marketTitle": "Will the Fed cut rates in June 2026?",
"side": "yes",
"shares": 100.00,
"avgPrice": 0.55,
"currentPrice": 0.63,
"cost": 55.00,
"currentValue": 63.00,
"pnl": 8.00,
"pnlPercent": 14.55,
"takeProfit": null,
"stopLoss": null,
"source": "polymarket",
"createdAt": "2026-03-20T10:00:00.000Z"
}
]
}Order History
Get the user's past orders with optional filters.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by order status |
type | string | Filter by order type (market, limit) |
marketId | string | Filter by specific market |
// GET /api/v1/portfolio/orders?status=filled
// Response 200
{
"orders": [
{
"id": "order-uuid-789",
"marketId": "mkt-uuid-456",
"marketTitle": "Will the Fed cut rates in June 2026?",
"side": "yes",
"type": "market",
"amount": 50.00,
"price": 0.55,
"shares": 90.91,
"fee": 0.50,
"status": "filled",
"createdAt": "2026-03-20T10:00:00.000Z"
}
]
}PnL Calendar
Get daily PnL data for a given month, useful for rendering a calendar heatmap of trading performance.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
month | number | Month (1-12) |
year | number | Year |
Portfolio Chart
Get historical portfolio value over time for chart rendering.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
period | string | Time period for the chart |
Notes
- All financial values use
Decimalprecision - Positions show real-time PnL calculated from the current market price
- The watchlist allows users to bookmark markets for quick access without holding a position
- Resolved positions must be explicitly claimed to collect winnings