alpaca-trading

Alpaca Trading — 交易 API

用于股票、加密货币和期权交易的 API。支持模拟交易（免费）和实盘交易。

基础 URL：

• 模拟交易：https://paper-api.alpaca.markets
• 实盘交易：https://api.alpaca.markets
• SDK：pip install alpaca-py

文档： docs.alpaca.markets

---

身份验证

获取 API 密钥

1. 前往 app.alpaca.markets
2. 创建账户（模拟交易免费）
3. 前往“API Keys” → Generate New Keys

配置

import os
from alpaca.trading.client import TradingClient

# Para paper trading
API_KEY = os.getenv("APCA_API_KEY_ID")
SECRET_KEY = os.getenv("APCA_API_SECRET_KEY")
BASE_URL = "https://paper-api.alpaca.markets"  # Paper

# Para live trading
# BASE_URL = "https://api.alpaca.markets"

client = TradingClient(API_KEY, SECRET_KEY, paper=True)

⚠️ 切勿将密钥硬编码。请使用环境变量。

---

速率限制

API	限制
订单	200 requests/min
账户/持仓	200 requests/min
账户活动	200 requests/min

建议

• 使用 WebSocket 获取实时更新 — 比轮询更高效
• 缓存账户/持仓信息 — 不要持续查询
• 针对 429 错误实现指数退避重试

---

账户

获取账户信息

account = client.get_account()
print(f"Buying Power: ${account.buying_power}")
print(f"Cash: ${account.cash}")
print(f"Portfolio Value: ${account.portfolio_value}")
print(f"Status: {account.status}")

账户配置

from alpaca.trading.requests import AccountConfigurationsRequest

config_request = AccountConfigurationsRequest(
    trade_confirmation_email=True,
    susi_transfer_email=True
)
client.update_account_configuration(config_request)

---

资产

列出所有资产

from alpaca.trading.requests import GetAssetsRequest
from alpaca.trading.enums import AssetClass, AssetStatus

request = GetAssetsRequest(
    asset_class=AssetClass.US_EQUITY,
    status=AssetStatus.ACTIVE
)

assets = client.get_all_assets(request)

# Filtrar symbols tradables
tradable = [a for a in assets if a.tradable]
print(f"Assets tradables: {len(tradable)}")

获取特定资产

asset = client.get_asset("AAPL")
print(f"AAPL tradable: {asset.tradable}")
print(f"AAPL class: {asset.asset_class}")

---

订单

订单类型

类型	描述
market	按当前价格执行
limit	最高价格（买入）或最低价格（卖出）
stop	达到 stop_price 时触发市价单
stop_limit	结合止损单和限价单
trailing_stop	相对于价格的止损

有效期

TIF	描述
day	仅限当日有效
gtc	持续有效，直到取消
opg	在市场开盘时开盘
cls	在市场收盘时收盘
ioc	立即成交，否则取消
fok	全部成交，否则取消

创建市价单

from alpaca.trading.requests import MarketOrderRequest
from alpaca.trading.enums import OrderSide, TimeInForce

order_request = MarketOrderRequest(
    symbol="AAPL",
    qty=10,
    side=OrderSide.BUY,
    time_in_force=TimeInForce.DAY
)

order = client.submit_order(order_request)
print(f"Order ID: {order.id}")
print(f"Status: {order.status}")

创建限价单

from alpaca.trading.requests import LimitOrderRequest

order_request = LimitOrderRequest(
    symbol="AAPL",
    qty=10,
    side=OrderSide.BUY,
    limit_price=150.00,  # Máximo a pagar
    time_in_force=TimeInForce.GTC
)

order = client.submit_order(order_request)

创建止损单

from alpaca.trading.requests import StopOrderRequest

order_request = StopOrderRequest(
    symbol="AAPL",
    qty=10,
    side=OrderSide.SELL,
    stop_price=145.00,  # Vende cuando caiga a este precio
    time_in_force=TimeInForce.GTC
)

获取订单

# Todas las órdenes abiertas
open_orders = client.get_orders(status="open")
print(f"Órdenes abiertas: {len(open_orders)}")

# Órdenes filladas hoy
from datetime import datetime
filled_orders = client.get_orders(
    status="fill",
    start=datetime(2024, 1, 15)
)

# Orden por ID
order = client.get_order_by_id(order_id)

取消订单

# Cancelar una orden
client.cancel_order(order_id)

# Cancelar todas las órdenes abiertas
client.cancel_orders()

替换订单

from alpaca.trading.requests import ReplaceOrderRequest

