Package 'tradesimr'

Description

Normalize market bars for tradesimr

Usage

as_market_bars(
  data,
  timestamp_col = "timestamp",
  symbol_col = NULL,
  asset_id_col = NULL,
  symbol = NULL,
  asset_id = NULL,
  open_col = "open",
  high_col = "high",
  low_col = "low",
  close_col = "close",
  observation_timestamp_col = NULL,
  bar_start_col = NULL,
  bar_end_col = NULL,
  market_timezone = "UTC"
)

Arguments

Value

A data.table with canonical timestamp, open, high, low, close columns.

Description

Normalize target-position intents for tradesimr

Usage

as_target_positions(
  data,
  timestamp_col = NULL,
  tgt_pos_col = "tgt_pos",
  pos_strat_col = NULL,
  tol_pos_col = NULL,
  strat = 0L,
  tol_pos = 0
)

Arguments

Value

A data.table with canonical intent columns.

Description

Legacy R6 demonstration client for PaperTradingPlatform. The production simulation path is sim_backtest() and the C++ execution engine.

Public fields

Methods

Public methods

• PaperTrader$new()

• PaperTrader$place_order()

• PaperTrader$cancel_order()

• PaperTrader$get_all_orders()

• PaperTrader$get_order()

• PaperTrader$get_wallet()

• PaperTrader$get_position()

• PaperTrader$clone()

PaperTrader$new()

Create a paper trader demo client.

Usage

PaperTrader$new(user_id, platform)

Arguments

PaperTrader$place_order()

Place a demo order through the platform.

Usage

PaperTrader$place_order(inst_id, type, pos, size, price, pricing_method, tag)

Arguments

Returns

Order id.

PaperTrader$cancel_order()

Cancel a demo order.

Usage

PaperTrader$cancel_order(order_id)

Arguments

Returns

Platform cancel result.

PaperTrader$get_all_orders()

Get all orders for this trader.

Usage

PaperTrader$get_all_orders()

Returns

A data.table of orders.

PaperTrader$get_order()

Get one order for this trader.

Usage

PaperTrader$get_order(order_id)

Arguments

Returns

A data.table with matching order rows.

PaperTrader$get_wallet()

Get this trader's wallet balance.

Usage

PaperTrader$get_wallet()

Returns

Wallet balance or account cash.

PaperTrader$get_position()

Get this trader's position.

Usage

PaperTrader$get_position()

Returns

A data.table of positions.

PaperTrader$clone()

The objects of this class are cloneable with this method.

Usage

PaperTrader$clone(deep = FALSE)

Arguments

Description

Legacy R6 demonstration of a paper trading platform. The production simulation path is sim_backtest() and the C++ execution engine.

Public fields

Methods

Public methods

• PaperTradingPlatform$new()

• PaperTradingPlatform$register_user()

• PaperTradingPlatform$place_user_order()

• PaperTradingPlatform$cancel_user_order()

• PaperTradingPlatform$get_user_orders()

• PaperTradingPlatform$get_user_order()

• PaperTradingPlatform$get_live_orders()

• PaperTradingPlatform$get_order()

• PaperTradingPlatform$update_bar()

• PaperTradingPlatform$process_order()

• PaperTradingPlatform$fill_order()

• PaperTradingPlatform$get_user_wallet()

• PaperTradingPlatform$get_user_position()

• PaperTradingPlatform$update_user_wallet()

• PaperTradingPlatform$update_user_position()

• PaperTradingPlatform$clone()

PaperTradingPlatform$new()

Create a paper trading platform demo.

Usage

PaperTradingPlatform$new(config = list())

Arguments

PaperTradingPlatform$register_user()

Register a demo user and return a trader client.

Usage

PaperTradingPlatform$register_user(user_id, initial_balance = 10000)

Arguments

Returns

A PaperTrader instance.

PaperTradingPlatform$place_user_order()

Place a demo user order.

Usage

PaperTradingPlatform$place_user_order(
  user_id,
  inst_id,
  type,
  pos,
  size,
  price,
  pricing_method,
  tag
)

Arguments

Returns

Order id.

PaperTradingPlatform$cancel_user_order()

Cancel a demo user order.

Usage

PaperTradingPlatform$cancel_user_order(user_id, order_id)

Arguments

PaperTradingPlatform$get_user_orders()

Get all orders for a user.

Usage

PaperTradingPlatform$get_user_orders(user_id)

Arguments

Returns

A data.table of orders.

PaperTradingPlatform$get_user_order()

Get a user order.

Usage

PaperTradingPlatform$get_user_order(user_id, order_id)

Arguments

Returns

A data.table with matching order rows.

PaperTradingPlatform$get_live_orders()

Get live demo orders.

Usage

PaperTradingPlatform$get_live_orders()

Returns

A data.table of live orders.

PaperTradingPlatform$get_order()

Get an order by id.

Usage

PaperTradingPlatform$get_order(order_id)

Arguments

Returns

A data.table with matching order rows.

PaperTradingPlatform$update_bar()

Update the latest market bar and append it to the exchange.

Usage

PaperTradingPlatform$update_bar(inst_id, timestamp, open, high, low, close)

Arguments

PaperTradingPlatform$process_order()

Process one demo order against the latest bar.

Usage

PaperTradingPlatform$process_order(order)

Arguments

PaperTradingPlatform$fill_order()

Fill a demo order and pass target exposure to the exchange.

Usage

PaperTradingPlatform$fill_order(order_id, fill_price)

