alpaca-trading-paper-trading

Alpaca 模拟交易

当你希望 AI Agent 使用 Alpaca 的 Trading API 预览、提交、查看和管理模拟交易订单时，请使用此技能。

此技能面向你——使用自己的 Alpaca 模拟交易账户、凭证和本地工作区的 Trading API 用户。你的 Agent 应明确展示假设、保护机密，并在提交前确认订单详情。

这是通用（与具体实现无关）的模拟交易技能。它介绍工作流、安全检查点和输出规范，不绑定任何特定的执行工具。你可以使用 Alpaca Python SDK（alpaca-py）、直接调用 REST API、使用 JavaScript/TypeScript、Go、C#，或任何支持 Trading API 的工具。也有面向 CLI 和 MCP 的配套技能，供偏好这些执行方式的用户使用——链接见 §10。

---

0 - AI Agent 应如何使用此技能

1. 从任务本身入手。 确定信号的来源——回测输出、手动交易想法、定时触发器，还是自动化系统事件。你的 Agent 会读取相关上下文（回测运行文件夹、策略描述、警报载荷），以理解意图。

2. 重述策略逻辑。 你的 Agent 会用通俗语言重述对策略的理解——入场／退出条件、指标参数、头寸规模，以及任何假设——并在继续之前向你确认理解是否正确。

3. 执行前收集并确认所有详细配置。 你的 Agent 会明确收集每项订单参数：

   • 执行时间（立即、定时、条件触发）
   • 资产类别（美国股票、美国期权、加密货币）
   • 代码
   • 方向（买入／卖出）
   • 数量或名义金额
   • 订单类型（市价、限价、止损、止损限价、追踪止损）
   • 有效时间（当日有效、取消前有效、立即成交否则取消、全部成交否则取消、开盘竞价、收盘竞价）
   • 适用时的限价和／或止损价格
   • 盘前盘后交易标志
   • 风险控制（最大头寸规模、最大名义金额、止损、止盈）
   • 保证金使用情况

4. 确认所用的模拟账户。 你的 Agent 会验证模拟账户的配置是否符合策略要求——期权审批级别、是否启用加密货币、保证金账户还是现金账户、PDT 状态。不会假设某项功能已启用而不进行检查。

5. 提交前显示完整的订单预览表。 每笔订单都必须有可视化预览，其中显示所有参数、估算名义金额和购买力检查结果。未经预览，绝不提交订单。

6. 询问确认偏好。 你的 Agent 会询问你希望在提交每笔订单前明确确认，还是偏好自动提交模式。它会在本次会话中遵循你的偏好。默认：开启确认。

7. 仅向模拟交易环境提交订单。 每次提交前，你的 Agent 都会验证当前环境为模拟环境。绝不提交至实盘。

8. 返回完整的提交后详情。 提交后，你的 Agent 会返回订单 ID、状态、已提交载荷摘要以及后续检查步骤。

9. 监控订单生命周期并更新状态。

   • 已成交 → 成交的股数／合约数、成交价格，以及成交对投资组合风险的影响。
   • 部分成交 → 当前成交量与剩余数量，以及目前的平均成交价格。
   • 已拒绝 → 拒绝原因和具体的补救建议。
   • 已取消 → 取消方（你、系统、经纪商）及取消原因。

10. 绝不进行实盘交易。 如果检测到实盘凭证——基础 URL 不带 paper- 前缀，或配置文件设为实盘——你的 Agent 会立即停止并向你发出警告。这是强制阻止，不是一般警告。

---

1 - 前置条件

• Alpaca 模拟交易账户 — 可在 alpaca.markets 免费注册
• 模拟交易 API 密钥和密钥，存储在环境变量（APCA_API_KEY_ID、APCA_API_SECRET_KEY）或 SDK／CLI 配置中 — 切勿粘贴到聊天中
• 模拟交易基础 URL：https://paper-api.alpaca.markets（用于 REST），或配置为指向模拟交易环境的相应 SDK
• 对于期权：必须在模拟账户中启用期权交易，并获得相应的审批级别（第 1 级适用于备兑看涨期权和现金担保看跌期权；第 2 级适用于买入看涨期权和看跌期权；第 3 级适用于价差和跨式策略）
• 对于加密货币：必须在模拟账户中启用加密货币交易
• SDK／语言运行时（任选其一）：
  • Python 3.10+ 与 alpaca-py（推荐）
  • JavaScript／TypeScript 与 @alpacahq/alpaca-trade-api（v4+，由官方提供并积极维护）
  • Go 与 github.com/alpacahq/alpaca-trade-api-go/v3 — 必须使用 /v3 后缀；不带该后缀会拉取 v1 路径
  • C# 与 Alpaca.Markets（由官方提供）。Java 和其他语言也有社区 SDK。
  • 通过 curl、httpx、requests 或任何 HTTP 客户端直接调用 REST API
