Should every broker map to one identical feature set?
No. Normalize shared concepts and expose capabilities or extensions for genuine differences. Pretending every broker behaves identically creates unsafe assumptions.
Trading Systems
Designing a Broker Adapter With Commands and Events
Separate internal order commands from broker-specific requests and normalize broker events without discarding source detail.
How the workflow connects
- 1Validate an internal order command
- 2Translate to broker-specific parameters
- 3Submit with a stable client identifier
- 4Normalize acknowledgements and later events
- 5Retain source state for reconciliation
A connector becomes difficult to replace when venue field names and response assumptions spread through strategy, dashboard, and database code. A command-and-event contract keeps broker-specific translation at the edge while preserving the raw identifiers and states needed for investigation.
Define commands in business terms
A place-order command can include local request ID, account connection, instrument identity, side, quantity with units, order type, limit or stop values, time in force, environment, and trace ID. Validate internal invariants before calling the broker adapter.
Expose capabilities instead of guessing
The adapter should report supported order types, time-in-force values, fractional quantities, extended-hours behaviour, test environment, and relevant limits. A workflow can then reject unsupported commands with a structured reason before network submission.
Normalize events while retaining source data
Map acknowledgements, rejections, open status, partial fills, fills, cancellations, and replacements into internal events. Keep broker order IDs, execution IDs, source status, source timestamp, received timestamp, and a reference to the permitted raw payload.
- Internal event type and version
- Local request and trace IDs
- Broker order and execution IDs
- Source and normalized state
- Quantities, prices, fees, and timestamps when provided
Test the boundary with failure fixtures
Use recorded sanitized responses and sandbox tests for accepted, rejected, partial, cancelled, delayed, duplicated, and out-of-order events. Confirm that a timeout creates an uncertain state rather than an automatic duplicate command. Contract fixtures should be versioned when the broker API changes.
Model intent and observation as different records
A submit-order command expresses an intended action with client order ID, instrument, side, type, quantity, price terms, account, and control context. The immediate result may only confirm that the adapter accepted the command for processing. Broker events later report source facts such as accepted, rejected, open, partially filled, filled, cancelled, or expired.
Keep the normalized event and the broker payload or permitted source fields together. When a broker does not support a requested feature, return an explicit capability error before submission instead of approximating silently. When a timeout makes the result unknown, emit an uncertain state that triggers lookup or reconciliation rather than reporting a definite rejection.
Visual guide
Stable commands in, normalized events out
The adapter isolates venue-specific authentication, identifiers, capabilities, and responses from the wider trading workflow.
- 1
Command
A stable internal request with identity and defined terms.
- 2
Capability check
Validate connection, market, order type, and account support.
- 3
Venue request
Translate units, identifiers, parameters, and authentication.
- 4
Source response
Retain broker IDs, codes, payload, and timing.
- 5
Normalized event
Publish a consistent lifecycle fact with source evidence.
Detect provider changes before release
Keep approved fixtures for each supported response shape and compare both the normalized result and the retained source evidence after an adapter change. A renamed field, new status, altered error body, or different identifier format should fail visibly instead of becoming a silent mapping error.
Use the broker's permitted sandbox or demo environment for current compatibility checks, while retaining deterministic fixtures for failures that are difficult to trigger on demand. Record documentation versions and repeat capability discovery when the broker changes products, account permissions, or API behaviour.
| Provider condition | Normalized response | Next software action |
|---|---|---|
| Unsupported order type | Capability error | Reject before submission |
| Rate limited | Retryable provider error | Back off within request policy |
| Submission timeout | Outcome unknown | Query or reconcile before retry |
| Permission denied | Connection configuration error | Disable affected action and alert owner |
| Duplicate client ID | Existing-intent conflict | Load linked request and compare terms |
Practical questions
Questions that often come up
Can the adapter own trading strategy logic?
It should normally own broker translation and connection behaviour. Client-defined strategy and operating rules belong in layers that can be tested independently of a venue.
Continue exploring
Related projects and tutorials
Work with Sun Cluster
Planning a similar system for your organization?
Sun Cluster builds broker API adapters and trading-system integrations with explicit capabilities, order-state handling, and operational safeguards.