Arguments

PaperTradingPlatform$get_user_wallet()

Get a user's wallet balance.

Usage

PaperTradingPlatform$get_user_wallet(user_id)

Arguments

Returns

Wallet balance or account cash.

PaperTradingPlatform$get_user_position()

Get a user's position.

Usage

PaperTradingPlatform$get_user_position(user_id)

Arguments

Returns

A data.table of positions.

PaperTradingPlatform$update_user_wallet()

Update a user's demo wallet balance.

Usage

PaperTradingPlatform$update_user_wallet(user_id, delta_wallet_balance)

Arguments

PaperTradingPlatform$update_user_position()

Update a user's demo position after a fill.

Usage

PaperTradingPlatform$update_user_position(order)

Arguments

Returns

Wallet balance delta.

PaperTradingPlatform$clone()

The objects of this class are cloneable with this method.

Usage

PaperTradingPlatform$clone(deep = FALSE)

Arguments

Description

Extract account snapshots from a simulation

Usage

sim_account(sim)

Arguments

Value

A data.table of bar-level account snapshots.

Description

AI agents generate ordinary order requests; they do not bypass the exchange command/execution path.

Usage

sim_agent_add(
  exchange,
  agent_id = NULL,
  agent_type = c("chaos", "momentum", "contrarian", "mean_reversion", "strategy",
    "human"),
  config = list(),
  status = c("active", "paused")
)

Arguments

Value

The agent id.

Description

Get live-agent command schemas

Usage

sim_agent_command_schema()

Value

A named list of empty data.tables for append-only agent commands, order requests, and order cancellations.

Description

Export an agent-facing live dashboard

Usage

sim_agent_dashboard_export(exchange, path)

Arguments

Value

Invisibly returns a named character vector of written files.

Description

Open an agent-facing live dashboard

Usage

sim_agent_dashboard_open(
  exchange = sim_exchange_new(),
  path = tempfile("tradesimr-live-agent-")
)

Arguments

Value

Invisibly returns the dashboard index path.

Description

Rankings combine current per-agent account equity with order activity.

Usage

sim_agent_rankings(exchange)

Arguments

Value

A data.table of agent rankings.

Description

Removed agents stay in the durable registry with status removed.

Usage

sim_agent_remove(exchange, agent_id)

Arguments

Value

Invisibly returns TRUE when an agent was updated.

Description

Set an agent status

Usage

sim_agent_set_status(
  exchange,
  agent_id,
  status = c("active", "paused", "removed")
)

Arguments

Value

Invisibly returns TRUE when an agent was updated.

Description

Step active AI agents and append their order commands

Usage

sim_agents_step(exchange, bar = NULL)

Arguments

Value

A data.table of generated decisions.

Description

Register a tradable asset on an exchange

Usage

sim_asset_add(
  exchange,
  symbol,
  asset_id = NULL,
  status = c("active", "paused", "delisted", "expired", "removed"),
  asset_class = "other",
  instrument_profile = NULL,
  contract_size = 1,
  tick_size = NA_real_,
  qty_step = 1,
  base_ccy = NA_character_,
  quote_ccy = NA_character_,
  calendar_id = NULL,
  timezone = NULL,
  settlement_lag_days = NULL,
  margin_model = NULL,
  bar_cadence_seconds = NA_real_,
  metadata = list()
)

Arguments

Value

Invisibly returns the registered asset row.

Description

Removed assets remain in the durable registry with status removed.

Usage

sim_asset_remove(exchange, symbol = NULL, asset_id = NULL)

Arguments

Value

Invisibly returns TRUE when an asset was updated.

Description

List registered exchange assets

Usage

sim_assets(exchange)

Arguments

Value

A data.table of assets.

Description

sim_backtest() executes target-position intentions through the package's C++ exchange/accounting engine. Orders are planned at bar close and market orders are filled on the next bar open. Target-derived opening and increase orders are fee-aware: they are clipped at the executable price to the largest step-rounded quantity satisfying equity - fee >= initial_margin. Thus a tgt_pos of 1 at lev = 1 produces the largest near-100%-notional position that reserves its transaction fee rather than a failed order.

Usage

sim_backtest(
  data,
  timestamp_col = "timestamp",
  open_col = "open",
  high_col = "high",
  low_col = "low",
  close_col = "close",
  tgt_pos_col = "tgt_pos",
  pos_strat_col = NULL,
  tol_pos_col = NULL,
  order_type_col = NULL,
  limit_price_col = NULL,
  strat = 0L,
  asset = 0L,
  init_cash = 10000,
  ctr_size = 1,
  ctr_step = 1,
  lev = 10,
  fee_rt = 0,
  maker_fee_rt = NA_real_,
  taker_fee_rt = NA_real_,
  fund_rt = 0,
  funding_interval_hours = 8,
  mmr = 0.02,
  fill_model = c("next_open", "same_close"),
  slippage = 0,
  spread = 0,
  tol_pos = 0,
  record = TRUE
)

Arguments

Value

A data.table with timestamp and equity. If record = TRUE, an execution recorder is attached as attribute orders.

Description

The schedule uses a fixed ACT/day-count convention and equal coupon periods. At each eligible heterogeneous account boundary, C++ emits non-cash accrual events, books due coupons into settled cash, and redeems remaining inventory at maturity. A sparse replay boundary crossing multiple coupon dates is processed coupon-by-coupon before any remaining partial-period accrual. The cursor fields are durable exchange state, so resumed replay continues from the same coupon boundary.

