Back to Details

finnhub

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Finnhub API — Datos Financieros en Tiempo Real

Finnhub API — 实时金融数据

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
包含32个免费端点的REST API，覆盖：实时报价、OHLCV蜡烛图、企业资料、基本面数据、新闻、外汇、加密货币、经济数据、财报日历和WebSocket。
Base URL: 
https://finnhub.io/api/v1
官方文档: finnhub.io/docs/api 定价: finnhub.io/pricing

⚠️ IMPORTANTE: Endpoints Free vs Premium

⚠️ 重要提示：免费版 vs 付费版端点

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.
本技能文档涵盖所有端点，但会明确标记哪些是：
  • ✅ FREE — 免费版可用（每分钟60次调用，无需信用卡）
  • 🔒 PREMIUM — 需要付费套餐（入门版$11.99/月起，专业版$49.99/月，企业版）
关键提示： Finnhub的免费版比其文档描述的受限得多。根据2026年使用真实免费API密钥的测试，仅以下端点可用：
  • /quote
    （报价）、
    /stock/profile2
    （企业资料）、
    /stock/peers
    （同行股票）、
    /stock/earnings
    （财报收益）
  • /stock/recommendation
    （投资建议）、
    /stock/metric
    （指标数据）、
    /news
    （市场新闻）
  • /company-news
    （企业新闻）、
    /search
    （搜索）、
    /stock/market-status
    （市场状态）
诸如
stock/candle
（OHLCV蜡烛图）、
stock/financials
、
stock/price-target
、
stock/dividend
、
forex/rates
、
crypto/candle
等端点需要付费套餐。
完整表格请查看references/ENDPOINTS.md。

Autenticación

身份验证

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

获取API密钥（免费，无需信用卡）

  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
  1. 访问：https://finnhub.io/register
  2. 创建账户（邮箱+密码）
  3. 从控制台复制API密钥：https://finnhub.io/dashboard
  4. 免费版限制：每分钟60次调用，最多每秒30次调用

Usar la API Key

使用API密钥

python
import os
API_KEY = os.getenv("FINNHUB_API_KEY")  # Recomendado (variable de entorno)
python
import os
API_KEY = os.getenv("FINNHUB_API_KEY")  # 推荐方式（环境变量）

O directamente en tests:

或在测试中直接使用：

API_KEY = "tu_api_key_aqui"

API_KEY = "你的API密钥"


```bash

```bash

Header (recomendado)

请求头（推荐）

X-Finnhub-Token: tu_api_key
X-Finnhub-Token: 你的API密钥

O query param

或查询参数

?token=tu_api_key

**⚠️ NUNCA hardcodear la API key en código compartido.**

---
?token=你的API密钥

**⚠️ 切勿在共享代码中硬编码API密钥。**

---

Rate Limits

调用限制

LímitePlan FreeStarter ($11.99/mes)Professional ($49.99/mes)Enterprise ($3500/mes)
Calls/minuto60300+300+900 (market), 300 (fund)
Calls/segundo30 (global)30 (global)30 (global)30 (global)
WebSocket símbolos50IlimitadoIlimitadoIlimitado
Historia OHLCVLimitada30+ años30+ años30+ años
Noticias1 año20 años20 años20 años
Cobertura fundamentalUSGlobalGlobalGlobal
Tip: si recibís HTTP 429, esperá 1-2 segundos antes de reintentar.
限制项免费版入门版（$11.99/月）专业版（$49.99/月）企业版（$3500/月）
每分钟调用次数60300+300+900（市场数据），300（基本面数据）
每秒调用次数30（全局）30（全局）30（全局）30（全局）
WebSocket支持的标的数量50无限制无限制无限制
OHLCV历史数据有限30+年30+年30+年
新闻数据1年20年20年20年
基本面数据覆盖范围美股全球全球全球
提示： 如果收到HTTP 429错误，请等待1-2秒后重试。

Uso Rápido

快速上手

1. Cotización en tiempo real

1. 实时报价

python
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}%)")
python
import requests

API_KEY = "你的API密钥"
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

2. 企业资料

python
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")
python
r = requests.get(f"{BASE}/stock/profile2", params={"symbol": "AAPL", "token": API_KEY})
profile = r.json()
print(f"{profile['name']} | {profile['finnhubIndustry']} | 市值: ${profile['marketCapitalization']/1000:.2f}B")

3. Noticias de una empresa

3. 企业新闻

python
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]}...")
python
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

4. 每日OHLCV蜡烛图

