Skip to main content

SignalR Reference: Control Hub

Control Hub: APIs for managing strategies, positions, and orders.

  • Hub URL: /hubs/control/v2

All request/response methods return an API envelope (MesoLiveApiResponse<T>).

Envelope fields: MesoLiveApiResponse

2.0 breaking change

Prepared execution uses ExecPlanLegRef and ExecPlanLegId for order and paper-fill identity. LegGroupOrder.LegNames was replaced by LegGroupOrder.ExecPlanLegIds; ApplyPaperFillsArgs.PaperLegFills is now a list of PaperLegFill values.

GetIdempotencyRecord

Retrieve the idempotency record for a previously submitted idempotent operation.

Args model: GetIdempotencyRecordArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoIdempotency key used for an idempotent operation (e.g. SendOrder, ApplyPaperFills, CancelOrder).

Returns (payload): IdempotencyRecord

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoIdempotency key used to de-duplicate requests and enable safe retries.
OperationIdempotencyOperationYesNoOperation type associated with this key.
StatusIdempotencyRecordStatusYesNoProcessing state for this operation.
CreatedAtdatetimeYesNoUTC timestamp when the record was created.
UpdatedAtdatetimeYesNoUTC timestamp when the record was last updated.
RequestHashstrNoYesOptional hash of the original request payload (for diagnostics).
LiveExecPlanIdintNoYesOptional live execution plan id associated with the operation (if applicable).
LiveOrderIdslist[int]NoYesOptional live order ids created/affected by the operation (if applicable).
ErrorMessagestrNoYesError message for failed operations (if available).
JobIdstrNoYesJob id for asynchronous operations (if applicable).
JobStatusPreparationStatusNoYesJob status for asynchronous operations (if applicable).
JobResultJsonElementNoYesRaw job result payload for asynchronous operations (if applicable).
JobErrorMessagestrNoYesRaw job error message for asynchronous operations (if applicable).
ResponseStatusStatusCodeNoYesResponse status code returned by the original API call (if captured).
ResponseMessagestrNoYesResponse message returned by the original API call (if captured).
ResponseErrorMesoLiveApiErrorNoYesResponse error details returned by the original API call (if captured).
ResponseDatastrNoYesRaw response data returned by the original API call (if captured).

ListAgents

List currently connected agent instances (per provider/connector).

Args model: ListAgentsArgs

No fields.

Returns (payload): ListAgentsResult

FieldTypeRequiredNullableDefaultDescription
Agentslist[AgentInfo]YesNoConnected agents.

ListAccounts

List brokerage accounts linked to the authenticated user.

Args model: ListAccountsArgs

FieldTypeRequiredNullableDefaultDescription
BrokerTypeFilterBrokerTypeNoYesOptional filter by broker type. null = all brokerages.
LimitintNoYesMaximum number of items to return. The server may cap this value.
ContinuationTokenstrNoYesPagination token returned by a previous ListAccounts call.

Returns (payload): ListAccountsResult

FieldTypeRequiredNullableDefaultDescription
Accountslist[LiveAccount]YesNoAccounts returned by this page.
ContinuationTokenstrNoYesPagination token for the next page. null/empty when no more items are available.

GetAccount

Get a single brokerage account by broker account id.

Args model: GetAccountArgs

FieldTypeRequiredNullableDefaultDescription
BrokerAccountIdstrNoNoBroker account id to retrieve.

Returns (payload): GetAccountResult

FieldTypeRequiredNullableDefaultDescription
AccountLiveAccountYesNoAccount details.

CreateStrategy

Create a new live strategy from a Strategy Definition.

Args model: CreateStrategyArgs

FieldTypeRequiredNullableDefaultDescription
NamestrYesNoUser-facing strategy name.
DescriptionstrYesNoUser-facing strategy description.
BacktestIdstrYesNoBacktest identifier used for traceability (as produced by MesoSim tooling).
MesoSimInstancestrYesNoMesoSim instance identifier where the strategy definition originated.
StrategyDefinitiondict[str, Any]YesNoStrategy Definition payload.
ActiveOnAccountslist[str]YesNoBroker account ids where this strategy should be active/enabled.

Returns (payload): CreateStrategyResult

FieldTypeRequiredNullableDefaultDescription
StrategyIdintNoNoLive strategy id created by the server.

UpdateStrategy

Update an existing live strategy definition and its activation settings.

Args model: UpdateStrategyArgs