• 网络访问权限，以访问 Alpaca API（paper-api.alpaca.markets）

---

2 - 收集输入

必需输入

输入	描述	默认值
signal_source	交易想法的来源（回测、手动、自动化）	必须提供
symbol	股票代码（例如，期权代码 AAPL、BTC/USD、AAPL250718C00200000）	必须提供
side	buy 或 sell	必须提供
qty_or_notional	股数／合约数，或金额（股数／合约数使用 qty，金额使用 notional）	必须提供
order_type	market、limit、stop、stop_limit、trailing_stop — 支持的值因资产类别而异，见下文	market
time_in_force	day、gtc、ioc、fok、opg、cls — 支持的值因资产类别而异，见下文	股票为 day；加密货币为 gtc

各资产类别的限制

API 会拒绝不符合此矩阵的组合，因此你的 Agent 应在提交前验证，而不是提交后才验证：

资产类别	订单类型	有效期限	订单类别
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

请将此表作为构建订单的指导，而非提交前的硬性拦截条件。Alpaca 的资料对期权这一行存在分歧：OpenAPI 的 TimeInForce／OrderType 描述指出仅支持 market／limit，且仅限 day；而 Options Trading 页面和 Placing Orders 矩阵均允许 gtc，也都允许单腿订单使用 stop／stop_limit。这两个产品页面的说法一致，与规范文件不同，因此本表遵循它们。期权默认使用 day 作为较保守的选择，但应允许 Alpaca 拒绝订单，而不是预先拦截矩阵允许的订单。

适用于多种订单类型的限制：

• 延长交易时段要求订单类型为 limit，有效期限为 day 或 gtc。其他所有情况都会被拒绝。
• 追踪止损仅接受 day 和 gtc。
• 名义金额订单不能与 qty 组合使用，且无法替换 — 应先取消，再重新提交。股票订单还必须使用 market 类型和 day 有效期限；加密货币名义金额订单属于市价类型，使用加密货币的有效期限集合（gtc／ioc），因此不受股票的 day 限制。
• Bracket、OCO 和 OTO 仅适用于股票，要求有效期限为 day 或 gtc，且不支持延长交易时段。
• mleg 最多包含 4 条腿，用于表示多腿期权策略。

可选输入

输入	描述	默认值
limit_price	limit 和 stop_limit 订单必填	无
stop_price	stop 和 stop_limit 订单必填	无
trail_price 或 trail_percent	用于追踪止损订单（二选一，不可同时使用）	无
extended_hours	允许在延长交易时段执行（仅限股票；limit 类型，且 TIF 为 day 或 gtc）	false
client_order_id	用户提供的幂等键（最多 128 个字符）	自动生成的 UUID
confirmation_mode	Agent 是否在每笔订单前请求明确确认	on
risk_controls	最大持仓规模、最大名义金额、最大亏损阈值	无（建议设置）
asset_class	us_equity、us_option、crypto	根据代码格式推断
order_class	simple、bracket、oco、oto、mleg——参见上方按资产类别划分的矩阵	simple
position_intent	buy_to_open、buy_to_close、sell_to_open、sell_to_close（仅限期权）	根据上下文推断

策略确认清单

在结束配置阶段之前，Agent 必须与你确认以下各项：

• 策略逻辑理解正确——Agent 对策略的复述符合你的意图
• 时间安排——立即执行，还是定时／有条件执行（例如“仅当价格跌破 $180 时”）
• 资产类别和代码正确——股票代码正确，合约正确（期权），交易对正确（加密货币）
• 订单参数符合策略意图——类型、方向、数量、价格、TIF 均符合你的要求
• 纸面交易账户已针对该资产类别配置——期权审批、已启用加密货币、保证金类型
• 已设置风险控制（或明确豁免）——你已确认持仓规模、止损和集中度限制

---

3 - 事实来源

来源	URL	用途
Trading API 概览	https://docs.alpaca.markets/us/docs/trading-api	API 功能和结构
使用订单	https://docs.alpaca.markets/us/docs/working-with-orders	订单提交、替换、取消
Alpaca 上的订单	https://docs.alpaca.markets/us/docs/orders-at-alpaca	订单类型、TIF 值、状态生命周期
纸面交易	https://docs.alpaca.markets/us/docs/paper-trading	纸面交易环境的行为和限制
使用持仓	https://docs.alpaca.markets/us/docs/working-with-positions	持仓查询和管理
使用账户	https://docs.alpaca.markets/us/docs/working-with-account	账户状态、购买力、日内交易次数
使用资产	https://docs.alpaca.markets/us/docs/working-with-assets	可交易性检查、资产属性
期权交易	https://docs.alpaca.markets/us/docs/options-trading	期权订单细节、审批级别
加密货币交易	https://docs.alpaca.markets/us/docs/crypto-trading	加密货币订单细节、支持的交易对
Alpaca 披露信息	https://alpaca.markets/disclosures	必需的披露措辞

