What goes into the Position Hold
Only executors that end with close typePOSITION_HOLD add to it. That is:
- every order executor that filled anything;
- a position or grid executor stopped with
keep_position=true; - a grid that crossed its
limit_pricewithkeep_position: truein its config; - an LP executor that closed with
keep_positiontrue, or whose close kept failing.
How positions are keyed
Each position is identified by four values:controller_id is the session ID, such as my_agent.my_loop_3 (see Session IDs). So the inventory is per session, not per agent: a new session of the same loop starts with an empty inventory, and the agent can’t see what an earlier session held.
The connector is the one the executor traded on. For an LP executor that is the network, such as solana-mainnet-beta, not the DEX.
Position fields
All amounts are in the base asset and all P&L is in the quote asset.
How P&L is calculated
Whenever a position has both buys and sells, the API matches them right away:realized_pnl_quote and unrealized_pnl_quote don’t include fees. Fees are kept in cum_fees_quote.
Example
Reading the inventory
From Condor, uselist_positions_held. Pass controller_id to see one session’s positions, and both connector_name and trading_pair for one position’s detail.
Through the API:
controller_id=main, so pass the session ID to read an agent’s position. The summary also returns total_realized_pnl and total_unrealized_pnl across the positions it lists.
A position whose buys and sells have fully matched no longer appears in these listings.
Positions are saved in the API’s database and restored when the API restarts.
Related
- Position Handover: which executors add to the inventory, and when
- Executors overview: close types and stop calls
- Sessions: why each session has its own inventory

