Get Account

Overview

The simulator.getAccount endpoint retrieves the current snapshot of a simulated trading account, including cash balances, open positions, margin usage, and profit/loss calculations.

This endpoint requires simulation mode to be enabled (IS_SIMULATION_ENABLED=true).

Request

Parameters

string

The simulator account identifier. Defaults to "default" if not provided.Use different account IDs to maintain separate simulated portfolios with independent balances and positions.

Response

object

Complete account snapshot containing balances, positions, and P&L.

number

Total cash in the account (includes borrowed balance if negative).

number

Cash available for new positions after accounting for margin requirements.

number

Amount of borrowed funds (used when trading with leverage or shorting).

number

Total account value: cashBalance + totalUnrealizedPnl.

number

Total margin locked in open positions.

string

Quote currency for all monetary values (e.g., "USD").

number

Cumulative realized profit/loss from closed positions.

number

Current unrealized profit/loss from all open positions.

array

Array of open positions.

string

Trading pair symbol (e.g., "BTC-USD").

enum<string>

Position direction: "LONG" or "SHORT".

number

Position size in base currency.

number

Average entry price for the position (weighted by quantity).

number

Realized P&L from partial closes of this position.

number

Current unrealized P&L based on mark price.

number

Current market price used for P&L calculations.

number

Margin locked for this position.

number

Position notional value: quantity * markPrice.

number | null

Leverage multiplier used when opening the position (if applicable).

object | null

Planned exit levels (if set).

number | null

Stop loss price level.

number | null

Take profit price level.

string | null

Conditions that invalidate the trade thesis.

Code Example

import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";

export function AccountSummary() {
  const { data, isLoading, error } = useQuery(
    orpc.simulator.getAccount.queryOptions({
      input: {
        accountId: "default", // optional, defaults to "default"
      },
    })
  );

  if (isLoading) return <div>Loading account...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!data) return null;

  const { account } = data;

  return (
    <div className="space-y-4">
      <div className="grid grid-cols-2 gap-4">
        <div>
          <h3>Equity</h3>
          <p className="text-2xl font-bold">
            ${account.equity.toFixed(2)}
          </p>
        </div>
        <div>
          <h3>Available Cash</h3>
          <p className="text-2xl">
            ${account.availableCash.toFixed(2)}
          </p>
        </div>
      </div>

      <div className="grid grid-cols-2 gap-4">
        <div>
          <h3>Realized P&L</h3>
          <p className={account.totalRealizedPnl >= 0 ? "text-green-500" : "text-red-500"}>
            ${account.totalRealizedPnl.toFixed(2)}
          </p>
        </div>
        <div>
          <h3>Unrealized P&L</h3>
          <p className={account.totalUnrealizedPnl >= 0 ? "text-green-500" : "text-red-500"}>
            ${account.totalUnrealizedPnl.toFixed(2)}
          </p>
        </div>
      </div>

      <div>
        <h3>Open Positions ({account.positions.length})</h3>
        {account.positions.map((position) => (
          <div key={position.symbol} className="border p-4 rounded">
            <div className="flex justify-between">
              <span className="font-bold">{position.symbol}</span>
              <span className={position.side === "LONG" ? "text-green-500" : "text-red-500"}>
                {position.side}
              </span>
            </div>
            <div className="grid grid-cols-3 gap-2 mt-2 text-sm">
              <div>
                <span className="text-gray-500">Quantity:</span> {position.quantity}
              </div>
              <div>
                <span className="text-gray-500">Entry:</span> ${position.avgEntryPrice.toFixed(2)}
              </div>
              <div>
                <span className="text-gray-500">Mark:</span> ${position.markPrice.toFixed(2)}
              </div>
            </div>
            <div className="mt-2">
              <span className="text-gray-500">Unrealized P&L:</span>
              <span className={position.unrealizedPnl >= 0 ? "text-green-500" : "text-red-500"}>
                {" "}${position.unrealizedPnl.toFixed(2)}
              </span>
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}

Account State Structure

The account snapshot represents the complete state at the time of the request:

Balance Components

Cash Balance: Starting capital + realized P&L ± borrowed funds
Available Cash: Cash not locked as margin (available for new trades)
Borrowed Balance: Negative balance from leverage or short selling
Equity: True account value including unrealized P&L
Margin Balance: Locked funds backing open positions

Position Tracking

Each position maintains:

Average entry price (weighted by partial fills)
Separate realized/unrealized P&L (partial closes tracked)
Current mark price (real-time market data)
Margin requirement (varies by leverage)
Optional exit plan (stop loss, take profit targets)

Real-Time Updates

Account state reflects:

All executed orders (market and limit fills)
Current market prices for unrealized P&L
Margin requirements based on position sizes
Borrowed balance changes from leverage use

Use Cases

Portfolio Dashboard

Display account equity, available cash, and position summaries in a trading dashboard.

Risk Management

Monitor margin usage, leverage exposure, and unrealized P&L to manage risk.

Performance Analytics

Track realized P&L over time and compare against equity changes.

Position Monitoring

List all open positions with entry prices, current P&L, and exit plans.

Error Handling

Error	Cause	Solution
`"Simulation mode is disabled"`	`IS_SIMULATION_ENABLED=false`	Enable simulation mode in environment config

Account state is computed in real-time from the simulator’s in-memory state. For persistent storage, the simulator rehydrates from the database Orders table on bootstrap.

Overview

Trading

Models & Invocations

Simulator

Analytics

Variants

Overview

Request

Parameters

Response

Code Example

Account State Structure

Balance Components

Position Tracking

Real-Time Updates

Use Cases

Portfolio Dashboard

Risk Management

Performance Analytics

Position Monitoring

Error Handling

​Overview

​Request

​Parameters

​Response

​Code Example

​Account State Structure

​Balance Components

​Position Tracking

​Real-Time Updates

​Use Cases

​Portfolio Dashboard

​Risk Management

​Performance Analytics

​Position Monitoring

​Error Handling

Overview

Request

Parameters

Response

Code Example

Account State Structure

Balance Components

Position Tracking

Real-Time Updates

Use Cases

Portfolio Dashboard

Risk Management

Performance Analytics

Position Monitoring

Error Handling