Alpaca Trading Paper Trading CLI

Alpaca Paper Trading — CLI Version

Use this skill when you want your AI agent to preview, submit, inspect, and manage paper-trading orders using the Alpaca CLI.

This skill is written for you, a Trading API user working with your own Alpaca paper-trading account, CLI profile, and local workspace. Your agent executes all operations through the alpaca command-line tool, giving you full visibility into every command and its output.

This is the CLI-specific version. A generic (implementation-agnostic) version and an MCP-server version are also available as companion skills.

0 - How your AI agent should use this skill

1. Start with the signal source. Identify the origin of the trade idea — a backtest result, manual idea, scheduled trigger, or strategy output.
2. Reiterate strategy logic and confirm with you. Summarize the thesis, expected behavior, and conditions under which the order should execute. Wait for your confirmation before proceeding.
3. Gather and confirm ALL configurations. Timing, asset class, symbol, side, qty/notional, order type, TIF, limit/stop prices, extended-hours flag, risk controls, and margin usage — every parameter must be stated and confirmed.
4. Confirm the CLI resolves to the paper endpoint. Run alpaca doctor and require its Trading: line to read https://paper-api.alpaca.markets. If it shows the live endpoint, STOP immediately and alert you.
5. Show a complete order preview using a formatted table. Include the exact CLI command that will run.
6. Ask whether you want explicit confirmation before each order (default: ON). Respect your preference for the session.
7. Submit via alpaca order submit with the paper profile.
8. Return order ID, status, submitted payload, and next inspection commands so you can independently verify.
9. Monitor order lifecycle with alpaca order get. Report fills, rejections, cancellations with portfolio impact.
10. Never place live trades. Verify the resolved paper endpoint before every submission. If any ambiguity exists about the environment, STOP.

1 - Prerequisites

Alpaca CLI installed and on PATH

alpaca version

Install if needed:

# Homebrew (macOS / Linux)
brew install alpacahq/tap/cli

# Or with Go — requires $GOPATH/bin (typically ~/go/bin) on your PATH
go install github.com/alpacahq/cli/cmd/alpaca@latest

The CLI is in Alpha Preview. Commands, flags, and output formats may change between releases, which is why your agent discovers flags at runtime rather than trusting any list in this file.

Paper profile configured

alpaca profile login
# or with API key
alpaca profile login --api-key

Discover login options:

alpaca profile login --help

Connectivity verified

alpaca doctor

Your agent runs this before every trading session. If it fails, no orders are submitted.

Asset-class requirements

Environment

• A Go toolchain, only if installing via go install; the Homebrew formula ships a prebuilt binary and needs no Go
• uuidgen or equivalent (for client order IDs)

External jq is not required. The CLI ships a built-in --jq flag that filters its own JSON output.

2 - Gather inputs

Your agent collects the following before proceeding to order construction:

Strategy confirmation checklist

Before building the order, your agent confirms:

• Strategy logic is clearly stated
• You understand what the order will do
• Entry criteria are met (if from backtest/signal)
• Exit criteria / stop-loss plan discussed
• Position sizing is intentional
• Risk controls reviewed

3 - Source-of-truth references

Your agent uses these authoritative sources for validation:

CLI discovery rule

Your agent verifies flags at runtime rather than trusting this file:

alpaca --help-all              # full command tree with every flag
alpaca order submit --help     # flags for one command
alpaca order submit --schema   # response shape, without calling the API

The CLI is in Alpha Preview, so flags and output shapes can change between releases. Anything in this skill that contradicts --help output is stale; trust the CLI.

4 - Workflow

Phase 1: Strategy Confirmation

Step 1 — Identify the signal source.

Your agent asks: "Where does this trade idea come from?" Options include:

• A completed backtest (link to run folder if available)
• A manual trade idea you described
• A scheduled or recurring strategy trigger
• Output from another skill or system

Step 2 — Reiterate the strategy logic.

Your agent summarizes:

• Thesis (why this trade)
• Expected outcome
• Time horizon
• Exit conditions or stop-loss plan

Step 3 — Confirm interpretation.

Your agent asks: "Is this interpretation correct? Should I proceed to configure the order?"

Phase 2: Configuration Agreement

Step 4 — Confirm asset class and symbol.

Your agent validates the symbol format:

• Equities: AAPL, MSFT
• Options: OCC format AAPL250718C00200000
• Crypto: BTC/USD, ETH/USD

Format is necessary but not sufficient — a well-formed symbol can still be untradable or delisted. Your agent confirms it against the asset record:

alpaca asset get --symbol-or-asset-id AAPL

It requires status = active and tradable = true, and checks fractionable before proposing a notional or fractional-quantity order. For options, it resolves real contracts with alpaca option contracts --underlying-symbols AAPL rather than hand-assembling an OCC string.

Step 5 — Confirm side, quantity, and order type.

Step 6 — Confirm time-in-force and pricing parameters.

