About finnhub
finnhub is a skill with Python and CLI scripts for querying Finnhub financial data. It documents free and premium endpoint access, API-key handling, rate limits, and available market-data categories.
Key features
- 01Live quotes and company profiles
- 02News, earnings, peers, and metrics
- 03Python client and CLI scripts
- 04Free versus premium endpoint guidance
Use cases
- 01Check a stock quote and company profile
- 02Find company or market news
- 03Review earnings and analyst recommendations
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/finnhubin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
references/ENDPOINTS.mdscripts/download_multiple.pyfinnhub_cli.pyfinnhub_client.pyDetails
From the project READMEFinnhub API — Datos Financieros en Tiempo Real
API REST con 32 endpoints gratuitos que cubre: cotizaciones en vivo, velas OHLCV, perfiles de empresa, fundamentales, noticias, forex, crypto, datos económicos, calendario de earnings y WebSocket.
Base URL: https://finnhub.io/api/v1
Documentación oficial: finnhub.io/docs/api
Pricing: finnhub.io/pricing
⚠️ IMPORTANTE: Endpoints Free vs Premium
Este skill documenta todos los endpoints, pero marca claramente cuáles son:
- ✅ FREE — Funcionan con el plan gratuito (60 calls/min, sin tarjeta)
- 🔒 PREMIUM — Requieren plan pago (Starter $11.99/mes+, Professional $49.99/mes o Enterprise)
NOTA CRÍTICA: El plan gratuito de Finnhub es mucho más limitado de lo que su documentación sugiere. Según pruebas con una API key gratuita real (2026), solo los siguientes endpoints funcionan:
/quote(cotización),/stock/profile2(perfil empresa),/stock/peers(pares),/stock/earnings(earnings)/stock/recommendation(recomendaciones),/stock/metric(métricas),/news(noticias mercado)/company-news(noticias empresa),/search(búsqueda),/stock/market-status(estado mercado)Endpoints como
stock/candle(velas OHLCV),stock/financials,stock/price-target,stock/dividend,forex/rates,crypto/candlerequieren plan pago.Ver la tabla completa en references/ENDPOINTS.md.
Autenticación
Obtener API Key (GRATIS, sin tarjeta de crédito)
- Ir a: https://finnhub.io/register
- Crear cuenta (email + contraseña)
- Copiar la API Key del dashboard: https://finnhub.io/dashboard
- Plan gratuito: 60 calls/minuto, 30 calls/segundo máximo
Usar la API Key
import os
API_KEY = os.getenv("FINNHUB_API_KEY") # Recomendado (variable de entorno)
# O directamente en tests:
# API_KEY = "tu_api_key_aqui"
# Header (recomendado)
X-Finnhub-Token: tu_api_key
# O query param
?token=tu_api_key
⚠️ NUNCA hardcodear la API key en código compartido.
Rate Limits
| Límite | Plan Free | Starter ($11.99/mes) | Professional ($49.99/mes) | Enterprise ($3500/mes) |
|---|---|---|---|---|
| Calls/minuto | 60 | 300+ | 300+ | 900 (market), 300 (fund) |
| Calls/segundo | 30 (global) | 30 (global) | 30 (global) | 30 (global) |
| WebSocket símbolos | 50 | Ilimitado | Ilimitado | Ilimitado |
| Historia OHLCV | Limitada | 30+ años | 30+ años | 30+ años |
| Noticias | 1 año | 20 años | 20 años | 20 años |
| Cobertura fundamental | US | Global | Global | Global |
Tip: si recibís HTTP 429, esperá 1-2 segundos antes de reintentar.
Uso Rápido
1. Cotización en tiempo real
import requests
API_KEY = "tu_api_key"
BASE = "https://finnhub.io/api/v1"
r = requests.get(f"{BASE}/quote", params={"symbol": "AAPL", "token": API_KEY})
quote = r.json()
print(f"AAPL: ${quote['c']:.2f} ({quote['dp']:+.2f}%)")
2. Perfil de empresa
r = requests.get(f"{BASE}/stock/profile2", params={"symbol": "AAPL", "token": API_KEY})
profile = r.json()
print(f"{profile['name']} | {profile['finnhubIndustry']} | Market Cap: ${profile['marketCapitalization']/1000:.2f}B")
3. Noticias de una empresa
r = requests.get(f"{BASE}/company-news", params={
"symbol": "AAPL", "from": "2025-01-01", "to": "2025-01-15", "token": API_KEY
})
for article in r.json()[:3]:
print(f" {article['headline'][:80]}...")
4. Velas OHLCV diarias
import time
end = int(time.time())
start = end - (90 * 86400) # 90 días
r = requests.get(f"{BASE}/stock/candle", params={
"symbol": "AAPL", "resolution": "D",
"from": start, "to": end, "token": API_KEY
})
candles = r.json()
print(f"Status: {candles['s']}, velas: {len(candles['c'])}")
5. Búsqueda de símbolos
r = requests.get(f"{BASE}/search", params={"q": "microsoft", "token": API_KEY})
for result in r.json()["result"]:
print(f"{result['symbol']}: {result['description']} ({result['type']})")
Scripts Disponibles
| Script | Descripción | Endpoints que usa |
|---|---|---|
| finnhub_client.py | Cliente Python completo con todos los endpoints gratuitos | quote, candle, profile2, peers, metric, financials, earnings, recommendation, price-target, company-news, news, forex, crypto, search, economic, market-status, dividends, splits, calendar |
| finnhub_cli.py | Interfaz de línea de comandos para consultas rápidas | quote, profile2, search, news, peers, earnings, market-status |
| download_multiple.py | Descarga batches de datos por categorías | quote, candle, metric, financials, earnings, recommendation, company-news |
Cobertura de la API (según pruebas con key gratuita real)
| Categoría | Endpoints | Free | Premium |
|---|---|---|---|
| Cotizaciones | quote | ✅ | — |
| Perfil empresa | profile2, peers | ✅ | — |
| Earnings | earnings (4 quarters free) | ✅ | — |
| Recomendaciones | recommendation (~8 meses) | ✅ | — |
| Métricas (133) | metric (sin historia, solo último valor) | ✅ | — |
| Noticias | company-news, news | ✅ | — |
| Búsqueda | search | ✅ | — |
| Estado mercado | market-status | ✅ | — |
| Velas OHLCV | candle | — | 🔒 Premium |
| Estados financieros | financials, financials-reported, price-target | — | 🔒 Premium |
| Dividendos/Splits | dividend, split | — | 🔒 Premium |
| Forex | rates, candle, exchange, symbol | — | 🔒 Premium |
| Crypto | candle, exchange, symbol | — | 🔒 Premium |
| Económico | economic/code, economic, country | — | 🔒 Premium |
| Símbolos | stock/symbol, market-holiday, ipo-calendar | — | 🔒 Premium |
| WebSocket | Trades (50 símbolos) | — | 🔒 Premium |
| Insider, Ownership | insider-transactions, ownership, etc. | — | 🔒 Premium |
| Estimates | eps-estimate, revenue-estimate, etc. | — | 🔒 Premium |
| ETFs, Índices, Bonos | etf/profile, etf/holdings, index/constituents, bond/price, etc. | — | 🔒 Premium |
| Alternativos | social-sentiment, covid-19, esg-score, etc. | — | 🔒 Premium |
⚠️ Esta tabla está basada en pruebas reales con una API key gratuita en junio 2026. Finnhub cambia su política de acceso periódicamente. Verificar siempre en la documentación oficial.
Buenas Prácticas
- Usar variable de entorno
FINNHUB_API_KEYen vez de hardcodear - Cachear resultados: los datos fundamentales cambian poco (especialmente company profile, financials)
- Rate limiting: 60 calls/min gratis = 1 call por segundo como mínimo
- Evitar endpoints premium con key gratuita — recibirás error
"You don't have access to this resource." - WebSocket: solo 1 conexión por API key, 50 símbolos en free
- Reutilizar sesión HTTP para mejor performance (
requests.Session()) - No usar para trading de alta frecuencia: API pública, sin garantía de latencia ultra-baja