Valuein MCP Server - US SEC Financial Data

Valuein — 面向分析师、量化从业者和 AI Agent 的 SEC EDGAR 基本面数据

基于特定时点、不受存续偏差影响的 SEC 基本面数据——专为 AI Agent 打造，也足够安全，能让对 AI 持谨慎态度的机构放心。 每个数字都源自申报文件，并带有 fact_id；模型绝不会凭空编造数字。数据以 Parquet 流式传输，可通过 DuckDB 或自然语言查询，并能在每次运行时复现结果。

本仓库是 Valuein 数据平台的公开主页和发现中心，提供文档、示例、笔记本，以及供 AI Agent 查找我们的 MCP 注册清单。SDK、MCP 服务和数据管道的源代码位于专门的仓库中——这里是入口。

pip install "valuein-sdk>=7.1.0" # data for code
# or add this URL to any MCP-capable AI client:
# https://mcp.valuein.biz/mcp     # data for agents

---

本仓库包含什么

您想要……	前往
无需令牌，30 秒内试用 SDK	快速入门
查看我们提供的所有渠道	分发渠道
查看定价及各方案所包含的功能	方案与访问权限
了解为什么 AI Agent 在这里享有一等地位	专为 AI Agent 打造
连接 AI Agent（Claude、Copilot、ChatGPT、Cursor……）	面向 AI Agent 的 MCP
按角色（分析师、PM、量化从业者、创作者）设置 Workspace	docs/WORKSPACE_GUIDE.md
阅读数据模型	数据模型
按角色查找快速示例	按角色分类的示例
运行端到端 Python 示例	examples/python/
运行交互式笔记本（Colab）	examples/notebooks/
阅读方法论 / SLA / 合规信息	文档
报告数据错误或申请功能	支持与社区
贡献示例或笔记本	CONTRIBUTING.md

---

数据产品

直接来源于 SEC EDGAR，无幸存者偏差、符合时点要求的美国基本面数据。

• 自 1993 年以来所有向 SEC 报告的美国上市公司 — 涵盖 10-K、10-Q、8-K、20-F、40-F 及其修正文件，包含仍在交易和已退市的公司：每一起破产、合并和退市都保留在数据中
• 将原始 XBRL 标签规范化为规范的 standard_concept 名称，并提供物化财务比率（财年 + TTM）；未映射的标签归入 'Other'，而非丢弃
• Parquet 表 — 基本面、比率、指数成分、重述事件、含总回报指数的价格历史，以及 Institutional 级别的聪明资金和 Form ADV 顾问表
• Cloudflare R2 上的云端 Parquet — 使用 DuckDB 流式读取；无需设置数据库，也无需下载到本地
• 符合时点要求 — 每个事实均带有 filing_date 和毫秒精度的 accepted_at

每次快照的计数都会变化，因此本页不复制这些数据；请实时读取。client.manifest() 会返回快照 ID、last_updated 和你所用套餐的表；curl -s https://data.valuein.biz/v1/sample/manifest.json | jq .schema_version 会打印实时架构版本；https://data.valuein.biz/v1/plans 提供各套餐的覆盖范围和历史窗口；docs/data_catalog.md 列出规范概念和比率。

差异所在

属性	对你的意义
🕒 符合时点要求	filing_date <= trade_date 可消除前视偏差。accepted_at 为同日信号提供日内精度。
⚖️ 无幸存者偏差	已退市、破产和被收购的公司都会保留在每份快照中——你的回测看到的是市场当时看到的全部公司。
📊 标准化概念	每一行都包含原始 XBRL 标签（fact.concept）和规范名称（fact.standard_concept）。没有隐藏的映射表。
🔍 经注册会计师验证的目录	每个 standard_concept 都带有 review_confidence — 会计师确认其名称、报表归属和规则后为 1.0（之后即锁定；数据管道只会新增概念，绝不更改已验证的概念），暂定时为 0.7。筛选 review_confidence >= 1.0，即可获得分析师、量化研究人员和 AI 模型能够达成共识并用于训练的标签。
🚀 原生支持 DuckDB	通过 httpfs 对远程 Parquet 执行毫秒级分析。无需配置数据库。
🔁 仅追加重述	10-K/A 会新增一行，原始记录仍保留。可重建任意历史日期的报告时视图。
🧾 已测量并公布的准确性	根据已发布且注明出处的会计恒等式检查数学一致性，由 CI 把关，也可通过一条 DuckDB 命令自行复现。当前测量值见 docs/accuracy/baseline.json。
🔐 一个令牌，适用于所有渠道	SDK、MCP 服务和批量数据 API 使用同一个 Bearer 令牌进行身份验证。

---

专为 AI Agent 打造

Valuein 以 MCP 为先，且不绑定 Agent：同一套类型化工具接口可用于 Claude、Copilot、ChatGPT、Perplexity、Gemini、Grok、Cursor，或你自己的 LangGraph / CrewAI Agent。设计目标很简单——模型绝不生成数字。数字由工具生成，作为带有溯源标签的事实传递；模型只能围绕交给它的数字组织文字。

