# Silicon Capital — Data API & MCP (path to paid data)

## Product surface (web)

| Path | Purpose |
|------|---------|
| **`/data`** | Design-partner pack: what you get, sample download, eval waitlist |
| **`/benchmarks`** | B2B underwriting benchmarks (universe ranks, peer compare, role leaders) |
| **`/data/sample-pack.json`** or **`/api/data/sample-pack`** | Downloadable seed/eval sample pack (live from research_os; stack map + scores + slim benchmarks) |
| **`/data/license`** | Design-partner / eval license (HTML). `/api/data/license` remains the plain-text sample license |

Waitlist source tags: `data_pilot`, `api_commercial` (filter leads separately from `landing` / `course`).

Commercial tier draft: [`COMMERCIAL_DATA_LICENSE.md`](COMMERCIAL_DATA_LICENSE.md).  
Benchmarks engine: `research_os/benchmarks.py`. Agent ops notes stay in the private repo (not on the public `/docs` catalog).

## What we expose (structured, no LLM required)

| Endpoint / tool | Output |
|-----------------|--------|
| `GET /api/universe` | Tickers + stack roles + **coverage provenance** (`data_nature`) |
| Coverage config | `SILICON_UNIVERSE_PATH` / `SILICON_UNIVERSE_MERGE_SEED` / `SILICON_LIVE_CLASSIFY` — default US sample + seed merge + live classify. Grow coverage with env + nightly rebuild; do not hardcode tickers. |
| `GET /api/underwrite/<TICKER>` | Multi-factor scorecard + flags |
| `GET /api/underwrite/<TICKER>?include_x=1` | Same + optional X social pulse (if `X_BEARER_TOKEN` set) |
| `GET /api/x/pulse/<TICKER>` | Top recent X posts + simple keyword sentiment (secondary; not the engineer score) |
| `POST /api/portfolio` | Stack concentration + thesis overlap |
| `POST /accounts/import` | Logged-in CSV upload or ticker paste → linked account (free; no SnapTrade cost) |
| `POST /accounts/link/start` | Start brokerage Link. **SnapTrade Connect requires durable Pro**; non-Pro XHR/API gets `402 pro_required`, browser form/navigation redirects to `/pricing`. |
| `GET /api/funds/<TICKER>` | Institutional holders + buy/sell-style directions. Seed 13F-style for most names; **semi-live SEC 13F-HR extract** (lagged, with `source` / `as_of` / `retrieved_at`) for a small top-coverage set (NVDA/TSM/AVGO). Fail-soft to seed. Not real-time smart money. |
| `GET /api/funds` | Tickers with fund coverage + `semi_live_tickers` |
| `GET /api/benchmarks` | Universe underwriting ranks + band distribution |
| `GET /api/benchmarks/peers/<TICKER>` | Peer cohort ranks + factor deltas |
| `GET /api/benchmarks/snapshot` | Multi-ticker peer tables + ranks (B2B eval) |
| `GET /api/data/sample-pack` | Multi-product sample JSON + license_text |
| MCP tools (below) | Same pure functions via tool calls |

### Free-tier API rate limits (optional hard)

All `/api/*` responses include `X-RateLimit-*` headers. Default is **soft / unlimited**: when `SILICON_API_RATE_LIMIT` is unset, clients only see informational headers (no `429`). Production keys are not required for public `/api/underwrite`.

When `SILICON_API_RATE_LIMIT` is set to a positive integer, excess calls receive **`429`** + `Retry-After`. Invalid or non-positive env values **fail-soft** to the informational default and never 500 the API.

| Header | Meaning |
|--------|---------|
| `X-RateLimit-Limit` | Allowed requests per rolling window (default **120** / hour; override `SILICON_API_RATE_LIMIT`) |
| `X-RateLimit-Remaining` | Remaining estimate for this client IP |
| `X-RateLimit-Reset` | Unix time when the oldest hit ages out of the window |
| `X-RateLimit-Policy` | `soft;…;mode=informational` or `hard;…;mode=enforce` |
| `Retry-After` | Seconds until a slot frees (**hard-mode 429 only**) |

Window seconds: `SILICON_API_RATE_WINDOW_SEC` (default `3600`). In-process only (not shared across workers). **API keys** still gate sellable depth (below); this is not a paid tier.

### Public vs keyed (MVP)