FieldTypeRequiredNullableDefaultDescription
StrategyIdintYesNoLive strategy id to update.
DescriptionstrNoYesOptional updated user-facing strategy description. When null, the existing description is preserved.
BacktestIdstrNoYesOptional updated backtest identifier used for traceability (as produced by MesoSim tooling). When null, the existing BacktestId is preserved. Must be provided together with MesoSimInstance when updating.
MesoSimInstancestrNoYesOptional updated MesoSim instance identifier where the strategy definition originated. When null, the existing MesoSimInstance is preserved. Must be provided together with BacktestId when updating.
StrategyDefinitiondict[str, Any]YesNoUpdated strategy definition payload.
ActiveOnAccountslist[str]YesNoBroker account ids where this strategy should be active/enabled.

Returns (payload): UpdateStrategyResult

No fields.

RenameStrategy

Rename an existing live strategy.

Args model: RenameStrategyArgs

FieldTypeRequiredNullableDefaultDescription
StrategyIdintYesNoLive strategy id to rename.
NamestrYesNoNew user-facing strategy name.

Returns (payload): RenameStrategyResult

FieldTypeRequiredNullableDefaultDescription
SuccessboolNoNoWhether the rename operation succeeded.

DeleteStrategy

Delete an existing live strategy.

Args model: DeleteStrategyArgs

FieldTypeRequiredNullableDefaultDescription
StrategyIdintYesNoLive strategy id to delete.

Returns (payload): DeleteStrategyResult

FieldTypeRequiredNullableDefaultDescription
SuccessboolNoNoWhether the delete operation succeeded.

ListStrategies

List strategies accessible to the authenticated user.

Args model: ListStrategiesArgs

FieldTypeRequiredNullableDefaultDescription
LimitintNoYesMaximum number of items to return. The server may cap this value.
ContinuationTokenstrNoYesPagination token returned by a previous ListStrategies call.
ActiveOnAccountslist[str]NoYesOptional filter: only strategies active on any of these broker account ids.

Returns (payload): ListStrategiesResult

FieldTypeRequiredNullableDefaultDescription
Strategieslist[LiveStrategy]YesNoStrategies returned by this page.
ContinuationTokenstrNoYesPagination token for the next page. null/empty when no more items are available.

GetStrategy

Get a single strategy by strategy id.

Args model: GetStrategyArgs

FieldTypeRequiredNullableDefaultDescription
StrategyIdintYesNoLive strategy id to retrieve.

Returns (payload): GetStrategyResult

FieldTypeRequiredNullableDefaultDescription
StrategyLiveStrategyYesNoStrategy details.

ListPositions

List live positions.

Args model: ListPositionsArgs

FieldTypeRequiredNullableDefaultDescription
KindLivePositionKindFilterNoNoLivePositionKindFilter.StrategyOrExecutionPlanWhich position namespace to query.
LiveStrategyIdintNoYesOptional filter by live strategy id.
LiveExecPlanIdintNoYesOptional filter by live execution plan id.
BrokerAccountIdstrNoYesOptional filter by broker account id.
UnderlyingContractIdintNoYesOptional filter by underlying live contract id.
StateLivePositionStateNoYesOptional filter by live position state.
LimitintNoYesMaximum number of items to return. The server may cap this value.
ContinuationTokenstrNoYesPagination token returned by a previous ListPositions call.

Returns (payload): ListPositionsResult

FieldTypeRequiredNullableDefaultDescription
Positionslist[LivePosition]NoNoPositions returned by this page.
ContinuationTokenstrNoYesPagination token for the next page. null/empty when no more items are available.

StartPreparePositionEntry

Start an asynchronous "prepare entry" job for entering a new position. Matches the Build Position functionality of the UI.

Args model: PreparePositionEntryArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
PositionNamestrYesNoUser-facing name for the new position to be created.
StrategyIdintYesNoLive strategy id to enter.
BrokerAccountIdstrYesNoTarget broker account id to enter the position on.
LegSelectionConstraintLiveLegSelectionConstraintYesNoConstraint for how option legs may be selected (uniqueness rules).
UnderlyingLiveUnderlyingYesNoUnderlying used as the basis for leg selection and quoting.
DataProviderDataProviderTypeYesYesOptional override for which market data provider to use. null = server default.

Returns (payload): StartPreparePositionEntryResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id identifying the asynchronous preparation.

GetPreparePositionEntryStatus

Get status and (if completed) the result of a "prepare entry" job.

Args model: GetPreparePositionEntryStatusArgs

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id returned by StartPreparePositionEntry.