保证	实现方式
事实级溯源	工具返回的每个数字都带有 fact_id 和来源文件；verify_fact_lineage 可通过一次调用，将任意 fact_id 追溯到确切的 SEC 文件 URL。
零前视偏差	每个时间序列工具都接受 as_of_date，并按该日期重建信息集——与 Parquet 层为回测执行的 PIT 规范一致。
可复现运行	工具具有确定性且幂等：相同输入，相同输出。没有滚动窗口，也没有隐藏的“最新”数据。Agent 可以缓存、重试和重放；你可以在之后复现某次运行。
Agent 无关的状态	论点、主张、关注列表、信号和报告会在服务端跨会话、跨客户端持久保存——今天从 Claude 保存论点，明天就能从 Cursor 查看。
人类监督（HOTL）	修改数据和对外操作的工具操作会经过分阶段操作审批台账：Agent 提出操作，人类批准，决策则记录为不可变的审计条目。只读工具不会进入暂存流程。
受治理的托管运行	服务端托管的 Agent 运行会以 temperature 0 执行，并采用模型允许列表和破坏性工具剔除机制——实现可复现研究，而非即兴发挥。
分级业绩记录	保存的论点和主张会根据后续基本面和价格评分；发布后会形成公开、可验证的业绩记录——由你的 Agent 负责计分。

完整工具参考见 docs/MCP_TOOLS.md；面向 Agent 的运行时说明见 AGENTS.md。

---

分发渠道

同一数据集，通过四种方式交付，让你能在现有工作环境中使用。

渠道	受众	端点 / 安装
Python SDK	量化分析师、工程师、数据科学家	pip install valuein-sdk · PyPI
MCP 服务	AI Agent（Claude、Copilot、ChatGPT、Cursor、自定义 Agent）	https://mcp.valuein.biz/mcp · server.json
Web 仪表板	个人投资者、高管、非技术用户	valuein.biz
批量数据 API	B2B 合作伙伴、金融科技平台	https://data.valuein.biz · 联系我们

一个由 Stripe 签发的令牌即可解锁你所在套餐包含的所有渠道——不按渠道单独计费。

---

套餐与访问权限

定价和功能范围与 valuein.biz/pricing 保持一致——该网站是权威信息源，我们的结账流程会导向正确的 Stripe 产品。

套餐	股票范围	历史数据	获取方式
Sample	美国大盘基准股票范围	近年数据	免费，无需注册：pip install "valuein-sdk>=7.1.0"
Benchmark	美国大盘基准股票范围	完整历史数据	免费，注册
Pro	美国全部在市及已退市股票，基本面数据集	滚动的时点数据窗口	订阅
Institutional	同一股票范围 + smart-money 数据集（Form 3/4/5/144 内部人交易 + Form 13F/13D/13G 机构持仓）	可追溯至 1993 年的完整历史数据	订阅
Enterprise	协商确定 · 专属基础设施 · 扩大的再分发范围	定制	[email protected]

价格、股票范围规模、历史数据窗口和速率限制均为实时提供；请直接读取，而非使用副本：

curl -s https://data.valuein.biz/v1/plans \
  | jq '.plans[] | {displayName, priceUsd, universeSize, earliestYear, perMinute, perHour}'

每个套餐针对的客户顾虑都各不相同——Pro 取消基本面数据集在股票范围和历史数据方面的限制；Institutional 增加 smart-money 数据集（内部人交易 + 机构持仓）、可追溯至 1993 年的无限历史数据、申报事件 Webhook，以及在工作时间 SLA 下提供的商业再分发许可；Enterprise 则增加专属基础设施和定制合同。

按次付费（MPP）

触及速率或等级限制的自主 AI Agent，可以使用 Stripe 卡片令牌按请求付费，无需人工参与结账。付款使用 Machine Payment Protocol。Agent 报出价格，对卡片共享付款令牌扣款，然后使用已确认的令牌重试 MCP 调用。

目前仅支持银行卡付款。 付款前，请获取 https://api.valuein.biz/api/mpp/well-known，查看当前可用的网络。

类别	示例	计费方式
溯源 / 架构	describe_schema、verify_fact_lineage	免费
发现	search_companies、get_sec_filing_links	按实体
基本面	get_company_fundamentals、get_financial_ratios	按实体
分析	get_valuation_metrics、get_peer_comparables、compare_periods、get_capital_allocation_profile	按实体
计算	compute_dcf、forensic_audit、generate_dcf_xlsx、generate_research_brief_docx、generate_comps_xlsx	按次
筛选 / 全市场	screen_universe、get_pit_universe	按次
聪明钱（机构数据集）	get_insider_transactions、get_insider_sentiment、get_institutional_holdings、get_manager_portfolio、get_blockholders、get_top_holders、get_smart_money_flow	按实体

实时报价：curl -s https://data.valuein.biz/v1/plans | jq '.paygRates, .toolToMeter'（各工具对应的计费表及其美元费率）；402 会在授权任何操作前报出确切价格。按次付费（PAYG）的单次成本高于订阅，因此稳定持续使用的 Agent 几乎总是订阅 Pro 或 Institutional 更划算。完整的三步 MPP 流程请参阅 AGENTS.md。

