Orders & Execution

All order execution follows the Trading-as-Git workflow: stage → commit → push. This page covers the order types, parameters, and reading tools available.

Order Types

Type	Required Parameters	Description
`MKT`	`totalQuantity` or `cashQty`	Market order — execute immediately at best available price
`LMT`	`totalQuantity` + `lmtPrice`	Limit order — execute at specified price or better
`STP`	`totalQuantity` + `auxPrice`	Stop order — becomes market order when stop price is hit
`STP LMT`	`totalQuantity` + `auxPrice` + `lmtPrice`	Stop-limit — becomes limit order when stop price is hit
`TRAIL`	`totalQuantity` + `auxPrice` or `trailingPercent`	Trailing stop — stop price trails the market by a fixed offset
`TRAIL LIMIT`	`totalQuantity` + `auxPrice` + `lmtPrice`	Trailing stop-limit — trailing stop that becomes a limit order
`MOC`	`totalQuantity`	Market-on-close — execute at the closing price

Quantity options:

totalQuantity — Number of shares/contracts
cashQty — Dollar amount (mutually exclusive with totalQuantity, broker support varies)

Time in Force

TIF	Description
`DAY`	Expires at end of trading day (default)
`GTC`	Good till cancelled
`IOC`	Immediate or cancel — fill what you can, cancel the rest
`FOK`	Fill or kill — fill entirely or cancel
`OPG`	Opening — execute at the market open
`GTD`	Good till date — requires `goodTillDate` parameter

Take Profit & Stop Loss (TPSL)

Attach automatic exit orders when placing an entry order:

Buy 100 shares of AAPL at market with a take profit at $200
and a stop loss at $175.

Alice stages this as a single placeOrder with TPSL parameters:

{
  "action": "BUY",
  "orderType": "MKT",
  "totalQuantity": 100,
  "takeProfit": { "price": "200" },
  "stopLoss": { "price": "175" }
}

The broker creates the bracket automatically — the take profit and stop loss are linked to the parent order with One-Cancels-All (OCA) logic.

For a stop-limit stop loss, add limitPrice:

{
  "stopLoss": { "price": "175", "limitPrice": "174.50" }
}

Full Execution Flow

1. placeOrder          → Stage the order
2. tradingCommit       → Bundle with a message, get commit hash
3. tradingPush         → Request execution (requires your approval)
4. [User approves]     → Guards run, order sent to broker
5. tradingSync         → Check fill status from broker

Staging

The placeOrder tool stages an operation without executing it. Multiple orders can be staged before committing:

Stage: BUY 10 AAPL @ MKT
Stage: SELL 5 NVDA @ LMT 135.00

Committing

tradingCommit bundles all staged operations with a descriptive message:

Commit a3f8c1d2: "Rotate portfolio — reduce NVDA, add AAPL"
  2 operations staged

Pushing

tradingPush signals that the commit is ready for execution. The push requires manual approval in the Web UI — Alice cannot bypass this step.

When approved:

The guard pipeline evaluates each operation
Approved operations are dispatched to the broker
Results are recorded (submitted/filled/rejected)
A snapshot captures the account state

Syncing

After pushing, orders may not fill immediately. tradingSync checks the broker for updates:

tradingSync(delayMs: 3000)  // Wait 3s for exchange to settle, then check

Reading Tools

Tool	Description
`getAccount`	Account info: net liquidation, cash, buying power, P&L
`getPortfolio`	Current positions with unrealized P&L and portfolio weight
`getOrders`	Pending orders (or specific orders by ID)
`getQuote`	Latest price for a contract
`getMarketClock`	Market open/close status and schedule
`tradingLog`	Commit history (filterable by symbol)
`tradingShow`	Details of a specific commit by hash
`tradingStatus`	Current staging area contents
`simulatePriceChange`	Dry-run portfolio impact of price movements

Multi-Account Queries

Most reading tools accept an optional source parameter:

Omit — Query all enabled accounts
Account ID — Target a specific account (e.g. "alpaca-paper")
Broker type — Target all accounts of a type (e.g. "ccxt")

Price Simulation

The simulatePriceChange tool lets you model portfolio impact without placing orders:

What would happen if AAPL dropped 10% and NVDA went to $150?

Alice calls simulatePriceChange with:

{
  "priceChanges": [
    { "symbol": "AAPL", "change": "-10%" },
    { "symbol": "NVDA", "change": "@150" }
  ]
}

Returns current vs simulated equity, P&L changes per position, and worst-case analysis.

Financial Precision

All monetary calculations use decimal.js for arbitrary-precision decimal arithmetic. This prevents floating-point errors that could affect order quantities and P&L calculations.

Search Documentation