---

4 - 工作流

阶段 1：确认策略

步骤 1 — 确定信号来源。 你的 Agent 会判断交易想法的来源：

• 回测输出：读取运行文件夹（notes.md、summary.json），提取策略逻辑、已确认的参数和最新信号。解析信号中的交易标的、方向、数量和任何目标价格。
• 手动提出的想法：你用自然语言描述交易。你的 Agent 会提取参数并提出澄清问题。
• 自动化系统：Webhook、警报或定时触发器。你的 Agent 会读取载荷并将其映射为订单参数。

步骤 2 — 重述策略逻辑。 你的 Agent 会用通俗语言重述对策略的完整理解：

• 触发交易的条件（入场条件）
• 退出交易的条件（退出条件、止损、止盈）
• 指标参数（例如，“20 日 SMA 与 50 日 SMA 的交叉”）
• 仓位规模规则（例如，“每笔交易承担投资组合 1% 的风险”）
• 你的 Agent 所作的任何假设（例如，“假设你希望以市价入场”）

步骤 3 — 确认理解无误。 你的 Agent 会请你确认或纠正其重述内容。在你确认之前，它不会继续。如果你进行了纠正，你的 Agent 会重述修正后的版本并再次征求确认。

阶段 2：确认配置

步骤 4 — 收集所有订单参数。 根据 §2 中的输入表，Agent 收集所有必需和可选参数，并询问尚未指定的参数。

步骤 5 — 显示参数来源。 对于每个参数，Agent 显示：

• 使用的值
• 该值是由你提供、根据上下文推断（例如，根据标的代码格式推断资产类别），还是设为标准值默认值

示例：

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)

步骤 6 — 确认执行时间。 Agent 确认执行时间：

• 立即：在当前交易时段立即提交
• 定时：在指定时间提交（Agent 会说明这需要外部调度）
• 条件触发：仅在满足条件时提交（Agent 会说明这需要监控逻辑）

如果执行时间不是立即，Agent 会说明你需要哪些工具，以及它能否协助设置（部署指南参见 §4 阶段 8）。

步骤 7 — 确认资产类别的具体事项。

对于美国股票：

• 通过资产端点验证标的代码是否可交易
• 如果数量包含小数，检查是否支持碎股交易
• 如果 extended_hours 为 true，确认是否支持延长时段交易（仅 limit 订单符合条件）
• 提醒卖出所得资金按 T+1 结算

对于美国期权：

• 验证合约代码是否符合 OCC 代码规范：AAPL250718C00200000
  • 根代码（AAPL）、到期日（250718 = 2025 年 7 月 18 日）、看涨/看跌（C/P）、行权价 × 1000（00200000 = $200.00）
• 确认到期日、行权价和看涨/看跌类型
• 确认持仓意图：买入开仓、买入平仓、卖出开仓、卖出平仓
• 提醒合约乘数：1 张合约 = 标的资产的 100 股
• 确认账户的期权审批级别符合策略要求
• 如果到期日在 5 个交易日内，警示到期风险

对于加密货币：

• 确认交易对格式（例如，BTC/USD、ETH/USD）
• 提醒市场每周 7 天、每天 24 小时开放，不受交易时段限制
• 检查该交易对的最低订单规模
• 确认账户已启用加密货币交易

步骤 8 — 确认风险控制。 Agent 询问风险控制事项：

• 最大持仓规模：单个持仓的最大股数或合约数
• 最大投资组合配置比例：单个标的占投资组合权益的最大比例
• 止损：平仓退出亏损持仓的价格或百分比
• 止盈：获利了结的价格或百分比

如果你尚未设置任何风险控制，Agent 会建议你考虑设置。它会询问你是要现在设置，还是不设风险控制继续操作。如果选择不设，Agent 会在会话日志中注明。

步骤 9 — 确认保证金使用情况。 Agent 会检查：

• 通过 account.multiplier 判断保证金分类——账户对象没有 account_type 字段。1 表示有限保证金的现金型账户；2 表示 Reg T 保证金账户，日内和隔夜购买力均为 2 倍；4 表示 PDT 账户，日内购买力为 4 倍，隔夜购买力为 2 倍
• 是否允许卖空（account.shorting_enabled），因为策略可能需要卖空
• 当前购买力（account.buying_power），以及期权的当前期权购买力（account.options_buying_power）
• 当前权益（account.equity）
• 如果涉及保证金，检查维持保证金要求（account.maintenance_margin）

