Skip to main content

​
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

​
accountId
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

​
account
object
Complete account snapshot containing balances, positions, and P&L.
​
cashBalance
number
Total cash in the account (includes borrowed balance if negative).
​
availableCash
number
Cash available for new positions after accounting for margin requirements.
​
borrowedBalance
number
Amount of borrowed funds (used when trading with leverage or shorting).
​
equity
number
Total account value: cashBalance + totalUnrealizedPnl.
​
marginBalance
number
Total margin locked in open positions.
​
quoteCurrency
string
Quote currency for all monetary values (e.g., "USD").
​
totalRealizedPnl
number
Cumulative realized profit/loss from closed positions.
​
totalUnrealizedPnl
number
Current unrealized profit/loss from all open positions.
​
positions
array
Array of open positions.
​
symbol
string
Trading pair symbol (e.g., "BTC-USD").
​
side
enum<string>
Position direction: "LONG" or "SHORT".
​
quantity
number
Position size in base currency.
​
avgEntryPrice
number
Average entry price for the position (weighted by quantity).
​
realizedPnl
number
Realized P&L from partial closes of this position.
​
unrealizedPnl
number
Current unrealized P&L based on mark price.
​
markPrice
number
Current market price used for P&L calculations.
​
margin
number
Margin locked for this position.
​
notional
number
Position notional value: quantity * markPrice.
​
leverage
number | null
Leverage multiplier used when opening the position (if applicable).
​
exitPlan
object | null
Planned exit levels (if set).
​
stop
number | null
Stop loss price level.
​
target
number | null
Take profit price level.
​
invalidation
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

ErrorCauseSolution
"Simulation mode is disabled"IS_SIMULATION_ENABLED=falseEnable 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us