alpaca-trading

Alpaca Trading — Trading API

API for trading stocks, crypto, and options. Supports paper trading (free) and live trading.

Base URLs:

Paper: https://paper-api.alpaca.markets
Live: https://api.alpaca.markets
SDK: pip install alpaca-py

Docs: docs.alpaca.markets

Authentication

Get API Keys

Go to app.alpaca.markets
Create account (paper trading is free)
Go to "API Keys" → Generate New Keys

Configuration

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)

⚠️ NEVER hardcode keys. Use environment variables.

Rate Limits

API	Limit
Orders	200 requests/min
Account/Positions	200 requests/min
Account Activities	200 requests/min

Recommendations

Use WebSocket for real-time updates — more efficient than polling
Cache account/positions — do not query constantly
Implement retry with exponential backoff for 429 errors

Account

Get Account Information

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

Account Configuration

from alpaca.trading.requests import AccountConfigurationsRequest

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

Assets

List All Assets

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

Get Specific Asset

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

Orders

Order Types

Type	Description
`market`	Executes at the current price
`limit`	Maximum price (buy) or minimum price (sell)
`stop`	Activates market order when it reaches stop_price
`stop_limit`	Combines stop + limit
`trailing_stop`	Stop relative to price

Time in Force

TIF	Description
`day`	Current day only
`gtc`	Good Till Cancelled
`opg`	Open at market open
`cls`	Close at market close
`ioc`	Immediate Or Cancel
`fok`	Fill Or Kill

Create Market Order

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

Create Limit Order

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)

Create Stop Order

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
)

Get Orders

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

Cancel Orders

# Cancelar una orden
client.cancel_order(order_id)

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

Replace Order

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

Get Open Positions

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

Get Specific Position

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

Close Position

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

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

Close All Positions

client.close_all_positions()

Options Trading

Trading Levels

Level	Description
0	No options trading
1	Covered calls, cash-secured puts
2	Buy/sell calls and puts
3	Spreads

Get Option Contracts

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
)

Exercise Option

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

Crypto Trading

List Available Symbols

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

Crypto Orders

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

Market Hours

Get Clock

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

Check if Market is Open

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

Portfolio History

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

Watchlists

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 Streaming

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

Example Scripts

See ./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

Common Errors

Error	Cause	Solution
403 Forbidden	Invalid keys	Verify API keys
403	No permissions	Enable in dashboard
400 Bad Request	Invalid parameters	See order docs
403 Trading Halted	Trading paused	Wait or verify
403 No Buying Power	No funds	Deposit money
422	Symbol not tradable	Verify symbol
429 Too Many Requests	Rate limit	Implement backoff

Comparison: Paper vs Live

Aspect	Paper	Live
URL	paper-api.alpaca.markets	api.alpaca.markets
Real money	❌ No	✅ Yes
Real orders	❌ Simulated	✅ Real
Market data	✅ Real	✅ Real
For testing	✅ Ideal	❌ No

Always test in paper first.