Usage

sim_bond_schedule_add(
  exchange,
  symbol,
  coupon_rate,
  coupon_frequency = 2L,
  issue_timestamp,
  maturity_timestamp,
  face_value = 100,
  accrual_day_count = 365,
  currency = NULL
)

Arguments

Value

Invisibly returns the registered schedule row.

Description

List durable bond schedules

Usage

sim_bond_schedules(exchange)

Arguments

Value

A data.table of bond schedule state.

Description

Generate expected completed bar timestamps from a calendar

Usage

sim_calendar_expected_bars(
  calendar_id,
  start,
  end,
  cadence_seconds,
  exceptions = NULL
)

Arguments

Value

A data.table of expected completed-bar timestamps.

Description

List deterministic built-in calendar holidays

Usage

sim_calendar_holidays(calendar_id, start, end)

Arguments

Value

A data.table of session dates, labels, and optional early close time.

Description

This deliberately provides deterministic session rules, not a vendor holiday database. XNYS includes fixed-date observed holidays; callers may mark exceptional closures with is_tradable = FALSE in market bars.

Usage

sim_calendar_is_open(timestamp, calendar_id = "ALWAYS_OPEN", exceptions = NULL)

Arguments

Value

A logical vector.

Description

Settlement lags count tradable calendar dates, not raw 24-hour periods. This gives FX spot its conventional weekday progression while preserving same-day settlement for 24/7 instruments. Exchange-specific closed-date exceptions are respected.

Usage

sim_calendar_settlement_timestamp(
  calendar_id,
  timestamp,
  settlement_lag_days = 0L,
  exceptions = NULL
)

Arguments

Value

A UTC POSIXct settlement timestamp.

Description

Get a trading-calendar specification

Usage

sim_calendar_spec(calendar_id)

Arguments

Value

A one-row data.table with timezone, session rule, and holiday policy.

Description

Submit an agent order cancellation command

Usage

sim_cancel_order(
  exchange,
  agent_id,
  order_id,
  client_order_id = NA_character_,
  timestamp = Sys.time(),
  process = TRUE
)

Arguments

Value

The generated command id.

Description

Extract cash ledger entries from a simulation

Usage

sim_cash_ledger(sim)

Arguments

Value

A data.table of event-level cash changes.

Description

Compute cross-asset risk for live exchange agents

Usage

sim_cross_asset_risk(exchange, stress_sigma = 2)

Arguments

Value

A data.table with one row per agent and exposed asset.

Description

Compatibility alias for sim_replay_dashboard_export().

Usage

sim_dashboard_export(sim, path)

Arguments

Value

Invisibly returns a named character vector of written files.

Description

Open an exported static dashboard

Usage

sim_dashboard_open(path)

Arguments

Value

Invisibly returns the dashboard index path.

Description

Convert a simulation recorder into an event table

Usage

sim_events(x)

Arguments

Value

A data.table of recorded simulation events.

Description

Get simulated exchange account state

Usage

sim_exchange_account(exchange)

Arguments

Value

A one-row data.table with the latest account snapshot.

Description

Returns the typed, profile-aware account projection used by the heterogeneous execution engine. Cash is valued in the exchange base currency; fully paid inventory contributes marked market value, while margin positions contribute marked unrealized P&L and maintenance margin. sim_exchange_account() remains the compatibility account snapshot API.

Usage

sim_exchange_account_state(exchange, agent_id = NULL)

Arguments

Value

A named list containing account, cash_balances, inventory_positions, margin_positions, and events data.tables.

Description

The function is idempotent at a timestamp and is called automatically before every executable exchange boundary. Call it explicitly to establish an initial accrual cursor or to accrue a durable account without new bars.

Usage

sim_exchange_accrue_carry(exchange, timestamp)

Arguments

Value

A data.table of booked carry events.

Description

Append market bars to a simulated exchange

Usage

sim_exchange_add_bars(exchange, bars)

Arguments

Value

The exchange, invisibly.

Description

Add an exchange-specific calendar exception

Usage

sim_exchange_calendar_exception(
  exchange,
  session_date,
  action = c("closed", "early_close"),
  calendar_id = NULL,
  symbol = NULL,
  asset_id = NULL,
  close_time = NULL,
  message = ""
)

Arguments

Value

Invisibly returns the durable exception row.

Description

Calendarize registered-asset market bars

Usage

sim_exchange_calendarize_bars(exchange, bars, strict = FALSE)

Arguments

Value

Canonical market bars with calendar-derived is_tradable values.

Description

Cancel an intent-level order in a simulated exchange

Usage

sim_exchange_cancel_order(exchange, order_id)

Arguments

Value

Invisibly returns TRUE if an order was cancelled.

Description

Deposit or withdraw a profile-aware currency balance

Usage

sim_exchange_cash_adjust(
  exchange,
  agent_id,
  amount,
  currency = NULL,
  timestamp = Sys.time(),
  message = "Manual cash adjustment"
)

Arguments

Value

Invisibly returns the resulting currency balance.

Description

Get profile-aware cash balances

Usage

sim_exchange_cash_balances(exchange, agent_id = NULL)

Arguments

Value

A data.table where amount is settled cash (kept for compatibility), unsettled is pending settlement cash, and the base-value columns report settled-only and total cash valuation respectively.

Description

Convert cash between currencies at an authoritative exchange FX mark

Usage

