cognis-digital/edgarpull

# edgarpull — 通过 ticker/CIK 获取 SEC EDGAR 情报（13F、Form 4、8-K） [](https://pypi.org/project/cognis-edgarpull/) [](https://github.com/cognis-digital/edgarpull/actions) [](LICENSE) [](https://github.com/cognis-digital) **通过 ticker 或 CIK 拉取 SEC EDGAR 数据 — 13F 机构持仓、Form 4 内部人士交易以及 8-K 重大事件。** *金融科技与市场 — 将公开的监管文件转化为结构化信号。* 使用**官方、公开、免费、无需 API key** 的 SEC endpoint： 使用 `company_tickers.json` 进行 ticker→CIK 的解析，并使用 `data.sec.gov` submissions API 获取提交历史。仅使用标准库（urllib/json）— 无需 pip 依赖。SEC 要求提供描述性的 `User-Agent`，并建议客户端 请求频率保持在 ~10 req/s 以下；edgarpull 会发送适当的 UA 并在实际 请求之间加入休眠。 ## 使用说明 — 分步指南 1. 从源码**安装**（Python 3.9+；实时 SEC EDGAR API，无需 key）： pip install . 2. 通过 ticker 或 CIK **拉取**近期文件： edgarpull filings AAPL --limit 20 3. **深入查看**内部人士（Form 4）、机构（13F）或重大事件（8-K）文件： edgarpull insiders AAPL --format json edgarpull institutions NVDA --format json edgarpull events TSLA 4. **使用输出**：传入 `--format json --out filings.json` 获取机器可读的结果；`--demo` 将完全离线运行，使用内置的示例数据。 5. 在 CI 中**实现自动化**，设置适当的速率限制并使用你自己的 User-Agent： edgarpull filings 0000320193 --format json --user-agent "you@example.com" --sleep 0.2 --out aapl.json 此外：`edgarpull ft "" --forms 8-K`（全文搜索）和 `edgarpull mcp`。 ## 为什么需要它 分析师和量化研究员需要快速、可脚本化地访问谁在买入、谁在 卖出，以及刚刚发生了什么重大变化 — 而无需部署一整套数据供应商系统。 `edgarpull` 是单一用途且对 CI 友好的：将其指向一个 ticker，即可获取 表格或 JSON 格式的结构化文件，当你想实现自动化时，可以通过 MCP 将其 接入代理。它附带了一个缓存的示例包，因此可以完全离线运行和测试。 ## 领域 **主要领域：** Intelligence & OSINT · **JTF MERIDIAN 部门：** NULLBYTE · BLACK CELL **主题：** `cognis` `osint` `intelligence` `recon` **Cognis Neural Suite** 的一部分 — 在 JTF MERIDIAN 指挥结构下，涵盖 12 个领域的 300 多个开源可用工具。请参阅 [GitHub 上的 suite](https://github.com/cognis-digital) 和 [jtf-meridian](https://github.com/cognis-digital/jtf-meridian) 了解它们是如何组合在一起的。 ## 安装 ``` pip install cognis-edgarpull # 或者，来自此 repo： pip install -e ".[dev]" ``` ## 快速开始 ``` edgarpull --version edgarpull institutions AAPL --demo # offline against the sample bundle edgarpull insiders AAPL --demo --format json edgarpull events AAPL --demo edgarpull filings 320193 --demo --limit 5 # by CIK instead of ticker edgarpull filings AAPL --demo --format html --out aapl.html # styled HTML report # 跨 ALL filers 的全文搜索 (EDGAR efts.sec.gov, 2001→至今)： edgarpull fulltext '"battery storage"' --forms 8-K --limit 10 edgarpull fulltext "artificial intelligence" --format html --out ai.html # live (真实的 SEC APIs，无需 key) — 请根据 SEC policy 提供一个 contact UA： edgarpull institutions AAPL --user-agent "Your Name you@example.com" edgarpull mcp # expose as an MCP server ``` ## 子命令 | 命令 | 返回结果 | 表格类型 | |----------------------------|--------------------------------------------|----------------------| | `filings ` | 任意类型的近期文件 | 全部 | | `insiders ` | 内部人士买入/卖出 | `4`, `4/A` | | `institutions `| 13F 机构持有人文件 | `13F-HR`, `13F-NT` | | `events ` | 重大事件（包含 8-K 项目代码） | `8-K`, `8-K/A` | | `fulltext ` | 跨**所有**提交者的全文搜索 | 任意 (`--forms`) | Flags：`--format table|json|html`、`--limit N`（`0` = 全部）、`--out FILE`、 `--demo`、`--user-agent STR`、`--sleep SECONDS`。`fulltext` 添加了 `--forms` 以 限制为逗号分隔的表格类型（例如 `--forms 8-K,10-K`）。 ## 内置演示场景 请参阅 [`demos/01-basic/SCENARIO.md`](demos/01-basic/SCENARIO.md)。该演示完全 离线运行，基于 [`edgarpull/sample_cache.json`](edgarpull/sample_cache.json)， 其数据结构映射了真实的 SEC `company_tickers.json` 和 submissions API。 ## 输出格式 - **Table**（默认） — 人类可读的终端摘要 - **JSON** — 用于 pipeline 的机器可读文件（带有直接的 EDGAR 存档 URL） - **HTML** (`--format html`) — 一个独立且带样式的报告，包含可点击的 指向 EDGAR 存档的 accession 链接；所有动态文本均经过 HTML 转义 ## 全文搜索 `edgarpull fulltext ` 查询 EDGAR 全文搜索 API （`efts.sec.gov`），该 API 索引了从 2001 年至今每位提交者的文件 **内容** — 作为对每个发行人 submissions feed 的补充。为短语添加引号以进行精确匹配，并使用 `--forms` 按表格类型缩小范围。它会发送相同的 描述性 `User-Agent`，并在离线时优雅地失败（使用 `--demo` 运行 以查看内置的测试数据）。 ## MCP server ``` { "command": "python", "args": ["-m", "edgarpull", "mcp"] } ``` 通过 stdio JSON-RPC 暴露 `filings`、`insiders`、`institutions` 和 `events` 作为 MCP 工具（每个都接受 `identifier`、可选的 `limit`、可选的 `demo`）。 基于标准库实现 — 无需 SDK。 ## 它如何融入 Cognis Neural Suite `edgarpull` 是 [Cognis Neural Suite](https://github.com/cognis-digital) 中的一个工具。 每个工具都提供了一个 MCP server，因此 [Cognis.Studio](https://cognis.studio) 代理 可以将它们作为限定范围内的能力进行调用。 ## 互操作性 `edgarpull` 可与 300 多个工具的 Cognis suite 组合 — JSON 输入/输出以及共享的 兼容 OpenAI 的 `/v1` 主干。请参阅 **[INTEROP.md](INTEROP.md)** 了解 suite 地图、组合模式和参考技术栈。 ## 集成 通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `edgarpull` 的发现转发至 STIS/MISP/Sigma/Splunk/Elastic/Slack/webhooks。请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。 ## 许可证 在 **Cognis Open Collaboration License (COCL) v1.0** 下开源可用 — 可免费用于个人、内部评估、研究和教育用途； **商业/生产环境使用需要获得许可证** (licensing@cognis.digital)。 请参阅 [LICENSE](LICENSE)。 ## 负责任地使用 EDGAR 数据是公开的。请遵守 SEC 的公平访问政策：发送描述性的 `User-Agent` 并保持合理的请求速率（edgarpull 默认会执行这两项操作）。 文件是监管披露信息，不构成投资建议。 ## 关于 **[Cognis Digital](https://cognis.digital)** — 美国 怀俄明州 · *让明天更美好：高级网络安全、AI 创新与区块链专业知识。*

标签：Python, SEC EDGAR, 命令控制, 数据采集, 文档结构分析, 无后门, 逆向工具, 量化金融, 金融数据