alpaca-trading-paper-trading-cli
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.
alpacahq · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add alpacahq/alpaca-skills --skill alpaca-trading-paper-trading-cliAbout this skill
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
- Start with the signal source. Identify the origin of the trade idea — a backtest result, manual idea, scheduled trigger, or strategy output.
- 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.
- 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.
- Confirm the CLI resolves to the paper endpoint. Run
alpaca doctorand require itsTrading:line to readhttps://paper-api.alpaca.markets. If it shows the live endpoint, STOP immediately and alert you. - Show a complete order preview using a formatted table. Include the exact CLI command that will run.
- Ask whether you want explicit confirmation before each order (default: ON). Respect your preference for the session.
- Submit via
alpaca order submitwith the paper profile. - Return order ID, status, submitted payload, and next inspection commands so you can independently verify.
- Monitor order lifecycle with
alpaca order get. Report fills, rejections, cancellations with portfolio impact. - 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 uuidgenor 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