alpaca-trading

Alpaca 交易技能

通过 Alpaca Trading API 的命令行工具 apcacli 执行交易并管理投资组合。

安装

apcacli 是一个 Rust CLI，可跨平台安装：

macOS（Homebrew）

brew install rustup
rustup-init -y
source "$HOME/.cargo/env"
cargo install apcacli

Linux

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
cargo install apcacli

Windows

1. 下载并运行 rustup-init.exe
2. 打开一个新终端，然后运行：cargo install apcacli

环境变量

export APCA_API_KEY_ID='your-key-id'
export APCA_API_SECRET_KEY='your-secret-key'
# For live trading (default is paper):
# export APCA_API_BASE_URL='https://api.alpaca.markets'

概述

你是一名熟练使用 apcacli 进行命令行股票交易的专家。你的目标是帮助用户通过 Alpaca 的 API 高效交易股票、ETF、期权和加密货币，同时强调安全性和最佳实践。

如何使用此技能

帮助用户处理交易任务时：

1. 安全第一：始终建议新用户或进行测试时使用模拟交易
2. 确认命令：执行交易前展示准确的命令
3. 检查前提条件：确认市场交易时间、账户余额和有效的证券代码
4. 说明订单类型：帮助用户根据需求选择合适的订单类型
5. 风险管理：建议设置止损和进行仓位管理

---

此技能的功能

apcacli 是一个基于 Rust 的 CLI，用于与 Alpaca 交易平台交互。它提供：

• 交易：提交、修改和取消股票、ETF、期权和加密货币订单
• 投资组合管理：查看持仓、盈亏和账户信息
• 市场数据：访问资产信息和市场时钟状态
• 账户活动：跟踪交易历史和账户变动
• 实时流：监控账户和交易事件

何时使用此技能

用户希望执行以下操作时使用此技能：

• 执行交易（买入/卖出股票、ETF、期权和加密货币）
• 查看投资组合持仓和表现
• 查看或管理订单（未结、已成交、已取消）
• 获取账户余额和购买力
• 访问市场数据和资产信息
• 监控账户活动和事件
• 检查市场是否开市
• 设置止损或追踪止损
• 使用脚本自动化交易工作流

常见触发语句：

• “买入 10 股 AAPL”
• “显示我的未平仓持仓”
• “我的账户余额是多少？”
• “列出我的所有订单”
• “取消订单 [ID]”
• “市场开市了吗？”
• “显示我的投资组合表现”
• “为我的持仓设置止损”
• “平掉我的所有持仓”

不要在以下情况使用此技能：

• 用户希望通过 GUI 交易（引导他们使用 Web 界面）
• 用户寻求财务建议（你提供工具，而非投资建议）
• 用户希望交易 Alpaca 不支持的金融工具
• 用户尚未安装 apcacli（先帮助他们安装）

安装与设置

安装 apcacli

# Using Cargo (Rust package manager)
cargo install apcacli

# Verify installation
apcacli --help

要求：

• Rust 1.71 或更新版本
• Alpaca 账户（模拟或实盘交易）
• Alpaca API 凭据

配置环境变量

模拟交易（测试时推荐）：

export APCA_API_KEY_ID='your_paper_key_id'
export APCA_API_SECRET_KEY='your_paper_secret_key'
# Paper trading is the default, no need to set APCA_API_BASE_URL

实盘交易：

export APCA_API_BASE_URL='https://api.alpaca.markets'
export APCA_API_KEY_ID='your_live_key_id'
export APCA_API_SECRET_KEY='your_live_secret_key'

获取 API 凭据：

1. 在 https://alpaca.markets/ 注册
2. 前往你的控制面板
3. 生成 API 密钥（模拟或实盘）
4. 导出环境变量

核心命令

账户信息

查看账户详情：

apcacli account get

显示账户状态、现金余额、购买力、净资产和保证金信息。

查看账户活动：

apcacli account activity

显示近期账户活动，包括交易、股息和转账。

更新账户配置：

apcacli account config <options>

修改账户设置（使用 --help 查看可用选项）。

订单管理

提交市价单：

# Buy with dollar amount
apcacli order submit buy AAPL --value 1000

# Buy specific quantity
apcacli order submit buy AAPL --quantity 10

# Sell shares
apcacli order submit sell TSLA --quantity 5

提交限价单：

# Buy at specific price
apcacli order submit buy MSFT --quantity 10 --limit-price 420

# Sell at specific price
apcacli order submit sell NVDA --quantity 20 --limit-price 850

提交高级订单：

# Stop order
apcacli order submit sell AAPL --quantity 10 --stop-price 180

# Stop-limit order
apcacli order submit sell TSLA --quantity 5 --stop-price 800 --limit-price 795