| Surface | Auth |
|---------|------|
| `GET /api/underwrite/<T>` | **Public** (rate headers; hard 429 only if env cap is set) |
| `GET /api/benchmarks`, peers, sample pack, funds, universe | **Public** |
| `POST /api/v1/benchmarks/snapshots` | **API key** — freeze rankings |
| `GET /api/v1/benchmarks/snapshots` · `.../<id>` | **API key** — list/retrieve frozen snapshots |
| `POST /api/v1/portfolio/stack-risk` | **API key** — structured stack-risk export |

**Key env:**

| Env | Meaning |
|-----|---------|
| `SILICON_API_KEYS` | Comma-separated keys |
| `SILICON_API_KEYS_PATH` | File with one key per line (default `data/api_keys.txt`) |
| `SILICON_BENCHMARK_SNAPSHOTS_PATH` | Directory for frozen snapshot JSON |

Send `Authorization: Bearer <key>` or `X-API-Key: <key>`.

```bash
# Public
curl -sS "$URL/api/underwrite/NVDA" | jq '.overall_score, .scoring_depth, .coverage_source'
# Listed US ticker absent from seed JSON still 200 (shallow live classify)
curl -sS "$URL/api/underwrite/AAPL" | jq '.ticker, .scoring_depth, .coverage_source'

# Produce snapshot (keyed)
curl -sS -X POST "$URL/api/v1/benchmarks/snapshots" \
  -H "Authorization: Bearer $SILICON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"top_n":20,"as_of":"2026-08-02","factor":null}'

# Stack-risk export (keyed)
curl -sS -X POST "$URL/api/v1/portfolio/stack-risk" \
  -H "X-API-Key: $SILICON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"ticker":"NVDA","weight":0.5},{"ticker":"CEG","weight":0.5}]}'
```

Core logic lives in `research_os/` — HTTP and MCP are thin wrappers. Pack builder: `research_os/sample_pack.py`.

## Local HTTP examples

```bash
curl -s localhost:8080/api/underwrite/NVDA | jq '.stack_roles, .overall_score'
curl -s localhost:8080/api/funds/ASML | jq '.summary, .holders[0]'
curl -s localhost:8080/api/universe | jq '.count'
curl -s localhost:8080/api/benchmarks | jq '.rankings[0], .band_distribution'
curl -s localhost:8080/api/benchmarks/peers/NVDA | jq '.rank_in_cohort, .factor_compare[0]'
```

Refresh the tiny 13F cache (optional, hits SEC EDGAR):

```bash
PYTHONPATH=. SILICON_13F_HTTP=1 python scripts/refresh_13f.py
```

## MCP server (MVP)

```bash
cd ~/git/siliconcapital
PYTHONPATH=. python mcp_server.py
# or: PYTHONPATH=. python -m mcp_server
```

Stdio JSON-RPC–style loop for agent hosts (Cursor/Claude-compatible shape):

- `tools/list` → tool definitions  
- `tools/call` with `name` + `arguments`  

Tools (must match `TOOLS` in `mcp_server.py`):

| Tool name | Arguments |
|-----------|-----------|
| `underwrite_company` | `{ "ticker": "NVDA" }` |
| `universe_benchmarks` | `{ "top_n": 20 }` optional `factor` |
| `peer_benchmark` | `{ "ticker": "ASML" }` |
| `portfolio_stack_risk` | `{ "holdings": [{"ticker":"NVDA","weight":0.5}, ...] }` or `{ "use_sample": true }` |
| `fund_flow_report` | `{ "ticker": "TSM" }` |
| `list_universe` | `{}` |

Sync check: `PYTHONPATH=. python -c "from mcp_server import TOOLS; print([t['name'] for t in TOOLS])"`

## How we sell this later

| Stage | Offer | Monetization |
|-------|--------|--------------|
| Now | Open JSON + MCP | Lead gen, product proof |
| Next | API keys + rate limits | $49–299/mo |
| Later | Commercial redistribution license | Contract |
| Later | Bulk dumps / warehouse feed | $2k–20k+/yr |

**We do not sell** commodity OHLCV. **We sell** stack taxonomy, underwriting scores, portfolio thesis risk, and institutional Δ on our coverage set.

See also: the `/data` catalog and `/pricing` (revenue-stream planning stays internal to the repo).

## License note for customers (draft)

Educational / internal research use on the free sample pack (design-partner eval, not a clickwrap marketplace).
Licensor: MOMENTUM LABS LLC. Educational tools, not investment advice. Seed/eval pack — not a live market data feed.
Redistribution, multi-tenant embedding, or competing terminal products require a written commercial / design-partner license.
Public `/api/underwrite` stays free. API keys (SC-018) already gate sellable depth.