python
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'])}")
python
import time
end = int(time.time())
start = end - (90 * 86400)  # 90天
r = requests.get(f"{BASE}/stock/candle", params={
    "symbol": "AAPL", "resolution": "D",
    "from": start, "to": end, "token": API_KEY
})
candles = r.json()
print(f"状态: {candles['s']}, 蜡烛图数量: {len(candles['c'])}")

5. Búsqueda de símbolos

5. 标的搜索

python
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']})")
python
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

可用脚本

ScriptDescripciónEndpoints que usa
finnhub_client.pyCliente Python completo con todos los endpoints gratuitosquote, candle, profile2, peers, metric, financials, earnings, recommendation, price-target, company-news, news, forex, crypto, search, economic, market-status, dividends, splits, calendar
finnhub_cli.pyInterfaz de línea de comandos para consultas rápidasquote, profile2, search, news, peers, earnings, market-status
download_multiple.pyDescarga batches de datos por categoríasquote, candle, metric, financials, earnings, recommendation, company-news
脚本描述使用的端点
finnhub_client.py包含所有免费端点的完整Python客户端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用于快速查询的命令行界面quote, profile2, search, news, peers, earnings, market-status
download_multiple.py按类别批量下载数据quote, candle, metric, financials, earnings, recommendation, company-news

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

API覆盖范围（基于真实免费密钥测试）

CategoríaEndpointsFreePremium
Cotizacionesquote✅—
Perfil empresaprofile2, peers✅—
Earningsearnings (4 quarters free)✅—
Recomendacionesrecommendation (~8 meses)✅—
Métricas (133)metric (sin historia, solo último valor)✅—
Noticiascompany-news, news✅—
Búsquedasearch✅—
Estado mercadomarket-status✅—
Velas OHLCVcandle—🔒 Premium
Estados financierosfinancials, financials-reported, price-target—🔒 Premium
Dividendos/Splitsdividend, split—🔒 Premium
Forexrates, candle, exchange, symbol—🔒 Premium
Cryptocandle, exchange, symbol—🔒 Premium
Económicoeconomic/code, economic, country—🔒 Premium
Símbolosstock/symbol, market-holiday, ipo-calendar—🔒 Premium
WebSocketTrades (50 símbolos)—🔒 Premium
Insider, Ownershipinsider-transactions, ownership, etc.—🔒 Premium
Estimateseps-estimate, revenue-estimate, etc.—🔒 Premium
ETFs, Índices, Bonosetf/profile, etf/holdings, index/constituents, bond/price, etc.—🔒 Premium
Alternativossocial-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.
类别端点免费版付费版
报价数据quote✅—
企业资料profile2, peers✅—
财报收益earnings（免费提供4个季度数据）✅—
投资建议recommendation（约8个月数据）✅—
指标数据（133项）metric（无历史数据，仅最新值）✅—
新闻数据company-news, news✅—
搜索功能search✅—
市场状态market-status✅—
OHLCV蜡烛图candle—🔒 付费版
财务报表financials, financials-reported, price-target—🔒 付费版
股息/拆股dividend, split—🔒 付费版
外汇数据rates, candle, exchange, symbol—🔒 付费版
加密货币数据candle, exchange, symbol—🔒 付费版
经济数据economic/code, economic, country—🔒 付费版
标的信息stock/symbol, market-holiday, ipo-calendar—🔒 付费版
WebSocket交易数据（支持50个标的）—🔒 付费版
内部交易、持股情况insider-transactions, ownership等—🔒 付费版
预期数据eps-estimate, revenue-estimate等—🔒 付费版
ETF、指数、债券etf/profile, etf/holdings, index/constituents, bond/price等—🔒 付费版
另类数据social-sentiment, covid-19, esg-score等—🔒 付费版
⚠️ 本表格基于2026年6月使用真实免费API密钥的测试。Finnhub会定期更改访问政策，请始终参考官方文档。

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
  1. 使用环境变量 
    FINNHUB_API_KEY
    而非硬编码密钥
  2. 缓存结果：基本面数据变化很少（尤其是企业资料、财务报表）
  3. 遵守调用限制：免费版每分钟60次调用 = 至少每秒1次调用
  4. 免费密钥避免使用付费端点 — 会收到错误提示 
    "You don't have access to this resource."
  5. WebSocket：每个API密钥仅支持1个连接，免费版最多50个标的
  6. 复用HTTP会话以提升性能（
    requests.Session()
    ）
  7. 勿用于高频交易：公开API，不保证超低延迟

Recursos

资源