Finnhub API

Access real-time and historical stock market data, company news, financial statements, and market indicators via the Finnhub API.

Quick Start

Get your API key from finnhub.io (free tier available).

Configure in OpenClaw:

{
  skills: {
    entries: {
      finnhub: {
        enabled: true,
        apiKey: "your-finnhub-api-key",
        env: {
          FINNHUB_API_KEY: "your-finnhub-api-key",
        },
      },
    },
  },
}

Or add to ~/.openclaw/.env:

FINNHUB_API_KEY=your-api-key-here

API Endpoints

Base URL: https://finnhub.io/api/v1

All requests require ?token=${FINNHUB_API_KEY} parameter.

Stock Quotes (Real-time)

Get current stock price:

curl "https://finnhub.io/api/v1/quote?symbol=AAPL&token=${FINNHUB_API_KEY}"

Returns: c (current price), h (high), l (low), o (open), pc (previous close), t (timestamp)

Company News

Get latest company news:

# News for a symbol
curl "https://finnhub.io/api/v1/company-news?symbol=AAPL&from=2025-01-01&to=2025-02-01&token=${FINNHUB_API_KEY}"

# General market news
curl "https://finnhub.io/api/v1/news?category=general&token=${FINNHUB_API_KEY}"

Company Profile

Get company information:

curl "https://finnhub.io/api/v1/stock/profile2?symbol=AAPL&token=${FINNHUB_API_KEY}"

Financial Statements

Get company financials:

# Income statement
curl "https://finnhub.io/api/v1/stock/financials-reported?symbol=AAPL&token=${FINNHUB_API_KEY}"

# Balance sheet
curl "https://finnhub.io/api/v1/stock/financials-reported?symbol=AAPL&statement=bs&token=${FINNHUB_API_KEY}"

# Cash flow
curl "https://finnhub.io/api/v1/stock/financials-reported?symbol=AAPL&statement=cf&token=${FINNHUB_API_KEY}"

# Search in SEC filings (10-K, 10-Q, etc.)
# Note: This endpoint may require premium tier or have a different path
curl "https://finnhub.io/api/v1/stock/search-in-filing?symbol=AAPL&query=revenue&token=${FINNHUB_API_KEY}"

Market Data

Get market indicators:

# Stock candles (OHLCV)
curl "https://finnhub.io/api/v1/stock/candle?symbol=AAPL&resolution=D&from=1609459200&to=1640995200&token=${FINNHUB_API_KEY}"

# Stock symbols (search)
curl "https://finnhub.io/api/v1/search?q=apple&token=${FINNHUB_API_KEY}"

# Market status
curl "https://finnhub.io/api/v1/stock/market-status?exchange=US&token=${FINNHUB_API_KEY}"

Trading Signals

Get technical indicators and signals:

# Technical indicators (may require premium tier)
curl "https://finnhub.io/api/v1/indicator?symbol=AAPL&indicator=rsi&resolution=D&token=${FINNHUB_API_KEY}"

# Support/Resistance (may require premium tier)
curl "https://finnhub.io/api/v1/scan/support-resistance?symbol=AAPL&resolution=D&token=${FINNHUB_API_KEY}"

# Pattern recognition (may require premium tier)
curl "https://finnhub.io/api/v1/scan/pattern?symbol=AAPL&resolution=D&token=${FINNHUB_API_KEY}"

Note: Some technical indicator endpoints may require a premium subscription. Free tier includes basic market data and quotes.

Earnings & Calendar

Get earnings data:

# Earnings calendar
curl "https://finnhub.io/api/v1/calendar/earnings?from=2025-02-01&to=2025-02-28&token=${FINNHUB_API_KEY}"

# Company earnings
curl "https://finnhub.io/api/v1/stock/earnings?symbol=AAPL&token=${FINNHUB_API_KEY}"

Common Use Cases

Find Trading Opportunities

1. Search for stocks: GET /search?q=keyword
2. Get current quote: GET /quote?symbol=SYMBOL
3. Check recent news: GET /company-news?symbol=SYMBOL&from=DATE&to=DATE
4. Analyze technical indicators: GET /indicator?symbol=SYMBOL&indicator=rsi
5. Review financials: GET /stock/financials-reported?symbol=SYMBOL
6. Search SEC filings: GET /stock/search-in-filing?symbol=SYMBOL&query=KEYWORD

Monitor Stock Performance

1. Get real-time quote: GET /quote?symbol=SYMBOL
2. Get historical candles: GET /stock/candle?symbol=SYMBOL&resolution=D
3. Check company profile: GET /stock/profile2?symbol=SYMBOL
4. Review earnings: GET /stock/earnings?symbol=SYMBOL

Research Company News

1. Company-specific news: GET /company-news?symbol=SYMBOL
2. General market news: GET /news?category=general
3. Sector news: GET /news?category=technology

Search SEC Filings

Search within company SEC filings (10-K, 10-Q, 8-K, etc.):

# Search for specific terms in filings
# Note: This endpoint may require premium tier or have a different path
curl "https://finnhub.io/api/v1/stock/search-in-filing?symbol=AAPL&query=revenue&token=${FINNHUB_API_KEY}"

# Search for risk factors
curl "https://finnhub.io/api/v1/stock/search-in-filing?symbol=AAPL&query=risk&token=${FINNHUB_API_KEY}"

# Search for specific financial metrics
curl "https://finnhub.io/api/v1/stock/search-in-filing?symbol=AAPL&query=EBITDA&token=${FINNHUB_API_KEY}"

This endpoint searches through SEC filings (10-K, 10-Q, 8-K, etc.) for specific keywords or phrases, useful for finding mentions of specific topics, risks, or financial metrics in official company documents.

Rate Limits

Free tier:

• 60 API calls/minute
• Real-time data: limited
• Historical data: available

Paid tiers offer higher limits and additional features.

Notes

• Always include token=${FINNHUB_API_KEY} in query parameters
• Use proper date formats: YYYY-MM-DD for date ranges
• Timestamps are Unix epoch seconds
• Symbol format: use exchange prefix if needed (e.g., US:AAPL for US stocks)
• For paper trading, combine Finnhub data with Alpaca API for execution