FinnHub API Integration

Complete integration with FinnHub's financial data API providing access to stocks, forex, crypto, company fundamentals, news, and real-time market data.

Quick Start

Authentication

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

# Or in .env file
FINNHUB_API_KEY=your_api_key

Basic Usage (Python)

import requests
import os

API_KEY = os.getenv("FINNHUB_API_KEY")
BASE_URL = "https://finnhub.io/api/v1"

def get_quote(symbol: str) -> dict:
    """Get real-time quote for a symbol."""
    response = requests.get(
        f"{BASE_URL}/quote",
        params={"symbol": symbol, "token": API_KEY}
    )
    return response.json()

# Example
quote = get_quote("AAPL")
print(f"AAPL: ${quote['c']:.2f} ({quote['dp']:+.2f}%)")

Using Official SDK

import finnhub

client = finnhub.Client(api_key="your_api_key")

# Get quote
quote = client.quote("AAPL")

# Get company profile
profile = client.company_profile2(symbol="AAPL")

# Get financials
financials = client.company_basic_financials("AAPL", "all")

API Endpoints Reference

Stock Market Data

Fundamental Data

Forex & Crypto

News & Sentiment

Calendar Events

Rate Limits

Rate limit headers:

• X-Ratelimit-Limit: Max calls per minute
• X-Ratelimit-Remaining: Calls remaining
• X-Ratelimit-Reset: Reset timestamp

Common Tasks

Task: Get Stock Quote with Change

def get_stock_info(symbol: str) -> dict:
    """Get comprehensive stock info."""
    quote = requests.get(
        f"{BASE_URL}/quote",
        params={"symbol": symbol, "token": API_KEY}
    ).json()

    profile = requests.get(
        f"{BASE_URL}/stock/profile2",
        params={"symbol": symbol, "token": API_KEY}
    ).json()

    return {
        "symbol": symbol,
        "name": profile.get("name"),
        "price": quote["c"],
        "change": quote["d"],
        "change_percent": quote["dp"],
        "high": quote["h"],
        "low": quote["l"],
        "market_cap": profile.get("marketCapitalization"),
        "industry": profile.get("finnhubIndustry")
    }

Task: Get Historical Candles

import time

def get_candles(symbol: str, resolution: str = "D", days: int = 30) -> dict:
    """
    Get historical OHLCV data.

    Resolutions: 1, 5, 15, 30, 60, D, W, M
    """
    end = int(time.time())
    start = end - (days * 24 * 60 * 60)

    response = requests.get(
        f"{BASE_URL}/stock/candle",
        params={
            "symbol": symbol,
            "resolution": resolution,
            "from": start,
            "to": end,
            "token": API_KEY
        }
    )
    return response.json()

Task: Get Earnings Calendar

def get_earnings_calendar(from_date: str, to_date: str) -> list:
    """Get upcoming earnings releases."""
    response = requests.get(
        f"{BASE_URL}/calendar/earnings",
        params={
            "from": from_date,
            "to": to_date,
            "token": API_KEY
        }
    )
    return response.json().get("earningsCalendar", [])

# Example: Get next week's earnings
earnings = get_earnings_calendar("2025-12-05", "2025-12-12")

Task: Get Company News

def get_company_news(symbol: str, days: int = 7) -> list:
    """Get