Phase 3：纸面账户验证

步骤 10 — 验证环境为纸面环境。 你的 Agent 会检查基础 URL、SDK 配置或 CLI 配置文件，确认环境为纸面环境，而非实盘环境。

检查项	纸面环境	实盘环境（已阻止）
REST 基础 URL	https://paper-api.alpaca.markets	https://api.alpaca.markets
SDK 配置	paper=True 或等效设置	paper=False 或未设置
CLI 配置文件	已选择纸面环境配置文件	已选择实盘环境配置文件

如果检测到实盘凭据：**立即停止。**你的 Agent 会显示明确警告并拒绝继续。它不会代你“切换到纸面环境”——你必须重新配置凭据。

步骤 11 — 获取账户状态。 你的 Agent 会获取账户信息并验证：

• status 为 ACTIVE 或 PAPER_ONLY——仅限纸面交易的账户对此技能有效，不得阻止使用
• trading_blocked 为 false
• account_blocked 为 false
• trade_suspended_by_user 为 false
• buying_power 足以满足计划中的订单
• 用于保证金分类的 multiplier，这也是唯一可用的 PDT 信号

Trading API 账户对象不包含 pattern_day_trader 或 daytrade_count 字段。你的 Agent 不得读取这些字段。multiplier 为 4 表示该账户属于 PDT 账户；如果需要日内交易次数，请通过 GET /v2/account/activities 推导，而不是从账户对象中读取。

步骤 12 — 验证期权交易准备情况（如果交易期权）。

• 根据 options_trading_level 而非 options_approved_level 进行判断。实际可用等级取 options_approved_level 和账户配置中的 max_options_trading_level 的较低值，Alpaca 会通过 options_trading_level 直接提供该值。获批等级为 3、但配置等级为 1 的账户只能交易等级 1 的期权。
• 每个等级都包含以下所有较低等级的权限：
  • 等级 0：禁用期权交易
  • 等级 1：卖出备兑看涨期权、卖出现金担保看跌期权
  • 等级 2：买入看涨期权、买入看跌期权
  • 等级 3：价差策略和跨式策略
• Alpaca 在任何等级下都不提供裸卖空期权。如果策略需要裸卖空期权，请停止并说明这一点，而不是尝试申请更高等级。
• 如果 options_trading_level 为 0，或低于策略所需等级，你的 Agent 会停止并说明所需等级以及如何申请升级

步骤 13 — 验证加密货币交易准备情况（如果交易加密货币）。

• crypto_status 为 ACTIVE
• 如果未启用加密货币交易，你的 Agent 会停止并说明如何在账户中启用

步骤 14 — 显示账户摘要。 你的 Agent 会显示账户状态摘要：

┌─────────────────────────────────────────┐
│         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                   │
└──────────────┴──────────────────────────┘

Phase 4：订单预览

步骤 15 — 构建订单载荷。 你的 Agent 会使用所有已确认的参数构建完整的 API 请求正文，并设置唯一的 client_order_id 以确保幂等性。

步骤 16 — 显示订单预览。 你的 Agent 会显示完整的订单预览表：

┌─────────────────────────────────────────┐
│           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) │
└──────────────┴──────────────────────────┘

对于期权，预览还会显示：

• 合约：AAPL 07/18/2025 $200 Call
• 合约数量：2
• 合约乘数：100 股/份合约
• 预估权利金：约 $3.50 × 2 × 100 = $700.00
• 持仓意图：买入开仓

对于加密货币，预览还会显示：

• 交易对：BTC/USD
• 市场：全天候（始终开放）
• 名义金额：$500.00（如果是名义金额订单）

步骤 17 — 确认开启模式。 如果 confirmation_mode 为 on，你的 Agent 会询问：

提交此订单？（是 / 否）

它会等待你明确回复“是”后再继续。任何不明确肯定的回复都会视为“否”，你的 Agent 会询问你想要修改什么。

步骤 18 — 确认关闭模式。 如果 confirmation_mode 为 off，你的 Agent 会告知你：

确认模式已关闭。此订单将立即提交。上方已显示预览，供你查看。

随后，你的 Agent 会继续提交订单。

阶段 5：提交订单

步骤 19 — 提交订单。 你的 Agent 通过所选的执行方式（SDK、REST、CLI 或 MCP 工具）将订单发送到模拟交易 API。该端点是模拟交易基础 URL 下的 POST /v2/orders。

步骤 20 — 记录响应。 提交成功后，你的 Agent 会记录：

• id（订单 ID）
• client_order_id
• status — 通常为 new，表示 Alpaca 已收到订单并将其路由。accepted 表示已收到但尚未路由，在交易时段以外很常见；文档指出，pending_new 和 accepted_for_bidding 很少见
• created_at
• submitted_at
• symbol、side、qty、type、time_in_force
• API 响应中回显的所有字段

