{
  "markdown": "# @pipeworx/finra\n\nFINRA short-sale data for US equities — daily short-sale **volume** from the Reg SHO\ndaily dataset, and bi-monthly consolidated **short interest**. Both come from the FINRA\nQuery API's `otcMarket` dataset group.\n\nPart of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1476+ live data sources.\n\nThe two are different measurements and are constantly confused. Short *volume* is how\nmany shares traded short on a given day. Short *interest* is how many shares are\ncurrently sold short and not yet covered, reported twice a month by settlement date —\nthat is the \"% short / days-to-cover\" figure investors quote.\n\n## Tools\n\n| Tool | What it returns |\n|------|-----------------|\n| `short_volume_daily` | One symbol's short-sale volume for one trading day, summed across every consolidated-NMS reporting facility: `short_volume`, `short_exempt_volume`, `total_volume`, `short_ratio`, and the per-facility split. |\n| `short_volume_history` | Up to 30 trading days of the same series for one symbol, ending at `end_date`. One upstream request, not one per day. |\n| `short_volume_top` | Symbols on one trading day ranked by `short_ratio`, with a `min_total_volume` filter to exclude thinly-traded micros. Scans the full published day (~12,300 symbols). |\n| `short_interest` | One symbol's consolidated short interest by settlement date: open short position, change vs the prior settlement, days-to-cover, average daily volume, plus recent history. |\n\nPublishing lag on the Reg SHO data is typically T+1 or better — 2026-08-25's rows were\nqueryable on 2026-08-25. Omit `date`/`end_date` and the pack probes back up to 7 days for\nthe most recent day with published rows. Short interest settles bi-monthly, so the newest\nrecord is routinely a week or two old — that is the source's cadence, not staleness on\nour side.\n\n## Reporting facilities, and why the sum matters\n\n`regShoDaily` returns **one row per reporting facility** per symbol per day. A symbol's\nreal short volume is the sum of them:\n\n| Facility | Market code | Venue | In consolidated NMS? |\n|---|---|---|---|\n| `NQTRF` | `Q` | Nasdaq TRF Carteret | yes |\n| `NYTRF` | `N` | NYSE TRF | yes |\n| `NCTRF` | `B` | Nasdaq TRF Chicago | yes |\n| `ORF` | `O` | OTC Reporting Facility | no — OTC / non-NMS securities |\n\n`combined` sums every non-ORF facility, which reproduces FINRA's own consolidated CNMS\nfigure exactly. Verified 2026-08-25 against `CNMSshvol20260821`: GME on 2026-08-21 sums\nto short 1,335,397.220545 / exempt 1,355 / total 2,315,275.403735, byte-identical to that\nfile's line (whose own market column reads `B,Q,N`), and market-wide the same day, 12,269\nsymbols summing to short 3,244,559,759 / total 6,564,367,888.\n\nUntil fleet #532 this pack read only the Nasdaq and NYSE TRFs and asserted current data\nlived \"exclusively\" there. It does not: omitting Nasdaq TRF Chicago undercounted short\nvolume by **0.77%** and total volume by **0.88%** market-wide, every day, with a clean\n200 and nothing in the response saying so — and far more on any symbol that trades\ndisproportionately on that facility.\n\nORF is excluded on purpose, and is a different thing from a missing facility: it is a\nseparate market, not a missing part of this one. A symbol with both gets its ORF volume\nlisted under `otc_reporting_facility` rather than folded into the NMS total; a symbol\nwith *only* ORF volume is returned with `scope: \"otc_reporting_facility\"` and a note,\nrather than a zero.\n\n## Symbol case is significant\n\nA lowercase letter is FINRA's preferred-share marker. On 2026-08-21 `BCpC` (Bancorp\npreferred series C, 2,267 shares) and `BCPC` (Balchem common, 52,413) are two different\nsecurities in the same day's data, as are `TpC` and `TPC`.\n\nThe Query API's `equal` filter is **case-insensitive**, so asking for `BCPC` returns both.\nThis pack therefore never upper-cases a symbol: it resolves to exactly one security, and\nif your input matches several it returns `reason: \"ambiguous_symbol\"` with the candidates\nrather than adding a preferred series into a common stock's total. When a near-miss\nsymbol exists, it is named in `also_reported` so you can see it was left out.\n\n## Auth\n\nKeyless. The upstream answers without a credential, and no `_apiKey` is accepted.\n\nKeyless is **not** the same as unencumbered — see Licence below.\n\n## Licence and attribution\n\nAll four tools read the `otcMarket` dataset group at `api.finra.org`, covered by\n[FINRA's Specific Terms for Equity Data](https://developer.finra.org/specific-terms-equity-data),\nsection 2.3. Two conditions bind us and are not optional:\n\n- **Attribution.** FINRA must be clearly identified as the owner and source of the data\n  and of anything derived from it. Every response from this pack therefore carries a\n  leading `attribution` string, attached centrally in `callTool` so a new tool or a new\n  early-return cannot ship unattributed by omission. It leads the object so a model\n  synthesizing an answer reads it first, and it survives into `ask_pipeworx` answers\n  because the answer path passes a pack's `structuredContent` through verbatim.\n- **No incremental fee.** We may not charge for the data. The whole pack is therefore\n  **zero-rated** at the gateway (`zeroRated: true` on its `MCP_PACKS` entry): zero credits\n  on every tier including paid, no monthly-volume slot consumed, not counted as a billable\n  lookup inside an answer, and quoted as zero in the pre-call cost disclosure. Responses\n  carry `_meta.cost.zero_rated: true`. A metered version of any of these tools would be a\n  licence breach, not a pricing choice — do not remove the flag.\n\nEnd users may not redistribute the data further and are limited to non-commercial\npersonal or professional use; that condition is stated in the `attribution` string and in\nsection 6 of the published terms at https://pipeworx.io/terms.\n\n**Do not reintroduce a `cdn.finra.org` fetch**, for a fallback or for freshness. The Reg\nSHO daily *files* published there are a different distribution, outside the Specific\nTerms; the general [FINRA.org Terms of Use](https://www.finra.org/terms-of-use) that\ngovern them instead are stricter — non-commercial use only, no redistribution without\nprior written consent, no bulk copying of the website, no creating a database from it,\nand an explicit bar on use \"in conjunction with any machine learning, neural network,\ndeep learning, predictive analytics or other artificial intelligence computer or software\nprogram\", which is what every caller of this gateway is. Both routes carried 2026-08-21\non 2026-08-25, so there is no freshness trade to make.\n\nBackground: fleet #531 and #532, and the licence analysis in\n`docs/finance-data-ingest-plan.md`.\n\n## Data sources\n\n- Reg SHO daily short-sale volume — `POST https://api.finra.org/data/group/otcMarket/name/regShoDaily`\n- Consolidated short interest — `POST https://api.finra.org/data/group/otcMarket/name/consolidatedShortInterest`\n- Field names and types — `GET https://api.finra.org/metadata/group/otcMarket/name/regShoDaily`\n- Catalog: https://www.finra.org/finra-data/browse-catalog/short-sale-volume-daily\n\nUpstream quirks worth knowing if you touch this pack: send `Accept: application/json` or\nFINRA returns CSV; `limit` is capped server-side at 5,000 and the true match count is in\nthe `record-total` response header; a query matching nothing answers **204 with an empty\nbody**, not `[]`, so a naive `res.json()` throws a parse error that reads like a pack bug\nwhen it means \"no data for that day\"; and sorting is rejected unless the partition key\n(`tradeReportDate`) is pinned with an `equal` filter, so there is no \"latest date\" query —\nthe pack probes backwards instead.\n\n## Quick Start\n\nAdd to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"finra\": {\n      \"url\": \"https://gateway.pipeworx.io/finra/mcp\"\n    }\n  }\n}\n```\n\n### What this endpoint actually serves\n\n`tools/list` at `https://gateway.pipeworx.io/finra/mcp` returns the tools in the table\nabove **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,\n`discover_tools`, `search_within`, `remember`/`recall` and the rest of the\ngateway-wide set. So the tool count you see is larger than this table: a\nsingle-pack endpoint currently lists roughly 30 shared tools alongside the\npack's own. The connection's `initialize` response states its exact scope, and\nis the authoritative answer for a given day.\n\nThis is deliberate, not multiplexing by accident. The meta-tools are what let a\nscoped connection answer a question this pack does not cover — via\n`ask_pipeworx`, which routes across the whole catalog — without you adding a\nsecond MCP server. There is currently no way to mount a pack endpoint without\nthem; if the extra schemas cost you more context than the routing is worth,\nconnect to the full gateway once rather than to several pack endpoints.\n\nOr connect to the full Pipeworx gateway to get every pack's tools listed\ndirectly, instead of just this one's:\n\n```json\n{\n  \"mcpServers\": {\n    \"pipeworx\": {\n      \"url\": \"https://gateway.pipeworx.io/mcp\"\n    }\n  }\n}\n```\n\nBoth URLs reach the same gateway and the same 1476+ data sources. The\nonly difference is which pack's tools are listed **directly**; `ask_pipeworx`\nreaches all of them from either one.\n\n## Using with ask_pipeworx\n\nInstead of calling tools directly, you can ask questions in plain English —\nthis works on the pack endpoint above as well as on the full gateway:\n\n```\nask_pipeworx({ question: \"your question about Finra data\" })\n```\n\nThe gateway picks the right tool and fills the arguments automatically.\n\n## More\n\n- [Docs and guides](https://pipeworx.io/docs)\n- [pipeworx.io](https://pipeworx.io)\n\n## License\n\nMIT\n",
  "bytes": 9706,
  "sha": "3b9dd8c072c33742c9e4810f65f7cd5b1ac214490ef79fdaec300f1ebf5478df",
  "repo_slug": "pipeworx-io/mcp-finra",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pipeworx_io_finra_9bcdc75e/readme"
}