Finra

@pipeworx/finra

美国股票的 FINRA 卖空数据——来自 Reg SHO 每日数据集的每日卖空成交量，以及每月两次汇总的空头持仓。两者都来自 FINRA Query API 的 otcMarket 数据集组。

属于 Pipeworx 的一部分——一个将 AI Agent 连接到 1879+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联、未经其认可，也非由其发布。

这是两种不同的指标，经常被混淆。卖空成交量指某一天卖空交易的股数。空头持仓指当前已卖空但尚未回补的股数，按结算日期每月报告两次——投资者所说的“卖空比例／回补天数”指的就是这个数字。

工具

工具	返回内容
short_volume_daily	一个交易日内，某个股票代码的卖空成交量，汇总所有纳入综合 NMS 报告的设施：short_volume、short_exempt_volume、total_volume、short_ratio，以及各设施的明细。
short_volume_history	某个股票代码最多 30 个交易日的相同序列，截止于 end_date。只需一次上游请求，而非每天请求一次。
short_volume_top	某个交易日按 short_ratio 排序的股票代码，可通过 min_total_volume 过滤掉交易清淡的微型股票。扫描当天发布的全部数据（约 12,300 个股票代码）。
short_interest	某个股票代码按结算日期汇总的空头持仓：未平仓空头头寸、与上个结算日相比的变动、回补天数、日均成交量，以及近期历史记录。

Reg SHO 数据的发布延迟通常为 T+1 或更短——2026-08-25 的数据行在 2026-08-25 就已可查询。省略 date／end_date 时，此工具包会向前探测最多 7 天，查找最近一个已发布数据的日期。空头持仓每月结算两次，因此最新记录通常已有一两周的时间——这是数据源的发布频率，并非我们这边的数据过时。

报告设施，以及汇总为何重要

regShoDaily 会为每个股票代码、每天的每个报告设施返回一行数据。某个股票代码的实际卖空成交量是这些数据行的总和：

设施	市场代码	交易场所	是否纳入综合 NMS？
NQTRF	Q	Nasdaq TRF Carteret	是
NYTRF	N	NYSE TRF	是
NCTRF	B	Nasdaq TRF Chicago	是
ORF	O	OTC Reporting Facility	否——OTC／非 NMS 证券

combined 会汇总除 ORF 以外的所有设施，这与 FINRA 自己发布的综合 CNMS 数据完全一致。经对照 CNMSshvol20260821 验证：2026-08-21，GME 的卖空成交量、豁免卖空成交量和总成交量分别为 1,335,397.220545、1,355 和 2,315,275.403735，与该文件中的对应行逐字节一致（该行自身的市场列为 B,Q,N）；市场整体同一天有 12,269 个股票代码，卖空成交量合计为 3,244,559,759，总成交量合计为 6,564,367,888。

在 fleet #532 之前，这个工具包只读取 Nasdaq 和 NYSE TRF，并声称当前数据“仅”存在于这两处。事实并非如此：漏掉 Nasdaq TRF Chicago 会导致市场整体卖空成交量每天低估 0.77%、总成交量低估 0.88%，但响应仍然正常返回 200，且没有任何提示说明数据不完整——对于交易量特别集中在该设施的股票，低估幅度会大得多。

有意排除 ORF，并不意味着 ORF 是缺失设施：它属于另一个市场，并非当前市场中缺失的一部分。若某个股票代码同时有两类数据，其 ORF 成交量会列在 otc_reporting_facility 下，而不会并入 NMS 总量；若某个股票代码只有 ORF 成交量，则会返回 scope: "otc_reporting_facility" 和一条说明，而不是返回零。

证券代码区分大小写

小写字母是 FINRA 首选股的标记。2026-08-21 的数据中，BCpC（Bancorp C 系列优先股，2,267 股）和 BCPC（Balchem 普通股，52,413 股）是两种不同的证券，TpC 和 TPC 也是如此。

Query API 的 equal 筛选条件不区分大小写，因此查询 BCPC 会返回两者。因此，本工具包绝不会将证券代码转换为大写：它会解析为唯一一种证券；如果输入匹配多个证券，则会返回包含候选项的 reason: "ambiguous_symbol"，而不是把优先股系列计入普通股总额。如果存在相似但不匹配的证券代码，则会在 also_reported 中列出，让你知道该证券未被计入。

身份验证

无需密钥。上游无需凭证即可响应，也不接受 _apiKey。

无需密钥并不意味着没有限制——请参阅下文的许可条款。

许可与署名

