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.

• Alpaca paper-trading account — free at 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

  )

us_equity

market

limit

stop

stop_limit

trailing_stop

day

gtc

opg

cls

ioc

fok

simple

bracket

oco

oto

us_option

market

limit

stop

stop_limit

stop

day

gtc

simple

mleg

crypto

market

limit

stop_limit

gtc

ioc

stop_limit

gtc

ioc

market

limit

simple

TimeInForce

OrderType

market

limit

day

gtc

stop

stop_limit

day

• Extended hours requires

  limit

  type with

  day

  or

  gtc

  TIF. Everything else is rejected.
• Trailing stop accepts only

  day

  and

  gtc

  .
• Notional orders cannot be combined with

  qty

  and cannot be replaced — cancel and resubmit instead. For equities they additionally require

  market

  type with

  day

  TIF; crypto notional orders are market-type and use the crypto TIF set (

  gtc

  /

  ioc

  ), so the equities

  day

  restriction does not apply to them.
• Bracket, OCO, and OTO are equities-only, require

  day

  or

  gtc

  , and do not support extended hours.

• mleg

  carries up to 4 legs and is how multi-leg options strategies are expressed.

• Strategy logic interpretation is correct — the agent's restatement of your strategy matches your intent
• Timing — immediate execution, or scheduled/conditional (e.g., "only if price drops below $180")
• Asset class and symbol are correct — the right ticker, the right contract (for options), the right pair (for crypto)
• Order parameters match the strategy intent — type, side, quantity, prices, TIF all align with what you want
• Paper account is configured for this asset class — options approval, crypto enabled, margin type
• Risk controls are set (or explicitly waived) — you've acknowledged position sizing, stop-loss, and concentration limits

• Backtest output: read the run folder (

  notes.md

  ,

  summary.json

  ) to extract the strategy logic, confirmed parameters, and the last signal. Parse the signal for symbol, side, quantity, and any price targets.
• Manual idea: you describe the trade in natural language. Your agent extracts the parameters and asks clarifying questions.
• Automated system: a webhook, alert, or scheduled trigger. Your agent reads the payload and maps it to order parameters.

• What triggers a trade (entry condition)
• What exits a trade (exit condition, stop-loss, take-profit)
• Indicator parameters (e.g., "20-day SMA crossover with 50-day SMA")
• Position sizing rules (e.g., "risk 1% of portfolio per trade")
• Any assumptions your agent is making (e.g., "assuming you want to enter at market price")

• The value being used
• Whether it was provided by you, inferred from context (e.g., asset class from symbol format), or defaulted to a standard value

Symbol:        AAPL           (provided)
Side:          buy            (provided)
Quantity:      50 shares      (provided)
Order type:    limit          (provided)
Limit price:   $180.00        (provided)
TIF:           day            (defaulted — standard for equities)
Extended hrs:  false          (defaulted)
Client order:  a7b3c9d1-...   (auto-generated)

• Immediate: submit now, during current market session
• Scheduled: submit at a specific time (your agent notes this requires external scheduling)
• Conditional: submit only when a condition is met (your agent notes this requires monitoring logic)

• Verify the symbol is tradable via the assets endpoint
• Check fractional share eligibility if quantity includes decimals
• Confirm extended-hours eligibility if

  extended_hours

  is

  true

  (only

  limit

  orders qualify)
• Note T+1 settlement for sell proceeds

• Validate the contract symbol follows OCC symbology:

  AAPL250718C00200000

  • Root symbol (AAPL), expiration (250718 = July 18, 2025), call/put (C/P), strike price × 1000 (00200000 = $200.00)
• Confirm expiration date, strike price, and put/call
• Confirm position intent: buy-to-open, buy-to-close, sell-to-open, sell-to-close
• Note the contract multiplier: 1 contract = 100 shares of the underlying
• Confirm the account's options approval level meets the strategy requirements
• Warn about expiration risk if the expiration is within 5 trading days

• Confirm the pair format (e.g.,

  BTC/USD

  ,

  ETH/USD

  )
• Note 24/7 market — no market-hours constraints
• Check minimum order size for the pair
• Confirm the account has crypto trading enabled

