alterlab-alpha-vantage

Alpha Vantage — Financial Market Data

Access 20+ years of global financial data: equities, options, forex, crypto, commodities, economic indicators, fundamentals, news sentiment, and 50+ technical indicators — all from one /query endpoint.

When to Use This Skill

• Pulling OHLCV price history or a latest quote for a ticker, FX pair, or crypto asset
• Fetching pre-computed company fundamentals (overview ratios, statements, earnings, dividends, splits)
• Computing technical indicators server-side (SMA, EMA, RSI, BBANDS, ...)
• Retrieving commodity prices or headline US macro series (GDP, CPI, yields, unemployment)
• News-sentiment, earnings-call transcripts, or insider transactions for event studies

Does NOT Trigger

Scenario	Use Instead
Macro series by FRED ID (UNRATE, GDPC1), server-side pc1 transforms, ALFRED vintages	alterlab-fred
Line items from the actual 10-K/10-Q, XBRL facts, Form 4/13F filings from SEC EDGAR	alterlab-edgartools
Treasury debt to the penny, Daily/Monthly Treasury Statements, auction results	alterlab-usfiscaldata
Aggregate hedge-fund leverage / SEC Form PF statistics	alterlab-hedgefund-monitor
Fitting ARIMA/regression models to the series you downloaded	alterlab-statsmodels

API Key Setup (Required)

1. Get a free key at https://www.alphavantage.co/support/#api-key (premium plans raise limits and unlock premium endpoints)
2. Set as environment variable:

export ALPHAVANTAGE_API_KEY="your_key_here"