步骤 21 — 处理提交失败。 如果提交失败，你的 Agent 会：

1. 记录完整的错误响应（HTTP 状态码、错误消息、错误代码）

2. 用通俗易懂的语言向你说明错误

3. 提供具体的解决建议。POST /v2/orders 文档明确说明了两种错误响应，它们的含义与常见的 HTTP 状态名称不同：

   • 403 Forbidden → 购买力或持有份额不足，而不是身份验证问题。显示当前购买力与所需购买力，或当前持仓与卖出数量
   • 422 Unprocessable Entity → 输入参数无法识别。指出具体参数，并对照第 2 节中按资产类别划分的矩阵进行检查
   • 429 Too Many Requests → 请求频率受限；遵守 Retry-After 并降低重试频率
   • 401 Unauthorized → 凭据问题。停止操作；不要使用相同凭据重试
   • 网络超时 → 先确认订单是否已收到，再采取其他操作

   不可交易或未知的交易品种会从订单端点返回 422，而不是 404。你的 Agent 会事先通过 GET /v2/assets/{symbol_or_asset_id} 验证交易品种；只有确实未知的交易品种才会返回 404。加密货币必须使用不带斜杠的旧版符号格式（BTCUSD）；如果仍有斜杠，必须进行 URL 编码（/v2/assets/BTC%2FUSDT），否则请求格式不正确。

4. 将失败尝试保存到会话日志

5. 对非幂等提交不自动重试。如果无法确定订单是否已收到（例如发生网络超时），你的 Agent 会先通过 client_order_id 检查现有订单。

阶段 6：提交后监控

步骤 22 — 获取订单状态。 提交成功后，你的 Agent 会立即通过 ID 获取订单（GET /v2/orders/{id}），以确认当前状态。

步骤 23 — 返回提交后摘要。 你的 Agent 会向你显示：

Order submitted successfully.

Order ID:        b1e2f3a4-5678-9012-cdef-abcdef123456
Status:          accepted
Symbol:          AAPL
Side:            buy
Qty:             10
Type:            limit
Limit Price:     $185.50
TIF:             day
Submitted at:    2026-07-26T15:30:00Z
Environment:     PAPER

Next steps:
- Ask me to check the status of this order
- Ask me to cancel this order
- Ask me to show your current positions
- Ask me to show your portfolio summary

步骤 24 — 订单生命周期更新。

你的 Agent 会跟踪订单的生命周期，并报告每次状态转换：

已成交：

✅ Order FILLED

Order ID:        b1e2f3a4-...
Symbol:          AAPL
Side:            buy
Filled Qty:      10 shares
Avg Fill Price:  $185.32
Fill Time:       2026-07-26T15:30:05Z

Portfolio impact:
- AAPL position:   10 shares @ $185.32 (new position)
- Position value:   $1,853.20
- Portfolio %:      1.85% of equity
- Buying Power:     $98,146.80 (was $100,000.00)

部分成交：

⏳ Order PARTIALLY FILLED

Order ID:        b1e2f3a4-...
Filled:          6 of 10 shares
Avg Fill Price:  $185.35
Remaining:       4 shares (still working)

已拒绝：

❌ Order REJECTED

Order ID:        b1e2f3a4-...
Reason:          insufficient buying power
Details:         Required ~$1,855.00, available $500.00

Remediation:
- Reduce order quantity
- Close existing positions to free buying power
- If this is unexpected, check your account for pending orders
  consuming buying power

已取消：

🚫 Order CANCELED

Order ID:        b1e2f3a4-...
Canceled by:     system
Reason:          day order expired at market close (16:00 ET)

If you still want this position, consider:
- Resubmitting as a GTC order
- Waiting for the next market open

已替换：

🔄 Order REPLACED

Old Order ID:    b1e2f3a4-...
New Order ID:    c2d3e4f5-...
Changed:
  Limit Price:   $185.50 → $186.00
  Quantity:      10 → 15

阶段 7：评估投资组合影响

步骤 25 — 获取更新后的持仓和账户信息。 订单成交后，你的 Agent 会获取当前持仓（GET /v2/positions）和账户信息（GET /v2/account），以展示其影响。

步骤 26 — 显示投资组合风险摘要。

┌─────────────────────────────────────────┐
│        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        │
└──────────────┴──────────────────────────┘

• 持仓集中度：abs(position.market_value) / equity × 100 — Position 字段为 market_value。（position_market_value 仅作为所有持仓的汇总字段存在于账户负载中。）
• 未实现盈亏：(current_price - avg_entry_price) × qty
• 当日交易次数：适用于权益低于 25,000 美元的股票账户
• 未结订单：仍在执行中、可能消耗额外购买力的订单