• Max position size: maximum number of shares/contracts in a single position
• Max portfolio allocation: maximum percentage of portfolio equity in one symbol
• Stop-loss: price or percentage at which to exit a losing position
• Take-profit: price or percentage at which to take gains

• Margin classification via

  account.multiplier

  — the account object has no

  account_type

  field.

  1

  is a limited-margin, cash-style account;

  2

  is a Reg T margin account with 2x intraday and overnight buying power;

  4

  is a PDT account with 4x intraday and 2x overnight
• Whether shorting is permitted (

  account.shorting_enabled

  ), since the strategy may require it
• Current buying power (

  account.buying_power

  ) and, for options,

  account.options_buying_power

• Current equity (

  account.equity

  )
• If margin is involved, the maintenance margin requirement (

  account.maintenance_margin

  )

https://paper-api.alpaca.markets

https://api.alpaca.markets

paper=True

paper=False

• status

  is

  ACTIVE

  or

  PAPER_ONLY

  — a paper-only account is valid for this skill and must not be blocked

• trading_blocked

  is

  false

• account_blocked

  is

  false

• trade_suspended_by_user

  is

  false

• buying_power

  is sufficient for the planned order

• multiplier

  for margin classification, which is also the only PDT signal available

pattern_day_trader

daytrade_count

multiplier

4

GET /v2/account/activities

• Gate on

  options_trading_level

  , not

  options_approved_level

  . The effective level is the minimum of

  options_approved_level

  and the

  max_options_trading_level

  in account configuration, and Alpaca exposes it directly as

  options_trading_level

  . An account approved for level 3 but configured to level 1 can only trade level 1.
• Each level includes the ones below it:
  • Level 0: options trading disabled
  • Level 1: sell covered calls, sell cash-secured puts
  • Level 2: buy calls, buy puts
  • Level 3: spreads and straddles
• Alpaca does not offer naked short options at any level. If a strategy requires one, stop and say so rather than looking for a higher level.
• If

  options_trading_level

  is

  0

  or below what the strategy needs, your agent stops and explains which level is required and how to request an upgrade

• crypto_status

  is

  ACTIVE

• If crypto is not enabled, your agent stops and explains how to enable it on the account

┌─────────────────────────────────────────┐
│         PAPER ACCOUNT SUMMARY           │
├──────────────┬──────────────────────────┤
│ Account ID   │ ****-****-****-a1b2     │
│ Status       │ ACTIVE                   │
│ Equity       │ $100,000.00             │
│ Buying Power │ $100,000.00             │
│ Cash         │ $100,000.00             │
│ Positions    │ 3 open                   │
│ Multiplier   │ 2 (Reg T margin)         │
│ Options Lvl  │ 2 (effective)            │
│ Crypto       │ ACTIVE                   │
└──────────────┴──────────────────────────┘

client_order_id

┌─────────────────────────────────────────┐
│           ORDER PREVIEW                  │
├──────────────┬──────────────────────────┤
│ Environment  │ PAPER                    │
│ Symbol       │ AAPL                     │
│ Side         │ buy                      │
│ Quantity     │ 10 shares                │
│ Order Type   │ limit                    │
│ Limit Price  │ $185.50                  │
│ Time-in-Force│ day                      │
│ Extended Hrs │ no                       │
│ Client Order │ abc-123-def              │
│ Est. Notional│ ~$1,855.00              │
│ Buying Power │ $98,500.00 (sufficient) │
└──────────────┴──────────────────────────┘

• Contract:

  AAPL 07/18/2025 $200 Call

• Contracts: 2
• Multiplier: 100 shares/contract
• Est. Premium: ~$3.50 × 2 × 100 = $700.00
• Position intent: buy-to-open

• Pair: BTC/USD
• Market: 24/7 (always open)
• Notional: $500.00 (if notional order)

confirmation_mode

on

Submit this order? (yes / no)

yes

confirmation_mode

off

Confirmation mode is OFF. This order will be submitted now. The preview is shown above for your review.

POST /v2/orders

• id

  (order ID)

• client_order_id

