OPBT SDK · 04

Trading API

On this page

Trading API

Backtest market orders use the next decision bar's open plus the configured slippage and fees. Paper uses completed bars as decision triggers but prices a submitted market order from a fresh OnePort BBO. If that quote is missing, stale or invalid, the Paper order is rejected without changing the account.

Order methods#

ctx.place_order(instrument, side, order_type, qty, *, account=None, price=None, reduce_only=False) → OrderSubmitResult

Submit an order in Backtest, Paper or Live. instrument uses venue:product:symbol; side is Buy or Sell; order_type is Market or Limit; qty is a positive coin quantity and is forwarded to OnePort without a second contract-size conversion. Limit requires price, while Market does not accept one. reduce_only applies only to UPERP. With multiple accounts, pass the account key selected in the run configuration.

ctx.cancel_order(order_id) → bool

Return whether the execution source confirmed the cancel request. This does not prove that the order is cancelled or terminal; query order_status later.

ctx.order_status(order_id) → OrderView | None

Read the latest known order state. Known orders, including completed ones, remain queryable throughout the run or deployment; only an ID that never existed may return None.

ctx.open_orders(instrument=None, account=None) → tuple[OrderView, ...]

Return local orders not explicitly terminal=true. Live terminal=null means unresolved, not active.

Order status is exactly New, PartiallyFilled, Filled, Cancelled, Rejected, Expired or Unknown. Live transport ambiguity is returned without retry or a global freeze; the SDK has no order-event DTO or callback.

python

result = ctx.place_order(
    "binance:UPERP:BTCUSDT", "Buy", "Market", 0.01, account="alpha",
)
ctx.state.pending_order_id = result.local_order_id
ctx.state.submit_success = result.success
ctx.state.submit_status = result.status

view = ctx.order_status(ctx.state.pending_order_id)
if view is not None and view.terminal is True:
    ctx.state.pending_order_id = None

Account & positions#

python

ctx.portfolio.nav              # unitless capital-flow-adjusted NAV | None
account = ctx.accounts["main"]    # account-scoped facts and multi-account orders use an explicit key
account.base_coin                  # USD/BTC/ETH/SOL/XRP denomination
account.cash                       # float | None; missing wallet fact stays None
account.equity                     # float | None; base-coin amount for sizing/risk
account.wallet_balance             # float | None; never inferred from equity
account.available_to_trade         # float | None
account.initial_margin             # float | None
account.maintenance_margin         # float | None
account.uni_mmr                    # float | None
account.as_of_ms / as_of_semantics
account.complete / availability / completeness
account.balances[asset].balance    # asset quantity used consistently in every mode
account.leverage                  # gross / equity
account.realized_pnl              # float | None; may be unavailable in Live
account.funding_pnl               # float | None; may be unavailable in Live
account.fees_paid                 # float | None; unavailable values stay None
account.nav                       # Live: None/unavailable; deployment NAV is ctx.portfolio.nav
account.positions                 # dict[instrument, Position]

pos = account.positions.get("binance:UPERP:BTCUSDT")
if pos:
    pos.qty                 # signed quantity (negative = short)
    pos.avg_price           # float | None; average entry price when available
    pos.last_price          # float | None; latest mark when available
    pos.unrealized_pnl      # float | None; requires avg + mark
    pos.notional            # float | None; requires mark
            pos.side                # "LONG" / "SHORT"