整个模式——由 Agent 安全地为自己的数据付费——已整理成参考实现，见 docs/AGENT_ECONOMY_RAIL.md：两种实时授权模式（由人工授权有上限的预算，自动扣费并内联提供服务；或由持有钱包的 Agent 使用 MPP 按次付费）、为何这是安全的默认选项，以及可运行的演示——examples/python/agent_buys_its_own_data.py，它会发现支付通道，并免费读取实时报价。

各等级的速率限制来自 https://data.valuein.biz/v1/plans 中的 perMinute / perHour 字段（计划与访问权限下的 jq 命令会输出这些字段）。

---

快速入门（30 秒，无需令牌）

选择你已在使用的任一 Python 工作流——两者都能在任何虚拟环境中运行，并执行下方相同的代码：

# Option A — pip (universal, ships with Python)
python -m venv .venv && source .venv/bin/activate
pip install "valuein-sdk>=7.1.0"

# Option B — uv (10–100× faster; install from https://docs.astral.sh/uv/)
uv venv && source .venv/bin/activate
uv pip install "valuein-sdk>=7.1.0"

专为零摩擦而设计。 没有 VALUEIN_API_KEY？没关系。SDK 会检测到缺少令牌，并回退到 SAMPLE 数据集（S&P 500，最近 5 年）；边缘网关也会这样处理——不带 Authorization 标头时，GET /v1/{sp500,pro,full}/:table 会自动 302 重定向到 /v1/sample/:table。下面的代码片段可直接运行。

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.me())               # {plan, status, email, createdAt}
    print(client.manifest())         # snapshot id, last_updated, tables
    print(client.tables())           # tables your plan can read (they load on first use)

    df = client.run_query("""
        SELECT r.symbol, r.name, r.sector
        FROM   "references" r
        JOIN   index_membership im ON im.cik = r.cik
        WHERE  im.index_name = 'SP500'
          AND  im.removal_date IS NULL
          AND  r.is_active = TRUE
        ORDER  BY r.name
        LIMIT  10
    """)
    print(df)

这是对实时 S&P 500 样例的真实查询。只有在需要完整全市场数据或完整历史数据时才添加令牌：

# optional — the sample tier works without a key
export VALUEIN_API_KEY="your_token_here"      # or add this line to a .env file

现在，相同代码会读取你所在等级的数据——无需其他更改。ValueinClient() 会从环境变量读取 VALUEIN_API_KEY，或从工作目录开始向上查找并读取找到的第一个 .env 文件；无论环境中有什么内容，ValueinClient(api_key="") 都会强制使用免费样例。本仓库中的 curl 和 DuckDB 示例都使用 $VALUEIN_TOKEN 保存同一个令牌：它只是该令牌的 Shell 变量名，SDK 不会读取这个变量。

生产环境模式——上下文管理器、类型化错误、预构建模板

from valuein_sdk import (
    ValueinClient,
    ValueinAuthError,
    ValueinPlanError,
    ValueinRateLimitError,
    ValueinAPIError,
    ValueinError,
)

# Two-level try/except is intentional:
#   outer = init errors raised by ValueinClient.__enter__ (auth, manifest, 503)
#   inner = per-query errors raised by run_query / run_template (rate-limit,
#           plan denial, bad SQL). Each level dispatches by exception type so
#           you can act on the right cause — exit on auth, sleep on rate-limit,
#           upsell on plan, log + skip on a single bad row.

try:
    with ValueinClient() as client:
        try:
            # 1) Build & run a raw SQL query → pandas DataFrame
            sql = "SELECT COUNT(cik) FROM entity"
            result = client.run_query(sql)
            print(result)

            # 2) Run a named SQL template with kwargs (the SDK quotes safely)
            df = client.run_template(
                "fundamentals_by_ticker",
                ticker="AAPL",
                start_date="2020-01-01",
                end_date="2024-12-31",
                form_types=["10-K", "10-Q"],
                metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
            )
            print(df.head())
        except ValueinPlanError:
            print("This query needs a higher plan — see valuein.biz/pricing.")
        except ValueinRateLimitError as e:
            print(f"Rate limited; retry in {e.retry_after}s.")
        except ValueinError as ve:
            # Catch-all for any other per-query failure (validation, bad SQL, etc.)
            print(f"Query failed: {ve}")
except ValueinAuthError:
    raise SystemExit("Token missing or expired — set VALUEIN_API_KEY.")
except ValueinAPIError as e:
    print(f"Gateway error during init (HTTP {e.status_code}).")
except Exception as e:
    print(f"Initialization failed: {e}")

SDK 附带适用于常见筛选、比率和时点（PIT）回测的命名 SQL 模板。列出已安装版本包含的模板：

from valuein_sdk import ValueinClient
with ValueinClient() as c:
    print(c.list_templates())

财报与筛选，每个数字都可追溯到其备案文件

from valuein_sdk import ValueinClient

with ValueinClient() as client:  # no token: free sample tier
    fin = client.financials("AAPL")  # income, balance sheet, cash flow as known at as_of
    print(fin.income)
    print(fin.lineage.head())  # each number's fact_id, filing accession and acceptance time

    screen = client.screen("2024-06-28", universe="SP500").where("return_on_equity > 0.15")
    print(screen.top(10, by="gpoa").to_pandas().summary())  # members on that date, delisted included