• status

  — usually

  new

  , meaning Alpaca received the order and routed it.

  accepted

  means received but not yet routed and is common outside trading hours;

  pending_new

  and

  accepted_for_bidding

  are documented as rare

• created_at

• submitted_at

• symbol

  ,

  side

  ,

  qty

  ,

  type

  ,

  time_in_force

• All echoed fields from the API response

1. Captures the full error response (HTTP status code, error message, error code)
2. Shows you the error in plain language
3. Suggests specific remediation.

   POST /v2/orders

   documents exactly two error responses, and they do not mean what their generic HTTP names suggest:

   • 403 Forbidden

     → insufficient buying power or shares, not an auth problem. Show current buying power versus required, or current position versus the quantity being sold

   • 422 Unprocessable Entity

     → input parameters not recognized. Show which ones, and check them against the per-asset-class matrix in section 2

   • 429 Too Many Requests

     → rate limited; honor

     Retry-After

     and back off

   • 401 Unauthorized

     → credential problem. Stop; do not retry with the same credentials
   • Network timeout → verify whether the order was received before doing anything else
   A non-tradable or unknown symbol surfaces as

   422

   from the order endpoint, not

   404

   . Your agent validates the symbol against

   GET /v2/assets/{symbol_or_asset_id}

   beforehand, where a genuinely unknown symbol does return

   404

   . Crypto requires the old symbology without a slash (

   BTCUSD

   ), and any slash that remains must be URL-encoded (

   /v2/assets/BTC%2FUSDT

   ) or the request is malformed.
4. Saves the failed attempt to the session log
5. Does NOT automatically retry for non-idempotent submissions. If it's unclear whether the order was received (e.g., network timeout), your agent checks existing orders by

   client_order_id

   first.

GET /v2/positions

GET /v2/account

┌─────────────────────────────────────────┐
│        PORTFOLIO RISK SUMMARY           │
├──────────────┬──────────────────────────┤
│ Total Equity │ $100,050.00             │
│ Buying Power │ $98,146.80              │
│ Open Pos.    │ 4 positions              │
│ Open Orders  │ 1 working                │
│                                         │
│ Position Concentration:                 │
│   AAPL       │  1.85% ($1,853.20)      │
│   MSFT       │  3.20% ($3,201.00)      │
│   TSLA       │  2.10% ($2,100.50)      │
│   BTC/USD    │  5.00% ($5,002.30)      │
│                                         │
│ Unrealized P&L (total): +$50.00        │
└──────────────┴──────────────────────────┘

• Position concentration:

  abs(position.market_value) / equity × 100

  — the Position field is

  market_value

  . (

  position_market_value

  exists only on the account payload as an all-positions aggregate.)
• Unrealized P&L:

  (current_price - avg_entry_price) × qty

• Day trade count: relevant for equity accounts with less than $25k equity
• Open orders: orders still working that may consume additional buying power

This phase is optional. Your agent provides this guidance only when you ask about deploying or automating a strategy.

• Use

  cron

  (Linux/macOS),

  launchd

  (macOS), or Windows Task Scheduler
• Write a Python script using

  alpaca-py

  that encapsulates the strategy logic
• Schedule it to run at your desired frequency
• Log output to a file for review

• AWS Lambda + EventBridge for serverless scheduled execution
• Google Cloud Functions + Cloud Scheduler
• Railway, Render, or Fly.io for persistent process hosting
• Any platform that can run a Python/Node.js process on a schedule

• TradingView alerts → webhook endpoint → your server → Alpaca API
• Custom alert system → webhook → order execution logic

• Pin the paper endpoint as a literal in code, not as configuration. An endpoint read from an environment variable, a config file, or a CI secret can be changed by someone who never reads this skill. In

  alpaca-py

  that means constructing the client as

  TradingClient(key, secret, paper=True)

  with

  paper=True

  written literally, never

  paper=os.getenv(...)

  .
• Abort on any signal that live was intended. If a live endpoint, a live-trading flag, or a live profile is present in the environment, exit non-zero before the first order rather than resolving the conflict silently.