sim_exchange_convert_cash(
  exchange,
  agent_id,
  amount,
  from_ccy,
  to_ccy,
  timestamp = Sys.time()
)

Arguments

Value

Invisibly returns the destination amount.

Description

Actions are applied at the first exchange step at or after their effective timestamp and retained in a durable audit table.

Usage

sim_exchange_corporate_action(
  exchange,
  symbol,
  action_type = c("dividend", "split", "coupon", "bond_accrual", "redemption",
    "delisting", "future_expiry", "future_roll"),
  amount,
  effective_timestamp,
  currency = NULL
)

Arguments

Value

Invisibly returns the action id.

Description

Export and open a simulated exchange dashboard

Usage

sim_exchange_dashboard(exchange, path)

Arguments

Value

Invisibly returns written dashboard files.

Description

Export exchange simulation events

Usage

sim_exchange_export_events(exchange, path, format = c("csv", "fst"))

Arguments

Value

Invisibly returns written file paths.

Description

Expiry settles the old contract's marked P&L into settled quote-currency cash and terminates its open margin position. A roll additionally opens the same signed quantity in a registered successor contract at roll_price. The successor must not already have an open margin position for an affected account; callers should make any independent successor adjustment first.

Usage

sim_exchange_future_roll(
  exchange,
  symbol,
  effective_timestamp,
  settlement_price,
  successor_symbol = NULL,
  roll_price = NULL
)

Arguments

Value

Invisibly returns the corporate action id.

Description

Rates express units of to_ccy per one unit of from_ccy. They are used only for account valuation and explicit currency conversion; they never alter an execution price.

Usage

sim_exchange_fx_rate(
  exchange,
  from_ccy,
  to_ccy,
  rate,
  timestamp = Sys.time(),
  source = "manual"
)

Arguments

Value

Invisibly returns the added rate row.

Description

Load exchange state from disk

Usage

sim_exchange_load(path)

Arguments

Value

A tradesimr_exchange.

Description

Create an in-memory simulated exchange state

Usage

sim_exchange_new(config = list())

Arguments

Value

A mutable environment containing market, intent, order, and result tables.

Description

Get new events since the previous exchange run

Usage

sim_exchange_new_events(exchange)

Arguments

Value

A data.table of newly observed simulation events.

Description

Get simulated exchange orders

Usage

sim_exchange_orders(exchange)

Arguments

Value

A data.table of accepted/cancelled intent-level orders.

Description

Explicit orders use qty_type = "contracts" by default for buy/sell/flat orders. Use qty_type = "target_pos" or side = "target" for exposure targets consumed by replay-style backtests.

Usage

sim_exchange_place_order(
  exchange,
  agent_id,
  timestamp,
  symbol = NULL,
  asset_id = NULL,
  tgt_pos = NULL,
  tol_pos = 0,
  order_type = c("market", "limit"),
  side = c("target", "buy", "sell", "flat"),
  qty_type = NULL,
  qty = NULL,
  limit_price = NA_real_,
  time_in_force = "gtc",
  atomic_group_id = NULL,
  client_order_id = NA_character_
)

Arguments

Value

The generated order id.

Description

Get simulated exchange positions

Usage

sim_exchange_positions(exchange)

Arguments

Value

A one-row data.table with the latest position snapshot.

Description

Converts pending append-only order request and cancellation commands into exchange orders and cancellation attempts.

Usage

sim_exchange_process_commands(exchange)

Arguments

Value

A data.table of processed command rows.

Description

Run or refresh a simulated exchange replay

Usage

sim_exchange_run(exchange)

Arguments

Value

A simulation result returned by sim_backtest().

Description

Export exchange events and state

Usage

sim_exchange_save(exchange, path, format = c("csv", "fst"))

Arguments

Value

Invisibly returns written file paths.

Description

Rates are annualized simple rates keyed by registered symbol for borrow and by currency for settled-cash interest. Positive cash earns the configured rate; negative cash is charged it. Short inventory is charged its symbol's borrow rate from the inventory quote-currency balance.

Usage

sim_exchange_set_carry_rates(
  exchange,
  borrow_rates = numeric(),
  cash_interest_rates = numeric()
)

Arguments

Value

Invisibly returns the configured rates.

Description

Settle due profile-aware cash movements

Usage

sim_exchange_settle(exchange, timestamp = Sys.time())

Arguments

Value

A data.table of settled ledger rows.

Description

Step a simulated exchange with one or more bars

Usage

sim_exchange_step(exchange, bars)

Arguments

Value

The incremental simulation snapshots.

Description

Validate registered-asset bar cadence

Usage

sim_exchange_validate_cadence(exchange, bars, strict = FALSE)

Arguments

Value

A data.table with calendar_open and cadence_ok columns.

Description

Export simulation tables to durable files

Usage

sim_export(
  sim,
  path,
  format = c("csv", "fst"),
  tables = c("simulation", "market_events", "events", "orders", "fills", "positions",
    "cash_ledger", "account", "risk")
)

Arguments

Value

Invisibly returns a named character vector of written file paths.

Description

Default live feed configuration

Usage

sim_feed_config(
  symbol = "BTC-USDT-SWAP",
  asset_id = NULL,
  timeframe = "4h",
  tz = "UTC",
  feed_mode = c("simulation", "external"),
  feed_adapter = NULL,
  start_time = NULL,
  simulation_model = c("random_walk", "ar", "garch11", "ar_garch", "regime"),
  random_walk = list(start_price = 100, drift = 0, vol = 0.02, seed = 1L),
  simulation = list()
)