主要动词

你想要……	调用	方案
基于时点视图执行原始 SQL	client.run_query(sql)、client.duckdb()	全部
查看截至某日已知的报表	client.financials("AAPL", freq="FY")（"Q"、"TTM"；.as_filed()）	全部
查看过去某日的指数成分股（包括已退市成分股）	client.universe(dates=[...])、client.pit_universe("2022-06-30")	全部
查看这些日期已知的比率	client.signal_panel(members, ratios=[...], include_price=False)	全部
进行时点筛选	client.screen("2024-06-28").where("return_on_equity > 0.15")	全部（价格字段：Pro）
执行包含可追溯输入项的两阶段 DCF	client.dcf("MSFT", stage1_growth_rate=0.08)	全部
查看同业和重述数据	client.peers("MSFT", n=5)、client.restatements(ticker="MPWR")	全部
执行分位数回测、查看版本并统计试验次数	client.factor_backtest(...)、client.restatement_impact(...)、client.study(...)	日线数据：Pro 和 Institutional
镜像或固定数据	client.sync(path)、ValueinClient.from_bundle(path)	受方案限制

from valuein_sdk import ValueinClient

client = ValueinClient()  # reads VALUEIN_API_KEY; no key = free sample

# S&P 500 members on a past date, later-removed companies included
members = client.universe(dates=["2022-06-30"])

# Return on equity as it was known on that date
panel = client.signal_panel(members, ratios=["return_on_equity"], include_price=False)
print(panel.head())

# A DCF with your growth assumption; every input traced to its filing
dcf = client.dcf("MSFT", stage1_growth_rate=0.08)
print(dcf.value_per_share, dcf.price, dcf.upside)

# Numbers a later filing changed, with both filings
print(client.restatements(ticker="MPWR").head())

同一个客户端可运行带有分析报告的因子回测、比较某个因子在时点数据、申报时数据和重述数据上的表现、统计你的试验次数（Deflated Sharpe），并镜像或固定数据快照：docs/SDK_USE_CASES.md。

参考文档：docs/QUERY_COOKBOOK.md（DuckDB 示例）· docs/data_catalog.md（权威概念）· PyPI README（SDK 快速入门）。

---

按角色分类的示例

以下链接均指向 examples/python/ 中可运行的脚本；大多数脚本都配有 examples/notebooks/ 中的笔记本。Sample 层级可运行所有示例，Institutional 智能资金筛选除外——无需令牌，无需注册。

你的角色是……	从这里开始	你将看到
金融分析师	financial_analysis.py	单只股票的营收趋势、利润率变化和同业比较
量化研究员	factor_backtest.py	包含交易成本和 IC 的时点、无幸存者偏差分位数回测
投资组合经理	entity_screening.py	筛选过去某日的 S&P 500 成分股，包括后来被移除的成分股
法证分析师	restatement_radar.py	每项重述数据、披露方式，以及用于核实的两份申报文件
资产管理人	survivorship_bias.py	量化幸存者偏差对收益的夸大影响
估值建模人员	dcf_inputs.py	client.dcf()：使用你设定的假设进行两阶段 DCF，追溯每项输入所依据的申报文件
审计师 / 合规人员	filing_provenance.py	每份申报文件对应的 SEC EDGAR 可点击链接——打开 iXBRL 查看器，查看某个数字所依据的确切源文件
数据工程师	production_service.py	定时将时点数据提取到 Parquet：限制、日志记录、退出代码
首次使用者	getting_started.py	方案检查、股票代码 → CIK、首次基本面查询
构建 AI Agent	面向 AI Agent 的 MCP	使用自然语言——无需 SDK

运行任意示例：

# Sample tier — works without a token
python examples/python/getting_started.py

# Paid tier
VALUEIN_API_KEY=xxx python examples/python/factor_backtest.py

---

数据模型

完整架构见 docs/schema.json（机器可读）和 docs/data_catalog.md（规范概念名称）。所有套餐等级都会读取以下核心表（包括 industry_classification，即时点 SIC 分类）；付费套餐还会读取 filing_registrant；Institutional 套餐会额外读取智能资金相关表（insider_party / insider_filing / insider_transaction / insider_ownership / insider_footnote / insider_ownership_purpose / institutional_filing / institutional_holding / institutional_other_manager）以及 Form ADV 顾问表（investment_adviser、investment_adviser_private_fund）。client.tables() 会列出你的套餐读取的内容；运行 curl -s https://data.valuein.biz/v1/sample/manifest.json | jq .schema_version 可打印当前架构版本。

