Skip to main content

Core Concepts

This section defines the key concepts you’ll see throughout the SDK and hub APIs, with special focus on automation concerns: idempotency, async preparation jobs, replay, and streaming semantics.

SignalR Hubs​

The SDK maps 1:1 to the MesoLive SignalR hubs:

  • Control Hub -> MesoLiveControlHub (/hubs/control/v1):
    request/response APIs for managing strategies, positions, and orders
  • Data Hub -> MesoLiveDataHub (/hubs/data/v1):
    snapshots and server-streaming market/portfolio data
  • Event Hub -> MesoLiveEventHub (/hubs/event/v1):
    server→client callbacks (signals, order/position updates, job completion) + history/replay APIs

In most automation clients:

  • Use Event Hub to react to signals (Entry, Exit, Adjustment, Error, etc.) and state changes.
  • Use Control Hub to prepare/execute entries/exits/adjustments.
  • Use Data Hub to continuously monitor marks/greeks/PnL (best-effort streaming) and to resync via snapshots.

Domain model​

At a high level:

  • Strategy: a live strategy definition, optionally active on one or more broker accounts.
  • Position: a live instance created by entering a strategy (contains legs and state).
  • Leg: one instrument (option/underlying) within a position, with quantity and lifecycle state.
  • Leg group: a set of legs that are executed together as one order group (used by SendOrder).
  • Execution plan (ExecPlan): a server-created plan that ties together “what to execute” (leg groups, quantities, operation).

Automation typically follows this pattern:

  1. Listen for signals on Event Hub (e.g. OnEntrySignal, OnExitSignal, OnAdjustmentSignal)
  2. Prepare a change (entry/exit/adjustment) → server creates an ExecPlan
  3. Execute it:
    • paper account: ApplyPaperFills
    • live broker: SendOrder (usually per leg group)
  4. Track progress via Event Hub updates and/or poll control APIs

Alternatively, the "Listen for signals" step can be replaced with user input or other external triggers, but the prepare → execute pattern remains the same.

SDK data types​

The SDK ships dataclass models under mesolive_sdk.models:

  • Fields are generally PascalCase to match the server payloads.
  • Numeric monetary values are decoded as decimal.Decimal for precision.
  • Datetimes are decoded from ISO strings into datetime.datetime (UTC timestamps are common).
  • Some enum types are open: unknown values are preserved as raw strings to avoid breaking older clients when the server adds new values.
  • Some numeric ids (notably event sequence ids) may be represented as strings in JSON; the SDK decodes them into Python int.

Errors and status codes​

There are two broad classes of failures:

  • MesoLiveApiException: the hub returned a structured MesoLiveApiResponse with Status != Success
  • MesoLiveSignalRError: transport/protocol issues (SignalR errors, stream cancellation, unexpected payload shapes)
note

The SDK treats any non-Success StatusCode as an exception, including DuplicateRequest and Conflict. For idempotent operations, handle these explicitly (see below).

Idempotency​

Several Control Hub operations are idempotent and require a client-provided IdempotencyKey (max length: 128). The server uses it to:

  • de-duplicate retries (safe retry)
  • prevent accidental double-submits
  • allow “unknown outcome” recovery via GetIdempotencyRecord

Idempotency key​

An idempotency key is scoped to:

  • the operation type (e.g. SendOrder vs ApplyPaperFills)
  • the request hash (the server checks the key is not reused with different parameters)
  • sometimes the execution plan id (for operations tied to an ExecPlanId)

If you reuse a key with different parameters, the server will reject it (typically Conflict).

  • Generate a new key for every “intent” (one human or one strategy decision).
  • Persist the key in your automation state so you can safely retry after restarts.
  • If you get a timeout / disconnect and don’t know whether an operation succeeded, use:
    • GetIdempotencyRecord(IdempotencyKey=...) to discover the outcome
    • Event replay (Event Hub) to catch up on state changes

Asynchronous preparation jobs​

Preparation is asynchronous for entry/exit/adjustment:

  • StartPreparePositionEntry → returns a JobId
  • GetPreparePositionEntryStatus(JobId=...) → returns Pending | Running | Completed | Failed | Cancelled and (on completion) a result payload with an ExecPlanId

You can observe completion in two ways:

  • Polling the status endpoint (simple, reliable)
  • Subscribing to Event Hub callbacks like OnPositionEntryPreparationCompleted (reactive, near real-time)

Cancellation is best-effort: CancelPrepare... may fail if the job already completed.

Data Hub Streaming​

Data Hub streams are optimized for “latest value” monitoring:

  • Server coalesces high-frequency updates into a small time window.
  • Both server and SDK use bounded queues; if your consumer is slow, older updates may be dropped.

Design your monitoring loop so it can tolerate missed ticks:

  • treat streams as level-triggered (“current state”), not edge-triggered (“every tick”)
  • periodically refresh with snapshots (Get*Snapshot) if you need hard resync