Agent-Skills.md

Agent Skills: Alpha Vantage API Integration

Alpha Vantage financial API for stocks, forex, crypto, and 50+ technical indicators. Use when fetching time series data, technical analysis, fundamentals, economic indicators, or news sentiment.

UncategorizedID: adaptationio/skrillz/alphavantage-api

Repository

adaptationio/skrillz
adaptationio
61

Install this agent skill to your local

pnpm dlx add-skill https://github.com/adaptationio/Skrillz/tree/HEAD/.claude/skills/alphavantage-api

Skill Files

Browse the full folder contents for alphavantage-api.

Download Skill

Loading file tree…

.claude/skills/alphavantage-api/SKILL.md

Skill Metadata

Name
alphavantage-api
Description
Alpha Vantage financial API for stocks, forex, crypto, and 50+ technical indicators. Use when fetching time series data, technical analysis, fundamentals, economic indicators, or news sentiment.

Alpha Vantage API Integration

Financial data API providing stocks, forex, crypto, technical indicators, fundamental data, economic indicators, and AI-powered news sentiment analysis.

Quick Start

Authentication

# Environment variable (recommended)
export ALPHAVANTAGE_API_KEY="your_api_key"

# Or in .env file
ALPHAVANTAGE_API_KEY=your_api_key

Basic Usage (Python)

import requests
import os

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

def get_quote(symbol: str) -> dict:
    """Get real-time quote for a symbol."""
    response = requests.get(BASE_URL, params={
        "function": "GLOBAL_QUOTE",
        "symbol": symbol,
        "apikey": API_KEY
    })
    return response.json().get("Global Quote", {})

# Example
quote = get_quote("AAPL")
print(f"AAPL: ${quote['05. price']} ({quote['10. change percent']})")

Using Python Package

from alpha_vantage.timeseries import TimeSeries
from alpha_vantage.techindicators import TechIndicators

# Time series data
ts = TimeSeries(key=API_KEY, output_format='pandas')
data, meta = ts.get_daily(symbol='AAPL', outputsize='compact')

# Technical indicators
ti = TechIndicators(key=API_KEY, output_format='pandas')
rsi, meta = ti.get_rsi(symbol='AAPL', interval='daily', time_period=14)

API Functions Reference

Stock Time Series

| Function | Description | Free | |----------|-------------|------| | TIME_SERIES_INTRADAY | 1-60min intervals | ✅ | | TIME_SERIES_DAILY | Daily OHLCV | ✅ | | TIME_SERIES_DAILY_ADJUSTED | With splits/dividends | ⚠️ Premium | | TIME_SERIES_WEEKLY | Weekly OHLCV | ✅ | | TIME_SERIES_MONTHLY | Monthly OHLCV | ✅ | | GLOBAL_QUOTE | Latest quote | ✅ | | SYMBOL_SEARCH | Search symbols | ✅ |

Fundamental Data

| Function | Description | Free | |----------|-------------|------| | OVERVIEW | Company overview | ✅ | | INCOME_STATEMENT | Income statements | ✅ | | BALANCE_SHEET | Balance sheets | ✅ | | CASH_FLOW | Cash flow statements | ✅ | | EARNINGS | Earnings history | ✅ | | EARNINGS_CALENDAR | Upcoming earnings | ✅ | | IPO_CALENDAR | Upcoming IPOs | ✅ |

Forex

| Function | Description | Free | |----------|-------------|------| | CURRENCY_EXCHANGE_RATE | Real-time rate | ✅ | | FX_INTRADAY | Intraday forex | ✅ | | FX_DAILY | Daily forex | ✅ | | FX_WEEKLY | Weekly forex | ✅ | | FX_MONTHLY | Monthly forex | ✅ |

Cryptocurrency

| Function | Description | Free | |----------|-------------|------| | CURRENCY_EXCHANGE_RATE | Crypto rate | ✅ | | DIGITAL_CURRENCY_DAILY | Daily crypto | ✅ | | DIGITAL_CURRENCY_WEEKLY | Weekly crypto | ✅ | | DIGITAL_CURRENCY_MONTHLY | Monthly crypto | ✅ |

Technical Indicators (50+)

