Skip to main content

MesoLive Control Hub

Use MesoLiveControlHubClient to manage agents, accounts, strategies, positions, and orders, and to execute the prepare → execute lifecycle for entries, exits, and adjustments.

Runnable examples​

The mesolive-sdk-examples package provides ready-to-run Control Hub examples:

python -m mesolive_sdk_examples.agents_example --help
python -m mesolive_sdk_examples.accounts_example --help
python -m mesolive_sdk_examples.strategies_example --help
python -m mesolive_sdk_examples.positions_example --help
python -m mesolive_sdk_examples.trade_e2e_example --help

Agents and accounts​

Automation should usually begin by validating connectivity and picking an account.

List connected agents​

python -m mesolive_sdk_examples.agents_example list

Each AgentInfo reports which provider/connector is currently connected and (when available) when it last produced a snapshot.

List accounts​

python -m mesolive_sdk_examples.accounts_example list --limit 50

If ContinuationToken is returned, pass it back to fetch the next page. Treat the token as opaque.

Get a single account​

python -m mesolive_sdk_examples.accounts_example get --account ML1234

Strategy lifecycle​

Strategies are the root object for trade automation. A strategy must typically be active on the target broker account in order to trigger entry events on that account.

List / get​

python -m mesolive_sdk_examples.strategies_example list --limit 50
python -m mesolive_sdk_examples.strategies_example get --strategy-id 123

Create / update / rename / delete​

These endpoints expect a StrategyDefinition payload (JSON-like dict).

python -m mesolive_sdk_examples.strategies_example create --clone-strategy-id 123 --active-on-account ML1234
python -m mesolive_sdk_examples.strategies_example create --definition-file ./strategy.json --backtest-id BT-123 --mesosim-instance mesosim-1 --active-on-account ML1234
python -m mesolive_sdk_examples.strategies_example update --strategy-id 123 --definition-file ./strategy.json
python -m mesolive_sdk_examples.strategies_example rename --strategy-id 123 --name "My live strategy"
python -m mesolive_sdk_examples.strategies_example delete --strategy-id 123 --force

Positions and legs​

Typical read operations:

  • list_positions(ListPositionsArgs) (filter by BrokerAccountId, LiveStrategyId, or LiveExecPlanId)
  • get_position(GetPositionArgs) (detailed position view)
  • list_legs(ListLegsArgs), get_leg(GetLegArgs), get_legs(GetLegsArgs)

These are useful for reconciliation after execution and for building monitoring views.

Entry: Prepare and Execute​

Entry is a two-phase workflow:

  1. Prepare: server selects contracts, evaluates conditions, builds an execution plan (ExecPlanId)
  2. Execute: paper fills or live broker orders

For a full runnable flow, see Workflows: Entry.

Runnable flow​

python -m mesolive_sdk_examples.positions_example create --strategy-id 123
python -m mesolive_sdk_examples.positions_example create --strategy-id 123 --execute --paper-fill-price mid

Terminal preparation states are Completed, Failed, Cancelled. On completion, the prepare result contains an ExecPlanId plus selected legs, leg groups, and price/greeks snapshots used during preparation.

Polling vs event-driven

You can poll GetPrepare...Status or listen for Event Hub callbacks such as OnPositionEntryPreparationCompleted / OnPositionEntryPreparationFailed. Polling is simpler; events are more responsive.

Execute: paper vs live​

If the target account is a MesoLive paper account, execute via ApplyPaperFills. Otherwise, execute via SendOrder (usually per leg group).

warning

SendOrder can place real orders on live broker accounts. Always add explicit environment gates in your automation (paper-only mode by default, allow-live flag, allowlist of accounts, etc.).

Orders and executions​

SendOrder​

SendOrder requires an IdempotencyKey. The server also validates idempotency keys against request hashes and operation type.

IBKR / TWS “Transmit”

When using the SDK/API, SendOrder submits live orders via the broker connector and transmits them for execution (no manual TWS “Transmit” click is required).

Common execution pattern:

  1. Iterate prepared.LegGroups (group id → leg name list)
  2. Build a LegGroupOrder (Market/Limit/Stop/StopLimit)
  3. Call SendOrder per group

See positions_example create/exit/adjust --execute for end-to-end execution (including paper fills vs live orders).

Operational notes worth handling in automation:

  • DuplicateRequest / Conflict: safe retry signals from the idempotency system (see “Idempotency and recovery” below).
  • IBKR placement pending: some broker connectors may acknowledge placement without a broker order id yet (e.g. timeouts). Treat a LiveOrderId as the primary handle and monitor OnOrderUpdate events for reconciliation.
  • Marker-only groups: some groups are administered locally (e.g., zero-qty “marker” legs). These may behave like an immediate fill.

ApplyPaperFills​

Use for MesoLive paper accounts. The PaperLegFills dictionary is keyed by leg name.

python -m mesolive_sdk_examples.positions_example create --strategy-id 123 --execute --paper-fill-price mid

CancelOrder​

CancelOrder(IdempotencyKey, LiveOrderId)

If the order is already cancelled, the call succeeds. If the order is already filled, cancellation is rejected.

Query order and execution state​

  • get_order(GetOrderArgs)
  • list_orders(ListOrdersArgs(ExecPlanId=...))
  • list_executions(ListExecutionsArgs(...)), get_execution, get_executions

Idempotency and recovery​

For idempotent operations (orders, paper fills, cancellations), “unknown outcome” is a normal failure mode (client timeout, disconnect, process crash).

Use GetIdempotencyRecord to recover:

record = await control.get_idempotency_record(models.GetIdempotencyRecordArgs(IdempotencyKey=key))
print(record.Status, record.Operation, record.ResponseStatus, record.ResponseMessage)

The record can contain:

  • whether the operation is still Processing or has Completed/Failed
  • captured response status/message/error (when available)
  • associated order ids / exec plan ids (when applicable)

Combine idempotency records with Event Hub replay (sequence ids) for robust restart behavior. See Workflows: Reliability.

References​