replace_request = ReplaceOrderRequest(
    limit_price=155.00,  # Nuevo precio límite
    qty=15               # Nueva cantidad
)
client.replace_order(order_id, replace_request)

---

持仓

获取未平仓持仓

positions = client.get_all_positions()

for pos in positions:
    print(f"{pos.symbol}: {pos.qty} shares")
    print(f"  Avg Entry: ${pos.avg_entry_price}")
    print(f"  Market Value: ${pos.market_value}")
    print(f"  P/L: ${pos.unrealized_pl}")

获取特定持仓

position = client.get_position("AAPL")
print(f"AAPL: {position.qty} shares @ ${position.avg_entry_price}")

平仓

# Cerrar toda la posición
client.close_position("AAPL")

# Cerrar posición parcialmente (qty=5)
client.close_position("AAPL", qty=5)

平掉所有持仓

client.close_all_positions()

---

期权交易

交易等级

等级	描述
0	不允许期权交易
1	备兑看涨期权、现金担保看跌期权
2	买入/卖出看涨期权和看跌期权
3	价差策略

获取期权合约

from alpaca.trading.requests import GetOptionContractsRequest
from datetime import datetime, timedelta

request = GetOptionContractsRequest(
    underlying_symbols=["AAPL"],
    expiration_date_gte=datetime.now().strftime("%Y-%m-%d"),
    expiration_date_lte=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
    strike_price_gte=100,
    strike_price_lte=200,
    limit=100
)

contracts = client.get_option_contracts(request)
contract = contracts.option_contracts[0]

# Trade con contract ID
order_request = MarketOrderRequest(
    symbol=contract.id,  # Usar ID del contract
    qty=1,
    side=OrderSide.BUY,
    time_in_force=TimeInForce.DAY
)

行使期权

# Ejercer una posición de opción
client.exercise_options(position_id)

---

加密货币交易

列出可用交易代码

from alpaca.trading.enums import AssetClass

crypto_assets = client.get_all_assets(asset_class=AssetClass.CRYPTO)
crypto = [a for a in crypto_assets if a.tradable]
print(f"Crypto tradables: {[a.symbol for a in crypto[:10]]}")

加密货币订单

order_request = MarketOrderRequest(
    symbol="BTC/USD",
    qty=0.1,  # Fracciones permitidas
    side=OrderSide.BUY,
    time_in_force=TimeInForce.GTC
)
client.submit_order(order_request)

---

市场时段

获取交易时钟

clock = client.get_clock()
print(f"Market open: {clock.is_open}")
print(f"Next open: {clock.next_open}")
print(f"Next close: {clock.next_close}")

检查市场是否开市

if clock.is_open:
    print("Mercado abierto - puedes tradear")
else:
    print("Mercado cerrado")

---

投资组合历史

from datetime import datetime

history = client.get_account_portfolio_history(
    date_start=datetime(2024, 1, 1),
    timeframe="1D"
)

print(f"Equity: {history.equity}")
print(f"Profit/Loss: {history.profit_loss}")

---

自选列表

from alpaca.trading.requests import CreateWatchlistRequest

# Crear watchlist
watchlist = client.create_watchlist(
    CreateWatchlistRequest(name="Tech Stocks")
)

# Agregar símbolo
client.add_to_watchlist(watchlist.id, "AAPL")

# Obtener watchlists
watchlists = client.get_watchlists()

---

WebSocket 流式传输

from alpaca.trading.stream import TradingStream

async def handle_trade_update(data):
    print(f"Update: {data}")

stream = TradingStream(API_KEY, SECRET_KEY, paper=True)

stream.subscribe_trade_updates(handle_trade_update)
stream.run()

---

示例脚本

查看 ./scripts/：

# Ver cuenta
python ./scripts/check_account.py

# Ver posiciones
python ./scripts/check_positions.py

# Enviar orden de prueba
python ./scripts/place_order.py --symbol AAPL --qty 10 --side buy --type market

---

常见错误

错误	原因	解决方案
403 Forbidden	密钥无效	检查 API 密钥
403	无权限	在控制面板中启用
400 Bad Request	参数无效	查看订单文档
403 Trading Halted	交易已暂停	等待或检查状态
403 No Buying Power	资金不足	存入资金
422	交易代码不可交易	检查交易代码
429 Too Many Requests	速率限制	实现退避

---

对比：模拟交易与实盘交易

方面	模拟交易	实盘交易
URL	paper-api.alpaca.markets	api.alpaca.markets
真实资金	❌ 否	✅ 是
真实订单	❌ 模拟订单	✅ 真实订单
市场数据	✅ 真实	✅ 真实
用于测试	✅ 理想	❌ 不适用

务必先在模拟交易环境中测试。