fintel-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fintel Data Skill

Fintel 数据技能

Fintel (fintel.io) is an institutional-grade market intelligence platform. Its strongest datasets are the ones most other providers lack: short interest, borrow rates, short volume, fails-to-deliver, 13F institutional ownership, and insider transactions.

Fintel exposes two surfaces backed by the same data contract:

Surface	Endpoint	Auth	Best for
REST	`https://api.fintel.io/v1/*`	`X-API-KEY` header	Default — curl from any CLI agent
MCP	`https://mcp.fintel.io/mcp`	`X-API-KEY` header	MCP-native clients, tool auto-discovery

Both require a Fintel API key. This skill is READ-ONLY — only call GET endpoints. The API also exposes write endpoints (create/delete stock lists, alert subscriptions, teams); do not call them.

Fintel（fintel.io）是一款机构级市场情报平台。其最具优势的数据集是其他多数提供商所欠缺的：空头兴趣、拆借利率、空头交易量、交割失败、13F机构持股情况以及内幕交易。

Fintel提供两种基于相同数据协议的访问方式：

访问方式	端点	认证方式	适用场景
REST	`https://api.fintel.io/v1/*`	`X-API-KEY` 请求头	默认方式 — 可通过任意CLI工具执行curl调用
MCP	`https://mcp.fintel.io/mcp`	`X-API-KEY` 请求头	MCP原生客户端、工具自动发现

两种方式都需要Fintel API密钥。本技能仅支持只读操作 — 仅调用GET端点。API还提供写入端点（创建/删除股票列表、警报订阅、团队）；请勿调用这些端点。

Step 1: Resolve FINTEL_API_KEY

步骤1：解析FINTEL_API_KEY

The skill resolves

FINTEL_API_KEY

in this order:

```
FINTEL_API_KEY
```
environment variable
```
FINTEL_API_KEY
```
in
```
.env
```
in the current directory
```
FINTEL_API_KEY
```
in
```
.env
```
at the git repo root (so a worktree inherits the key from the main checkout)

!`if [ -n "$FINTEL_API_KEY" ]; then echo "KEY_FROM_ENV_VAR"; elif [ -f .env ] && grep -qE "^FINTEL_API_KEY=" .env; then echo "KEY_FROM_LOCAL_DOTENV:$(pwd)/.env"; else GIT_COMMON=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null); if [ -n "$GIT_COMMON" ]; then ROOT=$(dirname "$GIT_COMMON"); if [ -f "$ROOT/.env" ] && grep -qE "^FINTEL_API_KEY=" "$ROOT/.env"; then echo "KEY_FROM_ROOT_DOTENV:$ROOT/.env"; else echo "KEY_NOT_SET"; fi; else echo "KEY_NOT_SET"; fi; fi`

Then act on the result:

```
KEY_FROM_ENV_VAR
```
— use
```
$FINTEL_API_KEY
```
directly in curl calls.

KEY_FROM_LOCAL_DOTENV:<path>

KEY_FROM_ROOT_DOTENV:<path>

— load once before calling:

bash