• Validate any new automation against paper for a meaningful period before considering live at all
• Your agent does not recommend any specific hosting provider or guarantee uptime
• Automating live trading is a separate, significant decision with additional regulatory and risk considerations
• Monitor automated systems regularly — do not "set and forget"
• Include error handling, logging, and alerting in any automated system
• Consider what happens when your automation encounters an unexpected market condition

• This skill operates in the paper-trading environment ONLY.
• If your agent detects live API credentials — base URL is

  https://api.alpaca.markets

  without the

  paper-

  prefix, or the SDK/CLI profile is set to live — it must STOP and warn you immediately.
• Your agent must verify the environment before every order submission, not just once per session. Environment state can change if credentials are reconfigured mid-session.
• Your agent never offers to "switch to live" or facilitate the transition from paper to live trading.

• At the start of each session, your agent asks whether you want explicit confirmation before each order (default: ON).
• In confirmation-ON mode, your agent shows the order preview and waits for your explicit "yes" before submitting.
• In confirmation-OFF mode, your agent still shows the order preview but submits after a brief display pause. It announces the submission clearly.
• You can toggle confirmation mode at any time during the session by telling your agent.
• Regardless of mode, your agent always shows the order preview. It never submits silently.

• Your agent sets a unique

  client_order_id

  on every order to prevent duplicate submissions.
• If submission fails with a network error and it's unclear whether the order was received, your agent checks existing orders for the

  client_order_id

  before retrying.

• client_order_id

  values are logged in the session's

  orders.json

  for audit.

• Drive throttling from the response headers rather than a hard-coded ceiling. Every response carries

  X-RateLimit-Limit

  ,

  X-RateLimit-Remaining

  , and

  X-RateLimit-Reset

  ; your agent slows down as

  Remaining

  approaches zero instead of waiting to be throttled. A figure of 200 requests per minute is widely cited for the Trading API but is not stated in Alpaca's current documentation, so do not hard-code it.
• If rate-limited (HTTP 429), stop and retry with exponential backoff plus jitter (1s, 2s, 4s, 8s, capped), and do not retry before the time given by

  X-RateLimit-Reset

  .
• Do not spam order status checks. Poll at reasonable intervals:
  • Active market order: every 2 seconds for the first 10 seconds, then every 5 seconds
  • Active limit order: every 5 seconds for the first minute, then every 30 seconds
  • No order should be polled more than 60 times total

• Standard market hours: 9:30 AM–4:00 PM ET
• Extended hours require

  extended_hours: true

  on a

  limit

  order with

  day

  or

  gtc

  TIF, and cover three sessions:
  • Overnight: 8:00 PM–4:00 AM ET, Sunday to Friday
  • Pre-market: 4:00 AM–9:30 AM ET, Monday to Friday
  • After-hours: 4:00 PM–8:00 PM ET, Monday to Friday
• Not every asset is eligible for the overnight session — confirm on the asset record rather than assuming
• Fractional shares supported for eligible symbols (check

  fractionable

  attribute)
• T+1 settlement — sell proceeds are available the next business day
• Short selling requires a margin account and locatable shares

• Standard market hours: 9:30 AM–4:00 PM ET
• One contract = 100 shares of the underlying
• Approval level required (1, 2, or 3) — verify before submitting
• Exercise and assignment are automatic at expiration for ITM options
• Options have expiration dates — they lose value over time (theta decay)
• American-style options can be exercised any time before expiration
• Weekly, monthly, and quarterly expirations available for major symbols

• 24/7 market — no market-hours constraints
• Minimum order sizes apply per pair (check the asset endpoint)
• Not all pairs are available — verify before submitting
• No extended-hours concept — always open
• Fractional quantities supported for most pairs
• No short selling of crypto

• Auth failure (401): Stop, show the error, suggest re-authenticating. Never retry with the same credentials.
• Insufficient buying power or shares (403): On

  POST /v2/orders

  ,

  403

  means the tradable balance or share count is insufficient — it is not an auth failure. Show current buying power, required notional, and the shortfall. Suggest reducing quantity or closing positions.
• Non-tradable symbol (422): The order endpoint reports unrecognized input as

  422

  . Show the asset status and suggest checking the symbol. Offer to search for the correct symbol.

  GET /v2/assets/{symbol_or_asset_id}

  is the place a

  404

  legitimately appears.
