alpacahq/alpaca-skills/trading-orders

Alpaca Broker API — Trading on Behalf of Accounts

Place, modify, cancel, and track orders for an end-user account, and read positions & buying power. The defining feature of Broker API trading: `account_id` is in the path — you act for a user account, not your own.

Read alpaca-broker-integration first for base URLs and auth (client-credentials Bearer token; legacy Basic still works). (The standalone Trading API uses /v2/orders with no account in the path; everything else here transfers.)

Reference

• Guides: https://docs.alpaca.markets/docs/orders-at-alpaca, https://docs.alpaca.markets/docs/fractional-trading
• API ref: https://docs.alpaca.markets/reference/postorder
• Live schema: alpaca-docs MCP → get-endpoint title "Broker API" path /v1/trading/accounts/{account_id}/orders

1. Endpoints

2. Create-order request

Schema-required: type and time_in_force. Conditionally required: symbol, side, and exactly one of qty/notional.

// notional market buy (dollar-based, fractional)
{ "symbol": "AAPL", "notional": "25.00", "side": "buy", "type": "market", "time_in_force": "day",
  "client_order_id": "your-own-uuid" }
// limit qty sell
{ "symbol": "AAPL", "qty": "3", "side": "sell", "type": "limit", "limit_price": "190.00", "time_in_force": "gtc" }

qty XOR notional (verbatim rule): pass one or the other — supplying both → 400. In the response, whichever you didn't use comes back null.

3. Fractional / notional rules

• On by default for all accounts (live + paper).
• Asset must have `fractionable: true` (check the Assets API — see alpaca-broker-market-data), else requested asset is not fractionable.
• TIF must be `day` for fractional/notional.
• Notional is limited to market and limit (day); only limit for extended hours.
• No shorting fractional — all fractional sells are marked long.
• Precision: 2 decimal places for `notional`, 9 for `qty` (Broker API FAQ, "What is the precision for notional and qty"; the order schema's "2 decimal points" on qty is stale). Eligible types: the order schema says fractional qty only on market+day; the Fractional Trading guide also accepts limit/stop/stop_limit at TIF day — confirm in sandbox before relying on the wider set.

4. Order status lifecycle

OrderStatus (the order object's status): new, partially_filled, filled, done_for_day, canceled, expired, replaced, pending_cancel, pending_replace, accepted, pending_new, accepted_for_bidding, stopped, rejected, suspended, calculated.

Order `status` ≠ trade-event `event`. The order object's status is the enum above. The SSE trade-update stream reports a richer event enum that adds operational events with no Broker order status — trade_bust, trade_correct, restated, order_cancel_rejected, order_replace_rejected. held is both: a trade event, and an OrderStatus in the Trading API enum though not in the Broker one, so don't assume the two enums match. See alpaca-broker-sse-events.

Terminal: filled, canceled, expired, rejected (and replaced for the original order). Everything else is in-flight.

Early-state distinctions (these trip people up):

• accepted — received by Alpaca, not yet routed to a venue (common outside market hours).
• new — received and routed to exchanges; the usual initial live state.
• pending_new — routed but not yet accepted for execution (rare).

An order usually reaches new directly; accepted/pending_new are rare intermediates. Lesson: treat new/accepted/pending_new as "exists but not done." Persist the order on submit, then update on fill/cancel/reject events — don't block the user waiting for a terminal state synchronously.

5. Positions & trading account

`Position` key fields: symbol, asset_id, qty, qty_available (free of open orders), side (long/short), avg_entry_price, market_value, cost_basis, unrealized_pl, unrealized_plpc, current_price, change_today.

`TradeAccount` key fields:

• buying_power (with margin multiplier 1–4), cash, cash_withdrawable, equity, last_equity.
• Blockers: trading_blocked, account_blocked, transfers_blocked, trade_suspended_by_user.
• multiplier, regt_buying_power, non_marginable_buying_power, long_market_value, initial_margin, maintenance_margin, sma.

Lesson — check buying power before notional orders. For a "spend $X" UX, read buying_power/cash first and reject/notify on insufficient funds, rather than letting Alpaca reject the order. Re-read it after every accepted order — each one consumes buying power.

PDT/day-trade fields are gone following FINRA's intraday-margin rule change: daytrade_count, pattern_day_trader, daytrading_buying_power and bod_dtbp are absent from the current TradeAccount schema, as are the dtbp_check/pdt_check configurations. Don't code against them.

6. Documented gotchas

• Minimum order value: every buy order needs a market value of at least $1 or it's rejected with 422; sells are exempt.
• Per-asset-class rules: options and crypto go through this same endpoint, gated by asset_class — crypto rejects time_in_force: day (only gtc/ioc) and allows only market/limit/stop_limit; options allow day/gtc only. Check the type/TIF matrix in the OrderType/TimeInForce descriptions at https://docs.alpaca.markets/reference/createorderforaccount rather than assuming the equity set.
• Wash-trade rejection (403): if a user's two orders could self-cross (opposite sides, crossable prices), Alpaca rejects. Opposing market/stop pairs are always rejected; opposing limits rejected when buy-limit ≥ sell-limit. Use `bracket`/`oco`/`trailing_stop` for simultaneous take-profit + stop-loss — they're exempt.
• Bracket constraints: requires both take_profit.limit_price and stop_loss.stop_price; TP must be above SL for a buy; no extended hours; TIF day/gtc; child legs activate only after the entry fully fills; canceling one cancels the group.
• Notional orders can't be replaced — cancel and resubmit (IPO-class notional is the exception). Fractional qty can't be changed on replace ("full shares only").
• Replace ≠ guaranteed: a 200 from PATCH can still be rejected if the original fills first; watch the trade-updates stream. Can't replace while accepted/pending_new/pending_cancel/pending_replace.
• Cancel semantics: single cancel → 204, or 422 if no longer cancelable; cancel-all → 207 per-order results; close-all positions → 207. Close-single accepts mutually-exclusive qty or percentage.

7. Idempotency & recurring-invest lessons

• Always set `client_order_id` from your own transaction record. It's your dedup key and lets you look the order up (orders:by_client_order_id) if the create response is lost. Note it dedups lookup, not necessarily replay — combine it with a local "already-submitted?" guard.
• Recurring/scheduled buys (lesson): the robust pattern is — fetch pending invest instructions from your DB → check buying power → place a notional market/day order per instruction → record the returned order → mark the instruction done only after a successful create. On insufficient funds, skip this run and surface it; whether to cancel a standing instruction is a product decision. Schedule the batch shortly before market open and respect the market clock (alpaca-broker-market-data).
• Track fills via the trade events SSE stream, not by polling each order — see alpaca-broker-sse-events.

Related skills: prices/assets/clock → alpaca-broker-market-data; fills in real time → alpaca-broker-sse-events; rate limits on bulk placement → alpaca-broker-rate-limits-resilience; money formatting → alpaca-broker-money-precision.