export FINTEL_API_KEY=$(grep -E "^FINTEL_API_KEY=" <path> | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//')

```
KEY_NOT_SET
```
— ask the user for their key. Keys come with a Fintel API plan (fintel.io, docs at api.fintel.io/docs). They can either
```
export FINTEL_API_KEY="..."
```
or add
```
FINTEL_API_KEY=...
```
to
```
.env
```
at the repo root (preferred for worktrees).

本技能按以下顺序解析

FINTEL_API_KEY

：

```
FINTEL_API_KEY
```
环境变量
当前目录下
```
.env
```
文件中的
```
FINTEL_API_KEY
```
Git仓库根目录下
```
.env
```
文件中的
```
FINTEL_API_KEY
```
（以便工作树从主检出目录继承密钥）

!`if [ -n "$FINTEL_API_KEY" ]; then echo "KEY_FROM_ENV_VAR"; elif [ -f .env ] && grep -qE "^FINTEL_API_KEY=" .env; then echo "KEY_FROM_LOCAL_DOTENV:$(pwd)/.env"; else GIT_COMMON=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null); if [ -n "$GIT_COMMON" ]; then ROOT=$(dirname "$GIT_COMMON"); if [ -f "$ROOT/.env" ] && grep -qE "^FINTEL_API_KEY=" "$ROOT/.env"; then echo "KEY_FROM_ROOT_DOTENV:$ROOT/.env"; else echo "KEY_NOT_SET"; fi; else echo "KEY_NOT_SET"; fi; fi`

根据结果执行相应操作：

```
KEY_FROM_ENV_VAR
```
— 在curl调用中直接使用
```
$FINTEL_API_KEY
```
。

KEY_FROM_LOCAL_DOTENV:<path>

KEY_FROM_ROOT_DOTENV:<path>

— 在调用前先加载密钥：

bash

export FINTEL_API_KEY=$(grep -E "^FINTEL_API_KEY=" <path> | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//')

```
KEY_NOT_SET
```
— 向用户索要密钥。密钥需通过Fintel API套餐获取（fintel.io，文档见api.fintel.io/docs）。用户可以执行
```
export FINTEL_API_KEY="..."
```
，或在仓库根目录的
```
.env
```
文件中添加
```
FINTEL_API_KEY=...
```
（推荐用于工作树场景）。

Step 2: Resolve the Security

步骤2：解析证券信息

Most endpoints are addressed by

{country}/{symbol}

— an ISO country code plus ticker, e.g.

us/AAPL

. Default to

us

when the user gives only a ticker.

If the ticker is ambiguous or the user gives a company name, CUSIP, ISIN, or FIGI, resolve it first:

bash

undefined

大多数端点通过

{country}/{symbol}

访问 — ISO国家代码加股票代码，例如

us/AAPL

。当用户仅提供股票代码时，默认使用

us

。

如果股票代码存在歧义，或用户提供了公司名称、CUSIP、ISIN或FIGI，需先解析：

bash

undefined

name / ticker / CUSIP / ISIN / FIGI search

名称 / 股票代码 / CUSIP / ISIN / FIGI 搜索

curl -s -H "X-API-KEY: $FINTEL_API_KEY" "https://api.fintel.io/v1/securities?query=apple&country=us"

exact identifier lookup (type: cusip, isin, ticker, id)

精确标识符查询（类型：cusip, isin, ticker, id）

curl -s -H "X-API-KEY: $FINTEL_API_KEY" "https://api.fintel.io/v1/identifiers/isin/US0378331005"

---

curl -s -H "X-API-KEY: $FINTEL_API_KEY" "https://api.fintel.io/v1/identifiers/isin/US0378331005"

---

Step 3: Match the Request to an Endpoint

步骤3：将请求匹配到对应端点

User wants	Endpoint	Notes
Short interest, days to cover	`/v1/securities/{country}/{symbol}/short-interest`	Trailing year, NYSE/NASDAQ-reported. Limited availability — must be enabled per account; 403 means not entitled
Borrow rate, cost to borrow, shares available	`/v1/securities/{country}/{symbol}/borrow-rate`	Latest securities-lending fee rate, rebate rate, shares available
Daily short volume	`/v1/securities/{country}/{symbol}/short-volume`	Trailing year: short, short-exempt, total volume
Fails-to-deliver / FTD	`/v1/securities/{country}/{symbol}/fails-to-deliver`	Trailing-year SEC FTD records (US only)
Institutional owners / 13F holders	`/v1/securities/{country}/{symbol}/owners`	Current SEC 13F-derived holders
Insider transactions / Form 4	`/v1/securities/{country}/{symbol}/insiders`	SEC Form 3/4/5-derived; `count` param
Analyst price targets	`/v1/securities/{country}/{symbol}/price-targets`	High, low, mean, median
Analyst buy/hold/sell ratings	`/v1/securities/{country}/{symbol}/analyst-ratings`	Aggregated recommendations
Revenue / EPS forecasts	`/v1/securities/{country}/{symbol}/forecast`	Aggregated analyst estimates
EOD price history	`/v1/securities/{country}/{symbol}/eod`	`period` : 1m, 3m, 6m, 1y (default), 2y, 3y, 5y, all
Latest price + derived stats	`/v1/securities/{country}/{symbol}/last-price`	52w high/low, WTD/MTD/YTD change; falls back to EOD close with `meta.warnings=["quote_stale"]`
Dividend history	`/v1/securities/{country}/{symbol}/dividends`
Earnings history and surprises	`/v1/securities/{country}/{symbol}/earnings`
Upcoming earnings (one stock / market-wide)	`/v1/securities/{country}/{symbol}/calendar/earnings` or `/v1/calendar/earnings`	`from` / `to` ISO dates, default today +7d, max 90d window
Upcoming dividends (one stock / market-wide)	`/v1/securities/{country}/{symbol}/calendar/dividends` or `/v1/calendar/dividends`	Same window rules
A specific fundamental metric	`/v1/securities/{country}/{symbol}/data-points/{key}`	Discover keys via `/v1/data-definitions?query=...`
Top/bottom ranked stocks	`/v1/leaderboards` then `/v1/leaderboards/{key}/entries`	503 not_available means retry later; `meta.status="beta"` means stub data
Security profile, listings, identifier history	`/v1/securities/{country}/{symbol}`
User's watchlists	`/v1/stock-lists` , `/v1/stock-lists/{id}/items`	Also `/insiders` , `/owners` , `/filings` per list
User's alerts	`/v1/alerts` , `/v1/alert-messages`
Account / entitlements	`/v1/account`

Full parameter details, country/exchange discovery endpoints, and more curl examples: read

references/api-reference.md

用户需求	端点	说明
空头兴趣、回补天数	`/v1/securities/{country}/{symbol}/short-interest`	过去一年的数据，由NYSE/NASDAQ上报。可用性受限 — 需按账户启用；返回403表示无权限
拆借利率、拆借成本、可拆借股票数量	`/v1/securities/{country}/{symbol}/borrow-rate`	最新的证券借贷费率、回扣率、可拆借股票数量
每日空头交易量	`/v1/securities/{country}/{symbol}/short-volume`	过去一年的数据：空头交易量、豁免空头交易量、总交易量
交割失败 / FTD	`/v1/securities/{country}/{symbol}/fails-to-deliver`	过去一年的SEC交割失败记录（仅美国市场）
机构所有者 / 13F持有人	`/v1/securities/{country}/{symbol}/owners`	当前基于SEC 13F文件的持有人信息
内幕交易 / Form 4	`/v1/securities/{country}/{symbol}/insiders`	基于SEC Form 3/4/5文件的数据；支持 `count` 参数
分析师目标价	`/v1/securities/{country}/{symbol}/price-targets`	最高、最低、平均、中位数目标价
分析师买入/持有/卖出评级	`/v1/securities/{country}/{symbol}/analyst-ratings`	汇总后的推荐评级
营收 / EPS预测	`/v1/securities/{country}/{symbol}/forecast`	汇总后的分析师预估
EOD价格历史	`/v1/securities/{country}/{symbol}/eod`	`period` 参数可选：1m、3m、6m、1y（默认）、2y、3y、5y、all
最新价格 + 衍生统计数据	`/v1/securities/{country}/{symbol}/last-price`	52周最高/最低价、WTD/MTD/YTD涨跌幅；若数据过时，会返回 `meta.warnings=["quote_stale"]` 并回退到EOD收盘价
股息历史	`/v1/securities/{country}/{symbol}/dividends`
收益历史与超预期情况	`/v1/securities/{country}/{symbol}/earnings`
即将到来的收益（单只股票 / 全市场）	`/v1/securities/{country}/{symbol}/calendar/earnings` 或 `/v1/calendar/earnings`	`from` / `to` 为ISO格式日期，默认是今日起7天内，最大窗口为90天
即将到来的股息（单只股票 / 全市场）	`/v1/securities/{country}/{symbol}/calendar/dividends` 或 `/v1/calendar/dividends`	窗口规则同上
特定基本面指标	`/v1/securities/{country}/{symbol}/data-points/{key}`	可通过 `/v1/data-definitions?query=...` 查询指标键值
排名靠前/靠后的股票	`/v1/leaderboards` 然后 `/v1/leaderboards/{key}/entries`	返回503 not_available表示需稍后重试； `meta.status="beta"` 表示为测试数据
证券概况、上市信息、标识符历史	`/v1/securities/{country}/{symbol}`
用户的观察列表	`/v1/stock-lists` , `/v1/stock-lists/{id}/items`	还支持按列表查询 `/insiders` 、 `/owners` 、 `/filings`
用户的警报	`/v1/alerts` , `/v1/alert-messages`
账户 / 权限	`/v1/account`

完整的参数细节、国家/交易所发现端点及更多curl示例：请查看

references/api-reference.md

。

Step 4: Call the API

步骤4：调用API

bash

curl -s -H "X-API-KEY: $FINTEL_API_KEY" \
  "https://api.fintel.io/v1/securities/us/AAPL/short-volume" | python3 -m json.tool

Success responses are JSON; some carry a
```
meta
```
object (warnings, freshness, status). Surface
```
meta.warnings
```
to the user when present.
Errors return
```
{"error": {"code": "...", "message": "..."}}
```
— e.g.
```
unauthorized
```
(bad/missing key),
```
403
```
(dataset not enabled for the account, common for short-interest),
```
503 not_available
```
(ranking service down — retry later, don't treat as empty data).
Usage is metered per account — batch thoughtfully; don't poll.

bash

curl -s -H "X-API-KEY: $FINTEL_API_KEY" \
  "https://api.fintel.io/v1/securities/us/AAPL/short-volume" | python3 -m json.tool

成功响应为JSON格式；部分响应包含
```
meta
```
对象（警告、数据新鲜度、状态）。当存在
```
meta.warnings
```
时，需向用户展示该内容。
错误响应返回
```
{"error": {"code": "...", "message": "..."}}
```
— 例如
```
unauthorized
```
（密钥无效/缺失）、
```
403
```
（账户未启用该数据集，空头兴趣数据常见此情况）、
```
503 not_available
```
（排名服务不可用 — 稍后重试，不要视为空数据）。
API使用按账户计量 — 需合理批量调用；请勿轮询。

Step 5: MCP Alternative (Optional)

步骤5：MCP替代方案（可选）

For MCP-native setups, the same tools are discoverable from the official server (tool names like

fintel.get_short_interest

fintel.get_security_owners

— REST parity, same entitlements):

bash

claude mcp add --transport http fintel https://mcp.fintel.io/mcp --header "X-API-KEY: your_key_here"

Prefer REST via curl when shell access is available — it needs no setup beyond the key. Use MCP when the user explicitly asks for it or shell access is restricted (note: neither works on Claude.ai's sandbox).

对于MCP原生环境，可从官方服务器发现相同工具（工具名称如

fintel.get_short_interest

、

fintel.get_security_owners

— 与REST功能一致，权限相同）：

bash

claude mcp add --transport http fintel https://mcp.fintel.io/mcp --header "X-API-KEY: your_key_here"

当具备Shell访问权限时，优先使用REST通过curl调用 — 除密钥外无需额外配置。当用户明确要求或Shell访问受限时使用MCP（注意：两种方式均无法在Claude.ai的沙箱环境中使用）。

Step 6: Respond to the User

步骤6：响应用户

Format numbers cleanly: prices to 2 decimals, percentages to 1-2 decimals, share counts with commas or abbreviations (2.3M, 1.1B).
For short data: contextualize — short interest as % of float, days to cover, borrow fee trend direction. High borrow fee + falling shares available is the classic squeeze setup; present the data, not a prediction.
For ownership/insiders: use tables (holder, shares, change, date). Distinguish buys from sells and option exercises in Form 4 data.
Note the data source: "Fintel" with dataset provenance (SEC 13F, Form 3/4/5, NYSE/NASDAQ short reports) when relevant.
Never turn the data into a trading recommendation, price target, or squeeze call — present facts and let the user draw conclusions.

清晰格式化数字：价格保留2位小数，百分比保留1-2位小数，股票数量使用逗号或缩写（2.3M、1.1B）。
对于空头数据：添加上下文 — 空头兴趣占流通股的比例、回补天数、拆借费率趋势。高拆借费率+可拆借股票数量减少是典型的轧空前兆；仅展示数据，不做预测。
对于持股/内幕交易数据：使用表格展示（持有人、持股量、变动、日期）。在Form 4数据中区分买入、卖出及期权行权。
注明数据源：相关场景下标注“Fintel”及数据来源（SEC 13F、Form 3/4/5、NYSE/NASDAQ空头报告）。
切勿将数据转化为交易建议、目标价或轧空判断 — 仅呈现事实，由用户自行得出结论。

Reference Files

参考文件

```
references/api-reference.md
```
— full REST endpoint reference: all GET endpoints with parameters, defaults, limits, error semantics, MCP tool name mapping, and curl examples.

```
references/api-reference.md
```
— 完整的REST端点参考：包含所有GET端点的参数、默认值、限制、错误语义、MCP工具名称映射及curl示例。