SmartMoney — 13F superinvestor tracker

Reconstructs hedge-fund / superinvestor portfolios straight from SEC EDGAR 13F-HR filings, and diffs quarter-over-quarter to surface new positions, exits, adds and trims. Data is U.S.-government public domain — free to use and redistribute.

Guides: TEST_LOCAL.md to run it on your machine in minutes · INSTALL_SERVER.md for production deployment · SECURITY.md for the threat model and audit.

Setup

pip install -r requirements.txt   # or: pip install requests defusedxml flask
export SEC_UA="SmartMoney/1.0 you@example.com"   # SEC requires a contact email or 403s you
export OPENFIGI_APIKEY="..."                       # optional, free; lifts FIGI rate limits
python run.py --list                 # tracked funds
python run.py --verify               # sanity-check seed CIKs against EDGAR
python run.py --fund "Berkshire Hathaway" --top 15 --enrich   # --enrich adds tickers

Offline tests (no network):

pip install pytest
python -m pytest tests/ -q     # offline suites: parsing, figi, db, valuation, alerts, resolver, security, Pro API

CUSIP resolution & the long tail

13F rows carry only CUSIPs. resolver.py runs a confidence-ranked chain so the tail that OpenFIGI misses still gets resolved where possible, with provenance recorded:

manual override (1.0) → OpenFIGI (0.95) → CUSIP issuer-prefix (0.65–0.85)
→ SEC name match (0.60) → unresolved (0.0, issuer name kept)

The CUSIP-prefix step reuses a confident sibling's ticker for a different share class/unit of the same issuer; the SEC step matches nameOfIssuer against SEC company_tickers.json. Misses are cached with a timestamp and re-tried after a TTL (the tail shrinks as data improves), not forever. --sync --enrich uses the full chain.

python run.py --coverage                 # % of 13F value resolved, per fund + the worst tail
python run.py --resolve-sweep            # re-run the chain over unresolved CUSIPs, back-fill

Provenance + confidence are stored per holding, so the dashboard's reconcile dot and the valuation reconcile ratio can flag weak mappings. Optional cusip_overrides.json ({"<cusip>":"TKR"}) hard-maps stubborn names at top confidence.

Dashboard (web UI)

A read-only Flask API exposes the store as JSON, and a single-file dashboard consumes it.

pip install flask
python -m smartmoney.api --db smartmoney.db            # serves http://localhost:5000
python -m smartmoney.api --db smartmoney.db --value     # also enable live valuation (stooq)

Open http://localhost:5000. The UI is branded 13FLOW (dark editorial theme — emerald = institutions, amber = insiders, converging like the Confluence score) with five screens: Consensus (who's buying / most owned), Funds (holdings, current weights, implied P&L, conviction sparklines), Compare (overlap matrix across funds), Alerts (subscriptions + the diff feed), and Confluence (13F accumulation × insider buying). A served FAQ page (/faq) explains the product, linked from the sidebar. Demo data is available only when explicitly requested (?demo=1 in the browser or SMARTMONEY_CONFLUENCE_DEMO=1 for the Confluence API); production errors are shown instead of silently substituting samples. API endpoints: /api/live-status, /api/funds, /api/fund/<cik>, /api/consensus/{buys,holdings}, /api/compare, /api/signals/confluence, /api/signals/confluence/history, /api/methodology/confluence-v1, /api/data-quality, /api/agent-stats, /api/openapi.json, and the MCP Streamable HTTP endpoint /api/mcp. The Registry surface exposes only bounded, read-only public tools. Optional Pro/x402 tools are disabled by default and are not advertised publicly. The official Registry manifest is server.json. Static, crawler-friendly pages are served at /funds, /funds/<cik>, /stocks, /stocks/<ticker>, /signals, and /signals/<ticker>, with SEC links where an accession or issuer search can be resolved. /agents and /fr/agents publish 7/30-day MCP activity from durable UTC aggregates. They make no unique-user claim and retain no IP address, User-Agent, client version, raw client identifier, arguments, prompts, responses or keys. The separate operator-only /stats/ surface is an optional password-protected GoAccess report generated from Apache logs. It adds no browser tracking, strips query strings, anonymizes report IPs at level 2 and keeps a 90-day reporting window. Its dedicated CSP is scoped to the authenticated report so the public site's nonce policy remains unchanged. Production also installs a first-in-order static 000-zen-default.conf vhost. Unknown Host headers receive an inert ZEN page and a separate minimal access log instead of reaching 13FLOW or contaminating 13flow_access.log; named vhosts continue to route normally. /api/live-status is the public, machine-readable proof of live state: SHA, source (SEC EDGAR), latest quarter, row counts, data-quality summary, and uses_synthetic_data=false. /api/product-status is the machine-readable operational status surface: it states live data coverage, disabled claims, and why full quantitative validation remains blocked until imported 2013-2026 adjusted-price and normalized Form 4 transaction artifacts are available. See the Core V1 scope gate in docs/CORE_V1_BOUNDARY.md. Current product and research boundaries are exposed at /status, /readiness, /api/product-status and /api/research-readiness. /api/pro-offer remains a retired compatibility endpoint and is not exposed as a canonical MCP tool.