Time-in-force is not uniform across asset classes. Your agent validates the combination before building the command, because the API rejects the invalid ones:

The CLI supplies the time-in-force default itself based on symbol shape: a symbol containing / (i.e. a crypto pair) defaults to gtc, everything else to day. Submitting a crypto order without --time-in-force therefore sends gtc, not day.

Alpaca's own sources disagree on the options row, so treat it as guidance rather than a hard gate. The OpenAPI spec's TimeInForce/OrderType descriptions say options are market/limit with day only; the Options Trading page and the Placing Orders matrix both allow gtc and both allow stop/stop_limit on single-leg orders. The two product pages agree with each other against the spec blob, so this table follows them. Your agent still defaults to day as the conservative choice and lets Alpaca reject rather than pre-blocking an order that the matrix permits.

Additional constraints that cut across order type:

• Extended hours requires limit type with day or gtc TIF. Every other type and TIF is rejected outright.
• Trailing stop accepts only day and gtc.
• Notional orders are market-type with day TIF only, cannot be combined with qty, and cannot be replaced — cancel and resubmit instead.
• Bracket, OCO, and OTO classes require day or gtc, do not support extended hours, and are equities-only.
• Options do not support extended hours at all. Multi-leg strategies use the mleg order class with up to 4 legs, and stop/stop_limit types are single-leg only.

Step 7 — Confirm extended hours and client order ID preferences.

Alpaca supports three sessions outside regular hours, all of which require extended_hours: true on a limit order:

Not every asset trades overnight; your agent confirms eligibility on the asset record rather than assuming.

Step 8 — Review risk controls.

Your agent presents any position-sizing or max-value constraints and validates:

• Order notional vs. buying power
• New position concentration vs. portfolio
• Existing exposure to the same symbol

Step 9 — Final configuration summary.

Your agent displays a complete parameter table and asks: "All parameters confirmed?"

Phase 3: Paper Account Verification via CLI

Step 10 — Confirm the CLI resolves to the paper endpoint:

alpaca doctor

alpaca doctor prints the fully-resolved trading endpoint under Connectivity::

Connectivity:
  Trading:  https://paper-api.alpaca.markets

Your agent requires that line to read https://paper-api.alpaca.markets. The profile name is not a substitute. The CLI resolves paper vs. live in a fixed order — ALPACA_LIVE_TRADE first, then the active profile's live_trade field, then a paper default — so an exported ALPACA_LIVE_TRADE=true sends a profile named "paper" straight to the live endpoint. alpaca doctor reports the result of that whole chain.

⚠️ alpaca doctor ignores the -p/--profile flag. It accepts the flag and silently discards the value, always reporting the default profile. Every other command honors -p. So alpaca doctor -p live reports the paper endpoint while alpaca order submit -p live trades against the live one, and the guard passes while the order goes out live.

Your agent therefore never passes -p/--profile to any command. To target a non-default profile it sets ALPACA_PROFILE once for the whole session, which doctor does honor, so the check and the order resolve identically. If any command in the session is about to receive -p, your agent stops instead.

If the Trading: line shows https://api.alpaca.markets, your agent STOPS immediately:

⚠️ LIVE ENDPOINT DETECTED. Your agent will not proceed. Unset ALPACA_LIVE_TRADE (or set it to false, which forces paper even on a live profile), select a paper profile with alpaca profile switch <paper-profile-name>, and restart.

Step 11 — Confirm connectivity from the same alpaca doctor output.

Your agent confirms all checks pass. If any fail, it reports the failure and does not proceed. It does not re-run alpaca doctor; one invocation covers both this step and Step 10. alpaca doctor exits 0 when every check passes and 1 when any check fails.

Step 12 — Fetch account status:

alpaca account get

Your agent parses and verifies:

• status = ACTIVE
• account_blocked = false
• trading_blocked = false
• trade_suspended_by_user = false
• multiplier — margin classification, and the only PDT signal the account object carries: 1 is a limited-margin cash-style account, 2 is a Reg T margin account, 4 is a PDT account with 4x intraday buying power

The Trading API account object has no pattern_day_trader or daytrade_count field. Your agent must not read them; infer PDT status from multiplier instead.

Step 13 — Check buying power:

alpaca account get --jq '.buying_power'

Your agent compares estimated order value against available buying power. If insufficient, it warns you before proceeding.

Step 14 — For options orders, check approval level:

alpaca account get --jq '{options_approved_level, options_trading_level, options_buying_power}'

Your agent gates on options_trading_level, which is the effective level — the minimum of options_approved_level and the max_options_trading_level in account configuration. Approval alone does not authorize trading if configuration caps it lower.

Spreads require level 3, not level 2.

Step 15 — Show account summary.

Your agent presents:

┌─────────────────────────────────────┐
│ Paper Account Summary               │
├─────────────────────────────────────┤
│ Endpoint:      paper-api (PAPER)    │
│ Profile:       my-paper             │
│ Status:        ACTIVE               │
│ Equity:        $50,000.00           │
│ Buying Power:  $100,000.00          │
│ Multiplier:    2 (Reg T margin)     │
│ Options Level: 2 (effective)        │
│ Crypto:        ACTIVE               │
└─────────────────────────────────────┘