Arguments

Value

A list suitable for sim_feed_configure().

Description

Configure a live exchange feed

Usage

sim_feed_configure(exchange, config = sim_feed_config())

Arguments

Value

The feed configuration, invisibly.

Description

Start a configured live feed

Usage

sim_feed_start(exchange, now = Sys.time(), symbol = NULL, asset_id = NULL)

Arguments

Value

Feed status.

Description

Get live feed status

Usage

sim_feed_status(exchange)

Arguments

Value

A list describing feed state.

Description

Generates or fetches all completed bars after the last processed feed boundary and appends them through sim_exchange_step().

Usage

sim_feed_step(
  exchange,
  now = Sys.time(),
  max_bars = Inf,
  symbol = NULL,
  asset_id = NULL
)

Arguments

Value

A data.table of bars appended by this call.

Description

Stop a configured live feed

Usage

sim_feed_stop(exchange, symbol = NULL, asset_id = NULL)

Arguments

Value

Feed status.

Description

Appends n_bars simulated OHLC bars ending at the latest completed boundary. This is a market-history warmup: it does not step AI agents or process pending orders.

Usage

sim_feed_warmup(
  exchange,
  n_bars = 100L,
  now = Sys.time(),
  symbol = NULL,
  asset_id = NULL
)

Arguments

Value

A data.table of appended market bars.

Description

Extract fill events from a simulation

Usage

sim_fills(sim)

Arguments

Value

A data.table of filled trade events.

Description

Marks inventory, settles futures/perpetual variation margin, and evaluates a normalized order batch without mutating the supplied R input tables.

Usage

sim_heterogeneous_account_step(
  base_currency,
  cash_balances,
  inventory_positions = data.frame(),
  margin_positions,
  bars,
  fx_rates,
  settlements = data.frame(),
  corporate_actions = data.frame(),
  orders = data.frame(),
  timestamp = Sys.time()
)

Arguments

Value

Updated account state, typed events, fills, and group outcomes.

Description

The schema carries generic order identity and eligibility fields plus derivative compatibility fields: action/direction codes, strategy/action identifiers, target-derived admission flag, per-asset quantity step, and funding settings. Inventory adapters may leave the compatibility fields at their typed defaults.

Usage

sim_heterogeneous_order_batch_schema()

Value

A typed empty data.table accepted by sim_heterogeneous_account_step().

Description

Import exported simulation tables

Usage

sim_import(path)

Arguments

Value

A named list containing manifest, simulation, and available durable tables.

Description

Resolve an instrument profile

Usage

sim_instrument_profile(instrument_profile)

Arguments

Value

A one-row data.table of profile defaults.

Description

Instrument profiles define accounting and calendar defaults. They are intentionally declarative: the current C++ execution kernel still uses the registered contract multiplier and quantity step as its numeric inputs. The synthetic_price_return profile models signed marked price exposure only. It makes no custody, borrow availability or cost, dividend, funding, carry, settlement, or corporate-action claims, and is therefore suitable for stated price-return simulations rather than brokerage execution. Target-derived fee scaling preserves target ratios subject to contract-step rounding and records fee_scaled fills as durable partial execution-quality outcomes. Explicit contract orders remain all-or-nothing.

Usage

sim_instrument_profiles()

Value

A data.table of supported profiles and their defaults.

Description

Builds an optional plumber app exposing local HTTP endpoints for agent commands. The service is a thin API over append-only command logs and the existing exchange APIs.

Usage

sim_live_service(exchange = sim_exchange_new())

Arguments

Value

A plumber router.

Description

Run a local live exchange service

Usage

sim_live_service_run(
  exchange = sim_exchange_new(),
  host = "127.0.0.1",
  port = 8080
)

Arguments

Value

The result of plumber's run() method.

Description

Open a live-state dashboard

Usage

sim_live_state_dashboard_open(
  exchange = sim_exchange_new(),
  path = tempfile("tradesimr-live-state-")
)

Arguments

Value

Invisibly returns the dashboard index path.

Description

Build an export manifest

Usage

sim_manifest(paths, tables, format, config = list())

Arguments

Value

A data.table manifest.

Description

Extract market bars from a simulation

Usage

sim_market_events(sim)

Arguments

Value

A data.table with timestamp, open, high, low, and close.

Description

Estimates per-asset drift, volatility, AR coefficients, GARCH-like variance persistence, covariance/correlation, one-factor loadings, and simple low/high-volatility regime covariance from historical closes.

Usage

sim_market_model_calibrate(
  bars,
  model = c("multi_asset_random_walk", "multi_asset_ar_garch", "factor_random_walk",
    "regime_random_walk"),
  ar_order = 1L,
  seed = 1L,
  timeframe = NULL,
  tz = "UTC"
)

Arguments

Value

A sim_market_model_config() list with calibration metadata.

Description

Configure an exchange market model from historical bars

Usage

sim_market_model_calibrate_exchange(
  exchange,
  bars,
  model = c("multi_asset_random_walk", "multi_asset_ar_garch", "factor_random_walk",
    "regime_random_walk"),
  ar_order = 1L,
  seed = 1L,
  timeframe = NULL,
  tz = "UTC"
)

Arguments

Value

The calibrated market model config, invisibly.

Description

Configure market-level multi-asset simulation

Usage

