Configuration

PyAlpacaAPI offers various configuration options to customize its behavior.

API Configuration

Basic Configuration

from py_alpaca_api import PyAlpacaAPI

api = PyAlpacaAPI(
    api_key="your_api_key",
    api_secret="your_secret_key",
    api_paper=True,  # Use paper trading (default)
    api_version="v2"  # API version (default)
)

Configuration Parameters

Parameter	Type	Default	Description
`api_key`	str	Required	Your Alpaca API key
`api_secret`	str	Required	Your Alpaca secret key
`api_paper`	bool	`True`	Use paper trading endpoint
`api_version`	str	`"v2"`	Alpaca API version
`cache_config`	CacheConfig	`None`	Cache configuration

Cache Configuration

Memory Cache (Default)

from py_alpaca_api.cache import CacheConfig, CacheType

cache_config = CacheConfig(
    cache_type=CacheType.MEMORY,
    max_size=1000,  # Maximum cache entries
    default_ttl=300  # Default TTL in seconds
)

api = PyAlpacaAPI(
    api_key="your_api_key",
    api_secret="your_secret_key",
    cache_config=cache_config
)

Redis Cache

from py_alpaca_api.cache import CacheConfig, CacheType

cache_config = CacheConfig(
    cache_type=CacheType.REDIS,
    redis_host="localhost",
    redis_port=6379,
    redis_password="optional_password",
    redis_db=0,
    default_ttl=300
)

api = PyAlpacaAPI(
    api_key="your_api_key",
    api_secret="your_secret_key",
    cache_config=cache_config
)

Custom TTL Configuration

Different data types have different optimal cache durations:

cache_config = CacheConfig(
    cache_type=CacheType.MEMORY,
    ttl_config={
        "market_hours": 86400,  # 1 day
        "assets": 3600,         # 1 hour
        "account": 60,          # 1 minute
        "positions": 10,        # 10 seconds
        "orders": 5,            # 5 seconds
        "quotes": 1,            # 1 second
        "bars": 300,            # 5 minutes
        "news": 600,            # 10 minutes
    }
)

Feed Configuration

PyAlpacaAPI automatically detects your data subscription level and falls back to available feeds.

Automatic Feed Detection

# Automatic feed selection (recommended)
quote = api.stock.latest_quote.get("AAPL")
# Tries SIP → IEX → OTC automatically

Manual Feed Selection

# Force specific feed
quote = api.stock.latest_quote.get("AAPL", feed="iex")

# Available feeds:
# - "sip": Full market data (requires subscription)
# - "iex": IEX Exchange data
# - "otc": OTC market data

Environment Variables

Using .env File

Create a .env file in your project root:

# API Credentials
ALPACA_API_KEY=your_api_key_here
ALPACA_SECRET_KEY=your_secret_key_here

# Optional Configuration
ALPACA_API_PAPER=true
ALPACA_API_VERSION=v2

# Redis Configuration (optional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0

# Cache Configuration
CACHE_TYPE=redis  # or memory
CACHE_DEFAULT_TTL=300
CACHE_MAX_SIZE=1000

Loading Environment Variables

import os
from dotenv import load_dotenv
from py_alpaca_api import PyAlpacaAPI
from py_alpaca_api.cache import CacheConfig, CacheType

# Load environment variables
load_dotenv()

# Configure cache from environment
cache_type = CacheType.REDIS if os.getenv("CACHE_TYPE") == "redis" else CacheType.MEMORY

cache_config = CacheConfig(
    cache_type=cache_type,
    redis_host=os.getenv("REDIS_HOST", "localhost"),
    redis_port=int(os.getenv("REDIS_PORT", 6379)),
    redis_password=os.getenv("REDIS_PASSWORD"),
    default_ttl=int(os.getenv("CACHE_DEFAULT_TTL", 300)),
    max_size=int(os.getenv("CACHE_MAX_SIZE", 1000))
)

# Initialize API
api = PyAlpacaAPI(
    api_key=os.getenv("ALPACA_API_KEY"),
    api_secret=os.getenv("ALPACA_SECRET_KEY"),
    api_paper=os.getenv("ALPACA_API_PAPER", "true").lower() == "true",
    cache_config=cache_config
)

Request Configuration

Retry Configuration

PyAlpacaAPI automatically retries failed requests with exponential backoff:

Maximum retries: 3
Backoff factor: 2
Retry on: 429 (Rate Limit), 500, 502, 503, 504

Timeout Configuration

Default timeouts:

Connect timeout: 10 seconds
Read timeout: 30 seconds

Logging Configuration

import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Set PyAlpacaAPI logging level
logging.getLogger("py_alpaca_api").setLevel(logging.DEBUG)

Performance Configuration

Batch Size Configuration

For operations involving multiple symbols:

# Automatic batching for 200+ symbols
symbols = ["AAPL", "GOOGL", ...] # 500 symbols
quotes = api.stock.latest_quote.get_multiple(symbols)
# Automatically batched into 3 requests (200, 200, 100)

Concurrent Request Configuration

# Concurrent processing for large datasets
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(max_workers=5) as executor:
    futures = []
    for symbol_batch in symbol_batches:
        future = executor.submit(api.stock.history.get_bars, symbol_batch)
        futures.append(future)

    results = [future.result() for future in futures]

Best Practices

Use Environment Variables: Never hardcode API credentials
Enable Caching: Reduce API calls and improve performance
Use Paper Trading: Always test with paper trading first
Configure Logging: Monitor API interactions and errors
Handle Rate Limits: Implement proper retry logic
Batch Operations: Use batch methods for multiple symbols
Set Appropriate TTLs: Balance freshness vs performance