Get Positions

read-only · idempotent

View all active trading positions with real-time P&L.

IMPORTANT — ALWAYS warm the price cache BEFORE calling this tool. Call get_quotes (batch) or get_quote (single) to ensure unrealizedPnL is calculated from the current market bid/ask. Without a prior quote call, unrealizedPnL will be 0 and priceSource will be “unavailable” for symbols not yet in the live price cache.

Recommended workflow:

1. Call get_positions (no symbol filter) to discover open position symbols.
2. Call get_quotes with all unique symbols returned (or get_quote per symbol).
3. Call get_positions again — unrealizedPnL will now be accurate.

Returns current open positions with:

• Position ID, symbol, side (BUY/SELL)
• Volume in units, entry price, current price
• unrealizedPnL / realizedPnL: P&L in USD (converted from quote currency via QUOTE session mid-price)
• unrealizedPnLRaw / realizedPnLRaw: P&L in original quote currency
• quoteCurrency: instrument’s quote currency (e.g. “JPY”, “GBP”, “USD”)
• pnlCurrency: “USD” when converted, quote currency code when conversion unavailable
• conversionRate: multiply-to-get-USD factor (null when quote currency is USD or rate unavailable)
• priceSource: “live_quote” (accurate) | “broker” (broker-provided) | “unavailable” (no price)
• Position open time and last update time

PARAMETERS:

• symbol: Optional filter by symbol (e.g., “EURUSD”). Omit for all positions.
• refresh: When true, fetches fresh position data from the broker and waits for the current snapshot before returning. Default false (reads cached state).

WHEN TO USE refresh=true:

• You have traded directly in cTrader UI or another tool during this session
• You are unsure whether the data reflects the current broker state
• You switched context (different chat, tool restart) and the session has been running a while

When to use default (refresh=false):

• All trades in this session went through this MCP server
• You want low-latency reads without a broker round-trip

STALENESS NOTE: Local state is populated at logon by requesting positions from the broker, then updated only by trade confirmations from trades placed through this server. Trades placed in cTrader UI or other tools are NOT reflected until refresh=true is used.

RESPONSE FIELDS:

• positions: Array of position objects
• count: Number of positions returned
• filter: Symbol filter applied (“all” if none)
• refreshed: true if a live broker refresh was performed
• stale: true if refresh was requested but session was not active (fallback to cache)
• pnlNote: Present when some positions have priceSource=unavailable

This is a read-only operation with no risk checks.

Parameters

Parameter	Type	Required	Description
symbol	string	No	Optional symbol filter (e.g., ‘EURUSD’). Omit to get all positions.
refresh	boolean	No	When true, fetches fresh position data from the broker and waits for the current snapshot before returning. Use when you have traded directly in cTrader, another tool, or a different Claude chat during this session. Default false (reads from cached local state, which is sufficient when all trades went through this server). Default: false.