controller_id, the tag that owns it. The default is main. In a Condor agent session, it is the session ID, such as my_agent.my_loop_3, so every executor can be traced to the run that opened it. See Session IDs.
Executors and Condor agents
Condor agents trade through executors. The agent decides once per tick; the executor handles orders and exits between ticks. In an agent session, the risk gate binds executors to the session:- An executor create must carry the session’s ID as
controller_id, or it is refused. stop_executoris refused on an executor that belongs to another session.- Each tick shows the agent only this session’s executors and held positions.
list_executors is not limited this way: without a controller_ids filter, it lists every executor on the server. See Risk engine.
Executor types
Condor can create only five executor types: order, position, grid, DCA and LP. TWAP, XEMM and arbitrage executors have no Condor tool, so agents and the Condor chat can’t open them. Create those through the Hummingbot API with
POST /executors/.Creating executors from Condor
Each creatable type has its own tool. The parameters are flat and typed, and enums are numbers:
Every create tool also takes
account_name (default master_account), controller_id (default main) and save_as_default.
Before Condor sends a create, it runs two checks:
- Exchange minimums. It reads the market’s trading rules and refuses an order below the minimum order size or minimum order value, saying what the minimum is.
- Balance, spot only. It refuses a spot executor the account visibly can’t fund, after re-reading balances to rule out a stale cache. Perpetuals are left to the executor’s own start-up check.
INSUFFICIENT_BALANCE or FAILED, the tool reports an error and says nothing was opened. Otherwise it reports how much has filled. “Nothing filled yet” means the entry isn’t confirmed: check with get_executor before treating the position as open.
Saved defaults
Condor keeps your default settings per executor type in~/.hummingbot_mcp/executor_preferences.md, on the machine that runs Condor’s Hummingbot MCP server. Every create merges these defaults under the arguments you pass: they fill in what you left out and never override what you set. A create with save_as_default=true saves its arguments there.
Read and change the file with the executor_defaults tool: get returns it, save replaces it, and reset restores the template but keeps the values already saved.
Lifecycle
When an executor starts, it checks the account can fund it. If not, it terminates at once with
INSUFFICIENT_BALANCE.
Executors run in the Hummingbot API’s memory. If the API restarts, executors that were running don’t resume: they are recorded as TERMINATED with close type SYSTEM_CLEANUP.
Close types
A filled order executor always ends as
POSITION_HOLD, never COMPLETED.
Stopping an executor
Stop an executor with thestop_executor tool or POST /executors/{executor_id}/stop. Both take keep_position, default false:
false: cancel open orders and close what the executor holds, where the type supports it.true: cancel open orders and keep the position. The executor ends asPOSITION_HOLD.
keep_position is also a config field on the grid and LP executors, where it decides what happens when the executor closes itself. Everywhere else it exists only as a stop parameter. See Position Handover.
Via the API
List one session’s running executors:
What every executor reports
An order executor reports 0 P&L: its fills are tracked in the Position Hold instead.
Learn more
- Position Handover: what happens to a kept position
- Inventory: how held positions and their P&L are tracked
- MCP Tools: the executor tools and which seats get them