/paper-trading

name: alpaca-trading-paper-trading
description: >
  Preview, submit, inspect, and manage Alpaca paper-trading orders across US
  equities, options, and crypto. Use this skill when you want your AI agent to
  take a strategy signal — from a backtest, manual idea, or automated system —
  and execute it safely in your Alpaca paper-trading environment. This generic
  version works with any Alpaca SDK, REST API call, or agent tool that can
  reach the Trading API.

Alpaca Paper Trading

Use this skill when you want your AI agent to preview, submit, inspect, and manage paper-trading orders using Alpaca's Trading API.

This skill is written for you, a Trading API user working with your own Alpaca paper-trading account, credentials, and local workspace. Your agent should make assumptions visible, protect secrets, and confirm order details before submission.

This is the generic (implementation-agnostic) version of the paper-trading skill. It describes the workflow, safety gates, and output contract without binding to any specific execution tool. You can use the Alpaca Python SDK (`alpaca-py`), the REST API directly, JavaScript/TypeScript, Go, C#, or any tool that speaks to the Trading API. CLI-specific and MCP-specific companion skills exist for users who prefer those execution paths — see §10 for links.

---

0 - How your AI agent should use this skill

1. **Start with your job.** Identify what the signal is — a backtest output, a manual trade idea, a scheduled trigger, or an automated system event. Your agent reads any associated context (backtest run folder, strategy description, alert payload) to understand the intent.

2. **Reiterate the strategy logic.** Your agent restates the strategy interpretation in plain language — entry/exit conditions, indicator parameters, position sizing, and any assumptions — and confirms with you that the interpretation is correct before proceeding.

3. **Gather and confirm ALL detailed configurations before execution.** Your agent collects every order parameter explicitly:

• Timing of execution (immediate, scheduled, conditional)
• Asset class (US equity, US options, crypto)
• Symbol(s)
• Side (buy / sell)
• Quantity or notional amount
• Order type (market, limit, stop, stop_limit, trailing_stop)
• Time-in-force (day, gtc, ioc, fok, opg, cls)
• Limit price and/or stop price if applicable
• Extended-hours flag
• Risk controls (max position size, max notional, stop-loss, take-profit)
• Margin usage

4. **Confirm which paper account is being used.** Your agent verifies that the paper account's configuration meets the strategy's requirements — options approval level, crypto enabled, margin vs cash account, PDT status. It does not assume features are enabled without checking.

5. **Show a complete order preview table before submission.** Every order gets a visual preview with all parameters displayed, estimated notional, and buying power check. No order is ever submitted without a preview.

6. **Ask about confirmation preference.** Your agent asks whether you want explicit confirmation before each order submission, or whether you prefer auto-submit mode. It respects your preference for the session. Default: confirmation ON.

7. **Submit the order to the paper-trading environment only.** Your agent verifies the environment is paper before every submission. It never submits to live.

8. **Return complete post-submission details.** After submission, your agent returns the order ID, status, submitted payload summary, and next inspection steps.

9. **Monitor and update on order lifecycle.**

• **Filled** → how many shares/contracts, at what price, and how the fill changes portfolio risk.
• **Partially filled** → current fill vs remaining quantity, average fill price so far.
• **Rejected** → the rejection reason and specific remediation suggestions.
• **Canceled** → who canceled (you, system, broker) and why.

10. **Never place live trades.** If live credentials are detected — base URL without the `paper-` prefix, or a profile set to live — your agent stops immediately and warns you. This is a hard block, not a soft warning.

---

1 - Prerequisites

• **Alpaca paper-trading account** — free at [alpaca.markets](https://alpaca.markets)
• **Paper API key and secret key** stored in environment variables (`APCA_API_KEY_ID`, `APCA_API_SECRET_KEY`) or SDK/CLI profile — never pasted into chat
• **Paper base URL**: `https://paper-api.alpaca.markets` (for REST) or appropriate SDK configuration pointing to the paper environment
• **For options**: options trading must be enabled on the paper account with the appropriate approval level (level 1 for covered calls and cash-secured puts, level 2 to buy calls and puts, level 3 for spreads and straddles)
• **For crypto**: crypto trading must be enabled on the paper account
• **SDK / language runtime** (choose one):
• Python 3.10+ with `alpaca-py` (recommended)
• JavaScript/TypeScript with `@alpacahq/alpaca-trade-api` (v4+, first-party and actively maintained)
• Go with `github.com/alpacahq/alpaca-trade-api-go/v3` — the `/v3` suffix is required; without it you pull the v1 path
• C# with `Alpaca.Markets` (first-party). Community SDKs exist for Java and others.
• Direct REST API calls via `curl`, `httpx`, `requests`, or any HTTP client
• **Network access** to Alpaca APIs (`paper-api.alpaca.markets`)

---

2 - Gather inputs

Required inputs

| Input | Description | Default | |---|---|---| | `signal_source` | Where the trade idea comes from (backtest, manual, automation) | Must be provided | | `symbol` | Ticker symbol (e.g., `AAPL`, `BTC/USD`, `AAPL250718C00200000` for options) | Must be provided | | `side` | `buy` or `sell` | Must be provided | | `qty_or_notional` | Number of shares/contracts OR dollar amount (use `qty` for shares/contracts, `notional` for dollar amount) | Must be provided | | `order_type` | `market`, `limit`, `stop`, `stop_limit`, `trailing_stop` —