/finnhub

name: finnhub
description: "API de datos financieros completa: stocks US/global, forex, crypto, fundamentales, noticias, earnings, recomendaciones, WebSocket. 60 calls/min gratis."
license: MIT
metadata:
  category: finanzas, api, stocks, forex, crypto, noticias, eeUU, global
  language: es
  source: https://finnhub.io/docs/api

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](https://finnhub.io/docs/api) **Pricing:** [finnhub.io/pricing](https://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](https://finnhub.io/register) 2. Crear cuenta (email + contraseña) 3. Copiar la API Key del dashboard: [https://finnhub.io/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

| 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](./scripts/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](./scripts/finnhub_cli.py)** | Interfaz de línea de comandos para consultas rápidas | quote, profile2, search, news, peers, earnings, market-status | | **[download_multiple.py](./scripts/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