sim_market_model_config(
  model = c("independent", "multi_asset_random_walk", "multi_asset_ar_garch",
    "factor_random_walk", "regime_random_walk"),
  corr = NULL,
  cov = NULL,
  factors = NULL,
  regimes = NULL,
  calibration = NULL,
  seed = 1L,
  timeframe = NULL,
  tz = NULL,
  start_time = NULL
)

Arguments

Value

A market model configuration list.

Description

Configure a market-level simulation model

Usage

sim_market_model_configure(exchange, config = sim_market_model_config())

Arguments

Value

The market model configuration, invisibly.

Description

Get market-level simulation model status

Usage

sim_market_model_status(exchange)

Arguments

Value

A list describing the market-level simulation model.

Description

Calculate core performance metrics from a simulation result

Usage

sim_metrics(sim)

Arguments

Value

A one-row data.table with return, drawdown, and event counts.

Description

Convert a simulation recorder into an order/event table

Usage

sim_orders(x)

Arguments

Value

A data.table of recorded execution events.

Description

A policy controls which completed market observations may create a target-weight decision. It never changes execution eligibility: every order still fills only on a strictly later, tradable bar for its own asset.

Usage

sim_portfolio_decision_policy(
  mode = c("complete_universe", "as_of_valuation", "per_asset_decision"),
  max_staleness = Inf
)

Arguments

Value

A validated decision-policy list.

Description

Build execution assumptions for a target-weight portfolio replay

Usage

sim_portfolio_execution(
  timing = "next_eligible_open",
  fee_rt = 0,
  maker_fee_rt = NA_real_,
  slippage = 0,
  spread = 0,
  lev = 1,
  mmr = 0.02,
  max_gross_weight = 1
)

Arguments

Value

A named execution configuration list.

Description

The projection evaluates each target using its decision-time target record, canonical order lifecycle, durable fills, and the position/account snapshot at the relevant settlement boundary. It never uses a later current mark to classify an earlier rebalance. Filled fee-aware target orders are assessed against their exact C++-recorded executable quantity.

Usage

sim_portfolio_execution_quality(exchange, agent_id = NULL, summary = FALSE)

Arguments

Value

A public-safe data.table. Symbol rows contain rebalance_id, agent_id, symbol, asset_id, decision_timestamp, eligible_after, settlement_timestamp, target_weight, decision_equity, decision_price, qty_step, contract_size, current_signed_quantity, expected_signed_quantity, expected_notional, realized_signed_quantity, realized_notional, quantity_deviation, notional_deviation, weight_deviation, execution_quality, and message.

Description

Export a safe portfolio replay snapshot for an external consumer

Usage

sim_portfolio_export(exchange, agent_id, path, format = "json")

Arguments

Value

A named vector of written paths. fills.json is sourced from the durable portfolio fill ledger and links every filled portfolio order to its order_id and rebalance_id; rebalances.json contains the linked accepted/rejected rebalance records.

Description

This API advances a timestamped batch of completed bars exactly once. It executes only orders submitted at earlier boundaries; it never creates a target decision or rebalance. Each supplied asset bar must be genuinely new, so duplicate and stale batches fail rather than being silently reprocessed.

Usage

sim_portfolio_market_step(
  exchange,
  bars,
  execution = sim_portfolio_execution()
)

Arguments

Value

A public-safe list with bars, fills, events, positions, account, and outcomes.

Description

Processes one timestamp batch of bars and explicit orders for one agent under one shared cash balance. This is the multi-asset primitive used by live exchanges when portfolio_margin = TRUE.

Usage

sim_portfolio_step(
  states,
  bars,
  orders = data.frame(),
  cov = diag(nrow(as_market_bars(bars))),
  shared_cash = 10000,
  ctr_size = 1,
  ctr_step = 1,
  lev = 10,
  fee_rt = 0,
  maker_fee_rt = NA_real_,
  taker_fee_rt = NA_real_,
  fund_rt = 0,
  funding_interval_hours = 8,
  mmr = 0.02,
  portfolio_margin_sigma = 3,
  portfolio_margin_floor = mmr,
  slippage = 0,
  spread = 0,
  record = TRUE
)

Arguments

Value

A list with states, cash, equity, maintenance_margin, liquidated, and events. The state-list input is a compatibility projection; exchange and replay callers should use the typed heterogeneous account route.

Description

This bulk API is intended for historical reconstruction. It preserves the public market-boundary and target-submission semantics while accumulating durable snapshots and events in batches rather than repeatedly growing their history tables. Live callers should continue to use sim_portfolio_market_step() and sim_portfolio_target_submit_batch().

Usage

sim_portfolio_target_replay(
  exchange,
  bars,
  target_weights,
  allowed_symbols = NULL,
  execution = sim_portfolio_execution(),
  decision_policy = sim_portfolio_decision_policy(),
  rebalance_policy = NULL,
  export_path = NULL,
  profile = FALSE,
  production_calendar = FALSE
)

Arguments

Value

A list with the exchange, durable orders/fills/positions/accounts, targets/rebalances, execution quality, optional export paths, and timings.

Description

This is the stable Vox Arena integration point. It accepts a batch of genuinely new completed OHLC bars and, optionally, an explicit target-weight decision. Existing eligible orders are stepped first. A new target decision is then translated atomically into contract orders using current account equity and the decision-bar close (or the latest carried valuation for an asset absent from the batch). New orders are eligible only on a strictly later bar for their own asset. At that later fill boundary, target-derived opening/increase orders are capped to the largest step-rounded quantity whose fee and initial margin fit the account. Consequently a target weight of 1 at lev = 1 is near 100% notional after reserving the fee, rather than a failed all-cash order. Explicit contract orders retain reject-on-insufficient margin semantics.

