OPBT SDK · BP

OPR best practices

On this page

OPR platform best practices

Guidance, not a second SDK#

This area collects reusable OPR engineering guidance across platform domains. A practice explains how to combine OPR facts safely; it does not add an API, redefine a field or promise provider behavior. The version-pinned SDK and tool schemas remain authoritative whenever wording conflicts.

Practice catalog#

Every entry has a stable ID, version, strength, applicability, controlled tags, contract references and a review date. The controlled v1 tag set is STRATEGY · DATA · EXECUTION · PORTFOLIO · RISK · STATE_RECOVERY · DEPLOYMENT · OBSERVABILITY · MCP · RESEARCH_WORKFLOW · CORRECTNESS · SAFETY · REPRODUCIBILITY · PERFORMANCE · CROSS_MODE_PORTABILITY.

ID	Applies to · strength	Tags	Practice
position-first-order-lifecycle v1 · ACTIVE	STRATEGY · BACKTEST · PAPER · LIVE RECOMMENDED	STRATEGY · EXECUTION · PORTFOLIO · RISK · STATE_RECOVERY · CORRECTNESS · SAFETY · CROSS_MODE_PORTABILITY	Position-first order lifecycle Keep the execution state machine in Strategy state, reconcile durable intent against mode-authoritative exposure, and never turn an ambiguous submit into a blind retry.
strategy-owned-account-risk-policy v2 · ACTIVE	STRATEGY · BACKTEST · PAPER · LIVE · MCP RECOMMENDED	STRATEGY · EXECUTION · PORTFOLIO · RISK · MCP · CORRECTNESS · SAFETY · CROSS_MODE_PORTABILITY	Strategy-owned account risk policy Keep sizing, positions and execution lifecycle in Strategy code; keep venue-account configuration under user control and framework admission limited to hard execution contracts.

BP-001 · Position-first order lifecycle#

Status: ACTIVE · Strength: RECOMMENDED · Last reviewed: 2026-08-18.

Authoritative boundaries: Trading API, Data API, Paper Portfolio and Live execution. MCP clients should also read the entry's exact related_contracts.

Treat actual account exposure and in-flight Strategy intent as independent evidence. Positions or canonical SPOT balances describe realized exposure. Local order views, immutable receipts and an optional exact native query describe what may still be in flight. Neither axis may be guessed from the other.

Key derivative exposure by exact account and instrument. Key SPOT exposure by exact account and the frozen canonical base asset; multiple SPOT routes for the same asset must share one economic target and risk budget rather than duplicate the balance. Keep order intents separately keyed by account, instrument and the Strategy's business-intent key.

Recover durable intentProcess execution receipts and the Strategy's ctx.state before creating new work.

Read actual exposureUse the exact account position or canonical SPOT balance, then calculate target minus actual.

Resolve only owned workRead the local order view first. Make one exact native query only when a complete identity exists and the Strategy's own cadence allows it.

Apply the Strategy policyThe Strategy owns timeout, backoff, maximum attempts, cancel confirmation, deadband and replacement rules.

Submit one durable intentPersist enough intent before the side effect, submit once, then store the returned local/native identity and the three-state success fact.

Strategy state-machine sketch (pseudocode)

# 1. Reconcile the Strategy's durable intent and receipts.
intent = getattr(ctx.state, "intent", None)
local_order_id = intent.get("local_order_id") if intent else None
view = ctx.order_status(local_order_id) if local_order_id is not None else None

# 2. Query one exact native identity only at the Strategy's own cadence.
if should_refresh(intent, view, ctx.now):
    view = ctx.order_status(
        native_order_id=intent["native_order_id"],
        instrument=intent["instrument"],
        account=intent["account"],
    )

# 3. The Strategy decides whether the prior intent is still blocking or replaceable.
if intent and not strategy_allows_replacement(intent, view, ctx.now):
    return

# 4. Recompute from actual exposure; account only for in-flight work the Strategy recognizes.
if actual_qty is None:
    return
remaining = target_qty - actual_qty - recognized_inflight_qty(intent, view)
side = "Buy" if remaining > 0 else "Sell"
qty = ctx.quantize_qty(instrument, abs(remaining))
if qty <= 0:
    return

# 5. Persist PREPARED intent before one submit; never infer or auto-retry its outcome.
ctx.state.intent = prepared_intent(instrument, account, target_qty, ctx.now)
ctx.save_state()
result = ctx.place_order(instrument, side, "Market", qty, account=account)
ctx.state.intent = submitted_intent(ctx.state.intent, result)

Anti-patterns include a global open_orders guard, deriving terminal from status/fill/success, immediately resubmitting an unresolved submit, clearing intent after only a cancel acknowledgement, querying every symbol on every bar, and relying on an order callback that the SDK does not provide.

BP-002 · Strategy-owned account risk policy#

Status: ACTIVE · Strength: RECOMMENDED · Last reviewed: 2026-08-28.

Authoritative boundaries: Trading API, Paper Portfolio and Live execution. MCP clients should read opr://sdk/portfolio/v1 and this entry's exact related_contracts.

Fact	What it proves	Strategy policy
complete	Core equity is present; optional evidence may still be unavailable.	Do not expand one boolean into an all-fields health gate.
equity / nav	Equity is nullable money; NAV is a separate unitless performance measure.	Size with available equity; never substitute NAV, an old value or zero.
positions / balances	Exact exposure according to the current mode and product contract.	Declare the exposure evidence required by each increase, reduction or exit.
borrow / liability / leverage	Independent nullable financing and risk evidence; None is never zero.	Choose an explicit hold, reduced size or exit path; do not rely on a framework account freeze.

Read the exact accountKeep account facts separate from deployment aggregates and retain unknown values as unknown.

Declare evidence per actionDefine the minimum facts required for an increase, reduction, exit and observation separately.

Apply Strategy risk policyOwn sizing, caps, target leverage, hold scope, reason, release condition and fallback in Strategy code.

Submit one commandThe framework enforces authority, exact routes, precision and request schema, then preserves the provider result.

Manage the outcomeRejection or ambiguity returns to the Strategy's durable lifecycle; the framework never retries or manages it.

Anti-patterns include treating complete as all-fields healthy, converting nullable leverage or borrow into zero, deriving a venue setLeverage action from Strategy target leverage or Paper leverage_max, treating legacy binding metadata as current account truth, silently blocking forever when an optional fact is absent, freezing every command because equity is non-positive or an observable position is non-executable, and adding provider-specific account gates. If a Strategy chooses fail-closed behavior, scope it to the intended action and expose both the missing evidence and release condition.

Adding a practice#

Add one self-contained entry for one reusable decision problem. Keep it neutral to incidental providers and symbols, select tags from the controlled set, name its applicability, link the exact contracts, include both the safe pattern and the failure pattern, and record the review date. Incident notes belong in runbooks; only the generalized lesson belongs here.