valuein

[![Valuein](https://www.valuein.biz/valuein/twitter-rounded.png)](https://valuein.biz)

[![PyPI version](https://img.shields.io/pypi/v/valuein-sdk?cacheSeconds=300)](https://pypi.org/project/valuein-sdk/)
[![PyPI downloads](https://img.shields.io/pypi/dm/valuein-sdk?label=pypi%20downloads&cacheSeconds=3600)](https://pypi.org/project/valuein-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/valuein-sdk/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/valuein/valuein?style=flat&cacheSeconds=3600)](https://github.com/valuein/valuein/stargazers)
[![MCP Registry](https://img.shields.io/badge/MCP-registry.modelcontextprotocol.io-blue)](https://registry.modelcontextprotocol.io)
[![Docs](https://img.shields.io/badge/docs-valuein.biz-purple)](https://valuein.biz/developers/catalog)

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

> **Survivorship-bias-free, point-in-time US fundamentals — streamed as Parquet, queried with DuckDB or natural language.**

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](server.json) 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.

```bash
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

| You want to… | Go to |
|---|---|
| Try the SDK in 30 seconds without a token | [Quickstart](#quickstart-30-seconds-no-token) |
| See every channel we ship through | [Distribution channels](#distribution-channels) |
| Check pricing and what each plan unlocks | [Plans & access](#plans--access) |
| Connect an AI agent (Claude, Cursor, Codex…) | [MCP for AI agents](#mcp-for-ai-agents) |
| Set up the Workspace by role (analyst, PM, quant, creator) | [`docs/WORKSPACE_GUIDE.md`](docs/WORKSPACE_GUIDE.md) |
| Read the data model | [Data model](#data-model) |
| Find a quick recipe by role | [Recipes by role](#recipes-by-role) |
| Run end-to-end Python examples | [`examples/python/`](examples/python/) |
| Run interactive notebooks (Colab) | [`examples/notebooks/`](examples/notebooks/) |
| Read the methodology / SLA / compliance | [Documentation](#documentation) |
| Report a data error or request a feature | [Support & community](#support--community) |
| Contribute an example or notebook | [`CONTRIBUTING.md`](CONTRIBUTING.md) |

---

## 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**
- **105M+ standardized facts** across **19,000+** active and delisted US public-company entities
- **11,966 raw XBRL tags** normalized to **~286 canonical `standard_concept`** values (95%+ coverage)
- **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`
- **Semantic core** — every 10-K / 10-Q / 20-F's narrative sections (Risk Factors, MD&A, Business, Legal, Controls) chunked and indexed for natural-language search via the MCP server

### Why it's different

| Property | What it means for you |
|---|---|
| 🕒 **Point-in-time** | `filing_date <= trade_date` removes look-ahead bias. `accepted_at` gives intraday resolution for same-day signals. |
| ⚖️ **Survivorship-bias free** | Delisted, bankrupt, and acquired companies remain in every snapshot — your backtest sees the universe the market saw. |
| 📊 **Standardized concepts** | Both the raw XBRL tag (`fact.concept`) and the canonical name (`fact.standard_concept`) are on every row. No hidden mapping table. |
| 🔍 **CPA-verified catalog** | Every `standard_concept` carries a `review_confidence` — `1.0` once an accountant has signed off on its name, statement and rule (then it's locked; the pipeline only ever adds new concepts, never mutates a verified one), `0.7` while provisional. Filter `review_confidence >= 1.0` for the labels analysts, quants and AI models can agree on and train against. |
| 🚀 **DuckDB-native** | Millisecond analytics over remote Parquet via `httpfs`. Zero database provisioning. |
| 🔁 **Append-only restatements** | A `10-K/A` adds a new row — the original stays. Reconstruct the as-reported view of any historical date. |
| 🔐 **One token, every channel** | The same Bearer token authenticates the SDK, MCP server, and bulk-data API. |

---

## Distribution channels

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

| Channel | Audience | Endpoint / install |
|---|---|---|
| **Python SDK** | Quants, engineers, data scientists | `pip install valuein-sdk` · [PyPI](https://pypi.org/project/valuein-sdk/) |
| **MCP server** | AI agents (Claude, Cursor, Codex, custom) | `https://mcp.valuein.biz/mcp` · [server.json](server.json) |
| **Web dashboard** | Retail, executives, non-technical users | [valuein.biz](https://valuein.biz) |
| **Bulk data API** | B2B partners, fintech platforms | `https://data.valuein.biz` · [contact us](mailto:sales@valuein.biz) |

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](https://valuein.biz/pricing) — the website is the source of truth and our checkout flow routes to the correct Stripe product.

| Plan | Universe | History | Data freshness | Price | Get it |
|---|---|---|---|---|---|
| **Sample** | S&P 500 (~500 tickers) | 5-year window | Quarterly snapshots | **Free** · no signup | Just `pip install valuein-sdk` |
| **Free** | S&P 500 (~500 tickers) | 1993 – present | Daily | **Free** · register | [Register](https://valuein.biz/signup/free) |
| **Pro** | Full active + delisted US universe (19,000+ entities) — fundamentals dataset only | 15-year rolling (2011 → present) | 24h after SEC | **$49 / mo** · $490 / yr | [Subscribe](https://valuein.biz/checkout?tier=pro&billing=monthly) |
| **Institutional** | Same universe + **smart-money dataset** (insider transactions on Forms 3/4/5/144 + institutional ownership on Forms 13F/13D/13G) | 1993 – present (unlimited) | 4h priority + filing-event webhooks | **$499 / mo** · $4,790 / yr | [Subscribe](https://valuein.biz/checkout?tier=full&billing=monthly) |
| **Enterprise** | Negotiated · dedicated infrastructure · expanded redistribution scope | Custom | Real-time 8-K + zero-retention option | Talk to us | [sales@valuein.biz](mailto:sales@valuein.biz) |

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](https://mpp.dev). 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.

| Category | Examples | Price |
|---|---|---|
| Provenance / schema | `describe_schema`, `verify_fact_lineage` | Free |
| Discovery | `search_companies`, `get_sec_filing_links` | **$0.01 / entity** |
| Fundamentals | `get_company_fundamentals`, `get_financial_ratios` | **$0.10 / entity** |
| Analytics | `get_valuation_metrics`, `get_peer_comparables`, `compare_periods`, `get_capital_allocation_profile`, `get_earnings_signals` | **$0.50 / entity** |
| Compute | `compute_dcf`, `forensic_audit`, `generate_dcf_xlsx`, `generate_research_brief_docx`, `generate_comps_xlsx` | **$2.50 / call** |
| Screens / universe | `screen_universe`, `get_pit_universe` | **$5.00 / call** |
| Smart money (Institutional dataset) | `get_insider_transactions`, `get_insider_sentiment`, `get_institutional_holdings`, `get_manager_portfolio`, `get_blockholders`, `get_top_holders`, `get_smart_money_flow` | **$5.00 / entity** |

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

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

| Plan | Per minute | Per hour |
|---|---:|---:|
| Sample (anonymous) | 15 | 150 |
| Free | 60 | 1,000 |
| Pro | 100 | 3,000 |
| Institutional / Enterprise | 300 | 10,000 |

---

## 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:

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

```bash
# 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.

```python
from valuein_sdk import ValueinClient

w