| Category | Indicators | |----------|------------| | Trend | SMA, EMA, WMA, DEMA, TEMA, KAMA, MAMA, T3, TRIMA | | Momentum | RSI, MACD, STOCH, WILLR, ADX, CCI, MFI, ROC, AROON, MOM | | Volatility | BBANDS, ATR, NATR, TRANGE | | Volume | OBV, AD, ADOSC | | Hilbert | HT_TRENDLINE, HT_SINE, HT_PHASOR, etc. |

Economic Indicators

| Function | Description | Free | |----------|-------------|------| | REAL_GDP | US GDP | ✅ | | CPI | Consumer Price Index | ✅ | | INFLATION | Inflation rate | ✅ | | UNEMPLOYMENT | Unemployment rate | ✅ | | FEDERAL_FUNDS_RATE | Fed funds rate | ✅ | | TREASURY_YIELD | Treasury yields | ✅ |

Alpha Intelligence

| Function | Description | Free | |----------|-------------|------| | NEWS_SENTIMENT | AI sentiment analysis | ✅ | | TOP_GAINERS_LOSERS | Market movers | ✅ | | INSIDER_TRANSACTIONS | Insider trades | ⚠️ Premium | | ANALYTICS_FIXED_WINDOW | Analytics | ⚠️ Premium |

Rate Limits

| Tier | Daily | Per Minute | Price | |------|-------|------------|-------| | Free | 25 | 5 | $0 | | Premium | Unlimited | 75-1,200 | $49.99-$249.99/mo |

Important: Rate limits are IP-based, not key-based.

Common Tasks

Task: Get Daily Stock Data

def get_daily_data(symbol: str, full: bool = False) -> dict:
    """Get daily OHLCV data."""
    response = requests.get(BASE_URL, params={
        "function": "TIME_SERIES_DAILY",
        "symbol": symbol,
        "outputsize": "full" if full else "compact",
        "apikey": API_KEY
    })
    return response.json().get("Time Series (Daily)", {})

# Example
data = get_daily_data("AAPL")
latest = list(data.items())[0]
print(f"{latest[0]}: Close ${latest[1]['4. close']}")

Task: Get Technical Indicator

def get_rsi(symbol: str, period: int = 14) -> dict:
    """Get RSI indicator values."""
    response = requests.get(BASE_URL, params={
        "function": "RSI",
        "symbol": symbol,
        "interval": "daily",
        "time_period": period,
        "series_type": "close",
        "apikey": API_KEY
    })
    return response.json().get("Technical Analysis: RSI", {})

# Example
rsi = get_rsi("AAPL")
latest_rsi = list(rsi.values())[0]["RSI"]
print(f"AAPL RSI(14): {latest_rsi}")

Task: Get Company Overview

def get_company_overview(symbol: str) -> dict:
    """Get comprehensive company information."""
    response = requests.get(BASE_URL, params={
        "function": "OVERVIEW",
        "symbol": symbol,
        "apikey": API_KEY
    })
    data = response.json()

    return {
        "name": data.get("Name"),
        "description": data.get("Description"),
        "sector": data.get("Sector"),
        "industry": data.get("Industry"),
        "market_cap": data.get("MarketCapitalization"),
        "pe_ratio": data.get("PERatio"),
        "dividend_yield": data.get("DividendYield"),
        "eps": data.get("EPS"),
        "52_week_high": data.get("52WeekHigh"),
        "52_week_low": data.get("52WeekLow"),
        "beta": data.get("Beta")
    }

Task: Get Forex Rate

def get_forex_rate(from_currency: str, to_currency: str) -> dict:
    """Get currency exchange rate."""
    response = requests.get(BASE_URL, params={
        "function": "CURRENCY_EXCHANGE_RATE",
        "from_currency": from_currency,
        "to_currency": to_currency,
        "apikey": API_KEY
    })
    return response.json().get("Realtime Currency Exchange Rate", {})

# Example
rate = get_forex_rate("USD", "EUR")
print(f"USD/EUR: {rate['5. Exchange Rate']}")

Task: Get Crypto Price

def get_crypto_price(symbol: str, market: str = "USD") -> dict:
    """Get cryptocurrency price."""
    response = requests.get(BASE_URL, params={
        "function": "CURRENCY_EXCHANGE_RATE",
        "from_currency": symbol,
        "to_currency": market,
        "apikey": API_KEY
    })
    data = response.json().get("Realtime Currency Exchange Rate", {})
    return {
        "symbol": symbol,
        "price": data.get("5. Exchange Rate"),
        "last_updated": data.get("6. Last Refreshed")
    }