表	内容	重要性
references	从这里开始。 将 entity 与 security 平铺连接。每种证券一行，包含 cik、is_active、行业、交易所和 FIGI。如需查询成分股信息，请按 cik = cik 连接 index_membership。	一次扫描即可获取跨公司的元数据；指数成分股信息保留在单独的表中，以便保留历史纳入和剔除记录。
entity	公司元数据 — CIK、名称、行业、SIC、状态、财年年末	法律实体维度。
security	股票代码历史记录（SCD Type 2，使用 valid_from / valid_to）	用于解析历史股票代码、股份类别和交易所。
filing	申报元数据 — accession_id、filing_date、report_date、表格类型、修订标记	“何时提交了什么”的维度。
fact	标准化财务事实 — 每行同时包含原始 concept 和规范化的 standard_concept	财务数据。通过 accepted_at 确保时间点（PIT）安全。
filing_registrant	某个 accession 的所有申报人（付费层级提供；免费样本清单中不包含）	filing 对每个 accession_id 只保留一行，因此合并申报的共同申报人文件只会显示在一个 CIK 下。按 accession_id 将 filing_registrant 连接到 filing，即可列出一家公司的申报，包括合并申报。
ratio	按申报计算的财务比率	无需编写 SQL — 利润率、回报率、杠杆率和效率指标均已预先计算。
taxonomy_guide	美国 GAAP 分类体系指南	每个 standard_concept 的定义。
index_membership	以 cik 为键的指数成分股，采用半开区间 effective_date / removal_date。SP500 的无幸存者偏差数据可追溯至 1996 年（confidence='high'）— 包含实际纳入和剔除记录，包括早已退市的申报人。RUSSELL1000 / RUSSELL2000 / RUSSELL3000 可追溯至 2000-09-30（confidence='medium'，source='fund_holdings'）— 根据跟踪各指数的大型基金公开披露的持仓重建，因此基金只是指数的代理，而非指数的定义依据；加入或退出日期的精度取决于观察间隔（截至 2006 年，每年约一至四次；自 2007 年起按月观察）。根据指数提供商公布的重新调整名单进行评估；我们使用这些名单进行衡量，但绝不再分发：召回率 96.5–98.3%，精确率 93.6–98.6%。2000-09-30 之前没有 Russell 数据，且 2016-12-30 至 2017-07-31 之间没有持仓观察记录。	重建历史日期的 S&P 500 或 Russell 指数。根据 confidence 分支处理 — medium 表示近似值，而非权威数据。按 references.cik = index_membership.cik 连接以获取公司元数据。
industry_classification	按时间点记录的 SEC SIC 分类：每家公司和每段 SIC 有一行，包含 4 位数的 sic_code（子行业）、sic_industry_group、sic_major_group、sic_division、sector 和 industry。valid_from 是首次显示该代码的申报被 SEC 接受的时间；valid_to 为排他边界，NULL = 当前有效。数据取自每份申报 SEC 页眉中的 SIC。所有层级均提供，且公司范围与 references 相同。不含 GICS（需授权）：4 位数 SIC 是公开发布的最细层级。	references.sector / industry / sic_code 是当前值，并标记在所有历史记录上。若要查询“公司在日期 t 属于什么行业”，请筛选 valid_from <= t AND (valid_to IS NULL OR t < valid_to)。公司首次出现相关证据之前没有记录。
standard_concept	规范概念目录本身 — 名称、报表、映射规则、CPA 审核状态	fact.standard_concept 背后的事实依据。
stock_price	按实体提供的粗粒度价格序列 — 每个财年期末和每个月末各有一个收盘价，每行均包含 total_return_index（所有层级）	适用于任何层级的估值与股价对比分析，以及按月再平衡的回测：两个按月末记录的 tri_b / tri_a - 1，即该时段持有者的总回报，包含股息。
insider_footnote · insider_ownership_purpose · institutional_other_manager	仅限机构层级 — Form 3/4/5 脚注（例如 10b5-1 计划或加权平均价格背后的依据）、Schedule 13D 的 Item 4“交易目的”原文，以及 13F 管理人名单	交易、持股或合并 13F 背后的文本；按 accession_id 将 insider_footnote 和 insider_ownership_purpose 连接到 insider_filing，并将 institutional_other_manager 连接到 institutional_filing。
stock_price_daily	仅限 Institutional 和 Pro — 按上市证券提供完整的每日 OHLCV 行情序列，包含 total_return_index 和原始公司行动因子（div_cash、split_factor）	可安全用于回测的价格数据 — 与基本面数据搭配，用于计算 PIT 估值倍数。计算总回报时请使用 total_return_index：该指数采用向前复合，因此与向后调整的序列不同，后续拆股不会改写此前的数据。adjusted_close 直接传递自供应商，在绝大多数行情记录中为 null。粒度为每种证券每天一行 — 添加 WHERE is_primary_listing 可获取每家公司一行。价格属于授权市场数据，并非 EDGAR 数据，因此不受基本面数据始于 1993 年的限制：1993 年没有行情数据，每种证券的最早行情各不相同，均始于 1994 年或之后。

直接读取 Parquet 文件

表格是通过 HTTPS 提供的纯 Parquet 文件。免费样例无需令牌，也无需文件扩展名；付费层级需发送 Bearer 令牌。对付费路由发出的无令牌请求会重定向（302）到样例副本。

# Free sample — no token, no card
curl -sL https://data.valuein.biz/v1/sample/entity -o entity.parquet