Returns (payload): GetPreparePositionEntryStatusResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoPreparation job id.
StatusPreparationStatusYesNoCurrent preparation status.
ResultPreparePositionEntryResultNoYesCompleted preparation result; null until the job succeeds.
ErrorstrNoYesFailure message when the job failed; otherwise null.
CreatedAtdatetimeYesNoUTC time when the job was created.
UpdatedAtdatetimeYesNoUTC time when the job was last updated.

CancelPreparePositionEntry

Cancel an in-progress "prepare entry" job.

Args model: CancelPreparePositionEntryArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
JobIdstrYesNoJob id returned by StartPreparePositionEntry.

Returns (payload): CancelPreparePositionEntryResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id.
CancelledboolYesNoWhether the job was cancelled.

StartPreparePositionExit

Start an asynchronous "prepare exit" job for exiting an existing position. Matches the Liquidate functionality of the UI.

Args model: PreparePositionExitArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
PositionIdintYesNoLive position id to exit.

Returns (payload): StartPreparePositionExitResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id identifying the asynchronous preparation.

GetPreparePositionExitStatus

Get status and (if completed) the result of a "prepare exit" job.

Args model: GetPreparePositionExitStatusArgs

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id returned by StartPreparePositionExit.

Returns (payload): GetPreparePositionExitStatusResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoPreparation job id.
StatusPreparationStatusYesNoCurrent preparation status.
ResultPreparePositionExitResultNoYesCompleted preparation result; null until the job succeeds.
ErrorstrNoYesFailure message when the job failed; otherwise null.
CreatedAtdatetimeYesNoUTC time when the job was created.
UpdatedAtdatetimeYesNoUTC time when the job was last updated.

CancelPreparePositionExit

Cancel an in-progress "prepare exit" job.

Args model: CancelPreparePositionExitArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
JobIdstrYesNoJob id returned by StartPreparePositionExit.

Returns (payload): CancelPreparePositionExitResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id.
CancelledboolYesNoWhether the job was cancelled.

StartPreparePositionAdjustment

Start an asynchronous "prepare adjustment" job for adjusting an existing position.

Args model: PreparePositionAdjustmentArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
PositionIdintYesNoLive position id to adjust.
OperationPositionAdjustmentOperationYesNoAdjustment operation to prepare (e.g. remove/add legs, move a leg, or update vars).
ConditionstrYesNoCondition identifier or expression used by the server to select and validate the adjustment.
LegSelectionConstraintLiveLegSelectionConstraintNoYesOptional constraint for how option legs may be selected (uniqueness rules). null = server default.
TargetLiveLegIdslist[int]NoYesCanonical live-leg ids to target for existing-leg operations. MoveLeg and RemoveLegs require one or more open live-leg ids. AddLegs and UpdateVars ignore this value.
DataProviderDataProviderTypeNoYesOptional override for which market data provider to use. null = server default.

Returns (payload): StartPreparePositionAdjustmentResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id identifying the asynchronous preparation.

GetPreparePositionAdjustmentStatus

Get status and (if completed) the result of a "prepare adjustment" job.

Args model: GetPreparePositionAdjustmentStatusArgs

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id returned by StartPreparePositionAdjustment.

Returns (payload): GetPreparePositionAdjustmentStatusResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoPreparation job id.
StatusPreparationStatusYesNoCurrent preparation status.
ResultPreparePositionAdjustmentResultNoYesCompleted preparation result; null until the job succeeds.
ErrorstrNoYesFailure message when the job failed; otherwise null.
CreatedAtdatetimeYesNoUTC time when the job was created.
UpdatedAtdatetimeYesNoUTC time when the job was last updated.

CancelPreparePositionAdjustment

Cancel an in-progress "prepare adjustment" job.

Args model: CancelPreparePositionAdjustmentArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
JobIdstrYesNoJob id returned by StartPreparePositionAdjustment.

Returns (payload): CancelPreparePositionAdjustmentResult

FieldTypeRequiredNullableDefaultDescription
JobIdstrYesNoJob id.
CancelledboolYesNoWhether the job was cancelled.

GetPosition

Get a detailed view of a single live position (legs, leg groups, vars, quotes/greeks).

Args model: GetPositionArgs

FieldTypeRequiredNullableDefaultDescription
LivePositionIdintNoNoLive position id to retrieve.

Returns (payload): GetPositionResult