If an Alpha Vantage MCP connector is configured (Alpha Vantage runs an official MCP server, see https://mcp.alphavantage.co/), prefer it for live lookups; the REST patterns below work everywhere.

Installation

uv pip install requests pandas

Base URL & Request Pattern

All requests go to:

https://www.alphavantage.co/query?function=FUNCTION_NAME&apikey=YOUR_KEY&...params

import os
import requests

API_KEY = os.environ.get("ALPHAVANTAGE_API_KEY")
BASE_URL = "https://www.alphavantage.co/query"

def av_get(function, **params):
    response = requests.get(BASE_URL, params={"function": function, "apikey": API_KEY, **params}, timeout=30)
    response.raise_for_status()
    data = response.json()
    # Alpha Vantage reports errors and limit hits with HTTP 200 + one of these keys
    for key in ("Error Message", "Information", "Note"):
        if key in data:
            raise RuntimeError(f"Alpha Vantage {key}: {data[key]}")
    return data

Quick Start Examples

# Stock quote (latest price; end-of-day unless you have a realtime entitlement)
quote = av_get("GLOBAL_QUOTE", symbol="AAPL")
price = quote["Global Quote"]["05. price"]

# Daily OHLCV: compact = latest 100 points (free); outputsize="full" (25+ years) is premium-only
daily = av_get("TIME_SERIES_DAILY", symbol="AAPL", outputsize="compact")
ts = daily["Time Series (Daily)"]

# Company fundamentals
overview = av_get("OVERVIEW", symbol="AAPL")
print(overview["MarketCapitalization"], overview["PERatio"])

# Income statement
income = av_get("INCOME_STATEMENT", symbol="AAPL")
annual = income["annualReports"][0]  # Most recent annual

# Crypto price
crypto = av_get("DIGITAL_CURRENCY_DAILY", symbol="BTC", market="USD")

# Economic indicator
gdp = av_get("REAL_GDP", interval="annual")

# Technical indicator
rsi = av_get("RSI", symbol="AAPL", interval="daily", time_period=14, series_type="close")

API Categories

Category	Key Functions
Time Series (Stocks)	GLOBAL_QUOTE, TIME_SERIES_INTRADAY*, TIME_SERIES_DAILY, TIME_SERIES_DAILY_ADJUSTED*, TIME_SERIES_WEEKLY(_ADJUSTED), TIME_SERIES_MONTHLY(_ADJUSTED), REALTIME_BULK_QUOTES*, MARKET_STATUS, SYMBOL_SEARCH
Index Data	INDEX_DATA*, INDEX_CATALOG*
Options	REALTIME_OPTIONS*, HISTORICAL_OPTIONS* (plus put-call and volume/OI ratio endpoints)
Alpha Intelligence	NEWS_SENTIMENT, EARNINGS_CALL_TRANSCRIPT, TOP_GAINERS_LOSERS, INSIDER_TRANSACTIONS, INSTITUTIONAL_HOLDINGS, ANALYTICS_FIXED_WINDOW, ANALYTICS_SLIDING_WINDOW
Fundamentals	OVERVIEW, ETF_PROFILE, INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW, SHARES_OUTSTANDING, EARNINGS, EARNINGS_ESTIMATES, DIVIDENDS, SPLITS, LISTING_STATUS, EARNINGS_CALENDAR, IPO_CALENDAR
Forex (FX)	CURRENCY_EXCHANGE_RATE, FX_INTRADAY*, FX_DAILY, FX_WEEKLY, FX_MONTHLY
Crypto	CURRENCY_EXCHANGE_RATE, CRYPTO_INTRADAY*, DIGITAL_CURRENCY_DAILY/WEEKLY/MONTHLY
Commodities	WTI, BRENT, NATURAL_GAS, COPPER, ALUMINUM, WHEAT, CORN, COTTON, SUGAR, COFFEE, GOLD_SILVER_SPOT, GOLD_SILVER_HISTORY, ALL_COMMODITIES
Economic Indicators	REAL_GDP, REAL_GDP_PER_CAPITA, TREASURY_YIELD, FEDERAL_FUNDS_RATE, CPI, INFLATION, RETAIL_SALES, DURABLES, UNEMPLOYMENT, NONFARM_PAYROLL
Technical Indicators	SMA, EMA, MACD*, RSI, BBANDS, STOCH, ADX, ATR, OBV, VWAP*, and 40+ more

* Premium-only (per the live documentation, checked 2026-09-23). Premium-gated parameters on free functions: outputsize=full on TIME_SERIES_DAILY, and entitlement=realtime|delayed on quotes.

Common Parameters

Parameter	Values	Notes
outputsize	compact / full	compact = last 100 points; full = 20+ years (premium for TIME_SERIES_DAILY)
datatype	json / csv	Default: json
interval	1min, 5min, 15min, 30min, 60min, daily, weekly, monthly	Depends on endpoint
adjusted	true / false	Adjust for splits/dividends
entitlement	realtime / delayed	Premium; omit for historical/end-of-day data

Rate Limits and Tiers

• Free key: 25 requests/day. Plan the calls before looping over symbols — a 30-ticker panel exhausts the daily quota. Cache responses to disk and reuse them.
• Premium plans are sold by requests per minute (75 to 1,200/min) and unlock the starred functions above.
• Limit hits and errors arrive as HTTP 200 with an Information (older responses: Note) or Error Message key instead of data, so check the JSON body rather than the status code; the av_get helper above raises on them.

Error Handling

try:
    data = av_get("GLOBAL_QUOTE", symbol="AAPL")
except RuntimeError as err:
    # "Information" usually means the daily quota is used up or the call needs a premium key;
    # "Error Message" usually means a bad function/parameter/symbol.
    print(err)

Reference Files

Load these for detailed endpoint documentation:

• time-series.md — Stock OHLCV data, quotes, bulk quotes, market status
• fundamentals.md — Company overview, financial statements, earnings, dividends, splits
• options.md — Realtime and historical options chain data
• intelligence.md — News/sentiment, earnings transcripts, insider transactions, analytics
• forex-crypto.md — Forex exchange rates and cryptocurrency prices
• commodities.md — Gold, silver, oil, natural gas, agricultural commodities
• economic-indicators.md — GDP, CPI, interest rates, employment data
• technical-indicators.md — 50+ technical analysis indicators (SMA, EMA, MACD, RSI, etc.)

Cite Alpha Vantage and the retrieval date for any figure used in a paper or report.

Part of the AlterLab Academic Skills suite.