# Paid tiers: sp500 | pro | full — the same Bearer token as the SDK, kept here in $VALUEIN_TOKEN
curl -sL -H "Authorization: Bearer $VALUEIN_TOKEN" https://data.valuein.biz/v1/pro/references -o references.parquet

# One company's partition of a large table (10-digit CIK)
curl -sL -H "Authorization: Bearer $VALUEIN_TOKEN" https://data.valuein.biz/v1/pro/fact/0000320193.parquet -o aapl_fact.parquet

https://data.valuein.biz/v1/sample/manifest.json 列出样例的表格和架构版本。

日期列——何时使用哪一列

列	表	用途
report_date / period_end	filing / fact	与财年日历对齐
filing_date	filing	PIT 回测筛选条件——SEC 收到文件的日期
accepted_at	fact、filing、ratio（以及 smart-money 和 price 表）	用于日内研究的毫秒精度 PIT

对于任何跨公司回测，始终按 filing_date <= trade_date 筛选。按 report_date 筛选会引入前视偏差。

在 DuckDB 中很实用的三种模式

1. 从 references 开始（跨公司筛选只需一次联接；成员资格在 index_membership 中）：

SELECT r.symbol, r.name, r.sector
FROM   "references" r
JOIN   index_membership im ON im.cik = r.cik
WHERE  im.index_name = 'SP500'
  AND  im.removal_date IS NULL          -- current member
  AND  r.is_active     = TRUE
  AND  r.sector ILIKE '%technology%'

2. 使用 LATERAL 获取每家公司最新的申报文件（以下为摘录：将此联接添加到模式 1 的查询中，该查询定义了 r）：

JOIN LATERAL (
    SELECT accession_id, filing_date FROM filing
    WHERE  entity_id = r.cik AND form_type = '10-K'
    ORDER  BY filing_date DESC LIMIT 1
) f ON TRUE

3. 在一次 fact 扫描中透视多个概念：

SELECT
    MAX(CASE WHEN standard_concept = 'TotalRevenue'       THEN numeric_value END) AS revenue,
    MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END) AS equity
FROM   fact
WHERE  standard_concept IN ('TotalRevenue', 'StockholdersEquity')
GROUP  BY accession_id

季度现金流：使用 COALESCE(derived_quarterly_value, numeric_value)——Q2/Q3 的 10-Q 会报告年初至今的数据；此列用于提取单季度数据。申报公司的 CAPEX 符号可能不同——始终使用 ABS(capex)。

完整的操作指南——包括示例、反模式和端到端因子筛选——见 docs/QUERY_COOKBOOK.md。

标准概念名称

使用 'TotalRevenue'、'NetIncome'、'OperatingCashFlow'、'CAPEX'、'StockholdersEquity' 等标准名称查询 fact.standard_concept，不要使用原始 XBRL 标签（'Revenues'、'NetIncomeLoss'、'Assets'）。完整列表见 docs/data_catalog.md，机器可读版本见 docs/data_catalog.json。

---

面向 AI Agent 的 MCP

Valuein 提供远程、原生协议的 Model Context Protocol 服务，让任何支持 MCP 的 Agent（Claude、Copilot、ChatGPT、Cursor 或自定义 Agent）都能回答基本面问题，并保留持久、可审计的研究状态，无需编写代码。

• 端点： https://mcp.valuein.biz/mcp（Streamable HTTP，MCP 规范 2025-11-25）
• 身份验证： Authorization: Bearer <your_api_token>——与 SDK 和批量数据 API 使用相同的令牌
• 清单： server.json——已作为 io.github.valuein/mcp-sec-edgar 发布至 registry.modelcontextprotocol.io
• 参考文档： docs/MCP_TOOLS.md——介绍每个工具、每项输入、每个层级门槛，以及错误和分页结果的显示方式（根据实时清单生成）

工具

服务提供 127 个实时工具，以及 39 个 Agent 工作流提示词（两个旗舰级跨角色简报——equity_research_brief 和 screen_and_shortlist——以及面向分析师、PM、量化、ratio、smart-money 和工作流角色的专用链），还有 3 个数据资源（schema://{table}、reference://sp500、pricing://current）。层级限制在数据层执行——Sample / Benchmark 令牌可查看 Sample / Benchmark 数据切片（S&P 500 成分股）；Pro 可访问覆盖 15 年时间窗口（2011 年至今）的全部 19,000 多个实体；Institutional 可解锁 smart-money 工具（Form 3 / 4 / 5 / 144 的内幕交易，以及 Form 13F / 13D / 13G 的机构持仓）、可追溯至 1993 年的无限历史数据、申报事件 webhook，以及商业再分发许可。

发现与架构

工具	功能
search_companies	查找股票代码、名称和 CIK；按行业、S&P 500、活跃状态筛选
describe_schema	返回任意表格的列、类型和说明
get_pit_universe	查询任意历史 as_of_date 的无生存者偏差成员资格（S&P 500、Russell 1000 / 2000 / 3000、某个行业或整个全集），结果分页
基本面与比率