Usage

sim_portfolio_target_step(
  exchange,
  agent_id,
  bars,
  target_weights = NULL,
  execution = sim_portfolio_execution(),
  decision_label = "target_weight",
  allowed_symbols = NULL,
  allowed_asset_ids = NULL,
  decision_policy = sim_portfolio_decision_policy()
)

Arguments

Details

A named target vector updates only its named symbols; supply an explicit zero target weight to flatten an asset. A NULL target is a no-decision: positions are retained and no new orders are submitted. Repeated/stale bars are ignored, so closed markets can retain their last valuation without creating strategy reactions or fills.

Value

A list containing orders, fills, positions, account, targets, realized_weights, and outcomes.

Description

The supplied decision bars must already have been accepted by sim_portfolio_market_step(). Targets are converted atomically using the completed-bar close and the post-step account state. Submitted orders are eligible only on a strictly later bar of the same asset. NULL records a durable no-decision outcome and preserves current positions. Target-derived opening and increasing orders are clipped down to the largest executable contract-step quantity when fees or shared portfolio margin make the exact target infeasible. Explicit contract orders remain all-or-nothing. For inventory-profile target groups, fee-aware scaling is applied once to the atomic group, preserving target ratios subject to contract-step rounding. Such fills retain the durable fee_scaled reason code and are reported as partial execution-quality outcomes when the requested target is not fully reached. A later accepted target decision supersedes still-unfilled target-derived orders for the same agent and overlapping allowed assets; explicit contract orders are never superseded. For a multi-asset allowed universe, a non-NULL target decision is accepted only when the same market boundary contains exactly one completed bar for every allowed asset. This prevents target allocation from being planned from a partial cross-asset information set. Single-asset submissions are unaffected.

Usage

sim_portfolio_target_submit(
  exchange,
  agent_id,
  bars,
  target_weights = NULL,
  execution = sim_portfolio_execution(),
  decision_label = "target_weight",
  allowed_symbols = NULL,
  allowed_asset_ids = NULL,
  decision_policy = sim_portfolio_decision_policy()
)

Arguments

Value

A list containing orders, fills, positions, account, targets, realized_weights, and outcomes.

Description

This is the efficient replay interface for a common completed market boundary. It does not step market data. Instead, it validates the accepted boundary once and snapshots account, position, and carried-price state once before translating each agent's decision atomically. Each decisions element is a named list containing target_weights (or NULL for a no-decision), and optionally decision_label, allowed_symbols, and allowed_asset_ids. A multi-asset decision requires exactly one completed bar for every allowed asset at the common decision boundary.

Usage

sim_portfolio_target_submit_batch(
  exchange,
  bars,
  decisions,
  execution = sim_portfolio_execution(),
  decision_policy = sim_portfolio_decision_policy()
)

Arguments

Value

A list with the common boundary timestamp, public account and position snapshots, and a named submissions list containing the same result contract as sim_portfolio_target_submit() for each agent.

Description

Extract position snapshots from a simulation

Usage

sim_positions(sim)

Arguments

Value

A data.table of bar-level position snapshots.

Description

Read exported account snapshots

Usage

sim_read_account(path)

Arguments

Value

A data.table of account snapshots.

Description

Read exported simulation events

Usage

sim_read_events(path)

Arguments

Value

A data.table of events.

Description

Read an export manifest

Usage

sim_read_manifest(path)

Arguments

Value

A data.table manifest.

Description

Read an exported simulation table

Usage

sim_read_table(path, table, format = NULL)

Arguments

Value

A data.table.

Description

Alias for sim_backtest() reserved for replay-oriented workflows.

Usage

sim_replay(data, ...)

Arguments

Description

Writes dashboard-ready CSV tables, a manifest, and static HTML/CSS/JS assets. The dashboard is a read-only consumer of durable market, strategy, event, account, risk, order, and fill tables; it does not call C++, R6, or live exchange internals.

Usage

sim_replay_dashboard_export(sim, path)

Arguments

Value

Invisibly returns a named character vector of written files.

Description

Extract risk snapshots from a simulation

Usage

sim_risk(sim)

Arguments

Value

A data.table of bar-level risk snapshots.

Description

Reconstruct simulation views from exported events

Usage

sim_run_from_events(path)

Arguments

Value

A data.table simulation result when a simulation table exists, otherwise event-level account state reconstructed from events.

Description

Missing columns are added with typed NA values and existing columns are retained unchanged. This makes older CSV/fst exports readable without silently discarding consumer-defined extension columns.

Usage

sim_schema_migrate(tables, from_version = NULL)

Arguments

Value

A named list upgraded to sim_schema_version().

Description

Get the tradesimr schema version

Usage

sim_schema_version()

Value

A scalar character schema version.

Description

Simulation table schemas

Usage

sim_schemas()

Value

A named list of empty data.tables representing durable simulation table schemas.

Description

This Rcpp-backed state machine is separate from the derivatives margin kernel. It models long-only inventory, quote-currency cash, fees, marked inventory value, dividends, and stock splits.

Usage

sim_spot_step(
  state = NULL,
  close,
  signed_qty = 0,
  execution_price = NA_real_,
  contract_size = 1,
  fee_rt = 0,
  dividend_per_unit = 0,
  split_ratio = 1
)