No browser accounts or checkout

Core V1 deliberately has no browser account system, no public signup, no self-serve checkout and no Stripe billing flow. Pro API access is operator issued: create a scoped key, deliver the plaintext token once through an approved secure channel, verify /api/pro/v1/status, and keep audit/rotation in the Pro control plane.

Pro API

The Pro API is an explicit, versioned API-key surface for institutional and automated use. It is off by default. Enable it with SMARTMONEY_PRO_API=1 and store keys, counters, and audit events in a dedicated control-plane SQLite file via SMARTMONEY_PRO_DB.

Recommended production split:

# /etc/13flow/13flow-web.env, used by 13flow.service on 127.0.0.1:8000
SMARTMONEY_OPEN=1
SMARTMONEY_DB_READONLY=1
SMARTMONEY_DB=/var/lib/13flow/13flow.db
SMARTMONEY_ADMIN_PANEL_USER=admin@toonux.com
SMARTMONEY_ADMIN_SESSION_SECRET=<server-only-random-secret>
SMARTMONEY_ADMIN_PASSWORD_PBKDF2=<pbkdf2-sha256$...>
SMARTMONEY_ADMIN_SESSION_SECONDS=1800
SMARTMONEY_ADMIN_TOTP_SECRET=<base32-secret>
SMARTMONEY_ADMIN_TOTP_REQUIRED=1

# /etc/13flow/13flow-pro.env, used by 13flow-pro.service on 127.0.0.1:8001
SMARTMONEY_OPEN=1
SMARTMONEY_DB_READONLY=1
SMARTMONEY_DB=/var/lib/13flow/13flow.db
SMARTMONEY_PRO_API=1
SMARTMONEY_PRO_DB=/var/lib/13flow-pro/13flow-pro.db
SMARTMONEY_PRO_KEY_PEPPER=<server-only-random-secret>
SMARTMONEY_PRO_REQUIRE_KEY_PEPPER=1
SMARTMONEY_PRO_ACCEPT_LEGACY_SHA256_KEYS=0

Do not grant /var/lib/13flow-pro write access to the public 13flow.service. Apache should route only /api/pro/ to 13flow-pro.service, while the public site and open JSON endpoints stay on the read-only service.

Admin panel access at /pro/admin is protected by a server-side admin session. Generate the session secret and password hash on the server; the Pro API key used inside the panel is still separate and must carry admin:read,admin:write.

openssl rand -hex 32
/opt/13flow/.venv/bin/python /opt/13flow/run.py --hash-admin-password
/opt/13flow/.venv/bin/python -c 'import base64,secrets; print(base64.b32encode(secrets.token_bytes(20)).decode().rstrip("="))'

Create an API key offline as the operator. The plaintext token is shown exactly once. In production, only an HMAC-SHA256 hash derived with the server-only SMARTMONEY_PRO_KEY_PEPPER is stored, so tokens generated from a GitHub clone or another instance cannot authenticate against 13flow.eu. With SMARTMONEY_PRO_REQUIRE_KEY_PEPPER=1, legacy SHA-256 rows are rejected unless SMARTMONEY_PRO_ACCEPT_LEGACY_SHA256_KEYS=1 is explicitly set for a short migration window.

sudo -u flowpro env SMARTMONEY_PRO_KEY_PEPPER="$SMARTMONEY_PRO_KEY_PEPPER" \
  SMARTMONEY_PRO_REQUIRE_KEY_PEPPER=1 \
  /opt/13flow/.venv/bin/python /opt/13flow/run.py \
  --create-api-key "Acme Asset Management" \
  --pro-db /var/lib/13flow-pro/13flow-pro.db \
  --api-key-scopes funds:read,quality:read \
  --api-key-rate-per-min 120 \
  --api-key-rate-per-day 10000

python run.py --list-api-keys --pro-db /var/lib/13flow-pro/13flow-pro.db
python run.py --revoke-api-key <key_id> --pro-db /var/lib/13flow-pro/13flow-pro.db
python run.py --prune-pro-audit-days 180 --pro-db /var/lib/13flow-pro/13flow-pro.db

Use Authorization: Bearer <token> or X-13FLOW-Key: <token>.

curl -H "Authorization: Bearer $TOKEN" https://13flow.eu/api/pro/v1/status
curl -H "Authorization: Bearer $TOKEN" https://13flow.eu/api/pro/v1/funds
curl -H "Authorization: Bearer $TOKEN" https://13flow.eu/api/pro/v1/fund/0001067983
curl -H "Authorization: Bearer $TOKEN" \
  "https://13flow.eu/api/pro/v1/fund/0001067983?include_holds=0&limit_positions=20&limit_moves=50"
curl -H "Authorization: Bearer $TOKEN" https://13flow.eu/api/pro/v1/data-quality
curl https://13flow.eu/api/pro/v1/openapi.json
curl https://13flow.eu/api/product-status
curl https://13flow.eu/api/research-readiness