工具	功能
get_company_fundamentals	按股票代码和期间获取损益表、资产负债表及现金流量表
get_financial_ratios	按类别获取利润率、回报率、杠杆、效率和 FCF 收益率
get_valuation_metrics	查看公司的交易估值及无需参数的参考值；内在价值由 compute_dcf 根据你提供的假设计算
get_capital_allocation_profile	资本支出强度、回购收益率和股息历史

申报文件与溯源

工具	功能
get_sec_filing_links	提供 10-K / 10-Q / 8-K / 20-F / 40-F 的 EDGAR 直达链接
verify_fact_lineage	将任意数值追溯至其来源的具体申报文件及 accession ID

比较与分析

工具	功能
compare_periods	跨期间并排比较，并标记重大变化
get_peer_comparables	按行业提供同行集合及可比指标
screen_universe	对整个市场进行多因子筛选

批量数据

工具	功能
get_compute_ready_stream	签发有时效限制的下载 URL，供直接流式传输 Parquet（绕过网关）

聪明钱 — 机构级及以上

聪明钱工具包用一个 Valuein 令牌取代 Bloomberg 的 INSIDER<GO> / OWNER<GO> / HDS<GO> 筛选界面。每个工具读取按 CIK 分区的 Parquet 文件，并返回包含 lineage 信封的结构化行，支持一键验证 SEC 信息。

工具	功能
get_insider_transactions	按发行方提供 Form 3 / 4 / 5 / 144 的明细行，并与 insider_party 关联以获取姓名和角色
get_institutional_holdings	提供单个发行方的 Form 13F 主要持有人，以及 HHI 集中度和 13F 延迟过时标记
get_manager_portfolio	提供 Form 13F 申报人的完整投资组合及季度环比变化（新建 / 增持 / 减持 / 清仓）
get_blockholders	提供 SC 13D / 13G，并包含一等 going_active 标记（13G→13D = 控制权变更信号）
get_insider_sentiment · get_top_holders · get_smart_money_flow	按发行方汇总内部人士买卖信号、最大持有人和机构净流入

持久化、与 Agent 无关的研究状态（适用于所有 MCP 客户端）

研究对象保存在服务端，并与你的令牌关联——可从一个 AI 客户端保存，再从另一个客户端读取，之后进行评分。

系列	工具（示例）	功能
投资论点与主张	save_thesis、save_claim、score_thesis_outcome、score_claim	带时间戳的判断及绑定来源的主张，可依据后续基本面和价格自动评分
观察列表与信号	save_watchlist、create_signal、list_signal_inbox	持续监控价格变动、基本面变化和申报文件，并发送到电子邮件、webhook、仪表板收件箱，或触发固定 Agent 团队的 agent_run
报告	create_report、render_report、save_freeform_report	持久化、带版本的研究成果，支持品牌化 md/docx 导出
延后处理与规则	schedule_task、create_rule、test_rule	“30 天后重新检查 AAPL 利润率” → 真正的定时重新运行；触发器→操作规则（信号触发、收件箱项目、任务唤醒、定时触发）
审批（HOTL）	stage_action、list_pending_approvals、approve_staged_action	修改性 / 破坏性操作会暂存，等待人工审批，并生成不可更改的审计记录
回测	run_backtest、get_pit_valuation_ratios、get_price_history	有界 PIT 因子网格，以及适用于回测的任意历史日期估值倍数
简报	get_morning_brief、list_agent_runs	从任意 MCP 客户端读取每日简报和托管运行历史

公开发布 — 免费积累声誉（适用于任何已登录的方案） 将已保存的研究发布到公开的 @handle 个人主页——免费建立公开的业绩记录和声誉。报告会变成可分享的 /r/[slug] 页面，可通过关键词目录搜索发现（暂不支持语义搜索）；论文和主张也可免费切换 publish / unpublish 可见状态。这是发布，不是出售。

工具	功能
publish_report	将已保存的报告发布到你的公开个人主页（@handle），生成可分享的 /r/[slug] 页面
unpublish_report	将之前发布的报告重新设为私密
search_reports	按股票代码、作者或关键词搜索公开报告目录（关键词目录搜索）
publish_thesis / unpublish_thesis	在你的个人主页上切换已保存论文的公开 / 私密状态——与 publish_report 保持一致
publish_claim / unpublish_claim	在你的个人主页上切换已保存主张的公开 / 私密状态——与 publish_report 保持一致

在 Claude Desktop 中配置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "valuein": {
      "url": "https://mcp.valuein.biz/mcp",
      "headers": { "Authorization": "Bearer YOUR_VALUEIN_API_KEY" }
    }
  }
}

对于任何支持 Streamable HTTP 远程服务的 MCP 客户端，使用相同的 URL 和 Bearer token 即可——包括 Copilot、ChatGPT、Cursor，以及你自己的 LangGraph / CrewAI Agent。

---

此仓库中的示例

每个脚本和笔记本都通过 PyPI 上发布的 SDK 运行。Sample 套餐无需令牌即可运行；添加 VALUEIN_API_KEY 即可使用付费套餐。

完整学习路径，以及每个项目适合的对象和所需套餐：examples/README.md。

Python 脚本（examples/python/）