阶段 8：部署指南

此阶段为可选阶段。只有在你询问如何部署或自动化策略时，Agent 才会提供此指南。

步骤 27 — 提供部署选项。

如果你询问如何部署或自动化策略，Agent 会概述以下方案：

本地调度器：

• 使用 cron（Linux/macOS）、launchd（macOS）或 Windows Task Scheduler
• 使用 alpaca-py 编写封装策略逻辑的 Python 脚本
• 按照你期望的频率安排运行时间
• 将输出记录到文件中以供查看

云托管：

• 使用 AWS Lambda + EventBridge 进行无服务器定时执行
• 使用 Google Cloud Functions + Cloud Scheduler
• 使用 Railway、Render 或 Fly.io 托管持久进程
• 使用任何能按计划运行 Python/Node.js 进程的平台

基于 Webhook：

• TradingView 警报 → Webhook 端点 → 你的服务器 → Alpaca API
• 自定义警报系统 → Webhook → 订单执行逻辑

所有已部署方案都会在启动时断言其使用的是 paper 环境。 调度、托管和 Webhook 触发方式各不相同，但都必须满足同一项要求：无人值守运行的程序在下单前，必须确认自己指向 paper 环境；若无法确认，则退出。没有操作人员监控，无法及时发现端点配置错误；而且 live 账户返回的数据格式与 paper 账户相同，因此后续流程也无法暴露此类错误。

以下两条规则可确保该断言可信：

• 将 paper 端点直接写死为代码字面值，而不是配置。 从环境变量、配置文件或 CI 密钥读取的端点，可能会被从未阅读此技能的人更改。在 alpaca-py 中，这意味着要使用 TradingClient(key, secret, paper=True) 构造客户端，将 paper=True 直接写在代码中，绝不能使用 paper=os.getenv(...)。
• 只要有任何信号表明预期使用 live 环境，就立即中止。 如果环境中存在 live 端点、live 交易标记或 live 配置档案，应在首次下单前以非零状态退出，而不是悄悄解决冲突。

将凭证或变量命名为“paper”并不能作为证据。只有最终解析出的端点才是依据。

Agent 始终会包含的重要提示：

• 在考虑 live 环境之前，应先在 paper 环境中对任何新的自动化方案进行足够长时间的验证
• Agent 不会推荐任何特定托管服务提供商，也不保证正常运行时间
• 自动化 live 交易是一个独立且重大的决定，还涉及额外的监管和风险考量
• 定期监控自动化系统——不要“设置好就不管”
• 任何自动化系统都应包含错误处理、日志记录和警报机制
• 考虑自动化系统遇到意外市场状况时会发生什么

---

5 - 执行规则

环境安全

• 此技能仅在 paper 交易环境中运行。
• 如果 Agent 检测到 live API 凭证——基础 URL 为不带 paper- 前缀的 https://api.alpaca.markets，或者 SDK/CLI 配置档案设为 live——就必须立即停止并向你发出警告。
• Agent 必须在每次提交订单前验证环境，而不是每个会话只验证一次。若在会话期间重新配置凭证，环境状态可能会发生变化。
• Agent 绝不会主动提出“切换到 live”，也不会协助从 paper 交易转为 live 交易。

确认行为

• 每次会话开始时，Agent 都会询问你是否希望在每笔订单提交前进行明确确认（默认：开启）。
• 在确认开启模式下，Agent 会显示订单预览，并等待你明确回复“是”后再提交。
• 在确认关闭模式下，Agent 仍会显示订单预览，但会在短暂展示后提交。它会明确告知你订单即将提交。
• 你可以在会话期间随时告知 Agent，切换确认模式。
• 无论处于何种模式，Agent 始终会显示订单预览，绝不会静默提交。

幂等性

• 你的 Agent 会为每笔订单设置唯一的 client_order_id，以防止重复提交。
• 如果提交因网络错误而失败，且无法确定订单是否已收到，你的 Agent 会在重试前检查现有订单中是否有对应的 client_order_id。
• client_order_id 值会记录在会话的 orders.json 中，以供审计。

速率限制

• 根据响应标头进行限流，而不要使用硬编码的上限。每个响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset；当 Remaining 接近零时，你的 Agent 应降低请求频率，而不是等到触发限流。Trading API 每分钟 200 次请求这一数据被广泛引用，但并未出现在 Alpaca 当前文档中，因此不要将其硬编码。
• 如果受到速率限制（HTTP 429），请停止请求，并采用指数退避加随机抖动后重试（1 秒、2 秒、4 秒、8 秒，之后封顶）；且不得早于 X-RateLimit-Reset 指定的时间重试。
• 不要频繁查询订单状态。请以合理的间隔轮询：
  • 活跃的市价单：前 10 秒每 2 秒一次，之后每 5 秒一次
  • 活跃的限价单：前 1 分钟每 5 秒一次，之后每 30 秒一次
  • 任何订单的轮询总次数不得超过 60 次

