Skip to main content
Executors are self-contained trading operations that manage their complete lifecycle—from entry to exit—with standardized P&L and fee reporting. Each executor is tagged with a controller_id linking it to the agent that created it.

​
Why Executors?

Executors are the heart of the Trading Agent design. Agents only act through executors, which provides:
BenefitDescription
StandardizationSame interface across 50+ exchanges
Error HandlingClear errors instead of cryptic API responses
IsolationEach agent only sees its own executors via controller_id
Frequency SeparationAgent reasons at mid-frequency; executor operates at high frequency
Position Handoverkeep_position=true retains inventory for the next tick

​
Executor Types

From simplest to most complex:
ExecutorDescriptionBuilds On
Order ExecutorPlaces and executes a single order-
Position ExecutorOrder + TP/SL/trailing stop/time limit managementOrder
Grid ExecutorMultiple Position Executors across a price rangePosition
DCA ExecutorMultiple orders at different price levelsOrder
TWAP ExecutorOrders spread over timeOrder
XEMM ExecutorCross-exchange market makingOrder
Arbitrage ExecutorCross-market arbitrageOrder
LP ExecutorConcentrated liquidity provision-

​
The Core Three

Order Executor is the simplest—it places an order using one of four execution strategies (LIMIT, LIMIT_MAKER, MARKET, LIMIT_CHASER) and terminates when filled. Position Executor builds on Order Executor by adding position management: after the entry order fills, it monitors the position and exits at take profit, stop loss, trailing stop, or time limit. Grid Executor is like running multiple Position Executors simultaneously across a price range, with each level having its own entry and take profit orders.

​
Lifecycle

All executors follow a standard lifecycle:
Close TypeDescription
TAKE_PROFITPrice reached profit target
STOP_LOSSPrice reached loss limit
TIME_LIMITMaximum duration exceeded
TRAILING_STOPTrailing stop triggered
EARLY_STOPManually stopped
COMPLETEDFinished normally (order filled)
FAILEDFailed after retries

​
Position Handover

When an executor terminates with keep_position=true:
  1. Inventory stays in the account, tagged with controller_id
  2. Agent sees it on the next tick via the positions provider
  3. Agent can manage it with a new executor (scale out, hedge, exit)
  4. P&L is not attributed until position is fully closed
Example: Grid hits stop-loss → keeps 0.005 BTC → agent waits for recovery → spawns Order Executor to exit at better price.

​
Creating Executors

​
Via MCP Tools

result = await mcp_tools.manage_executors(
    action="create",
    executor_type="position_executor",
    config={
        "connector_name": "binance_perpetual",
        "trading_pair": "SOL-USDT",
        "side": "BUY",
        "amount": 10.0,
        "triple_barrier_config": {
            "take_profit": 0.02,
            "stop_loss": 0.01,
        }
    }
)

​
Via API

# List executors
curl -u admin:admin http://localhost:8000/executors

# Filter by agent
curl -u admin:admin "http://localhost:8000/executors?controller_id=my-agent"

# Stop executor
curl -u admin:admin -X DELETE http://localhost:8000/executors/{id}

​
Standardized Metrics

All executors report:
MetricDescription
net_pnl_quoteRealized P&L in quote currency
fees_paid_quoteTrading fees, gas costs
volume_quoteTotal trading volume
close_typeHow executor terminated
duration_secondsTime from creation to termination