脚本	难度	内容
getting_started.py	初级	套餐、快照、股票代码 → CIK、年度收入和净收入
financial_analysis.py	初级	损益表和利润率、单季度现金流、同行比率
pit_backtest.py	中级	同一查询在两个 as_of 日期下会得到两个答案（真实的重述）
entity_screening.py	中级	根据过去某个日期的情况筛选标普 500 指数成分股
survivorship_bias.py	中级	真实收益与仅基于存续公司的等权收益
factor_backtest.py	高级	投资范围 → 信号 → 远期收益 → 计入成本的分位数回测
pit_factor_dataset.py	高级	将无幸存者偏差的时点因子文件导出为 Parquet 和 CSV
price_total_return.py	中级	拆股和股息对收益的影响；Pro 套餐的日频辅助工具
restatement_radar.py	中级	披露构成、一项已验证修订、近期 Item 4.02 修订
smart_money_screen.py	中级	内部人交易、13F 持有人、大额持有人（Institutional）
filing_provenance.py	初级	一个数字、其重新计算得出的 fact_id，以及对应 SEC 文件的链接
dcf_inputs.py	中级	使用可追溯输入的 client.dcf()、每股价值、隐含增长率
production_service.py	高级	将定时的时点数据提取为 Parquet，并设置限制、日志和退出代码
agent_buys_its_own_data.py	高级	Agent 发现支付渠道并读取实时价格报价

Jupyter 笔记本（examples/notebooks/）

使用免费 Sample 套餐运行，并连同运行结果一并提交。

笔记本	在 Colab 中打开
快速入门
截至某日期的基本面数据
无幸存者偏差的筛选
时点因子回测
价格与总回报
重述
聪明钱（机构）
验证一个数值
通过 AI 助手使用
DCF 估值
Piotroski F-score 筛选
盈利质量
行业比较
重述 Alpha
资本配置
申报延迟

---

文档

docs/ 中的所有内容都与生产数据和 PyPI 上的 SDK 保持同步。

文档	内容
docs/WORKSPACE_GUIDE.md	工作区欢迎指南——15 分钟完成设置，并为不同角色（分析师、PM、量化分析师、创作者）提供每日／每周／每月工作手册
docs/METHODOLOGY.md	数据来源、PIT 架构、重述处理、XBRL 规范化、DCF 模型
docs/accuracy/	准确性证明——衡量的真实数据源位于 docs/accuracy/baseline.json（当前快照：查看 baseline.json，了解现代时期（≥2010 年）S&P 500 财年申报文件的最新数据），可引用 FactSet PIT / FASB ASC / Penman，并可通过 duckdb -c ".read scripts/accuracy/accuracy_check.sql" 重现
docs/QUERY_COOKBOOK.md	可复制粘贴的 DuckDB 示例——LATERAL、数据透视、PIT、因子筛选
docs/SDK_USE_CASES.md	最常见的 SDK 使用场景，按从简单到高级排列，每项都链接到一个在免费层执行的 notebook
docs/MCP_TOOLS.md	每个 MCP 工具的参考文档——输入、输出字段、层级限制、错误和分页（由实时清单生成）
docs/data_catalog.md	标准 standard_concept 名称和定义
docs/DATA_CATALOG.xlsx	同一目录的工作簿版本——列、类型、示例值
docs/data_catalog.json	机器可读目录（供 SDK 元数据和文档网站使用）
docs/schema.json	机器可读的表和列架构
docs/COMPLIANCE_AND_DDQ.md	数据来源、MNPI 政策、PIT 完整性、安全性、SLA 摘要
docs/SLA.md	正常运行时间目标、数据新鲜度、支持响应时间、SLA 补偿

---

支持与社区

GitHub Issues 是主要支持渠道。请选择合适的模板——系统会将问题正确分流，以便更快处理。

我想……	打开
报告不正确或可疑的数据	数据质量报告
请求功能、概念或数据集	功能请求
报告服务中断或性能下降	服务中断
提出一般问题	问答
私下报告安全问题	请参阅 SECURITY.md
获取一般帮助	请参阅 SUPPORT.md

对于私人或合同相关事宜（DPA、采购、DDQ、企业 SLA）：[email protected]。

欢迎贡献示例、改进 notebook、修正文档和查询示例。有关工作流程，请参阅 CONTRIBUTING.md；有关社区规范，请参阅 CODE_OF_CONDUCT.md。

---

商标

S&P 500® 是 Standard & Poor's Financial Services LLC 的注册商标；Russell® 指数是 FTSE Russell 的商标；Nasdaq-100® 是 Nasdaq, Inc. 的商标。Valuein 与任何指数提供商均无关联，也未获其赞助、认可或授权。指数成分根据公开的 SEC 申报文件和公开的基金披露信息独立重建。

许可证与披露

本仓库中的代码和文档根据 Apache 2.0 许可。归属信息请参阅 NOTICE。

所有等级中的 Valuein 数据（包括免费样本）均根据单独的 Valuein Data Licence 获得许可：可供内部使用和研究，可在注明出处的情况下引用少量内容；未经书面协议，不得重新分发、转售或用于模型训练。

本仓库仅供研究和教育用途。本内容不构成投资建议。 本仓库不对其适用于任何特定的交易、投资或监管用途作出明示或暗示的保证。