• Market closed (422): Show current market status and next open time using the clock endpoint (

  GET /v2/clock

  ).
• Rate limit (429): Wait and retry with exponential backoff. Inform you of the delay.
• Network timeout: Check if the order was received (by

  client_order_id

  ) before deciding whether to retry.
• Unknown error: Show the full error response. Do not silently swallow errors. Log the error to the session file.

• Happy path scenarios for each asset class
• Missing and ambiguous input handling
• Auth and permission failure handling
• Environment safety verification (live credential detection)
• Order lifecycle transitions
• Edge cases: insufficient buying power, non-tradable symbols, market-closed, PDT warnings
• Idempotency and network failure recovery
• Confirmation mode switching

Important disclosure: This material is for informational, educational, and research purposes only. It is not investment advice, a recommendation, an offer, or a solicitation to buy or sell securities, options, cryptocurrencies, or any other financial product. All investing and trading involve risk, including possible loss of principal. Paper trading is simulated and may differ from live trading in fills, market impact, liquidity, fees, latency, and other factors. Review Alpaca's disclosures at https://alpaca.markets/disclosures.

• Paper trading results are simulated. They do not represent actual trading performance.
• Paper fills may differ from live fills in price, timing, partial fills, and rejection behavior.
• Paper trading does not charge real commissions or fees. Live trading may incur costs.
• Moving from paper to live trading is a separate, significant decision that requires additional review of risk tolerance, capital adequacy, and regulatory requirements.
• This skill will never facilitate that transition directly.

• Options involve significant risk and are not suitable for all investors.
• Options can expire worthless. You can lose the entire premium paid for long options.
• Selling options carries risk that can exceed the premium received, and assignment can force a position at an unfavorable price.
• Complex options strategies (spreads, straddles, strangles) carry additional risks and may have multiple legs with different outcomes.
• Options are subject to exercise and assignment risk, especially near expiration.
• Understand the Greeks (delta, gamma, theta, vega) and how they affect your position before trading.

• Cryptocurrency trading involves substantial risk due to high volatility.
• Crypto assets are not securities and may have different regulatory protections than traditional securities.
• Crypto markets operate 24/7 and can experience significant price swings at any time.
• Crypto assets are not FDIC insured or SIPC protected.
• Regulatory environment for crypto is evolving and may change.

• Your agent reads credentials from environment variables (

  APCA_API_KEY_ID

  ,

  APCA_API_SECRET_KEY

  ), SDK configuration files, or CLI profile settings.
• Never paste API keys or secrets into chat. Your agent will refuse to accept them if offered.
• Your agent redacts account IDs, order IDs, and personally identifiable information in any summaries shared outside the session.
• Raw API responses are stored locally only (in the run folder) and classified as account-level confidential.
• Your agent does not send trading data, account data, or credentials to any third party.
• Session artifacts (run folder files) remain on your local filesystem. Review and delete them as appropriate.

• NEVER submit orders to a live trading environment. This skill is paper-only.
• NEVER ask for API keys or secrets in chat. Credentials come from environment variables or config files.
• NEVER print credentials, tokens, account numbers, or profile details in plain text.
• NEVER skip the order preview — always show it, regardless of confirmation mode.
• NEVER retry a failed order submission without first checking if the original was received (use

  client_order_id

  for idempotency).
• NEVER give investment advice, recommend specific securities, or imply a strategy is suitable, profitable, or low-risk.
• NEVER assume the paper account has specific features enabled (options, crypto, margin) without checking the account endpoint.
• NEVER hide order parameters, defaults, or execution assumptions from you.
• NEVER treat paper trading results as proof or prediction of live trading performance.
• NEVER auto-submit orders in a loop without user awareness — if placing bulk orders, preview each one (or show a summary table of all orders and get batch confirmation).
• NEVER assume market hours — always check the clock/calendar endpoint before submitting time-sensitive orders.
• NEVER mix paper and live credentials in the same session.
• NEVER place orders for asset classes you haven't confirmed you want to trade.