/paper-trading-cli

name: alpaca-trading-paper-trading-cli
description: >
  Preview, submit, inspect, and manage Alpaca paper-trading orders using the
  Alpaca CLI. Supports US equities, options, and crypto. Use this skill when
  you want your AI agent to take a strategy signal and execute it as a paper
  trade through the Alpaca command-line interface.

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

| Asset class | Requirement | |---|---| | US equities | Paper account active | | Options | Options trading enabled on paper account | | Crypto | Crypto trading enabled on paper account |

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:

| Parameter | Description | Default | Required | |---|---|---|---| | `signal_source` | Origin of trade idea (backtest, manual, scheduled, strategy) | — | Yes | | `symbol` | Ticker symbol (e.g., AAPL, BTC/USD, AAPL250718C00200000) | — | Yes | | `asset_class` | `us_equity`, `us_option`, `crypto` | `us_equity` | Yes | | `side` | `buy` or `sell` | — | Yes | | `qty` | Number of shares/contracts/coins | — | Yes (or notional) | | `notional` | Dollar amount (fractional shares). Market orders with `day` TIF only; cannot combine with `qty` | — | Yes (or qty) | | `order_type` | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` — **supported values vary by asset class** | `market` | Yes | | `time_in_force` | `day`, `gtc`, `ioc`, `fok`, `opg`, `cls` — **supported values vary by asset class** | `day` for equities and options; `gtc` for crypto | Yes | | `order_class` | `simple`, `bracket`, `oco`, `oto` (equities); `simple`, `mleg` (options); `simple` (crypto) | `simple` | No | | `limit_price` | Required for limit/stop_limit | — | Conditional | | `stop_price` | Required for stop/stop_limit | — | Conditional | | `trail_percent` | For trailing_stop | — | Conditional | | `trail_price` | For trailing_stop | — | Conditional | | `extended_hours` | Allow pre/post-market fills | `false` | No | | `client_order_id` | Idempotency key, max 128 characters | Auto-generated by Alpaca if omitted | No | | `profile` | Alpaca CLI profile name. Set it via the `ALPACA_PROFILE` environment variable for the whole session — **never** with the `-p`/`--profile` flag. See the warning in Step 10 | Currently active paper profile | No | | `output_format` | JSON is the default; `--csv` for CSV, `--jq '<expr>'` to filter | JSON | No | | `confirmation_mode` | Require explicit yes before each order | `ON` | No | | `max_position_pct` | Max % of portfolio in single position | None | No | | `max_order_value` | Hard cap on single order notional | None | No |

Strategy confirmation checklist

Before building the order, your agent confirms:

• [ ] Strategy logic is clearly stated
• [ ] You understand what the order will do