Valuein — SEC EDGAR fundamentals for analysts, quants, and AI agents

Point-in-time, survivorship-free SEC fundamentals — built for AI agents, safe enough for institutions that fear AI. Every number is born in a filing and carries a fact_id; the model never mints a digit. Streamed as Parquet, queried with DuckDB or natural language, reproducible run to run.

This repository is the public home and discovery hub for the Valuein data platform. It hosts the documentation, examples, notebooks, and the MCP registry manifest used by AI agents to find us. Source code for the SDK, MCP server, and data pipeline lives in dedicated repositories — this is the front door.

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

What's in here

The data product

Survivorship-bias-free, point-in-time US fundamentals sourced directly from SEC EDGAR.

• 12M+ filings — 10-K, 10-Q, 8-K, 20-F, 40-F, and amendments since 1993
• 111M+ standardized facts across 19,000+ US public companies — including every bankruptcy, merger, and delisting since 1993
• 11,966 raw XBRL tags normalized to 292 canonical standard_concept values plus 164 materialized financial ratios (FY + TTM); unmapped tags are exposed under 'Other' rather than dropped
• 20 Parquet tables — 14 core (fundamentals, ratios, valuations, index membership, daily OHLCV price history with adjusted close) + 6 smart-money tables (Institutional tier)
• Cloud Parquet on Cloudflare R2 — stream with DuckDB; no database setup, no local downloads
• PIT-correct — every fact carries filing_date and millisecond-precision accepted_at

Why it's different

Built for AI agents

Valuein is MCP-first and agent-agnostic: the same typed tool surface works in Claude, Copilot, ChatGPT, Perplexity, Gemini, Grok, Cursor, or your own LangGraph / CrewAI agent. The design goal is simple — the model never mints a number. Numbers are born in tools, carried as provenance-tagged facts, and the model is only allowed to arrange words around figures it was handed.

The full tool reference is in docs/MCP_TOOLS.md; agent-facing runtime instructions are in AGENTS.md.

Distribution channels

The same dataset, delivered four ways so it lands where you already work.

A single Stripe-issued token unlocks every channel at your tier — no per-channel billing.

Plans & access

Pricing and feature scope are mirrored from valuein.biz/pricing — the website is the source of truth and our checkout flow routes to the correct Stripe product.

Each tier removes a different buyer objection — Pro removes the universe + history limits on the fundamentals dataset; Institutional adds the smart-money dataset (insider transactions + institutional ownership), unlimited history back to 1993, filing-event webhooks, and a commercial redistribution license under a business-hours SLA; Enterprise adds dedicated infrastructure and bespoke contracts.

Pay-per-call (MPP)

Autonomous AI agents that hit a rate or tier limit can pay per request using Stripe card tokens — no human checkout loop. Payment uses the Machine Payment Protocol. The agent quotes a price, charges a card Shared Payment Token, then retries the MCP call with the confirmed token.

Payment is card-only today. Fetch https://api.valuein.biz/api/mpp/well-known to see which networks are live before paying.

PAYG is priced at 5× the subscription-equivalent rate — steady-state agent usage is almost always cheaper with a Pro or Institutional subscription. Daily spend caps exist per token as abuse protection; caps are raisable on request. See AGENTS.md for the full three-step MPP flow.

The whole pattern — an agent that buys its own data, safely — is written up as a reference implementation in docs/AGENT_ECONOMY_RAIL.md: the two live consent models (a human-authorized bounded budget that auto-charges and serves inline; or per-call MPP for wallet-holding agents), why it's the safe default, and a runnable demo — examples/python/agent_buys_its_own_data.py — that discovers the rail and reads back a live quote for free.

Rate limits per tier (canonical at https://data.valuein.biz/v1/plans):

Quickstart (30 seconds, no token)

Pick whichever Python workflow you already use — both work in any virtual environment, and both run the same code below:

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

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

Zero-friction by design. No VALUEIN_API_KEY? No problem. The SDK detects the missing token and falls back to the SAMPLE dataset (S&P 500, last 5 years); the edge gateway does the same — GET /v1/{sp500,pro,full}/:table with no Authorization header automatically 302-redirects to /v1/sample/:table. The snippet below runs as-is.

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())           # currently loaded tables

    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)

That's a real query against the live S&P 500 sample. Add a token only when you need full universe or full history:

# optional — sample tier works without a key
echo 'VALUEIN_API_KEY="your_token_here"' >> .env

The same code now reads from your tier — no other changes.

Production pattern — context manager, typed errors, pre-built templates

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}")

The SDK ships 60 named SQL templates for the most common screens, ratios, and PIT backtests. List them:

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

Reference: docs/QUERY_COOKBOOK.md (DuckDB recipes) · docs/data_catalog.md (canonical concepts) · PyPI README (SDK quickstart).

Recipes by role

Every link below points to a runnable script in examples/python/ (mirror notebook in examples/notebooks/). The Sample tier runs every example — no token, no signup.

