--- 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

```bash alpaca version ```

Install if needed:

```bash # 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

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

Discover login options:

```bash alpaca profile login --help ```

### Connectivity verified

```bash 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 - [ ] 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:

| Source | URL | Used for | |---|---|---| | Create an order | https://docs.alpaca.markets/us/reference/postorder | Order parameters, per-asset-class constraints, status codes | | Alpaca CLI docs | https://docs.alpaca.markets/us/docs/alpacas-cli | CLI commands, flags, syntax | | Order types | https://docs.alpaca.markets/us/docs/orders-at-alpaca | Order type behavior and requirements | | Paper trading | https://docs.alpaca.markets/us/docs/paper-trading | Paper environment specifics | | Options trading | https://docs.alpaca.markets/us/docs/options-trading | Options order requirements and approval levels | | Crypto trading | https://docs.alpaca.markets/us/docs/crypto-trading | Crypto order specifics | | Alpaca disclosures | https://alpaca.markets/disclosures | Disclosure language |

### CLI discovery rule

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

```bash 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:

```bash 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:

| Asset class | Order types | Time-in-force | Order classes | |---|---|---|---| | US equities | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` | `day`, `gtc`, `opg`, `cls`, `ioc`, `fok` | `simple`, `bracket`, `oco`, `oto` | | US options | `market`, `limit`, `stop`, `stop_limit` (`stop` types single-leg only) | `day`, `gtc` | `simple`, `mleg` | | Crypto | `market`, `limit`, `stop_limit` | `gtc`, `ioc` — but `stop_limit` is `gtc`-only, and `ioc` applies only to `market` and `limit` | `simple` |

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:

| Session | Window (ET) | Days | |---|---|---| | Overnight | 8:00pm – 4:00am | Sunday to Friday | | Pre-market | 4:00am – 9:30am | Monday to Friday | | After-hours | 4:00pm – 8:00pm | Monday to Friday |

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 parameter

--- 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

```bash alpaca version ```

Install if needed:

```bash # 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

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

Discover login options:

```bash alpaca profile login --help ```

### Connectivity verified

```bash 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 - [ ] 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:

| Source | URL | Used for | |---|---|---| | Create an order | https://docs.alpaca.markets/us/reference/postorder | Order parameters, per-asset-class constraints, status codes | | Alpaca CLI docs | https://docs.alpaca.markets/us/docs/alpacas-cli | CLI commands, flags, syntax | | Order types | https://docs.alpaca.markets/us/docs/orders-at-alpaca | Order type behavior and requirements | | Paper trading | https://docs.alpaca.markets/us/docs/paper-trading | Paper environment specifics | | Options trading | https://docs.alpaca.markets/us/docs/options-trading | Options order requirements and approval levels | | Crypto trading | https://docs.alpaca.markets/us/docs/crypto-trading | Crypto order specifics | | Alpaca disclosures | https://alpaca.markets/disclosures | Disclosure language |

### CLI discovery rule

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

```bash 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:

```bash 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:

| Asset class | Order types | Time-in-force | Order classes | |---|---|---|---| | US equities | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` | `day`, `gtc`, `opg`, `cls`, `ioc`, `fok` | `simple`, `bracket`, `oco`, `oto` | | US options | `market`, `limit`, `stop`, `stop_limit` (`stop` types single-leg only) | `day`, `gtc` | `simple`, `mleg` | | Crypto | `market`, `limit`, `stop_limit` | `gtc`, `ioc` — but `stop_limit` is `gtc`-only, and `ioc` applies only to `market` and `limit` | `simple` |

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:

| Session | Window (ET) | Days | |---|---|---| | Overnight | 8:00pm – 4:00am | Sunday to Friday | | Pre-market | 4:00am – 9:30am | Monday to Friday | | After-hours | 4:00pm – 8:00pm | Monday to Friday |

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 parameter

--- 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

```bash alpaca version ```

Install if needed:

```bash # 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

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

Discover login options:

```bash alpaca profile login --help ```

### Connectivity verified

```bash 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 - [ ] 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:

| Source | URL | Used for | |---|---|---| | Create an order | https://docs.alpaca.markets/us/reference/postorder | Order parameters, per-asset-class constraints, status codes | | Alpaca CLI docs | https://docs.alpaca.markets/us/docs/alpacas-cli | CLI commands, flags, syntax | | Order types | https://docs.alpaca.markets/us/docs/orders-at-alpaca | Order type behavior and requirements | | Paper trading | https://docs.alpaca.markets/us/docs/paper-trading | Paper environment specifics | | Options trading | https://docs.alpaca.markets/us/docs/options-trading | Options order requirements and approval levels | | Crypto trading | https://docs.alpaca.markets/us/docs/crypto-trading | Crypto order specifics | | Alpaca disclosures | https://alpaca.markets/disclosures | Disclosure language |

### CLI discovery rule

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

```bash 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:

```bash 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:

| Asset class | Order types | Time-in-force | Order classes | |---|---|---|---| | US equities | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` | `day`, `gtc`, `opg`, `cls`, `ioc`, `fok` | `simple`, `bracket`, `oco`, `oto` | | US options | `market`, `limit`, `stop`, `stop_limit` (`stop` types single-leg only) | `day`, `gtc` | `simple`, `mleg` | | Crypto | `market`, `limit`, `stop_limit` | `gtc`, `ioc` — but `stop_limit` is `gtc`-only, and `ioc` applies only to `market` and `limit` | `simple` |

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:

| Session | Window (ET) | Days | |---|---|---| | Overnight | 8:00pm – 4:00am | Sunday to Friday | | Pre-market | 4:00am – 9:30am | Monday to Friday | | After-hours | 4:00pm – 8:00pm | Monday to Friday |

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 parameter

--- 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

```bash alpaca version ```

Install if needed:

```bash # 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

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

Discover login options:

```bash alpaca profile login --help ```

### Connectivity verified

```bash 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 - [ ] 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:

| Source | URL | Used for | |---|---|---| | Create an order | https://docs.alpaca.markets/us/reference/postorder | Order parameters, per-asset-class constraints, status codes | | Alpaca CLI docs | https://docs.alpaca.markets/us/docs/alpacas-cli | CLI commands, flags, syntax | | Order types | https://docs.alpaca.markets/us/docs/orders-at-alpaca | Order type behavior and requirements | | Paper trading | https://docs.alpaca.markets/us/docs/paper-trading | Paper environment specifics | | Options trading | https://docs.alpaca.markets/us/docs/options-trading | Options order requirements and approval levels | | Crypto trading | https://docs.alpaca.markets/us/docs/crypto-trading | Crypto order specifics | | Alpaca disclosures | https://alpaca.markets/disclosures | Disclosure language |

### CLI discovery rule

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

```bash 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:

```bash 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:

| Asset class | Order types | Time-in-force | Order classes | |---|---|---|---| | US equities | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` | `day`, `gtc`, `opg`, `cls`, `ioc`, `fok` | `simple`, `bracket`, `oco`, `oto` | | US options | `market`, `limit`, `stop`, `stop_limit` (`stop` types single-leg only) | `day`, `gtc` | `simple`, `mleg` | | Crypto | `market`, `limit`, `stop_limit` | `gtc`, `ioc` — but `stop_limit` is `gtc`-only, and `ioc` applies only to `market` and `limit` | `simple` |

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:

| Session | Window (ET) | Days | |---|---|---| | Overnight | 8:00pm – 4:00am | Sunday to Friday | | Pre-market | 4:00am – 9:30am | Monday to Friday | | After-hours | 4:00pm – 8:00pm | Monday to Friday |

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 parameter