所有四种工具都会读取 api.finra.org 上的 otcMarket 数据集组，该数据集受 FINRA 关于股票数据的特定条款第 2.3 节约束。我们必须遵守两项条件，不得例外：

• 署名。 必须明确标明 FINRA 是数据及其衍生内容的所有者和来源。因此，本工具包的每个响应都会带有开头的 attribution 字符串，该字符串由 callTool 集中附加，确保新增工具或新增的提前返回路径不会因疏漏而缺少署名。它位于对象开头，以便综合答案的模型优先读取；由于答案路径会原样传递工具包的 structuredContent，该署名也会保留在 ask_pipeworx 的答案中。
• 不得收取额外费用。 我们不得对数据收费。因此，整个工具包在网关中均设为零费率（MCP_PACKS 条目中的 zeroRated: true）：所有层级（包括付费层级）均不扣除额度，不占用月度用量名额，不计入答案中的计费查询，并且在调用前的费用说明中标为零。响应会包含 _meta.cost.zero_rated: true。将这些工具改为按量计费将违反许可，而不是一种定价选择——请勿移除此标记。

最终用户不得进一步转发数据，且仅限将其用于非商业性的个人或专业用途；attribution 字符串和已发布条款的第 6 节（https://pipeworx.io/terms）中均说明了这一条件。

请勿重新引入对 cdn.finra.org 的抓取，无论是用于回退还是获取最新数据。该网站发布的 Reg SHO 每日文件属于不同的数据分发渠道，不受《特定条款》约束；适用于这些文件的 FINRA.org 使用条款则限制更严格——仅限非商业用途，未经事先书面同意不得转发，不得批量复制网站内容，不得据此创建数据库，并明确禁止“与任何机器学习、神经网络、深度学习、预测分析或其他人工智能计算机或软件程序结合使用”，而所有调用此网关的用户都属于这一范畴。两种渠道在 2026-08-25 提供的数据均截至 2026-08-21，因此无需在数据新鲜度上作取舍。

背景：fleet #531 和 #532，以及 docs/finance-data-ingest-plan.md 中的许可分析。

数据源

• Reg SHO 每日卖空成交量 — POST https://api.finra.org/data/group/otcMarket/name/regShoDaily
• 综合卖空持仓 — POST https://api.finra.org/data/group/otcMarket/name/consolidatedShortInterest
• 字段名称和类型 — GET https://api.finra.org/metadata/group/otcMarket/name/regShoDaily
• 目录：https://www.finra.org/finra-data/browse-catalog/short-sale-volume-daily

使用此工具包时，值得了解的上游行为：请发送 Accept: application/json，否则 FINRA 会返回 CSV；limit 在服务端的上限为 5,000，实际匹配总数位于 record-total 响应标头中；如果查询没有匹配结果，响应为 204，且响应体为空，而不是 []，因此直接调用 res.json() 会抛出解析错误，看起来像是工具包故障，实际上只是“当天没有数据”；除非使用 equal 筛选器固定分区键（tradeReportDate），否则排序请求会被拒绝，因此无法查询“最新日期”——工具包会改为向前逐日探查。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "finra": {
      "url": "https://gateway.pipeworx.io/finra/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/finra/mcp 上的 tools/list 会返回上表中的工具，以及共享的 Pipeworx 元工具——ask_pipeworx、discover_tools、search_within、remember/recall 和整个网关共享工具集中的其他工具。因此，你看到的工具数量会多于此表中的数量：目前，单个工具包端点会列出约 30 个共享工具，以及该工具包自身的工具。连接的 initialize 响应会说明其确切范围，是了解特定日期实际情况的权威依据。

这是有意为之，并非意外的多路复用。元工具可以让受限连接回答此工具包未涵盖的问题——通过 ask_pipeworx 路由到整个目录——而无需添加第二个 MCP 服务。目前无法挂载不包含这些工具的工具包端点；如果额外的架构信息占用的上下文比路由带来的价值更多，请连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出每个工具包的所有工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

这两个 URL 都会访问同一个网关和相同的 1879+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论使用哪个 URL，ask_pipeworx 都能访问全部工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/short_volume_daily \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"AAPL"}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/short_volume_daily。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经由网关往返：

{
  "mcpServers": {
    "finra": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-finra"]
    }
  }
}

或者直接运行它，确认服务能正常启动：

npx -y @pipeworx/mcp-finra

它通过 stdin/stdout 使用 MCP，并为仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接额外提供的任何共享元工具。数据源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你也可以用通俗的英文提问，而不是直接调用工具——此方式既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Finra data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT