Profile Analysis

​

Overview

​

Endpoint

​

Query Parameters

​

Authentication

curl -H "X-API-Key: ps_live_your_key" \
  https://api.polysimulator.com/v1/account/profile-analysis

​

Response

​

profile — User Metadata

​

balance — Balance Summary

​

trading_stats — Trading Statistics

​

risk_metrics — Risk Analysis

​

How Metrics Are Calculated

​

Balance and PnL

• Total portfolio value = api_balance + total_position_value
• UI PnL = ui_balance - 1000.00
• API PnL = total_portfolio_value - 10000.00
• UI PnL % = ui_pnl / 1000.00 * 100
• API PnL % = api_pnl / 10000.00 * 100

​

Open Position Valuation

• Cost basis = avg_entry_price * quantity
• Market value = current_price * quantity (if live price exists)
• If no live price is available, cost basis is used as fallback valuation.
• Unrealized PnL (position) = market_value - cost_basis
• Unrealized PnL (account) = sum(open_position_market_values) - sum(open_position_cost_basis)

​

Realized PnL (Closed Positions)

• buy_notional = sum(BUY order notionals)
• sell_notional = sum(SELL order notionals)
• buy_qty = sum(BUY order quantities)
• sell_qty = sum(SELL order quantities)
• remaining_qty = buy_qty - sell_qty
• settlement_value = exit_price * remaining_qty
• position_realized_pnl = sell_notional + settlement_value - buy_notional

• realized_pnl = sum(position_realized_pnl over closed positions)

​

Win Rate and Win/Loss Counts

• Win: position_realized_pnl > 0
• Loss: position_realized_pnl < 0
• Break-even: position_realized_pnl == 0 (excluded from win/loss counts)

• win_rate = wins / total_closed_positions * 100

​

Profit Factor and Trade PnL Stats

• Gross profit = sum(all positive position_realized_pnl)
• Gross loss = sum(abs(all negative position_realized_pnl))
• profit_factor = gross_profit / gross_loss (when gross_loss > 0)
• best_trade_pnl = max positive closed-position PnL
• worst_trade_pnl = min negative closed-position PnL
• avg_win_pnl = average of positive closed-position PnLs
• avg_loss_pnl = average of negative closed-position PnLs

​

Drawdown (7d and 30d)

1. Walk snapshots in chronological order
2. Track highest value seen so far (peak)
3. Compute drawdown each point: (value - peak) / peak
4. Maximum drawdown = most negative drawdown in the period

​

Portfolio Diversity and Concentration

• Effective value = market_value (live price × quantity) when a live price exists, or cost_basis (entry price × quantity) as fallback when no live price is available.
• Weight per position: w_i = effective_value / total_invested
• HHI = sum(w_i^2)
• portfolio_diversity_score = 1 - HHI
• largest_position_weight = largest w_i
• top_3_concentration = sum of top 3 w_i

​

Equity Returns

• return_7d: first-to-last return among snapshots in last 7 days
• return_30d: first-to-last return among snapshots in last 30 days
• return_all_time: first-to-last return across the full equity_days window

• period_return = (end_value - start_value) / start_value * 100

​

Data Scope and Semantics

• open_positions contains only status=OPEN with quantity > 0
• Trading stats and realized metrics use only filled orders
• Category exposure is based on open-position values
• Cash/invested percentages are relative to current total portfolio value

​

equity_timeline — Performance Timeline

​

category_exposure — Category Breakdown

[
  { "category": "crypto", "position_count": 3, "total_value": "500.00", "weight_percentage": "45.5%" },
  { "category": "sports", "position_count": 2, "total_value": "300.00", "weight_percentage": "27.3%" }
]

​

natural_language_summary

“trader123 is a PolySimulator paper trader who joined 45 days ago. Current API balance: $9,750.00 (started at$10,000.00, P&L: -$250.00, -2.50$1,100.00. Top categories: crypto (45.5%), sports (27.3%), politics (18.2%).”

​

MCP Server

​

Available MCP Tools