alpaca-trading

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Alpaca Trading — Trading API

Alpaca交易 — 交易API

API para trading de acciones, crypto y opciones. Soporta paper trading (gratis) y live trading.
Base URLs:
  • Paper:
    https://paper-api.alpaca.markets
  • Live:
    https://api.alpaca.markets
  • SDK:
    pip install alpaca-py

用于股票、加密货币和期权交易的API。支持免费的模拟交易(paper trading)和实盘交易(live trading)。
基础URL:
  • 模拟环境:
    https://paper-api.alpaca.markets
  • 实盘环境:
    https://api.alpaca.markets
  • SDK安装:
    pip install alpaca-py

Autenticación

认证

Obtener API Keys

获取API密钥

  1. Ir a app.alpaca.markets
  2. Crear cuenta (paper trading es gratis)
  3. Ir a "API Keys" → Generate New Keys
  1. 访问 app.alpaca.markets
  2. 创建账户(模拟交易免费)
  3. 进入“API Keys” → 生成新密钥

Configuración

配置

python
import os
from alpaca.trading.client import TradingClient
python
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
API_KEY = os.getenv("APCA_API_KEY_ID") SECRET_KEY = os.getenv("APCA_API_SECRET_KEY") BASE_URL = "https://paper-api.alpaca.markets" # 模拟环境

Para live trading

用于实盘交易

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

**⚠️ NUNCA hardcodear keys. Usar variables de entorno.**

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

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

---

Rate Limits

请求速率限制

APILímite
Orders200 requests/min
Account/Positions200 requests/min
Account Activities200 requests/min
API限制
订单200次请求/分钟
账户/仓位200次请求/分钟
账户活动200次请求/分钟

Recomendaciones

建议

  • Usar WebSocket para updates en tiempo real — más eficiente que polling
  • Cachear account/positions — no consultar constantemente
  • Implementar retry con exponential backoff para 429 errors

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

Account

账户

Obtener Información de Cuenta

获取账户信息

python
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}")
python
account = client.get_account()
print(f"购买力: ${account.buying_power}")
print(f"现金余额: ${account.cash}")
print(f"投资组合价值: ${account.portfolio_value}")
print(f"账户状态: {account.status}")

Configuración de Cuenta

账户配置

python
from alpaca.trading.requests import AccountConfigurationsRequest

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

python
from alpaca.trading.requests import AccountConfigurationsRequest

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

Assets

资产

Listar Todos los Assets

列出所有资产

python
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)
python
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)}")
undefined
tradable = [a for a in assets if a.tradable] print(f"可交易资产数量: {len(tradable)}")
undefined

Obtener Asset Específico

获取特定资产

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

python
asset = client.get_asset("AAPL")
print(f"AAPL是否可交易: {asset.tradable}")
print(f"AAPL资产类别: {asset.asset_class}")

Orders

订单

Tipos de Órdenes

订单类型

TipoDescripción
market
Ejecuta al precio actual
limit
Precio máximo (buy) o mínimo (sell)
stop
Activa orden de mercado cuando alcanza stop_price
stop_limit
Combina stop + limit
trailing_stop
Stop relativo al precio
类型描述
market
按当前市价执行
limit
设置买入最高价或卖出最低价
stop
价格达到止损价时触发市价订单
stop_limit
结合止损与限价订单
trailing_stop
相对价格的止损订单

Time in Force

订单有效期(Time in Force)

TIFDescripción
day
Solo para día actual
gtc
Good Till Cancelled
opg
Open at market open
cls
Close at market close
ioc
Immediate Or Cancel
fok
Fill Or Kill
TIF描述
day
仅当日有效
gtc
未撤销前持续有效
opg
开盘时执行
cls
收盘时执行
ioc
立即执行未成交部分撤销
fok
全部成交否则撤销

Crear Orden de Market

创建市价订单

python
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}")
python
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"订单ID: {order.id}")
print(f"订单状态: {order.status}")

Crear Orden Limit

创建限价订单

python
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)
python
from alpaca.trading.requests import LimitOrderRequest

order_request = LimitOrderRequest(
    symbol="AAPL",
    qty=10,
    side=OrderSide.BUY,
    limit_price=150.00,  # 最高买入价
    time_in_force=TimeInForce.GTC
)

order = client.submit_order(order_request)

Crear Orden Stop

创建止损订单

python
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
)
python
from alpaca.trading.requests import StopOrderRequest

order_request = StopOrderRequest(
    symbol="AAPL",
    qty=10,
    side=OrderSide.SELL,
    stop_price=145.00,  # 价格跌至该值时卖出
    time_in_force=TimeInForce.GTC
)

Obtener Órdenes

获取订单

python
undefined
python
undefined

Todas las órdenes abiertas

获取所有未成交订单

open_orders = client.get_orders(status="open") print(f"Órdenes abiertas: {len(open_orders)}")
open_orders = client.get_orders(status="open") print(f"未成交订单数量: {len(open_orders)}")

Órdenes filladas hoy

获取今日已成交订单

from datetime import datetime filled_orders = client.get_orders( status="fill", start=datetime(2024, 1, 15) )
from datetime import datetime filled_orders = client.get_orders( status="fill", start=datetime(2024, 1, 15) )

Orden por ID

通过ID获取订单

order = client.get_order_by_id(order_id)
undefined
order = client.get_order_by_id(order_id)
undefined

Cancelar Órdenes

取消订单

python
undefined
python
undefined

Cancelar una orden

取消单个订单

client.cancel_order(order_id)
client.cancel_order(order_id)

Cancelar todas las órdenes abiertas

取消所有未成交订单

client.cancel_orders()
undefined
client.cancel_orders()
undefined

Reemplazar Orden

修改订单

python
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)

python
from alpaca.trading.requests import ReplaceOrderRequest

