Finnhub API — Datos Financieros en Tiempo Real

https://finnhub.io/api/v1

⚠️ IMPORTANTE: Endpoints Free vs Premium

• ✅ 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.

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

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

   FINNHUB_API_KEY

   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
• Dashboard (API key)
• Estado del servicio