Skip to main content

​
Overview

The simulator.placeOrder endpoint places a simulated order in the exchange simulator. It supports both market and limit orders with configurable leverage and confidence levels.
This endpoint requires simulation mode to be enabled (IS_SIMULATION_ENABLED=true). Orders are executed against simulated market conditions and do not affect real funds.

​
Request

​
Parameters

​
accountId
string
The simulator account identifier. Defaults to "default" if not provided. Use different account IDs to simulate multiple portfolios.
​
symbol
string
required
Trading pair symbol (e.g., "BTC-USD", "ETH-USD"). Symbol is automatically trimmed of whitespace.
​
quantity
number
required
Order quantity in base currency. Must be a positive number.
​
side
enum<string>
required
Order side. Accepts: "buy", "sell", "long", or "short".
  • "buy" and "long" are equivalent (open/increase long position)
  • "sell" and "short" are equivalent (open/increase short position)
​
type
enum<string>
default:"market"
Order type. Accepts: "market" or "limit".
  • "market": Executes immediately at current market price
  • "limit": Executes only at specified limit price or better
​
limitPrice
number
Limit price for limit orders. Required when type is "limit". Must be a valid finite number.
​
price
number
Alternative parameter for limit price. If both limitPrice and price are provided, limitPrice takes precedence.
​
leverage
number
Position leverage multiplier. Must be a positive number. Allows trading with borrowed funds.Example: leverage: 5 means 5x leverage (controls 5000positionwith5000 position with 1000 margin).
​
confidence
number
AI model confidence level for the trade decision. Used for analytics and tracking.
  • Accepts values 0-1 (e.g., 0.85) or 0-100 (e.g., 85)
  • Values >1 are automatically normalized by dividing by 100
  • Invalid or zero values are stored as null

​
Response

​
order
object
The created order object containing execution details, position changes, and account state.

​
Code Example

import { useMutation, useQueryClient } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";

export function PlaceOrderButton() {
  const queryClient = useQueryClient();
  
  const placeOrder = useMutation({
    mutationFn: async (params: {
      symbol: string;
      quantity: number;
      side: "buy" | "sell" | "long" | "short";
      type?: "market" | "limit";
      limitPrice?: number;
      leverage?: number;
      confidence?: number;
    }) => {
      const result = await orpc.simulator.placeOrder.mutate(params);
      return result;
    },
    onSuccess: () => {
      // Invalidate account and positions queries
      queryClient.invalidateQueries({ queryKey: ["simulator", "getAccount"] });
    },
  });

  const handlePlaceTrade = () => {
    placeOrder.mutate({
      symbol: "BTC-USD",
      quantity: 0.5,
      side: "long",
      type: "market",
      leverage: 3,
      confidence: 0.85,
    });
  };

  return (
    <button 
      onClick={handlePlaceTrade}
      disabled={placeOrder.isPending}
    >
      {placeOrder.isPending ? "Placing Order..." : "Place Order"}
    </button>
  );
}

​
Behavior Details

​
Order Execution

  • Market orders: Execute immediately at current simulator market price
  • Limit orders: Execute only when market price reaches the limit price
  • Order fills update the account’s positions, cash balance, and margin

​
Account ID Normalization

Account IDs are automatically normalized:
  • Empty strings or whitespace-only values default to "default"
  • Trimmed to remove leading/trailing whitespace
  • Use consistent account IDs to maintain separate portfolio states

​
Side Normalization

The side parameter accepts multiple formats:
  • "buy" or "long" → normalized to "buy" (increase long position)
  • "sell" or "short" → normalized to "sell" (increase short position)

​
Validation

  • Symbol cannot be empty after trimming
  • Quantity must be positive
  • Limit price (if provided) must be a finite number
  • Leverage (if provided) must be positive
  • Validation errors throw descriptive error messages

​
Error Handling

Common errors:
ErrorCauseSolution
"Simulation mode is disabled"IS_SIMULATION_ENABLED=falseEnable simulation mode in environment config
"Symbol is required"Empty or whitespace-only symbolProvide valid trading pair symbol
"limitPrice must be a valid number"Non-finite limit priceProvide valid numeric limit price
"Failed to place order"Simulator execution errorCheck simulator logs, verify symbol exists, ensure sufficient margin
All orders are executed within the simulator’s isolated environment. Position and balance changes do not affect any live exchange accounts.

Build docs developers (and LLMs) love

Get started for freeTalk to us