Finnhub 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/candle requieren plan pago.

Ver la tabla completa en [references/ENDPOINTS.md](./references/ENDPOINTS.md).

Autenticación

Obtener API Key (GRATIS, sin tarjeta de crédito)

1. Ir a: https://finnhub.io/register
2. Crear cuenta (email + contraseña)
3. Copiar la API Key del dashboard: https://finnhub.io/dashboard
4. 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

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

Cobertura de la API (según pruebas con key gratuita real)

⚠️ 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

1. Usar variable de entorno FINNHUBAPIKEY en vez de hardcodear
2. Cachear resultados: los datos fundamentales cambian poco (especialmente company profile, financials)
3. Rate limiting: 60 calls/min gratis = 1 call por segundo como mínimo
4. Evitar endpoints premium con key gratuita — recibirás error "You don't have access to this resource."
5. WebSocket: solo 1 conexión por API key, 50 símbolos en free
6. Reutilizar sesión HTTP para mejor performance (requests.Session())
7. No usar para trading de alta frecuencia: API pública, sin garantía de latencia ultra-baja

Recursos

• Documentación oficial Finnhub
• Pricing oficial
• Python SDK oficial
• [Referencia de endpoints free vs premium](./references/ENDPOINTS.md)
• Dashboard (API key)
• Estado del servicio