# Example
btc = get_crypto_price("BTC")
print(f"BTC: ${float(btc['price']):,.2f}")

Task: Get News Sentiment

def get_news_sentiment(tickers: str = None, topics: str = None) -> list:
    """Get AI-powered news sentiment analysis."""
    params = {
        "function": "NEWS_SENTIMENT",
        "apikey": API_KEY
    }
    if tickers:
        params["tickers"] = tickers
    if topics:
        params["topics"] = topics

    response = requests.get(BASE_URL, params=params)
    return response.json().get("feed", [])

# Example
news = get_news_sentiment(tickers="AAPL")
for article in news[:3]:
    sentiment = article.get("overall_sentiment_label", "N/A")
    print(f"{article['title'][:50]}... [{sentiment}]")

Task: Get Economic Indicators

def get_economic_indicator(indicator: str) -> dict:
    """Get US economic indicator data."""
    response = requests.get(BASE_URL, params={
        "function": indicator,
        "apikey": API_KEY
    })
    return response.json()

# Examples
gdp = get_economic_indicator("REAL_GDP")
cpi = get_economic_indicator("CPI")
unemployment = get_economic_indicator("UNEMPLOYMENT")
fed_rate = get_economic_indicator("FEDERAL_FUNDS_RATE")

Task: Get Earnings Calendar

def get_earnings_calendar(horizon: str = "3month") -> list:
    """Get upcoming earnings releases."""
    import csv
    from io import StringIO

    response = requests.get(BASE_URL, params={
        "function": "EARNINGS_CALENDAR",
        "horizon": horizon,  # 3month, 6month, 12month
        "apikey": API_KEY
    })

    # Returns CSV format
    reader = csv.DictReader(StringIO(response.text))
    return list(reader)

# Example
earnings = get_earnings_calendar()
for e in earnings[:5]:
    print(f"{e['symbol']}: {e['reportDate']}")

Error Handling

def safe_api_call(params: dict) -> dict:
    """Make API call with error handling."""
    params["apikey"] = API_KEY

    try:
        response = requests.get(BASE_URL, params=params)
        data = response.json()

        # Check for rate limit
        if "Note" in data:
            print(f"Rate limit: {data['Note']}")
            return {}

        # Check for error message
        if "Error Message" in data:
            print(f"API Error: {data['Error Message']}")
            return {}

        # Check for information message (often rate limit)
        if "Information" in data:
            print(f"Info: {data['Information']}")
            return {}

        return data

    except Exception as e:
        print(f"Request error: {e}")
        return {}

Free vs Premium Features

Free Tier Includes

  • 25 requests per day
  • 5 requests per minute
  • Historical time series (20+ years)
  • 50+ technical indicators
  • Fundamental data
  • Forex and crypto
  • Economic indicators
  • News sentiment

Premium Required

  • Unlimited daily requests
  • Adjusted time series
  • Realtime US market data
  • 15-minute delayed data
  • Insider transactions
  • Advanced analytics
  • Priority support

Best Practices

  1. Cache responses - Data doesn't change frequently
  2. Use compact outputsize - Unless you need full history
  3. Batch requests wisely - 25/day limit is strict
  4. Handle rate limits - Check for "Note" key in response
  5. Use pandas output - With alpha_vantage package
  6. Store historical data - Avoid re-fetching same data

Installation

# Official Python wrapper
pip install alpha_vantage pandas

# For async support
pip install aiohttp

Usage with Pandas

from alpha_vantage.timeseries import TimeSeries
from alpha_vantage.techindicators import TechIndicators
import pandas as pd

# Initialize with pandas output
ts = TimeSeries(key=API_KEY, output_format='pandas')
ti = TechIndicators(key=API_KEY, output_format='pandas')

# Get daily data
data, meta = ts.get_daily(symbol='AAPL', outputsize='compact')

# Get indicators
sma, _ = ti.get_sma(symbol='AAPL', interval='daily', time_period=20)
rsi, _ = ti.get_rsi(symbol='AAPL', interval='daily', time_period=14)

# Combine
analysis = data.join([sma, rsi])

Related Skills

  • finnhub-api - Real-time quotes and news
  • twelvedata-api - More indicators, better rate limits
  • fmp-api - Fundamental analysis focus

References