FieldTypeRequiredNullableDefaultDescription
PositionLivePositionNoNoPosition details.
Varsdict[str, Decimal]NoNoCurrent strategy/position variables (var name → value).
PositionStrategyDefinitionPositionStrategyDefinitionSnapshotNoYesPosition-specific strategy definition captured at entry time. Null for legacy/discretionary positions.
LegGreeksdict[int, LiveGreeks]NoNoPer-leg greeks keyed by live leg id.
LegPricesdict[int, LivePrices]NoNoPer-leg prices keyed by live leg id.
PositionLegsdict[int, LiveLeg]YesNoPosition legs keyed by live leg id.
LegGroupsdict[int, list[int]]YesNoLeg groups keyed by leg group id. Values are lists of live leg ids in that group.
LegGroupQtysdict[int, PositionLegGroupQtys]YesNoPer-leg-group quantities (group qty and per-leg quantities) keyed by leg group id.
LegGroupGreeksdict[int, LiveGreeks]NoNoPer-leg-group greeks keyed by leg group id.
LegGroupPricesdict[int, LivePrices]NoNoPer-leg-group prices keyed by leg group id.
PositionGreeksLiveGreeksNoNoAggregated greeks for the position.
PositionPriceLivePricesNoNoAggregated prices for the position.

ListLegs

List live legs.

Args model: ListLegsArgs

FieldTypeRequiredNullableDefaultDescription
LivePositionIdintNoYesOptional filter by live position id.
LiveStrategyIdintNoYesOptional filter by live strategy id.
LiveExecPlanIdintNoYesOptional filter by live execution plan id.
BrokerAccountIdstrNoYesOptional filter by broker account id.
IsOpenboolNoYesOptional filter by open/closed state. null = both open and closed.
LimitintNoYesMaximum number of items to return. The server may cap this value.
ContinuationTokenstrNoYesPagination token returned by a previous ListLegs call.

Returns (payload): ListLegsResult

FieldTypeRequiredNullableDefaultDescription
Legslist[LiveLeg]NoNonew()Legs returned by this page.
ContinuationTokenstrNoYesPagination token for the next page. null/empty when no more items are available.

GetLegs

Get multiple legs by leg id.

Args model: GetLegsArgs

FieldTypeRequiredNullableDefaultDescription
LegIdslist[int]YesNoLive leg ids to retrieve.

Returns (payload): GetLegsResult

FieldTypeRequiredNullableDefaultDescription
Legsdict[int, LiveLeg]YesNoLegs keyed by live leg id.
LegGreeksdict[int, LiveGreeks]NoYesOptional greeks keyed by live leg id (if available).
LegPricesdict[int, LivePrices]NoYesOptional prices keyed by live leg id (if available).

GetLeg

Get a single leg by leg id.

Args model: GetLegArgs

FieldTypeRequiredNullableDefaultDescription
LegIdintNoNoLive leg id to retrieve.

Returns (payload): GetLegResult

FieldTypeRequiredNullableDefaultDescription
LegLiveLegYesNoLeg details.
LegGreeksLiveGreeksNoYesOptional greeks snapshot for the leg (if available).
LegPricesLivePricesNoYesOptional prices snapshot for the leg (if available).

ApplyPaperFills

Apply fills to an execution plan on a paper account. Each fill identifies an execution-plan leg id. A signed quantity can partially fill the remaining planned quantity; when omitted, the remaining planned quantity is filled. All tradeable legs in a leg group that still have remaining quantity must be filled in matching ratios.

Args model: ApplyPaperFillsArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
BrokerAccountIdstrYesNoTarget paper broker account id to apply fills to.
ExecPlanIdintYesNoLive execution plan id to apply paper fills for.
QtyMultiplierDecimalYesYesQuantity multiplier for AddPosition/AddLegs paper fills. Positive and required for entry/add-leg plans; it may override the prepared multiplier only before execution starts, then must match the locked multiplier. Must be null for exits, removals, and moves.
PaperLegFillslist[PaperLegFill]YesNoPer-leg paper fills; each fill carries an explicit execution-plan leg id.

Returns (payload): ApplyPaperFillsResult

FieldTypeRequiredNullableDefaultDescription
SuccessboolYesNoWhether the paper fills were applied successfully.

GetExecutionPlanFillState

Get fill progress for an execution plan prepared through Control Hub v2.

Args model: GetExecutionPlanFillStateArgs

FieldTypeRequiredNullableDefaultDescription
ExecPlanIdintYesNoLive execution plan id.

Returns (payload): GetExecutionPlanFillStateResult

