> ## 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.

# Reconciliation

> How Scalar Field keeps strategy positions in sync with your brokerage account — pending order tracking, aggregate position verification, settlement grace periods, and the freeze/unfreeze flow.

# 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

```mermaid theme={null}
sequenceDiagram
    participant Strategy as Your Strategy
    participant Platform as Scalar Field
    participant Broker as Brokerage

    Strategy->>Platform: strategy.state() or strategy.execute()
    Platform->>Broker: Check pending order statuses
    Broker-->>Platform: Order fills / cancellations
    Platform->>Platform: Apply fills to strategy positions & cash
    Platform->>Broker: Fetch actual holdings
    Platform->>Platform: Compare aggregate strategy positions vs broker
    alt Positions match
        Platform-->>Strategy: Return updated state (tradable: true)
    else Discrepancy detected
        Platform->>Platform: Check settlement grace period
        alt Within grace period
            Platform-->>Strategy: Return state normally
        else Grace period expired
            Platform->>Platform: Freeze strategy
            Platform-->>Strategy: Return state (tradable: false, reason: frozen)
        end
    end
```

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 Type                                | Grace Period |
| ----------------------------------------- | ------------ |
| Traditional brokerages (Alpaca)           | 2 minutes    |
| Hyperliquid                               | 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**.

On **Hyperliquid**, one extra step runs first: a divergence in either direction may be an **exchange (forced) liquidation** of the shared account. Before deciding to freeze, the platform scans the account's recent fills for liquidation markers and, if found, applies those closes to the affected agents pro-rata at the actual liquidation price — see [Hyperliquid Agent Architecture](/docs/trading/venues/hyperliquid-agents). Only a divergence that liquidation fills cannot explain leads to a freeze.

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.

<Info>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.</Info>

# 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

| Cause                            | Explanation                                                                                                                                                                         |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trading outside Scalar Field** | Placing 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 delays**        | Temporary delays in order status updates from the broker. Usually resolved within the settlement grace period.                                                                      |
| **Partial fills**                | An 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.