Run any of them:

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

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

Data model

Full schema in docs/schema.json (machine-readable) and docs/data_catalog.md (canonical concept names). The snapshot ships 20 Parquet tables — the core tables below plus 6 smart-money tables on the Institutional tier (insider_party / insider_filing / insider_transaction / institutional_filing / institutional_holding / insider_ownership).

Date columns — which to use when

For any cross-company backtest, always filter by filing_date <= trade_date. Filtering by report_date introduces look-ahead bias.

Three patterns that pay off in DuckDB

1. Start from references (one join for cross-company filters; membership is in 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 for the latest filing per company:

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. Pivot multiple concepts in one fact scan:

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

Quarterly cash flows: use COALESCE(derived_quarterly_value, numeric_value) — Q2/Q3 10-Qs report YTD; this column isolates the single quarter. CAPEX sign varies by filer — always ABS(capex).

The full cookbook — 20 recipes, 8 anti-patterns, end-to-end factor screen — lives in docs/QUERY_COOKBOOK.md.

Canonical concept names

Query fact.standard_concept with canonical names like 'TotalRevenue', 'NetIncome', 'OperatingCashFlow', 'CAPEX', 'StockholdersEquity' — not raw XBRL tags ('Revenues', 'NetIncomeLoss', 'Assets'). The full list lives in docs/data_catalog.md and the machine-readable form is in docs/data_catalog.json.

MCP for AI agents

Valuein ships a remote, protocol-native Model Context Protocol server so any MCP-capable agent (Claude, Copilot, ChatGPT, Cursor, custom) can answer fundamentals questions — and keep persistent, auditable research state — without writing code.

• Endpoint: https://mcp.valuein.biz/mcp (Streamable HTTP, MCP spec 2025-11-25)
• Auth: Authorization: Bearer <your_api_token> — same token as the SDK and bulk-data API
• Manifest: server.json — published to registry.modelcontextprotocol.io as io.github.valuein/mcp-sec-edgar
• Reference: docs/MCP_TOOLS.md — every tool, every parameter, every tier gate

Tools

The server exposes 118 live tools, plus 39 agentic SOP prompts (two flagship cross-persona briefs — equity_research_brief and screen_and_shortlist — plus specialised chains for analyst, PM, quant, ratio, smart-money, and workflow personas) and 3 data resources (schema://{table}, reference://sp500, pricing://current). Tier gating happens at the data layer — Sample / Free tokens see Sample / S&P 500 data; Pro sees the full 19,000+-entity universe with a 15-year point-in-time window (2011 → present); Institutional unlocks the smart-money tools (insider transactions on Forms 3 / 4 / 5 / 144 + institutional ownership on Forms 13F / 13D / 13G), unlimited history back to 1993, filing-event webhooks, and the commercial redistribution license.

Discovery & schema

Fundamentals & ratios

Filings & lineage

Comparison & analytics

Bulk data

Smart money — Institutional tier and above

The smart-money bundle replaces Bloomberg's INSIDER<GO> / OWNER<GO> / HDS<GO> screens with a single Valuein token. Each tool reads a per-CIK Parquet partition and returns structured rows with the lineage envelope for one-click SEC verification.

Persistent, agent-agnostic research state (all MCP clients)

Research objects live server-side, keyed to your token — save from one AI client, read from another, score later.

Public publishing — free reputation building (all tiers)

Publish your saved research to a public @handle profile — free to build a public track record and reputation. Reports become a shareable /r/[slug] page discoverable via keyword catalog search (no semantic search yet); theses and claims get the same free publish / unpublish visibility toggle. This is publishing, not selling; the paid report-marketplace tools (purchase_report, list_my_purchases, connect_stripe_account) remain unreleased.

Configure in Claude Desktop

Add to claude_desktop_config.json:

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

Same URL + Bearer token works for any MCP client that supports Streamable HTTP remotes — Copilot, ChatGPT, Cursor, your own LangGraph / CrewAI agent.

Examples in this repository

Every script and notebook works against the SDK published on PyPI. The Sample tier runs without a token; add VALUEIN_API_KEY to use a paid tier.

Python scripts (examples/python/)

Jupyter notebooks (examples/notebooks/)

Notebook	Open in Colab
Quickstart
Fundamental Analysis
PIT Backtest
Survivorship Bias
Factor Screen
Earnings Momentum
DCF Inputs

Documentation

Everything in docs/ is kept in sync with the production data and the SDK on PyPI.

Support & community

GitHub Issues is the primary support channel. Use the right template — it routes correctly and gets faster triage.

For private or contractual matters (DPAs, procurement, DDQs, enterprise SLAs): support@valuein.biz.

Contributions — examples, notebook improvements, documentation fixes, query recipes — are very welcome. See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community standards.

License & disclosure

Apache 2.0. See NOTICE for attribution.

This repository is provided for research and educational purposes. It is not investment advice. No warranty of fitness for any particular trading, investment, or regulatory purpose is implied.