Alpaca 交易技能
透過 Alpaca REST API 使用 scripts/alpaca.sh 進行交易與管理投資組合。
設定
必要的環境變數
| 變數 | 用途 |
|---|---|
APCA_API_KEY_ID | Alpaca API 金鑰 |
APCA_API_SECRET_KEY | Alpaca API 密鑰 |
選用的環境變數
| 變數 | 預設值 | 用途 |
|---|---|---|
APCA_API_BASE_URL | https://paper-api.alpaca.markets | 交易端點。設為 https://api.alpaca.markets 以切換為實盤交易 |
APCA_DATA_API_BASE_URL | https://data.alpaca.markets | 市場數據端點 |
預設為紙上交易。 在切換為實盤交易前,務必先與使用者確認。
輔助腳本
從此技能目錄來源化 scripts/alpaca.sh。使用方式:
alpaca METHOD PATH [JSON_BODY]
# 市場數據:
ALPACA_DATA=1 alpaca METHOD PATH
快速參考
帳戶與投資組合
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' # 交易日曆
委託單 — 股票與加密貨幣
# 市價買入(按股數或金額)
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 # 取消全部
委託單 — 選擇權
# 買進買權(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
持倉
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' # 全部平倉
市場數據 — 股票
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'
市場數據 — 選擇權
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(需訂閱)
市場數據 — 加密貨幣
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'
公司行為
ALPACA_DATA=1 alpaca GET '/v1/corporate-actions?symbols=AAPL&types=cash_dividend'
# 類型:forward_split, reverse_split, cash_dividend, stock_dividend, spin_off 等
資產與自選清單
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 參考
請閱讀 references/api.md 取得完整的端點文件,包含:
- 所有委託單類型(限價、停損、停損限價、移動停損、第三方、OCO、OTO)
- 委託單欄位參考(side、type、time_in_force、order_class)
- 自選清單 CRUD
- 選擇權合約
- 歷史 K 線/成交/報價及所有查詢參數
- 加密貨幣端點
- 市場行事曆
安全規則
- 預設使用紙上交易。 未經使用者明確確認,絕不將
APCA_API_BASE_URL設為實盤環境。 - 送出委託單前先顯示 JSON。 讓使用者確認代號、數量、買賣方向及委託類型。
- 下單前檢查市場時鐘 — 股票僅在交易時段(美東時間 9:30-16:00)內交易,除非限價單設有
extended_hours: true。 - 下大單前檢查購買力,透過
GET /v2/account確認。 - 絕不提供財務建議。 呈現數據;讓使用者自行決定。
- 警告不可逆的操作 — 例如全部平倉、全部取消委託。
故障排除
| 症狀 | 解決方法 |
|---|---|
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 以獲得更好的輸出格式 |