资产类别规则

美国股票：

• 常规交易时段：美国东部时间上午 9:30 至下午 4:00
• 延长交易时段要求在 limit 订单中设置 extended_hours: true，并使用 day 或 gtc TIF，覆盖以下三个时段：
  • 隔夜时段：美国东部时间周日至周五晚上 8:00 至次日凌晨 4:00
  • 盘前时段：美国东部时间周一至周五凌晨 4:00 至上午 9:30
  • 盘后时段：美国东部时间周一至周五下午 4:00 至晚上 8:00
• 并非所有资产都符合隔夜时段的交易条件——请以资产记录为准，不要想当然
• 符合条件的代码支持零碎股交易（检查 fractionable 属性）
• T+1 结算——卖出所得款项将在下一个工作日可用
• 卖空需要保证金账户和可借入的股票

美国期权：

• 常规交易时段：美国东部时间上午 9:30 至下午 4:00
• 一份合约等于 100 股标的资产
• 需要相应的审批级别（1、2 或 3）——提交前请确认
• 对于价内期权，到期时会自动行权或被指派
• 期权有到期日——其价值会随时间推移而降低（Theta 损耗）
• 美式期权可在到期前的任何时间行权
• 主要代码提供每周、每月和每季度到期的期权

加密货币：

• 市场全天候开放——不受交易时段限制
• 各交易对设有最低订单规模（请检查资产端点）
• 并非所有交易对都可用——提交前请确认
• 没有延长交易时段的概念——市场始终开放
• 大多数交易对支持零碎数量
• 加密货币不支持卖空

错误处理

• 身份验证失败（401）： 停止操作，显示错误，并建议重新进行身份验证。绝不要使用相同凭据重试。
• 购买力或可用股票不足（403）： 对于 POST /v2/orders，403 表示可交易余额或股票数量不足，而非身份验证失败。显示当前购买力、所需名义金额和差额。建议减少数量或平仓。
• 不可交易的代码（422）： 订单端点会将无法识别的输入报告为 422。显示资产状态并建议检查代码。提供搜索正确代码的选项。GET /v2/assets/{symbol_or_asset_id} 是合法返回 404 的端点。
• 市场已关闭（422）： 使用时钟端点（GET /v2/clock）显示当前市场状态和下一次开盘时间。
• 速率限制（429）： 等待后采用指数退避重试。告知你需要等待的时间。
• 网络超时： 决定是否重试前，先通过 client_order_id 检查订单是否已收到。
• 未知错误： 显示完整错误响应。不要悄悄忽略错误。将错误记录到会话文件中。

---

6 - 输出约定

提交后的聊天内响应

Order submitted successfully.

Order ID:        {order_id}
Status:          {status}
Symbol:          {symbol}
Side:            {side}
Qty:             {qty}
Type:            {order_type}
TIF:             {time_in_force}
Submitted at:    {submitted_at}
Environment:     PAPER

Next steps:
- Ask me to check the status of this order
- Ask me to cancel this order
- Ask me to show your current positions
- Ask me to show your portfolio summary

运行文件夹中的产物

当此技能用于包含多个订单的会话时，你的 Agent 会将会话产物写入运行文件夹：

runs/<YYYYMMDD-HHMMSS>-paper-trading/
  notes.md              # strategy context, confirmation choices, assumptions
  orders.json           # all orders submitted in this session
  order_log.csv         # timeline: order_id, timestamp, event, status, details
  positions_snapshot.json # positions after last fill
  portfolio_summary.md  # human-readable portfolio state
  review.md             # session review and open questions

文件说明：

文件	内容	格式
notes.md	策略说明、信号来源、确认偏好、所作假设、应用的风险控制	Markdown
orders.json	所有已提交订单的数组，包含请求负载和响应	JSON
order_log.csv	按时间顺序排列的事件日志：order_id, timestamp, event_type, status, details	CSV
positions_snapshot.json	会话结束时的持仓（来自 GET /v2/positions）	JSON
portfolio_summary.md	易于阅读的投资组合状态：权益、购买力、持仓、集中度、盈亏	Markdown
review.md	会话回顾：有效之处、未奏效之处、待解问题、改进建议	Markdown

---

7 - 验证与测试

针对以下情况验证行为：

• 每种资产类别的正常流程场景
• 缺失和含糊输入的处理
• 身份验证和权限失败的处理
• 环境安全验证（检测实盘凭证）
• 订单生命周期转换
• 边缘情况：购买力不足、不可交易的标的代码、市场休市、PDT 警告
• 幂等性和网络故障恢复
• 确认模式切换

