Skip to main content

Documentation Index

Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

When you run trading strategies on Scalar Field, the platform maintains a position ledger for each strategy — tracking what it owns, its cash balance, and its trade history. Since multiple strategies can share a single brokerage account, the platform must continuously verify that the sum of all strategy positions matches what the broker actually holds. This process is called reconciliation. It runs automatically and requires no action from you under normal conditions.

​
How Reconciliation Works

Reconciliation happens in three phases, triggered automatically every time you call strategy.state(), strategy.execute(), strategy.liquidate(), or strategy.cancel().

​
Phase 1: Pending Order Tracking

For brokerages where orders fill asynchronously (like Alpaca), the platform checks the status of every pending order with the broker:
  • Filled orders: The fill is applied to your strategy’s positions and cash. Your position quantity updates, cash is debited (for buys) or credited (for sells), and any platform fees are deducted.
  • Cancelled or expired orders: The order is marked as terminal. If the order was partially filled before cancellation, the filled portion is applied and the remainder is released.
For synchronous venues (Polymarket, Jupiter DEX), fills are confirmed inline during order placement — there are no pending orders to reconcile.

​
Phase 2: Aggregate Position Verification

After pending orders are resolved, the platform performs an aggregate check:
  1. Sum all strategy positions across every strategy on the same brokerage account, grouped by symbol.
  2. Fetch the broker’s actual holdings.
  3. Compare the aggregate to the broker’s positions.
If there are in-flight orders (e.g. a pending Alpaca order targeting a specific quantity), the platform accounts for these by using a protected floor — the minimum quantity the broker should hold given the outstanding targets. This prevents false alarms from orders that are expected to change the position.

​
Phase 3: Settlement Grace Period

After a trade, positions may not update instantly at the broker — especially on-chain venues where blockchain confirmations take time. The platform allows a settlement grace window before flagging any mismatch:
Venue TypeGrace Period
Traditional brokerages (Alpaca)2 minutes
On-chain venues (Polymarket, Jupiter DEX)10 minutes
During the grace window, the platform will not freeze a strategy even if the aggregate and broker positions diverge. Once the window expires, any remaining discrepancy triggers a freeze.

​
What Happens When a Discrepancy Is Detected

If the broker holds fewer shares of a symbol than the aggregate of all strategies claims to own — and the settlement grace period has passed — the affected strategy is automatically frozen. When frozen:
  • The strategy cannot place new orders (strategy.execute() returns BLOCKED with reason STRATEGY_FROZEN_RECONCILIATION_MISMATCH).
  • The strategy’s scheduled execution continues to run, but any trade attempts will be rejected.
  • Other strategies on the same brokerage account are not affected unless they also have discrepancies.
A strategy is frozen only when broker holdings drop below its protected floor — the shares the strategy must still own. External buys at the broker (adding shares outside Scalar Field) do not cause a freeze.

​
Unfreezing a Strategy

You can unfreeze a frozen strategy from the strategy detail page in the Scalar Field UI:
  1. Review the discrepancy: The unfreeze panel shows each symbol with your strategy’s expected quantity alongside the broker’s actual quantity.
  2. Adjust targets (optional): You can override the target quantity for each symbol if you want to align to a different position than the broker holds.
  3. Confirm unfreeze: The platform cancels any remaining pending broker orders, realigns your strategy’s position book and cash to match reality, and resumes trading.
After unfreezing, the strategy returns to the Active state and can place orders again.

​
Common Causes of Position Mismatches

CauseExplanation
Trading outside Scalar FieldPlacing trades directly on the brokerage (e.g. through the Alpaca dashboard) while strategies are active. The broker’s positions change, but strategy ledgers do not know about it.
Network or API delaysTemporary delays in order status updates from the broker. Usually resolved within the settlement grace period.
Partial fillsAn order that fills partially and then expires. The filled portion is applied, but the remaining quantity may create a temporary mismatch until reconciliation runs.

​
Best Practices

  • Avoid trading directly on the brokerage while strategies are active. Use Scalar Field’s chat trading (venue.trade()) or strategy agents (strategy.execute()) so the platform can track all orders.
  • Check strategy state after every execution. Call strategy.state() to see reconciled positions, and use it as the source of truth rather than tracking positions locally.
  • Don’t panic on PENDING. Alpaca orders submitted during market hours typically fill within seconds. Orders submitted outside market hours will remain PENDING until the next market open — this is normal.
  • Review frozen strategies promptly. A frozen strategy cannot trade, which means it may miss scheduled executions. Unfreeze as soon as you can review and confirm the correct position targets.