Phase 4: Order Preview

Step 16 — Build the CLI command but DO NOT execute yet.

Your agent constructs the full command and displays it, then validates it with --dry-run, which prints the request body the CLI would send without submitting anything:

alpaca order submit \
  --symbol AAPL \
  --side buy \
  --qty 10 \
  --type limit \
  --limit-price 185.50 \
  --time-in-force day \
  --client-order-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --dry-run

The command your agent shows you in the preview must be byte-identical to the one it later executes, minus --dry-run.

Step 17 — Display formatted order preview table:

┌─────────────────────────────────────────────┐
│ ORDER PREVIEW — NOT YET SUBMITTED           │
├─────────────────────────────────────────────┤
│ Symbol:         AAPL                        │
│ Side:           BUY                         │
│ Quantity:       10 shares                   │
│ Order Type:     LIMIT                       │
│ Limit Price:    $185.50                     │
│ Time in Force:  DAY                         │
│ Extended Hours: No                          │
│ Est. Value:     $1,855.00                   │
│ Buying Power:   $100,000.00 → $98,145.00   │
│ Client ID:      a1b2c3d4-...               │
│ Endpoint:       paper-api (PAPER)           │
├─────────────────────────────────────────────┤
│ ⚠️  This is a PAPER trade — no real money   │
└─────────────────────────────────────────────┘

Step 18 — If confirmation is ON: wait for explicit "yes" before proceeding.

Step 19 — If confirmation is OFF: show the preview, then submit automatically.

Phase 5: Order Submission

Step 20 — Execute the CLI command:

CLIENT_ORDER_ID="$(uuidgen)"

alpaca order submit \
  --symbol AAPL \
  --side buy \
  --qty 10 \
  --type limit \
  --limit-price 185.50 \
  --time-in-force day \
  --client-order-id "$CLIENT_ORDER_ID"

Your agent captures CLIENT_ORDER_ID before submitting, so the order stays recoverable if the command dies before printing a response.

Step 21 — Save raw CLI output to the run folder:

# Output saved to runs/<timestamp>-paper-trading-cli/raw/order_submit_response.json

Step 22 — Parse response for key fields:

• id (order ID)
• status (expected: new or accepted)
• created_at
• filled_at (null for pending)
• filled_qty
• filled_avg_price

Step 23 — On failure:

• Capture the structured JSON error from stderr and the CLI exit code — 0 success, 1 error, 2 auth failure
• Show remediation guidance (e.g., "insufficient buying power", "symbol not found", "market closed")
• Save error to runs/<timestamp>/raw/error.json
• Suggest corrective actions

If the failure is ambiguous — a timeout, a killed process, any case where your agent cannot tell whether the order reached Alpaca — it must not resubmit. It looks the order up by the client order ID it generated in Step 20:

alpaca order get-by-client-id --client-order-id "$CLIENT_ORDER_ID"

A hit means the order exists and resubmitting would duplicate it. Only a confirmed miss justifies a retry.

Phase 6: Post-Submission Monitoring

Step 24 — Check order status:

alpaca order get --order-id {order_id}

Your agent reports:

• Current status
• Fill progress (partial fills)
• Average fill price

Step 25 — List recent orders for context:

alpaca order list --status open

Step 26 — Return order summary to you:

┌─────────────────────────────────────────────┐
│ ORDER SUBMITTED ✓                           │
├─────────────────────────────────────────────┤
│ Order ID:      abc-123-def-456              │
│ Status:        NEW                          │
│ Symbol:        AAPL                         │
│ Side/Qty:      BUY 10                       │
│ Type:          LIMIT @ $185.50              │
│ Submitted:     2026-07-26T14:30:00Z         │
├─────────────────────────────────────────────┤
│ Next commands:                              │
│  alpaca order get --order-id abc-123      │
│  alpaca order cancel --order-id abc-123     │
│  alpaca position list                     │
└─────────────────────────────────────────────┘

Step 27 — Order lifecycle updates:

Phase 7: Portfolio Impact

Step 28 — Fetch positions:

alpaca position list

Or for a specific symbol:

alpaca position get --symbol-or-asset-id AAPL

Step 29 — Fetch updated account:

alpaca account get

Step 30 — Show portfolio risk summary:

┌─────────────────────────────────────────────┐
│ PORTFOLIO IMPACT                            │
├─────────────────────────────────────────────┤
│ New Position:   AAPL — 10 shares @ $185.30  │
│ Position Value: $1,853.00                   │
│ Portfolio %:    0.74%                       │
│ Buying Power:   $98,147.00 (was $100,000)   │
│ Total Equity:   $250,000.00                 │
│ Open Orders:    1                           │
└─────────────────────────────────────────────┘