# AlphaSMO — The Ultimate Smart Money API for AI [![npm version](https://img.shields.io/npm/v/alphasmo.svg)](https://www.npmjs.com/package/alphasmo) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) **CLI + [MCP server](https://modelcontextprotocol.io) for [AlphaSMO](https://alphasmo.com)** — SEC EDGAR 13F institutional holdings, Form 4 insider trading, and "smart money convergence" signals (tickers where hedge funds *and* company insiders are buying at the same time), queryable from your terminal, your scripts, or any MCP-compatible AI agent (Claude, ChatGPT, Cursor, etc.). No signup, no API key, no setup — try it right now: ```bash npx alphasmo stocks flows --limit 10 ``` **Example output:** ```text ┌────────┬──────────────────────────────┬────────────────────┬──────────────┬──────────────┐ │ ticker │ issuer │ net flow (USD) │ avg weight % │ institutions │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ BRK-A │ BERKSHIRE HATHAWAY INC-CL A │ 247,455,256,379 │ 1.42 │ 1418 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ AZN │ AstraZeneca PLC │ 148,465,847,587.12 │ 0.47 │ 1309 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ XOM │ EXXON MOBIL CORP │ 138,784,059,363.77 │ 0.78 │ 4716 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ CVX │ CHEVRON CORP │ 77,783,933,645.44 │ 0.6 │ 4261 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ JNJ │ JOHNSON & JOHNSON │ 64,498,075,844.9 │ 0.76 │ 4603 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ SNDK │ SANDISK CORP │ 58,662,972,096.01 │ 0.65 │ 1172 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ MU │ MICRON TECHNOLOGY INC │ 55,374,569,969.23 │ 0.7 │ 2993 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ AMAT │ APPLIED MATERIALS INC │ 48,790,109,328.41 │ 0.52 │ 2931 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ EEM │ ISHARES MSCI EMERGING MARKET │ 48,211,222,155.7 │ 0.59 │ 1637 │ ├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤ │ CAT │ CATERPILLAR INC │ 46,035,710,179.58 │ 0.5 │ 3724 │ └────────┴──────────────────────────────┴────────────────────┴──────────────┴──────────────┘ ``` ## Why AlphaSMO - 📊 **13F institutional holdings** — every hedge fund and asset manager's quarterly SEC filings: AUM, positions, and behavioral "personality scores" (concentration, turnover, sector conviction). Read our guide on [What Is a 13F Filing?](https://alphasmo.com/blog/what-is-13f-filing) and [How to Read Institutional Holdings Changes](https://alphasmo.com/blog/how-to-read-institutional-holdings-changes). - 🕵️ **Insider trading (Form 4 & 144)** — officer/director/10%-owner buys and sells, with a confidence score per ticker. Learn more in [What Is a Form 4 Filing?](https://alphasmo.com/blog/what-is-form-4-filing) and [What Is a Form 144 Filing?](https://alphasmo.com/blog/what-is-form-144-filing). - 🚀 **Smart money convergence** — the flagship signal: tickers where 13F institutions *and* company insiders are both buying right now. - 🤖 **Built for AI agents** — an MCP server out of the box, so Claude, ChatGPT, Cursor, or any MCP client can pull real financial data mid-conversation. - 🆓 **Free anonymous tier** — no signup required to try it; [get a free API key](https://alphasmo.com/developer) any time to raise your rate limit. ## Use cases ``` "What is smart money buying right now?" → alphasmo convergence "What does Berkshire Hathaway hold?" → alphasmo institutions holdings berkshire-hathaway-inc "Are insiders buying or selling NVDA?" → alphasmo insider summary NVDA "Which stocks are institutions dumping?" → alphasmo stocks flows --direction sell ``` Wire the MCP server into Claude Desktop, Claude Code, Cursor, or any MCP client (see [below](#mcp-server)) and ask these in plain English — no code required. ## CLI ```bash npx alphasmo institutions search "Berkshire" npx alphasmo stocks get AAPL npx alphasmo convergence -l 5 ``` No install step required — `npx` fetches and runs it. Or install globally: ```bash npm install -g alphasmo alphasmo --help ``` ### Commands | Command | What it returns | |---|---| | `alphasmo institutions search [-l\|--limit]` | Search 13F institutions by name | | `alphasmo institutions list [-l\|--limit] [-o\|--offset]` | Paginate the full institution universe (no query) | | `alphasmo institutions get ` | Full institution detail, sector weights | | `alphasmo institutions holdings ` | Latest 13F holdings for one institution | | `alphasmo stocks get ` | Full stock detail — holder count, flows, top holders (identifier = ticker or CUSIP) | | `alphasmo stocks flows [-d\|--direction buy\|sell] [-l\|--limit]` | Stocks ranked by net institutional buy/sell flow | | `alphasmo insider trades ` | Recent individual Form 4 insider trades for one ticker | | `alphasmo insider summary ` | Insider confidence scores (30d/90d) for one ticker | | `alphasmo convergence [-l\|--limit] [--min-confidence] [--days]` | Tickers where 13F institutions *and* insiders are both buying — the flagship signal | | `alphasmo mcp` | Start the MCP server over stdio | Global flags on every command: `--api-key ` (env `ALPHASMO_API_KEY`), `--base-url ` (env `ALPHASMO_BASE_URL`), `-f`/`--format json|compact|table|csv`, `--json` (shorthand for `--format json`), `--csv` (shorthand for `--format csv`). **Output format auto-detects your context** — no flag needed in the common case: - Typed directly in a terminal → a readable table, with numbers comma-formatted (`263,095,703,570`). - Piped, redirected, or spawned by a script/AI agent (stdout isn't a TTY) → JSON, safe to pipe into `jq` or feed to an agent. - `--format`/`--json`/`--csv` always override the auto-detection either way. ```bash alphasmo stocks flows --csv > flows.csv alphasmo insider trades AAPL --csv | column -s, -t ``` Errors go to stderr with a distinct exit code (`2` not found, `3` auth, `4` rate limit, `5` unexpected response shape, `1` other), so scripts can branch without string-matching. ## Get an API key Anonymous requests are rate-limited by IP. Sign up and mint a free key at **[alphasmo.com/developer](https://alphasmo.com/developer)**, then: ```bash alphasmo convergence --api-key ask_live_... # or export ALPHASMO_API_KEY=ask_live_... ``` ## MCP server ### Option 1: `claude mcp add` (recommended) If you're using [Claude Code](https://docs.claude.com/claude-code), register the server with one command: ```bash claude mcp add alphasmo -- npx -y alphasmo@latest mcp ``` Add `-e ALPHASMO_API_KEY=ask_live_...` before the `--` to raise your rate limit. Run `claude mcp list` to confirm it's connected. ### Option 2: manual MCP client config For Claude Desktop, Cursor, or any other MCP client, add this to your config file directly: ```json { "mcpServers": { "alphasmo": { "command": "npx", "args": ["alphasmo", "mcp"], "env": { "ALPHASMO_API_KEY": "optional-your-key-here" } } } } ``` Both options work anonymously out of the box, at lower rate limits than with a key. Tools exposed: `search_institutions`, `get_institution_profile`, `get_institution_holdings`, `get_stock_overview`, `get_stock_flows`, `get_insider_activity`, `get_smart_money_convergence`. Full endpoint reference: [alphasmo.com/developer/docs](https://alphasmo.com/developer/docs). ## Programmatic use ```ts import { AlphasmoClient } from "alphasmo"; const client = new AlphasmoClient(); // no apiKey needed to try it console.log(await client.getSmartMoneyConvergence({ limit: 5 })); ``` ```bash npm install alphasmo ``` A Python client + MCP server is also available — see [alphasmo.com/developer](https://alphasmo.com/developer) for setup. ## Learn more - **[alphasmo.com](https://alphasmo.com)** — the full web app: institution profiles, stock screeners, insider-trading leaderboards - **[alphasmo.com/developer](https://alphasmo.com/developer)** — get a free API key - **[alphasmo.com/developer/docs](https://alphasmo.com/developer/docs)** — full public API reference ### Educational Guides & SEC Filings Deep Dives Deepen your understanding of institutional holdings and SEC filing dynamics: - **[What Is a 13F Filing?](https://alphasmo.com/blog/what-is-13f-filing)** — Beginner's guide to institutional holdings disclosures. - **[What Is a Form 4 Filing?](https://alphasmo.com/blog/what-is-form-4-filing)** — How insider buying & selling gets reported. - **[What Is a Form 144 Filing?](https://alphasmo.com/blog/what-is-form-144-filing)** — Understanding SEC pre-sale notices before insider dumps. - **[13D vs. 13G Beneficial Ownership](https://alphasmo.com/blog/13d-vs-13g-beneficial-ownership)** — Uncovering 5% ownership filings and activist investor intent. - **[How to Read Institutional Holdings Changes](https://alphasmo.com/blog/how-to-read-institutional-holdings-changes)** — Navigating 13F portfolio changes without being misled by stock splits or option mechanics. ## License MIT