canonical: https://jentic.com/apis/finnhub.io/finnhub

# Finnhub API

Jentic publishes the only available OpenAPI specification for Finnhub API, keeping it validated and agent-ready. Finnhub is a real-time financial data API providing institutional-grade market data, fundamentals, alternative data, and news for global stocks, forex, crypto, bonds, ETFs, and economic indicators. Coverage spans 60+ exchanges with company financials, earnings calendars, insider transactions, analyst estimates, sentiment scores, and an AI Copilot endpoint for natural-language financial queries. The 108 endpoints make it suitable for trading research, portfolio analytics, and agent-driven market intelligence pipelines.

## For AI agents

Query real-time stock quotes, company fundamentals, news, earnings, crypto and forex data, and economic indicators across global markets. Includes an AI Copilot endpoint for natural-language financial questions.

## Scope

Does not handle order execution, brokerage account management, or portfolio custody - use for market data, fundamentals, and financial news retrieval only.

## Capabilities

- Pull real-time stock quotes, candles, and tick data for global equities across 60+ exchanges
- Retrieve company fundamentals including financials-as-reported, peers, ownership, and ESG scores
- Fetch earnings calendars, IPO calendars, and economic event calendars with consensus estimates
- Track insider transactions, lobbying activity, and senate trading disclosures for a ticker
- Query crypto candles and forex rates across multiple exchanges and currency pairs
- Score news sentiment and surface company news, press releases, and earnings call transcripts
- Send natural-language financial questions to the AI Copilot endpoint for analyst-style answers

## Use cases

### Real-Time Trading Research

Power systematic and discretionary trading workflows with real-time quotes, candles, and order book data for stocks, ETFs, forex, and crypto. Finnhub serves institutional-grade tick data through endpoints like /quote, /stock/candle, and /forex/candle, enabling backtests and live signal generation against 60+ exchanges. Integration takes a few hours with the apiKey query parameter.

Example prompt: Fetch the last 30 days of daily candles for AAPL, NVDA, and MSFT from /stock/candle and compute the 20-day rolling correlation matrix

### Earnings and Calendar Tracking

Build earnings dashboards and event-driven trading alerts using the /calendar/earnings, /calendar/ipo, and /calendar/economic endpoints. Each calendar entry includes consensus estimates, prior values, and surprise calculations, so agents can flag earnings beats and macro releases without scraping investor relations pages. Setup takes under an hour.

Example prompt: Pull the next 7 days of earnings releases from /calendar/earnings filtered to S&P 500 tickers and post a summary to Slack

### Alternative Data and Sentiment

Enrich research notes with insider transactions, lobbying spend, senate trading disclosures, social sentiment, and news sentiment scores. Finnhub aggregates these alternative signals into per-ticker endpoints like /stock/insider-transactions and /news-sentiment, which agents can poll alongside price data to detect divergences. A typical sentiment integration is live the same day.

Example prompt: Compare /stock/insider-transactions for TSLA over the last 90 days against /news-sentiment scores and flag weeks where insider sales coincided with negative sentiment

### AI Agent Market Intelligence

Use Finnhub through Jentic so agents answer multi-step market questions without juggling endpoints. The /ai-chat Copilot accepts natural-language queries, while structured endpoints back deeper analysis. Jentic exposes both as discoverable tools so an agent can answer 'What is the consensus EPS for AAPL Q4?' or 'Pull NVDA insider sales' through the same search-load-execute flow. Get started with Jentic One, the self-hosted execution layer

Example prompt: Through Jentic, search 'get stock fundamentals', load the /stock/metric schema, and execute a call for ticker AAPL with metric=all

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /quote | Real-time quote for a symbol |
| GET | /stock/candle | OHLCV candle data for stocks |
| GET | /calendar/earnings | Upcoming earnings with consensus estimates |
| GET | /calendar/ipo | Upcoming IPO calendar |
| GET | /company-news | News articles for a company |
| GET | /crypto/candle | OHLCV candles for crypto pairs |
| POST | /ai-chat | AI Copilot natural-language financial queries |

## Key resources

- **Stock** — Quotes, candles, fundamentals, peers, ownership, and analyst estimates for global equities
- **Calendar** — Earnings, IPO, and economic event calendars with consensus and surprise data
- **News** — Company news, press releases, and per-article sentiment scoring
- **Crypto** — Candles, exchanges, symbols, and profiles for crypto pairs
- **Forex** — Candles and exchange-rate data across major and exotic currency pairs
- **Alternative Data** — Insider transactions, senate trading, lobbying, and ESG scores
- **AI Copilot** — Natural-language financial query endpoint at /ai-chat

## Why Jentic

- **Setup:** Wiring the Finnhub API by hand means threading its token query parameter onto every request, spreading calls across 108 endpoints, and handling retries and rate limits yourself. Through Jentic you install once, import Finnhub from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Finnhub passes its target as query parameters rather than as an owned resource in the URL path, so scope your agent to the operations it needs, such as quote lookups, earnings calendars, and company news, and leave everything else out of the allowed set. You decide which of the 108 operations it may call.
- **Credential handling:** Your Finnhub token is stored once, encrypted, by your own Jentic One instance and injected as the token parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a stock quote' or 'pull the earnings calendar', and Jentic returns the matching Finnhub operation with its input schema so the agent calls the right one of 108 endpoints without browsing the reference docs.

## Related APIs

- **Fintel API** — Adds institutional ownership, short interest, and options flow detail beyond Finnhub's coverage
- **Fitbit Web API** — Different data domain - health and activity rather than financial markets
- **Fire Financial Services Business API** — Brings live business banking and payment initiation to complement Finnhub's market data

## FAQ

### Why is there no official OpenAPI spec for Finnhub API?

Finnhub does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Finnhub API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Finnhub API use?

Finnhub uses an API key passed as the `token` query parameter on every request. Through Jentic, the key is held in the encrypted vault and injected at execution time so it never enters the agent context.

### Can I get real-time quotes with the Finnhub API?

Yes. The /quote endpoint returns current price, daily high/low, previous close, and timestamp for any supported symbol. Free-tier delays apply for some exchanges; premium tiers stream real-time US equities.

### What are the rate limits for the Finnhub API?

The free tier allows 60 API calls per minute. Premium tiers raise this substantially and unlock real-time and intraday endpoints. Rate-limit headers are returned on every response so agents can back off automatically.

### How do I pull earnings data through Jentic?

Search Jentic for 'get earnings calendar', load the /calendar/earnings schema, then execute with a `from` and `to` date range. Jentic returns the structured response your agent can act on without any HTTP plumbing.

### Does Finnhub cover crypto and forex?

Yes. The /crypto/candle, /crypto/symbol, and /forex/candle endpoints provide OHLCV data across multiple exchanges and currency pairs, suitable for cross-asset agent strategies.

### Can I limit what my agent is allowed to do with the Finnhub API?

Yes. Because you run Jentic One yourself, you decide which of the Finnhub API's 108 operations your agent may call, so you can allow just the ones it needs, such as /quote lookups, the /calendar/earnings feed, and /company-news, and leave everything else out of the allowed set. Since Finnhub passes its target as query parameters rather than as an owned URL path resource, this operation-level allowlist is how you keep the agent scoped to the data it should touch. Your own rules also govern the stored token, so the agent only reaches Finnhub through the calls you have permitted.