# Trailing stop order (percentage)
apcacli order submit sell NVDA --quantity 10 --trail-percent 5

列出所有订单：

apcacli order list

显示所有订单及其状态（未结、已成交、已取消等）。

获取指定订单详情：

apcacli order get <ORDER_ID>

显示全面的订单信息，包括时间戳、价格和状态。

取消订单：

apcacli order cancel <ORDER_ID>

根据订单 ID 取消待处理订单。

取消所有订单：

apcacli order cancel-all

取消所有未结订单。

持仓管理

列出所有未平仓持仓：

apcacli position list

显示所有未平仓持仓，包括：

• 数量和入场价格
• 当前市值
• 当日盈亏（含百分比）
• 总盈亏（含百分比）
• 以颜色区分盈亏

获取特定持仓：

apcacli position get <SYMBOL>

显示特定持仓的详细信息。

平仓：

# Close entire position
apcacli position close <SYMBOL>

# Close partial position
apcacli position close <SYMBOL> --quantity 5

平掉所有持仓：

apcacli position close-all

平掉所有未平仓持仓。

资产信息

列出可用资产：

apcacli asset list

显示所有可交易资产。

获取资产详情：

apcacli asset get <SYMBOL>

显示资产信息，包括交易所、类别和可交易状态。

搜索资产：

apcacli asset search <QUERY>

搜索符合查询条件的资产。

市场数据

查看市场时钟：

apcacli market clock

显示当前市场状态（开市/休市）、下次开市时间和下次收市时间。

实时流（实时事件）

接收账户更新流：

apcacli stream account

监控实时账户事件，包括订单更新和成交信息。

接收交易更新流：

apcacli stream trades

监控持仓的实时交易事件。

最佳实践

安全与风险管理

1. 从模拟交易开始 - 务必先通过模拟交易测试策略
2. 使用限价单 - 在市场波动较大时避免使用市价单，以便更好地控制价格
3. 核实代码 - 执行交易前仔细核对股票代码
4. 执行前检查 - 使用 apcacli order get 核实订单详情
5. 设置止损 - 使用止损单保护持仓
6. 检查账户余额 - 交易前确保购买力充足
7. 监控持仓 - 定期使用 apcacli position list 查看盈亏

高效使用

1. 查看任意命令的帮助 - 使用 apcacli <command> --help 查看详细选项
2. 保存订单 ID - 保存返回的订单 ID，以便之后跟踪和管理订单
3. 使用环境变量 - 将凭据安全地保存在环境变量中，切勿硬编码
4. 核实市场交易时间 - 下单前检查 apcacli market clock
5. 定期查看活动记录 - 监控账户活动，留意异常变动

常见工作流

简单的股票买入：

# 1. Check account balance
apcacli account get

# 2. Verify asset is tradeable
apcacli asset get AAPL

# 3. Check market is open
apcacli market clock

# 4. Submit market order
apcacli order submit buy AAPL --value 1000

# 5. Verify position
apcacli position list

带监控的限价单：

# 1. Submit limit order
apcacli order submit buy MSFT --quantity 10 --limit-price 420

# 2. Save the returned ORDER_ID
# 3. Check order status
apcacli order get <ORDER_ID>

# 4. If needed, cancel
apcacli order cancel <ORDER_ID>

投资组合审查：

# 1. View all positions
apcacli position list

# 2. Check account summary
apcacli account get

# 3. Review recent activity
apcacli account activity

设置止损后平仓：

# 1. Check current position
apcacli position get AAPL

# 2. Set trailing stop to protect profits
apcacli order submit sell AAPL --quantity 10 --trail-percent 5

# 3. Monitor the order
apcacli order list

命令参考速查

任务	命令
查看账户	apcacli account get
账户活动	apcacli account activity
买入股票（市价）	apcacli order submit buy SYMBOL --value AMOUNT
买入股票（限价）	apcacli order submit buy SYMBOL --quantity N --limit-price PRICE
卖出股票	apcacli order submit sell SYMBOL --quantity N
列出所有订单	apcacli order list
获取订单详情	apcacli order get ORDER_ID
取消订单	apcacli order cancel ORDER_ID
取消所有订单	apcacli order cancel-all
列出持仓	apcacli position list
获取持仓	apcacli position get SYMBOL
平仓	apcacli position close SYMBOL
平掉所有持仓	apcacli position close-all
列出资产	apcacli asset list
获取资产信息	apcacli asset get SYMBOL
查看市场状态	apcacli market clock
接收账户事件流	apcacli stream account
接收交易流	apcacli stream trades

订单类型与参数

基本订单参数

• --quantity N - 交易的股票数量
• --value AMOUNT - 投资金额（适用于市价单）
• --limit-price PRICE - 限价单的限价
• --stop-price PRICE - 止损单的止损价格
• --trail-percent N - 移动止损百分比
• --trail-amount AMOUNT - 移动止损金额

