Skip to main content
An agent’s inventory is its Position Hold: the positions its executors ended without closing. The Hummingbot API keeps it separately from the exchange balances, so several agents can trade the same pair on the same account and each still has its own position, breakeven price and P&L.

What goes into the Position Hold

Only executors that end with close type POSITION_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_price with keep_position: true in its config;
  • an LP executor that closed with keep_position true, or whose close kept failing.
An executor that closes its own position (a take profit or stop loss, for example) reports its P&L itself and adds nothing here. For the rules per executor, see Position Handover.

How positions are keyed

Each position is identified by four values:
In an agent session, 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:
The matched amount is then removed from both sides, so only the open position is left, and the breakeven prices always describe that open position. For the open position:
realized_pnl_quote and unrealized_pnl_quote don’t include fees. Fees are kept in cum_fees_quote.

Example

Reading the inventory

From Condor, use list_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:
The single-position route defaults to 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.