Quickstart Guide

This guide will help you get started with PyAlpacaAPI quickly.

Basic Setup

from py_alpaca_api import PyAlpacaAPI
import os

# Initialize the API client
api = PyAlpacaAPI(
    api_key=os.environ.get("ALPACA_API_KEY"),
    api_secret=os.environ.get("ALPACA_SECRET_KEY"),
    api_paper=True  # Use paper trading
)

Trading Operations

Get Account Information

# Get account details
account = api.trading.account.get()
print(f"Buying Power: ${account.buying_power}")
print(f"Portfolio Value: ${account.portfolio_value}")

Place Orders

# Place a market order
order = api.trading.orders.market(
    symbol="AAPL",
    qty=10,
    side="buy"
)
print(f"Order placed: {order.id}")

# Place a limit order with stop loss and take profit
order = api.trading.orders.limit(
    symbol="AAPL",
    qty=10,
    limit_price=150.00,
    side="buy",
    stop_loss=145.00,
    take_profit=160.00
)

Manage Positions

# Get all positions
positions = api.trading.positions.get_all()
for position in positions:
    print(f"{position.symbol}: {position.qty} shares at ${position.avg_entry_price}")

# Get specific position
aapl_position = api.trading.positions.get("AAPL")

Market Data

Get Stock Quotes

# Get latest quote for a single symbol
quote = api.stock.latest_quote.get("AAPL")
print(f"AAPL: ${quote.ask_price} / ${quote.bid_price}")

# Get quotes for multiple symbols (automatic batching)
symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "TSLA"]
quotes = api.stock.latest_quote.get_multiple(symbols)
for symbol, quote in quotes.items():
    print(f"{symbol}: ${quote.ask_price}")

Get Historical Data

import pendulum

# Get historical bars
bars = api.stock.history.get_bars(
    symbol="AAPL",
    start=pendulum.now().subtract(days=30),
    end=pendulum.now(),
    timeframe="1Day"
)
print(bars.head())

Stock Analysis

Screen for Top Performers

# Get top gainers
gainers = api.stock.screener.get_gainers(top=10)
for stock in gainers:
    print(f"{stock['symbol']}: +{stock['change_percentage']:.2f}%")

# Get top losers
losers = api.stock.screener.get_losers(top=10)

Get Stock Predictions

# Get ML prediction for a stock
prediction = api.stock.predictor.predict(
    symbol="AAPL",
    days=30  # Predict 30 days ahead
)
print(f"Predicted price in 30 days: ${prediction['predicted_price']}")

Get News and Sentiment

# Get latest news
news = api.trading.news.get(symbols=["AAPL"], limit=5)
for article in news:
    print(f"{article.headline} - {article.created_at}")

# Get analyst recommendations
recommendations = api.trading.recommendations.get("AAPL")
print(f"Consensus: {recommendations['consensus']}")
print(f"Target Price: ${recommendations['target_price']}")

Watchlists

# Create a watchlist
watchlist = api.trading.watchlists.create(
    name="Tech Stocks",
    symbols=["AAPL", "GOOGL", "MSFT", "AMZN"]
)

# Get all watchlists
watchlists = api.trading.watchlists.get_all()
for wl in watchlists:
    print(f"{wl.name}: {len(wl.symbols)} symbols")

Using Caching

from py_alpaca_api.cache import CacheConfig, CacheType

# Configure caching
cache_config = CacheConfig(
    cache_type=CacheType.REDIS,  # or CacheType.MEMORY
    redis_host="localhost",
    redis_port=6379,
    default_ttl=300  # 5 minutes
)

# Initialize API with caching
api = PyAlpacaAPI(
    api_key=os.environ.get("ALPACA_API_KEY"),
    api_secret=os.environ.get("ALPACA_SECRET_KEY"),
    api_paper=True,
    cache_config=cache_config
)

Error Handling

from py_alpaca_api.exceptions import (
    PyAlpacaAPIError,
    AuthenticationError,
    APIRequestError,
    ValidationError
)

try:
    order = api.trading.orders.market(
        symbol="INVALID",
        qty=10,
        side="buy"
    )
except ValidationError as e:
    print(f"Invalid input: {e}")
except APIRequestError as e:
    print(f"API error: {e}")
except PyAlpacaAPIError as e:
    print(f"General error: {e}")

Next Steps