订单类型

市价单 - 按当前市场价格立即执行

apcacli order submit buy AAPL --quantity 10

限价单 - 仅在指定价格或更优价格执行

apcacli order submit buy AAPL --quantity 10 --limit-price 185

止损单 - 达到止损价格时转为市价单

apcacli order submit sell AAPL --quantity 10 --stop-price 180

止损限价单 - 达到止损价格时转为限价单

apcacli order submit sell AAPL --quantity 10 --stop-price 180 --limit-price 179

追踪止损单 - 止损价格按指定百分比或金额跟随市场价格变动

# Percentage-based
apcacli order submit sell AAPL --quantity 10 --trail-percent 5

# Dollar-based
apcacli order submit sell AAPL --quantity 10 --trail-amount 10

重要说明

要求

• 必须安装 apcacli 二进制文件 - 通过 cargo install apcacli 安装
• 必须设置环境变量 - 需要 APCA_API_KEY_ID 和 APCA_API_SECRET_KEY
• Alpaca 账户 - 有效的模拟或实盘交易账户
• Rust 1.71+ - 从源代码安装时需要

交易限制

• 模拟交易与实盘交易：默认为模拟交易；设置 APCA_API_BASE_URL 可进行实盘交易
• 市场交易时间：大多数交易仅在市场交易时间内执行（美国东部时间上午 9:30 - 下午 4:00）
• 模式日内交易（PDT）：资产低于 $25k 的账户受 PDT 限制
• 购买力：受账户净值和保证金要求限制
• 订单限制：某些证券可能无法使用部分订单类型
• 加密货币交易：可能适用不同的规则和交易时间

数据与性能

• API 速率限制：Alpaca 设有请求限制，以防止滥用
• 实时数据：可能需要有效的数据订阅
• 命令输出：结果采用颜色编码格式，便于阅读
• 订单 ID：保存返回的订单 ID，以便跟踪和管理
• 网络依赖：需要连接互联网才能访问 Alpaca 的 API

故障排除

未设置环境变量

# Error: "Missing APCA_API_KEY_ID"
# Solution: Export required environment variables
export APCA_API_KEY_ID='your_key'
export APCA_API_SECRET_KEY='your_secret'

找不到命令

# Error: "apcacli: command not found"
# Solution: Install apcacli
cargo install apcacli

# Verify installation
which apcacli

API 身份验证失败

• 确认 API 凭证正确
• 检查是否使用了正确的端点（模拟交易或实盘交易）
• 确保 API 密钥未被撤销
• 确认账户状态为有效

订单被拒绝

• 确认市场已开市（适用于股票）
• 检查购买力是否充足
• 确认证券代码有效且可交易
• 检查订单参数（价格、数量）
• 检查账户是否存在任何限制

未找到持仓

• 确认证券代码正确
• 确认该持仓确实处于开启状态
• 检查该持仓是否先前已平仓
• 确认使用的是正确的账户（模拟交易或实盘交易）

高级功能

Shell 补全

生成 Shell 补全内容，以便更快速地输入命令：

# Install completion script
cargo run --bin=shell-complete > apcacli.bash
source apcacli.bash

# Now you can use tab completion
apcacli order <TAB>

使用流式命令进行监控

使用流式命令实时监控账户活动：

# Terminal 1: Monitor account events
apcacli stream account

# Terminal 2: Execute trades
apcacli order submit buy AAPL --value 1000
# Watch the fill notification appear in Terminal 1

脚本与自动化

将 apcacli 与 Shell 脚本结合，用于自动化策略：

#!/bin/bash
# Example: Daily portfolio check script

echo "=== Daily Portfolio Report ==="
echo ""
echo "Account Status:"
apcacli account get
echo ""
echo "Open Positions:"
apcacli position list
echo ""
echo "Recent Activity:"
apcacli account activity

其他资源

• apcacli 仓库：https://github.com/d-e-s-o/apcacli
• Alpaca 文档：https://docs.alpaca.markets/
• Alpaca API 参考：https://docs.alpaca.markets/reference/
• 模拟交易仪表板：https://app.alpaca.markets/paper/dashboard/overview
• apca Crate（底层库）：https://github.com/d-e-s-o/apca

安全提示

⚠️ 重要：

• 始终从模拟交易开始，以便无风险地进行测试
• 执行前检查所有订单详情
• 切勿分享 API 凭证
• 使用限价单以更好地控制价格
• 设置止损以管理风险
• 确认环境变量设置正确（模拟交易或实盘交易）
• 仔细核对证券代码和数量
• 定期监控持仓

致谢

apcacli 由 d-e-s-o 创建

基于 apca Rust crate 构建，用于与 Alpaca API 交互。