Broker integration

The Trading quickstart proves the two-method minimum. The production path owns one broker session, publishes authoritative state in order, exposes only real capabilities, and verifies the boundary before users trade through it.

Your backend remains the authority for accounts, permissions, order acceptance, fills, positions, and risk. The SDK owns the typed controller state and the surfaces that render it.

The production boundary

Within one broker session, charts and standalone widgets should receive the same TradingControllerApi. Passing broker to one owning chart or composition lets that owner create the controller. Pass trading to additional surfaces that must share it. Independently passing the same broker to several chart mounts can create several controllers and backend sessions.

Live chart and order-entry prices stay separate. Bars, quotes, depth, option chains, and prediction-market outcome quotes come from MarketDataFeed. A broker can still publish account-scoped valuation facts such as a position's marketPrice and P&L; those facts do not turn broker state into a quote feed.

Follow this path

Step	What it establishes	Required?
Adapter lifecycle and ownership	One controller owner, authenticated connect/disconnect, truthful structural support	Yes
State synchronization and reconnect	Complete snapshots, one push lane, ordered reconnect	Yes for live updates
Accounts, capabilities, and symbol rules	Exact account selection, tradability, and per-route rules	When the product exposes accounts or order entry
Orders and mutation completion	Acknowledgements, authoritative order state, idempotency, and uncertain outcomes	When users place or manage orders
Executions	Stable fill identity, corrections, and retention	When fills are displayed
Positions and P&L	Broker-owned exposure, protection, and supported actions	When positions are displayed or managed
Test and troubleshoot	Contract, reconnect, mutation, leak, and browser smoke coverage	Before production

Order tickets, chart trading, Account Manager, and the trading terminal are downstream surfaces. Add them after the broker facts and operations they consume are proven.

Backend requirements

• Authenticate reads, streams, and every mutation. Never authorize an account from a browser-supplied id alone.
• Revalidate account access, symbol routing, quantity and price rules, buying power, and risk on the server immediately before submission.
• Runtime-validate every network response before returning a public SDK type.
• Preserve exact symbol, account, and contract identities. Order, position, and execution ids must be globally unique within one controller, even when the backend's native ids are only account-scoped. Display labels are not routing keys.
• Give each mutation a backend correlation id. When an operation id is supplied, enforce one documented idempotency policy for that exact account and payload.
• Treat timeouts, network loss, rate limits, authentication expiry, and 5xx responses as unknown financial outcomes unless the backend proves the request was never submitted. Reconcile authoritative state before retrying.
• Publish each backend change through one event lane and order it against the snapshot used at initial connection or reconnect.
• Redact credentials, session tokens, personal data, and full account payloads from logs.

Capability authorities

Do not compress every capability into one boolean:

Authority	Question it answers
trading.getOperationSupport()	Is this controller operation structurally callable under its construction-time adapter and risk wiring, subject to entitlement filtering?
await trading.getFeatures()	Is a structurally available feature eligible in the current broker/account session?
TradingAccount.capabilities	Which account-level order and protection choices should the UI offer?
TradingSymbolInfo	Which rules apply to this exact symbol and account route?
isTradable(context)	Is this exact route tradable now, and what should the user do if it is not?

See Accounts, capabilities, and symbol rules for the precedence and refresh rules.

Production definition of done

• One owning composition creates one controller and one backend session.
• connect() is followed by an explicit fresh getState().
• A racing stream cannot let an older snapshot overwrite a newer event.
• An accepted placement creates no row or chart line until authoritative broker state reports it.
• Every mutation has documented completion, rejection, unknown-outcome, and retry semantics.
• Unsupported actions remain absent from every surface. When chart action visibility is enabled explicitly, map its close, protect, and reverse flags from the entitlement-filtered operation-support map.
• Disconnect stops adapter resources; destroying the owner releases controller listeners and adapter subscriptions.
• Contract tests and a mounted browser smoke test pass against production-shaped fixtures.

The full public contract is in the Trading API reference.

Next steps

Continue with Adapter lifecycle and ownership.