FieldTypeRequiredNullableDefaultDescription
ExecPlanIdintYesNoLive execution plan id.
IsCompleteboolYesNoTrue when all non-marker execution-plan legs are fully filled and every broker execution for the plan was attributed to an execution-plan leg.
Legslist[ExecPlanLegFillState]YesNoPer-leg fill progress.
Groupslist[LegGroupOrderState]YesNoPer-group order and fill progress.

SendOrder

Submit an order for a real (non-paper) brokerage account. The submitted leg ids must exactly match the selected execution-plan leg group. Paper-trading accounts should use ApplyPaperFills for manual paper fills.

Args model: SendOrderArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
ReplacesOrderintYesYesExisting live order id to replace; null submits a new order.
BrokerAccountIdstrYesNoBroker account id where the order should be submitted.
ExecPlanIdintYesNoLive execution plan id produced by a preparation job.
QtyMultiplierDecimalYesYesQuantity multiplier for AddPosition/AddLegs orders. Positive and required for entry/add-leg plans; it may override the prepared multiplier only before execution starts, then must match the locked multiplier. Must be null for exits, removals, and moves.
LegGroupIdintYesNoExecution-plan leg group id being ordered.
LegGroupOrderLegGroupOrderYesNoOrder parameters and execution-plan leg ids for the selected leg group.

Returns (payload): SendOrderResult

FieldTypeRequiredNullableDefaultDescription
LiveOrderIdintNoYesLive order id created/updated by the server (if available).
OrderStateOrderStateNoYesCurrent order state (if available).
RejectionOrderRejectionInfoNoYesRejection details when the order is rejected.

CancelOrder

Request cancellation of an existing live order.

Args model: CancelOrderArgs

FieldTypeRequiredNullableDefaultDescription
IdempotencyKeystrYesNoClient-provided idempotency key used to de-duplicate requests and enable safe retries.
LiveOrderIdintYesNoLive order id to cancel.

Returns (payload): CancelOrderResult

FieldTypeRequiredNullableDefaultDescription
LiveOrderIdintYesNoLive order id that was cancelled (or cancellation was requested for).

GetOrder

Get a single order by order id.

Args model: GetOrderArgs

FieldTypeRequiredNullableDefaultDescription
OrderIdintYesNoLive order id to retrieve.

Returns (payload): GetOrderResult

FieldTypeRequiredNullableDefaultDescription
OrderOrderYesNoOrder details.

ListOrders

List orders for a given execution plan.

Args model: ListOrdersArgs

FieldTypeRequiredNullableDefaultDescription
ExecPlanIdintYesNoLive execution plan id to list orders for.
LimitintNoYesMaximum number of items to return. The server may cap this value.
ContinuationTokenstrNoYesPagination token returned by a previous ListOrders call.

Returns (payload): ListOrdersResult

FieldTypeRequiredNullableDefaultDescription
Orderslist[Order]YesNoOrders returned by this page.
ContinuationTokenstrNoYesPagination token for the next page. null/empty when no more items are available.

ListExecutions

List executions.

Args model: ListExecutionsArgs

FieldTypeRequiredNullableDefaultDescription
LiveLegIdintNoYesOptional filter by live leg id.
LivePositionIdintNoYesOptional filter by live position id.
LiveStrategyIdintNoYesOptional filter by live strategy id.
LiveExecPlanIdintNoYesOptional filter by live execution plan id.
BrokerAccountIdstrNoYesOptional filter by broker account id.
LimitintNoYesMaximum number of items to return. The server may cap this value.
ContinuationTokenstrNoYesPagination token returned by a previous ListExecutions call.

Returns (payload): ListExecutionsResult

FieldTypeRequiredNullableDefaultDescription
Executionslist[LiveExecution]YesNoExecutions returned by this page.
ContinuationTokenstrNoYesPagination token for the next page. null/empty when no more items are available.

GetExecution

Get a single execution by execution id.

Args model: GetExecutionArgs

FieldTypeRequiredNullableDefaultDescription
ExecutionIdintYesNoLive execution id to retrieve.

Returns (payload): GetExecutionResult

FieldTypeRequiredNullableDefaultDescription
ExecutionLiveExecutionYesNoExecution details.

GetExecutions

Get multiple executions by execution ids.

Args model: GetExecutionsArgs

FieldTypeRequiredNullableDefaultDescription
ExecutionIdslist[int]YesNoLive execution ids to retrieve.

Returns (payload): GetExecutionsResult

FieldTypeRequiredNullableDefaultDescription
Executionsdict[int, LiveExecution]YesNoExecutions keyed by live execution id.