Finnhub Pro

---
name: finnhub-pro
description: "Finnhub 美股金融数据 CLI。实时报价、公司档案、新闻、分析师推荐、内部人交易、盈利日历、基本面财务、同行比较。Python 脚本封装，免费层 60 次/分钟。Use when: 查股价、查公司信息、看最新新闻、了解内部人是否在买卖、查看近期财报日期。NOT for: K线数据、目标价、情绪分析（需付费层）。"
version: 1.0.0
---

# Finnhub Pro — 美股金融数据 CLI

Python CLI 封装 Finnhub API，聚焦免费层实际可用的 10 个功能。

## 安装

```bash
pip install finnhub-python
```

## API Key

1. 去 [finnhub.io](https://finnhub.io) 注册获取免费 API Key
2. 设置环境变量：`export FINNHUB_API_KEY="your-key-here"`
3. 或写入 `~/.openclaw/.env`

**⚠️ 脚本不硬编码 Key，必须通过环境变量 `FINNHUB_API_KEY` 传入！**

## 使用方法

```bash
# 基础格式
FINNHUB_API_KEY="your-key" python3 scripts/finnhub_cli.py <command> [args] [--json] [--limit N]

# 推荐：设好环境变量后直接用
python3 scripts/finnhub_cli.py quote AAPL
```

## 免费层支持的命令（10 个）

### 实时报价
```bash
python3 scripts/finnhub_cli.py quote AAPL
python3 scripts/finnhub_cli.py quote NVDA --json   # 原始 JSON
```

### 公司档案
```bash
python3 scripts/finnhub_cli.py profile AAPL
```

### 公司新闻（最近 7 天）
```bash
python3 scripts/finnhub_cli.py news NVDA
python3 scripts/finnhub_cli.py news AAPL --from 2026-02-01 --to 2026-02-21 --limit 5
```

### 分析师推荐趋势
```bash
python3 scripts/finnhub_cli.py recommend NVDA
```

### 内部人交易记录（最近 90 天）
```bash
python3 scripts/finnhub_cli.py insiders AAPL
python3 scripts/finnhub_cli.py insiders NVDA --from 2026-01-01 --to 2026-02-21
```

### 盈利日历（未来 30 天）
```bash
python3 scripts/finnhub_cli.py earnings             # 所有股票
python3 scripts/finnhub_cli.py earnings NVDA        # 指定股票
python3 scripts/finnhub_cli.py earnings --from 2026-02-21 --to 2026-03-07
```

### 基本面财务指标
```bash
python3 scripts/finnhub_cli.py financials AAPL
python3 scripts/finnhub_cli.py financials NVDA --json   # 全部指标
```

### 市场状态
```bash
python3 scripts/finnhub_cli.py market          # 默认美国
python3 scripts/finnhub_cli.py market NYSE
```

### 同行公司
```bash
python3 scripts/finnhub_cli.py peers AAPL
```

### 股票代码搜索
```bash
python3 scripts/finnhub_cli.py search "apple"
```

## 不可用功能（付费层）

- K 线数据（`stock_candles`）
- 分析师目标价（`price_target`）
- 新闻情绪分析（`news_sentiment`）

## 限制

- 免费层：60 次/分钟
- 403 = 需付费升级
- 429 = 触发限速

## 依赖

- Python 3.10+
- `finnhub-python`（`pip install finnhub-python`）