replace_request = ReplaceOrderRequest(
    limit_price=155.00,  # 新的限价
    qty=15               # 新的数量
)
client.replace_order(order_id, replace_request)

Positions

仓位

Obtener Posiciones Abiertas

获取未平仓仓位

python
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}")
python
positions = client.get_all_positions()

for pos in positions:
    print(f"{pos.symbol}: {pos.qty} 股")
    print(f"  平均入场价: ${pos.avg_entry_price}")
    print(f"  市值: ${pos.market_value}")
    print(f"  浮动盈亏: ${pos.unrealized_pl}")

Obtener Posición Específica

获取特定仓位

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

Cerrar Posición

平仓

python
undefined
python
undefined

Cerrar toda la posición

全部平仓

client.close_position("AAPL")
client.close_position("AAPL")

Cerrar posición parcialmente (qty=5)

部分平仓(数量=5)

client.close_position("AAPL", qty=5)
undefined
client.close_position("AAPL", qty=5)
undefined

Cerrar Todas las Posiciones

平所有仓位

python
client.close_all_positions()

python
client.close_all_positions()

Options Trading

期权交易

Trading Levels

交易等级

LevelDescripción
0Sin trading de opciones
1Covered calls, cash-secured puts
2Buy/sell calls y puts
3Spreads
等级描述
0不允许期权交易
1备兑看涨期权、现金担保看跌期权
2买入/卖出看涨期权和看跌期权
3期权价差策略

Obtener Option Contracts

获取期权合约

python
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]
python
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

使用合约ID下单

order_request = MarketOrderRequest( symbol=contract.id, # Usar ID del contract qty=1, side=OrderSide.BUY, time_in_force=TimeInForce.DAY )
undefined
order_request = MarketOrderRequest( symbol=contract.id, # 使用合约ID qty=1, side=OrderSide.BUY, time_in_force=TimeInForce.DAY )
undefined

Ejercitar Opción

行权期权

python
undefined
python
undefined

Ejercer una posición de opción

对期权仓位行权

client.exercise_options(position_id)

---
client.exercise_options(position_id)

---

Crypto Trading

加密货币交易

Listar Symbols Disponibles

列出可用标的

python
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]]}")
python
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"可交易加密货币: {[a.symbol for a in crypto[:10]]}")

Órdenes de Crypto

加密货币订单

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

python
order_request = MarketOrderRequest(
    symbol="BTC/USD",
    qty=0.1,  # 允许 fractional 交易
    side=OrderSide.BUY,
    time_in_force=TimeInForce.GTC
)
client.submit_order(order_request)

Market Hours

市场时间

Obtener Clock

获取市场时钟

python
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}")
python
clock = client.get_clock()
print(f"市场是否开盘: {clock.is_open}")
print(f"下次开盘时间: {clock.next_open}")
print(f"下次收盘时间: {clock.next_close}")

Verificar si Mercado está Abierto

检查市场是否开盘

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

python
if clock.is_open:
    print("市场已开盘 - 可以交易")
else:
    print("市场已收盘")

Portfolio History

投资组合历史

python
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}")

python
from datetime import datetime

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

print(f"权益: {history.equity}")
print(f"盈亏: {history.profit_loss}")

Watchlists

关注列表

python
from alpaca.trading.requests import CreateWatchlistRequest
python
from alpaca.trading.requests import CreateWatchlistRequest

Crear watchlist

创建关注列表

watchlist = client.create_watchlist( CreateWatchlistRequest(name="Tech Stocks") )
watchlist = client.create_watchlist( CreateWatchlistRequest(name="科技股") )

Agregar símbolo

添加标的

client.add_to_watchlist(watchlist.id, "AAPL")
client.add_to_watchlist(watchlist.id, "AAPL")

Obtener watchlists

获取所有关注列表

watchlists = client.get_watchlists()

---
watchlists = client.get_watchlists()

---

WebSocket Streaming

WebSocket流

python
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()

python
from alpaca.trading.stream import TradingStream

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

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

stream.subscribe_trade_updates(handle_trade_update)
stream.run()

Scripts de Ejemplo

示例脚本

Ver ./scripts/:
bash
undefined
查看 ./scripts/:
bash
undefined

Ver cuenta

查看账户信息

python ./scripts/check_account.py
python ./scripts/check_account.py

Ver posiciones

查看仓位信息

python ./scripts/check_positions.py
python ./scripts/check_positions.py

Enviar orden de prueba

提交测试订单

python ./scripts/place_order.py --symbol AAPL --qty 10 --side buy --type market

---
python ./scripts/place_order.py --symbol AAPL --qty 10 --side buy --type market

---

Errores Comunes

常见错误

ErrorCausaSolución
403 ForbiddenKeys inválidasVerificar API keys
403Sin permisosHabilitar en dashboard
400 Bad RequestParámetros inválidosVer docs de orden
403 Trading HaltedTrading pausadoEsperar o verificar
403 No Buying PowerSin fondosDepositar dinero
422Symbol no tradableVerificar symbol
429 Too Many RequestsRate limitImplementar backoff

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

Comparación: Paper vs Live

对比:模拟交易 vs 实盘交易

AspectoPaperLive
URLpaper-api.alpaca.marketsapi.alpaca.markets
Dinero real❌ No✅ Sí
Órdenes reales❌ Simuladas✅ Reales
Datos de mercado✅ Reales✅ Reales
Para testing✅ Ideal❌ No
Siempre probar en paper primero.
方面模拟交易实盘交易
URLpaper-api.alpaca.marketsapi.alpaca.markets
真实资金❌ 否✅ 是
真实订单❌ 模拟✅ 真实
市场数据✅ 真实✅ 真实
用于测试✅ 理想❌ 不建议
请始终先在模拟环境中测试。