Overview
The simulator.resetAccount endpoint resets a simulated trading account to its initial configuration, clearing all positions and restoring the starting balance.
This action is irreversible and will:
- Close all open positions
- Reset cash balance to initial capital
- Clear all realized/unrealized P&L
- Remove account history (positions, orders)
Use with caution. This is typically used when starting a new simulation or testing scenario. Request
Parameters
The simulator account identifier to reset. Defaults to "default" if not provided.Each account ID maintains independent state, so resetting one account does not affect others.
Response
The reset account snapshot with initial balances and no positions.Cash balance reset to initial capital (e.g., 10000).
Available cash equals cash balance (no positions using margin).
Always 0 after reset (no leverage or borrowed funds).
Equity equals cash balance (no unrealized P&L).
Always 0 after reset (no open positions).
Quote currency (e.g., "USD").
Always empty array [] after reset.
Code Example
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";
import { useState } from "react";
export function ResetAccountButton() {
const queryClient = useQueryClient();
const [showConfirm, setShowConfirm] = useState(false);
const resetAccount = useMutation({
mutationFn: async (accountId?: string) => {
const result = await orpc.simulator.resetAccount.mutate({ accountId });
return result;
},
onSuccess: () => {
// Invalidate all simulator queries to refresh UI
queryClient.invalidateQueries({ queryKey: ["simulator"] });
setShowConfirm(false);
},
});
const handleReset = () => {
resetAccount.mutate("default");
};
if (!showConfirm) {
return (
<button
onClick={() => setShowConfirm(true)}
className="bg-red-500 text-white px-4 py-2 rounded"
>
Reset Account
</button>
);
}
return (
<div className="space-y-2">
<p className="text-red-500 font-bold">
Warning: This will close all positions and reset your balance!
</p>
<div className="flex gap-2">
<button
onClick={handleReset}
disabled={resetAccount.isPending}
className="bg-red-600 text-white px-4 py-2 rounded"
>
{resetAccount.isPending ? "Resetting..." : "Confirm Reset"}
</button>
<button
onClick={() => setShowConfirm(false)}
className="bg-gray-300 px-4 py-2 rounded"
>
Cancel
</button>
</div>
</div>
);
}
Reset Behavior
What Gets Reset
- Positions: All open positions are immediately closed
- Cash Balance: Restored to initial capital (configured in simulator options)
- P&L: Both realized and unrealized P&L reset to zero
- Margin: All margin is released
- Borrowed Balance: Cleared to zero
What Persists
- Simulator configuration (initial capital, margin requirements, etc.)
- Market data (price feeds continue operating)
- Other accounts (only the specified account ID is reset)
Initial State
After reset, the account returns to:
{
"cashBalance": 10000,
"availableCash": 10000,
"borrowedBalance": 0,
"equity": 10000,
"marginBalance": 0,
"quoteCurrency": "USD",
"totalRealizedPnl": 0,
"totalUnrealizedPnl": 0,
"positions": []
}
Use Cases
Testing New Strategies
Reset the account to test different trading strategies from a clean slate:
// Reset before backtesting new strategy
await orpc.simulator.resetAccount.mutate({ accountId: "strategy-test" });
// Execute strategy trades
await orpc.simulator.placeOrder.mutate({
accountId: "strategy-test",
symbol: "BTC-USD",
quantity: 1,
side: "buy"
});
Multiple Simulation Scenarios
Use different account IDs for parallel simulations:
// Scenario A: Conservative
await orpc.simulator.resetAccount.mutate({ accountId: "conservative" });
// Scenario B: Aggressive
await orpc.simulator.resetAccount.mutate({ accountId: "aggressive" });
Recovery from Errors
Reset if the simulator state becomes inconsistent:
try {
// Attempt risky operation
await orpc.simulator.placeOrder.mutate({ /* ... */ });
} catch (error) {
// Reset on error
await orpc.simulator.resetAccount.mutate();
}
Account ID Management
Default Account
If no account ID is provided, the "default" account is reset:
// These are equivalent
await orpc.simulator.resetAccount.mutate({});
await orpc.simulator.resetAccount.mutate({ accountId: "default" });
Named Accounts
Use custom account IDs for isolation:
// Reset specific named account
await orpc.simulator.resetAccount.mutate({ accountId: "model-apex-test" });
Whitespace Normalization
Account IDs are automatically trimmed:
// These all reset the "default" account
await orpc.simulator.resetAccount.mutate({ accountId: "" });
await orpc.simulator.resetAccount.mutate({ accountId: " " });
await orpc.simulator.resetAccount.mutate({ accountId: "\t" });
Error Handling
| Error | Cause | Solution |
|---|
"Simulation mode is disabled" | IS_SIMULATION_ENABLED=false | Enable simulation mode in environment config |
"Failed to reset account" | Simulator internal error | Check simulator logs for details |
- Fast operation: Reset is near-instantaneous (clears in-memory state)
- No database impact: Simulator state is ephemeral (rehydrates from DB on restart)
- Safe concurrency: Each account ID is isolated
Resetting an account does not affect historical trade data stored in the database. If you need to clear historical records, use database cleanup operations separately.
Best Practices
- Confirm before reset: Always show a confirmation dialog to prevent accidental resets
- Invalidate queries: Refresh all related TanStack Query caches after reset
- Use named accounts: Avoid resetting
"default" account in multi-user scenarios
- Log resets: Track reset events for audit trails
- Test in isolation: Use separate account IDs for testing vs. production simulations