每当修改此技能时，都应在脑海中或使用模拟账户运行这些测试。

---

8 - 披露、安全与数据处理

必需披露

重要披露： 本材料仅用于信息、教育和研究目的，不构成投资建议、推荐、购买或出售证券、期权、加密货币或任何其他金融产品的要约或招揽。所有投资和交易都涉及风险，包括可能损失本金。模拟交易是仿真的，在成交、市场影响、流动性、费用、延迟及其他因素方面可能与实盘交易不同。请查阅 Alpaca 的披露：https://alpaca.markets/disclosures。

你的 Agent 会在每份会话摘要、报告和投资组合回顾中加入此披露。

模拟交易专项说明

• 模拟交易结果为仿真结果，不代表实际交易表现。
• 模拟成交在价格、时机、部分成交和拒绝行为方面可能与实盘成交不同。
• 模拟交易不收取真实佣金或费用。实盘交易可能产生费用。
• 从模拟交易转为实盘交易是一个独立且重大的决定，需要额外审查风险承受能力、资本充足性和监管要求。
• 此技能绝不会直接促成这一转变。

期权专项说明

涉及期权时，你的 Agent 会加入以下内容：

• 期权涉及重大风险，并不适合所有投资者。
• 期权可能到期作废。买入期权可能损失全部已支付的权利金。
• 卖出期权所承担的风险可能超过收到的权利金，且被指派可能导致以不利价格建立持仓。
• 复杂期权策略（价差、跨式、宽跨式）会带来额外风险，并且可能包含结果各异的多个腿。
• 期权存在行权和指派风险，尤其是在临近到期时。
• 交易前请了解希腊字母（delta、gamma、theta、vega）以及它们对持仓的影响。

加密货币专项说明

涉及加密货币时，你的 Agent 会加入以下内容：

• 加密货币交易因波动性高而涉及重大风险。
• 加密资产不属于证券，可能不享有传统证券所受的监管保护。
• 加密货币市场全天候运行，价格可能随时大幅波动。
• 加密资产不受 FDIC 保险承保，也不受 SIPC 保护。
• 加密货币的监管环境仍在演变，且可能发生变化。

凭据和数据处理

• 你的 Agent 会从环境变量（APCA_API_KEY_ID、APCA_API_SECRET_KEY）、SDK 配置文件或 CLI 配置文件设置中读取凭据。
• 绝不要在聊天中粘贴 API 密钥或机密信息。如果你提供这些信息，Agent 会拒绝接收。
• 你的 Agent 会在任何会话外分享的摘要中，隐去账户 ID、订单 ID 和个人身份信息。
• 原始 API 响应仅存储在本地（运行文件夹中），并归类为账户级机密信息。
• 你的 Agent 不会向任何第三方发送交易数据、账户数据或凭据。
• 会话文件（运行文件夹中的文件）会保留在你的本地文件系统中。请酌情检查并删除。

---

9 - 反模式

• 绝不要向真实交易环境提交订单。此技能仅用于模拟交易。
• 绝不要在聊天中索要 API 密钥或机密信息。凭据应来自环境变量或配置文件。
• 绝不要以纯文本形式输出凭据、令牌、账户号码或配置文件详细信息。
• 绝不要跳过订单预览——无论确认模式如何，都必须显示预览。
• 绝不要在未先检查原始订单是否已收到的情况下重试失败的订单提交（使用 client_order_id 确保幂等性）。
• 绝不要提供投资建议、推荐特定证券，或暗示某种策略适用、有利可图或风险较低。
• 绝不要在未检查账户端点的情况下，假设模拟账户已启用特定功能（期权、加密货币、保证金）。
• 绝不要向你隐瞒订单参数、默认值或执行假设。
• 绝不要将模拟交易结果视为真实交易表现的证明或预测。
• 绝不要在用户不知情的情况下循环自动提交订单——如果要批量下单，请逐一预览每个订单（或显示所有订单的汇总表并获取批量确认）。
• 绝不要假设市场开放时间——提交有时效要求的订单前，务必检查时钟／日历端点。
• 绝不要在同一会话中混用模拟交易和真实交易凭据。
• 绝不要为你尚未确认要交易的资产类别下单。

---

10 - 相关文件

文件	说明
reference.md	API 端点详情、订单架构、状态生命周期图、错误代码

配套技能

技能	说明
alpaca-trading-paper-trading-cli	使用 Alpaca CLI 的 CLI 专用版本
alpaca-trading-paper-trading-mcp	使用 Alpaca MCP 服务工具的 MCP 专用版本

相关技能

技能	说明
alpaca-trading-backtest	运行历史回测，为此技能生成信号