Arguments

Value

A list containing cash, units, average cost, market value, equity, P&L, fees, corporate-action cash, and execution status.

Description

This is the inventory-accounting counterpart to the derivatives portfolio target API. It plans all supplied spot legs from one completed boundary and emits only next-eligible explicit inventory orders.

Usage

sim_spot_target_submit(exchange, agent_id, bars, target_weights, fee_rt = 0)

Arguments

Value

A list of accepted orders and planned target quantities.

Description

Create a simulation state object

Usage

sim_state(
  cash = 10000,
  pos_dir = 0L,
  ctr_unit = 0,
  avg_price = NA_real_,
  last_px = 0,
  strat = 0L,
  asset = 0L,
  action_id_now = 1L,
  old_timestamp = NA_real_,
  liquidated = FALSE
)

Arguments

Value

A list suitable for sim_step().

Description

Writes the current exchange state using the god-facing live-state dashboard shell. This dashboard can configure and step the feed but cannot place orders.

Usage

sim_state_dashboard_export(exchange, path)

Arguments

Value

Invisibly returns a named character vector of written files.

Description

Processes one bar and a batch of explicit order actions against prior account state. This is the incremental primitive underneath future live exchange workflows; it does not replay earlier bars.

Usage

sim_step(
  state,
  bar,
  orders = data.frame(),
  asset = state$asset %||% 0L,
  ctr_size = 1,
  ctr_step = 1,
  lev = 10,
  fee_rt = 0,
  maker_fee_rt = NA_real_,
  taker_fee_rt = NA_real_,
  fund_rt = 0,
  funding_interval_hours = 8,
  mmr = 0.02,
  slippage = 0,
  spread = 0,
  record = TRUE
)

Arguments

Value

A list with state and events.

Description

List registered strategy ids

Usage

sim_strategy_list(exchange)

Arguments

Value

Character vector of registered strategy ids.

Description

Registered functions are runtime-only and are not serialized into exported CSV files. Store the durable strategy name in the agent config via strategy_id; register the function again after loading a saved exchange.

Usage

sim_strategy_register(exchange, strategy_id, strategy_fn)

Arguments

Value

The strategy id, invisibly.

Description

Unregister a strategy function

Usage

sim_strategy_unregister(exchange, strategy_id)

Arguments

Value

Invisibly returns TRUE when a strategy was removed.

Description

Checks that a strategy agent config points to a registered function or a resolvable function name, and that supplied param_ keys are compatible with the strategy function signature when the function does not accept ....

Usage

sim_strategy_validate_config(exchange, config)

Arguments

Value

A list with valid, message, strategy_id, strategy_fun, and params.

Description

Appends an order request to the exchange command log. By default the command is processed immediately into the same exchange order model used by sim_exchange_step().

Usage

sim_submit_order(
  exchange,
  agent_id,
  timestamp = Sys.time(),
  symbol = NULL,
  asset_id = NULL,
  tgt_pos = NULL,
  tol_pos = 0,
  order_type = c("market", "limit"),
  side = c("target", "buy", "sell", "flat"),
  qty_type = NULL,
  qty = NULL,
  limit_price = NA_real_,
  time_in_force = "gtc",
  client_order_id = NA_character_,
  process = TRUE
)

Arguments

Value

The generated command id.

Description

List built-in trading calendars

Usage

sim_trading_calendars()

Value

A data.table describing the deterministic built-in session rules.

Description

Heterogeneous account schema version

Usage

TRADESIMR_ACCOUNT_SCHEMA_VERSION

Format

An object of class character of length 1.

Description

tradesimr durable schema version

Usage

TRADESIMR_SCHEMA_VERSION

Format

An object of class character of length 1.

Description

Validate target-position intent columns

Usage

validate_intents(data, tgt_pos_col = "tgt_pos", tol_pos_col = NULL)

Arguments

Value

Invisibly returns TRUE on success.

Description

Validate core market-bar columns

Usage

validate_market_data(
  data,
  timestamp_col = "timestamp",
  open_col = "open",
  high_col = "high",
  low_col = "low",
  close_col = "close"
)

Arguments

Value

Invisibly returns TRUE on success.

Description

Legacy helper that loads candle data through strategyr and applies signal strategies before forming long, short, and both-side position series.

Usage

vec_batch_run_simulations(
  inst_ids,
  bar,
  signal_strategies,
  root_path = Sys.getenv("OKX_Candle_Data_Path"),
  bg_time = NULL,
  ed_time = NULL
)

Arguments

Value

A named list of data.tables.

Description

Plot vectorized simulation results

Usage

vec_sim_gen_plot(vec_sim_res, report_mode = c("simple", "full"))

Arguments

Description

Summarize vectorized simulation results

Usage

vec_sim_gen_summary(
  vec_sim_res,
  report_mode = c("short_txt", "long_txt", "dt")
)

Arguments

Value

Text or a one-row data.table depending on report_mode.

Description

Summarize a batch of vectorized simulations

Usage

vec_sim_gen_summary_table(DTs)

Arguments

Value

A data.table of summaries.

Description

Lightweight legacy helper that converts a precomputed position column into log returns and an equity curve. It does not model the stateful exchange, order, margin, funding, or liquidation mechanics used by sim_backtest().

Usage

vec_sim_run_backtest(DT)

Arguments

Value

A list containing equity series and summary statistics.