Historical Auctions

The auctions module provides access to opening and closing auction data for stocks.

Overview

The auctions module allows you to retrieve:

Opening auction prices and volumes
Closing auction prices and volumes
Intraday returns between auctions
Daily aggregated auction data

Usage

Historical Auctions

from py_alpaca_api import PyAlpacaAPI

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

# Get auction data for a single symbol
auctions = api.stock.auctions.get_auctions(
    "AAPL",
    start="2024-01-01",
    end="2024-01-31"
)

# Returns a DataFrame with columns:
# - opening_price: Opening auction price
# - opening_volume: Opening auction volume
# - closing_price: Closing auction price
# - closing_volume: Closing auction volume
# - intraday_return: Return from opening to closing

Multiple Symbol Auctions

# Get auctions for multiple symbols
symbols = ["AAPL", "MSFT", "GOOGL"]
auctions = api.stock.auctions.get_auctions(
    symbols,
    start="2024-01-01",
    end="2024-01-31"
)

# Returns a dictionary mapping symbols to DataFrames
for symbol, df in auctions.items():
    print(f"{symbol}: {len(df)} auctions")
    print(f"Average intraday return: {df['intraday_return'].mean():.2f}%")

Daily Aggregated Auctions

# Get daily aggregated auction data
daily_auctions = api.stock.auctions.get_daily_auctions(
    "AAPL",
    start="2024-01-01",
    end="2024-01-31"
)

# Returns daily aggregated data with:
# - One row per trading day
# - Opening and closing prices for the day
# - Daily return calculation

Parameters

get_auctions()

symbols: Single symbol string or list of symbols
start: Start date in YYYY-MM-DD format
end: End date in YYYY-MM-DD format
limit: Maximum number of auctions per symbol (default: 10000)
asof: As-of date for corporate actions adjustments
feed: Data feed to use (“iex”, “sip”, or “otc”)
page_token: Pagination token from previous request
sort: Sort order (“asc” or “desc”)

get_daily_auctions()

symbols: Single symbol string or list of symbols
start: Start date in YYYY-MM-DD format
end: End date in YYYY-MM-DD format
feed: Data feed to use (“iex”, “sip”, or “otc”)

Features

Intraday Return Calculation

The module automatically calculates intraday returns:

# Analyze intraday returns
auctions = api.stock.auctions.get_auctions("AAPL", start="2024-01-01", end="2024-01-31")

print(f"Average intraday return: {auctions['intraday_return'].mean():.2f}%")
print(f"Max intraday return: {auctions['intraday_return'].max():.2f}%")
print(f"Min intraday return: {auctions['intraday_return'].min():.2f}%")

# Find days with large movements
large_moves = auctions[abs(auctions['intraday_return']) > 2]
print(f"Days with >2% intraday move: {len(large_moves)}")

Auction Volume Analysis

# Analyze auction volumes
auctions = api.stock.auctions.get_auctions("AAPL", start="2024-01-01", end="2024-01-31")

# Compare opening vs closing volumes
avg_opening_vol = auctions['opening_volume'].mean()
avg_closing_vol = auctions['closing_volume'].mean()

print(f"Average opening volume: {avg_opening_vol:,.0f}")
print(f"Average closing volume: {avg_closing_vol:,.0f}")
print(f"Closing/Opening ratio: {avg_closing_vol/avg_opening_vol:.2f}")

Daily Aggregation

# Get daily summary
daily = api.stock.auctions.get_daily_auctions(
    "AAPL",
    start="2024-01-01",
    end="2024-01-31"
)

# Analyze daily patterns
print(f"Average daily return: {daily['daily_return'].mean():.2f}%")
print(f"Volatility (std): {daily['daily_return'].std():.2f}%")

# Find trending days
up_days = daily[daily['daily_return'] > 0]
down_days = daily[daily['daily_return'] < 0]
print(f"Up days: {len(up_days)} ({len(up_days)/len(daily)*100:.1f}%)")
print(f"Down days: {len(down_days)} ({len(down_days)/len(daily)*100:.1f}%)")

Pagination

The module handles pagination automatically:

# Automatically handles pagination for large requests
auctions = api.stock.auctions.get_auctions(
    "AAPL",
    start="2023-01-01",
    end="2024-12-31",
    limit=50000  # Will paginate as needed
)

Error Handling

from py_alpaca_api.exceptions import ValidationError

try:
    auctions = api.stock.auctions.get_auctions(
        "AAPL",
        start="invalid-date",
        end="2024-01-01"
    )
except ValidationError as e:
    print(f"Validation error: {e}")