Alpaca 交易技能 (Alpaca Trading Skill)
通过 scripts/alpaca.sh 脚本,利用 Alpaca REST API 进行投资组合交易与管理。
设置 (Setup)
必需的环境变量 (Required env vars)
| 变量 (Variable) | 用途 (Purpose) |
|---|---|
APCA_API_KEY_ID | Alpaca API 密钥 |
APCA_API_SECRET_KEY | Alpaca API 密钥对应的 Secret |
可选的环境变量 (Optional env vars)
| 变量 (Variable) | 默认值 (Default) | 用途 (Purpose) |
|---|---|---|
APCA_API_BASE_URL | https://paper-api.alpaca.markets | 交易接口端点。如需进行实盘交易,请设置为 https://api.alpaca.markets |
APCA_DATA_API_BASE_URL | https://data.alpaca.markets | 市场数据接口端点 |
默认使用模拟交易环境。 在切换为实盘交易前,务必与用户确认。
辅助脚本 (Helper script)
请从本技能目录引入 scripts/alpaca.sh。使用方式:
alpaca METHOD PATH [JSON_BODY]
# 市场数据:
ALPACA_DATA=1 alpaca METHOD PATH
快速参考 (Quick Reference)
账户与投资组合 (Account & portfolio)
alpaca GET /v2/account # 余额、权益、购买力
alpaca GET /v2/account/configurations # 交易配置
alpaca GET '/v2/account/portfolio/history?period=1M&timeframe=1D' # 投资组合走势图
alpaca GET '/v2/account/activities?activity_types=FILL,DIV' # 交易/股息历史
alpaca GET /v2/clock # 市场开/闭市状态
alpaca GET '/v2/calendar?start=2026-03-01&end=2026-03-31' # 交易日历
订单 — 股票与加密货币 (Orders — Equities & Crypto)
# 市价买入(按数量或金额)
alpaca POST /v2/orders '{"symbol":"AAPL","qty":"10","side":"buy","type":"market","time_in_force":"day"}'
alpaca POST /v2/orders '{"symbol":"AAPL","notional":"1000","side":"buy","type":"market","time_in_force":"day"}'
# 加密货币(24/7 交易)
alpaca POST /v2/orders '{"symbol":"BTC/USD","qty":"0.001","side":"buy","type":"market","time_in_force":"gtc"}'
# 限价单 / 止损单 / 止损限价单 / 追踪止损单 / 括号单 / 一单开另一单(OTO) / 二选一单(OCO) — 请参阅 references/api.md
# 列出 / 查询 / 修改 / 取消订单
alpaca GET /v2/orders
alpaca GET /v2/orders/ORDER_ID
alpaca PATCH /v2/orders/ORDER_ID '{"qty":"20","limit_price":"190.00"}'
alpaca DELETE /v2/orders/ORDER_ID
alpaca DELETE /v2/orders # 取消所有订单
订单 — 期权 (Orders — Options)
# 买入看涨期权(需要 Level 2 及以上权限)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00260000","qty":"1","side":"buy","type":"market","time_in_force":"day"}'
# 备兑开仓卖出看涨期权(需要 Level 1 及以上权限,每张合约需持有 100 股正股)
alpaca POST /v2/orders '{"symbol":"AAPL260418C00270000","qty":"1","side":"sell","type":"limit","limit_price":"2.00","time_in_force":"day"}'
# 买入/卖出看跌期权、现金担保卖沽、价差交易(需要 Level 3 权限)— 请参阅 references/api.md
# 行权
alpaca POST /v2/positions/AAPL260418C00260000/exercise
# 查询合约
alpaca GET '/v2/options/contracts?underlying_symbols=AAPL&expiration_date_gte=2026-04-01&type=call&limit=10'
alpaca GET /v2/options/contracts/AAPL260418C00260000
持仓 (Positions)
alpaca GET /v2/positions # 所有未平仓持仓
alpaca GET '/v2/positions?asset_class=us_option' # 仅显示期权持仓
alpaca GET /v2/positions/AAPL # 单个股票持仓
alpaca GET /v2/positions/NVDA260417C00220000 # 单个期权持仓
alpaca DELETE /v2/positions/AAPL # 平仓
alpaca DELETE '/v2/positions/AAPL?qty=5' # 部分平仓
alpaca DELETE '/v2/positions?cancel_orders=true' # 平所有仓位
市场数据 — 股票 (Market data — Stocks)
ALPACA_DATA=1 alpaca GET /v2/stocks/AAPL/snapshot # 报价 + 成交 + K线
alpaca_data=1 alpaca GET '/v2/stocks/snapshots?symbols=AAPL,MSFT,GOOGL' # 多股票快照
ALPACA_DATA=1 alpaca GET '/v2/stocks/AAPL/bars?timeframe=1Day&start=2026-03-01&limit=30'
ALPACA_DATA=1 alpaca GET /v1beta1/screener/stocks/most-actives
ALPACA_DATA=1 alpaca GET '/v1beta1/screener/stocks/movers?top=10'
ALPACA_DATA=1 alpaca GET '/v1beta1/news?symbols=AAPL&limit=5'
市场数据 — 期权 (Market data — Options)
ALPACA_DATA=1 alpaca GET '/v1beta1/options/snapshots/AAPL?feed=indicative&limit=10' # 期权链
alpaca_data=1 alpaca GET '/v1beta1/options/bars?symbols=NVDA260417C00220000&timeframe=1Day&limit=10'
ALPACA_DATA=1 alpaca GET '/v1beta1/options/quotes/latest?symbols=NVDA260417C00220000'
ALPACA_DATA=1 alpaca GET '/v1beta1/options/trades/latest?symbols=NVDA260417C00220000'
# feed 参数:indicative(免费/延迟数据)或 opra(需要订阅)
市场数据 — 加密货币 (Market data — Crypto)
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/latest/quotes?symbols=BTC/USD'
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/bars?symbols=BTC/USD&timeframe=1Day&limit=30'
ALPACA_DATA=1 alpaca GET '/v1beta3/crypto/us/snapshots?symbols=BTC/USD,ETH/USD'
公司行为 (Corporate Actions)
ALPACA_DATA=1 alpaca GET '/v1/corporate-actions?symbols=AAPL&types=cash_dividend'
# 支持的类型:forward_split, reverse_split, cash_dividend, stock_dividend, spin_off 等
资产与自选列表 (Assets & Watchlists)
alpaca GET /v2/assets/AAPL # 资产信息
alpaca GET '/v2/assets?status=active&attributes=has_options' # 支持期权的股票
alpaca GET /v2/watchlists # 列出所有自选列表
alpaca POST /v2/watchlists '{"name":"科技股","symbols":["AAPL","MSFT","GOOGL"]}'
完整 API 参考 (Full API reference)
请阅读 references/api.md 获取完整的接口文档,包括:
- 所有订单类型(限价单、止损单、止损限价单、追踪止损单、括号单、OCO、OTO)
- 订单字段参考(方向、类型、有效期限、订单类别)
- 自选列表的增删改查
- 期权合约
- 历史 K线/成交/报价(含所有查询参数)
- 加密货币接口
- 市场日历
安全规则 (Safety Rules)
- 默认使用模拟交易。 未经用户明确确认,切勿将
APCA_API_BASE_URL设置为实盘地址。 - 提交订单前,先展示订单 JSON。 让用户确认代码、数量、买卖方向和订单类型。
- 下单前检查市场时钟 — 股票仅在交易时段(美东时间 9:30-16:00)内交易,除非限价单启用了
extended_hours: true。 - 大额订单前,通过
GET /v2/account验证购买力。 - 切勿提供金融建议。 仅呈现数据,由用户自行决策。
- 提醒不可逆操作的风险 — 例如平掉所有持仓、取消所有订单。
故障排除 (Troubleshooting)
| 现象 (Symptom) | 解决方法 (Fix) |
|---|---|
HTTP 401 | 检查 APCA_API_KEY_ID / APCA_API_SECRET_KEY 是否已设置且有效 |
HTTP 403 | 模拟交易密钥使用了实盘 URL,或反之;检查 APCA_API_BASE_URL |
HTTP 422(数量不足) | 检查购买力、是否支持碎股、或代码有效性 |
HTTP 429 | 已达到速率限制 — 请等待后重试;Alpaca 每分钟允许 200 个请求 |
| 非交易时段下单被拒 | 添加 "extended_hours":true(仅限价单有效),或等待市场开盘 |
jq: command not found | 脚本会回退到 python3 -m json.tool;建议安装 jq 以获得更好的输出格式 |