# Public Stock Intelligence

Agent Media Tools hosts a **public-disclosure intelligence layer** for humans and local AI agents (including the [Local AI Stock Bot](/stock-bot)).

**Product page:** [/stock-intelligence](/stock-intelligence)

## Monetization

| Tier | What you get |
|------|----------------|
| **Free** | Local AI Stock Bot, product page, methodology, inventory counts (`/status`, `/sources`) |
| **Pro** ($5/mo) | Hosted row data: SEC Form 3/4/5, House PTRs, 13D/G, Form 144, curated 13F, signals, deterministic brief, **Mira AI daily brief with buy/sell research notes**, entity search, MCP tools |
| **Builder** ($15/mo) | Everything in Pro + higher page sizes, deeper pagination, bulk `/export` |

Upstream filings remain free government data. **We charge for hosted access, normalization, and agent packaging** — not ownership of public records.

Unauthenticated or free-plan requests to data endpoints return **HTTP 402** with `code: STOCK_INTEL_PRO_REQUIRED`.

## Promise

- Upstream data from **free official sources only** (SEC EDGAR, House Clerk).
- Every published row keeps **provenance** (source URL, filing id, parser version).
- Transaction date and filing date are **never conflated**.
- No paid congressional, celebrity, or whale APIs.
- Deterministic briefs and signals always available; Mira’s AI brief is **shared once per day** (cached, not billed per page view).
- Mira buy/sell notes are **research commentary on public filings only** — not personalized financial advice.
- Not financial advice.

## Sources

| Source | What we ingest | Notes |
|--------|----------------|-------|
| SEC recent ownership feed + ownership XML | Forms 3/4/5 | Mega-cap watchlist + live feed |
| SEC Form 144 atom + XML | Proposed sales | Intent, not confirmed trades |
| SEC Form 8-K atom + HTML | Material company events | Item codes best-effort (2.02 earnings, 5.02 officers, …) |
| SEC Form 5 (ownership) | Annual / late insider reports | Same family as Form 4 |
| SEC Schedule 13D/13G | Large beneficial ownership | From issuer + mega-filer submissions (BlackRock, Vanguard, …) |
| SEC 13F information tables | Curated “whale” managers | Quarterly delayed snapshots |
| House Clerk `YYYYFD.zip` + PTR PDFs | Periodic Transaction Reports | Amounts are ranges; PDF parse is best-effort |
| SEC `company_tickers.json` | Ticker ↔ CIK map | Name/CIK resolution |
| Senate EFD | Senate PTRs | **Link only** — no free bulk ZIP; not scraped |

**Not automated yet:** full Senate PTR PDF pipeline (compliance + portal friction).

## API

Base: `https://agentmediatools.com/api/market-intelligence`

### Public (free)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/status` | Inventory counts + your access summary |
| GET | `/sources` | Source registry + policy |
| GET | `/entitlements` | Plan matrix for the current identity |

### Pro / Builder (session or Pro agent key)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/insiders/trades` | SEC insider transactions |
| GET | `/congress/trades` | House PTR trades |
| GET | `/institutions/holdings` | Curated 13F holdings |
| GET | `/large-holders` | Schedule 13D/13G large beneficial ownership |
| GET | `/form144` | Form 144 proposed-sale notices |
| GET | `/events` | Form 8-K material company events |
| GET | `/watchlists` | List your ticker watchlists |
| POST | `/watchlists` | Create watchlist (`tickers`, `notify_email`, `webhook_url`) |
| PATCH | `/watchlists/:id` | Update name/tickers/notify flags |
| DELETE | `/watchlists/:id` | Delete watchlist |
| GET | `/watchlists/:id/matches` | Filings matching watchlist tickers |
| POST | `/watchlists/scan` | Scan + optional email/webhook delivery |
| GET | `/watchlist-alerts` | Recent alert history |
| GET | `/entities?q=` | Entity search |
| GET | `/entities/:id` | Entity profile + related rows |
| GET | `/signals` | Deterministic derived signals |
| GET | `/daily-brief` | Deterministic Markdown/JSON brief (no model) |
| GET | `/mira-brief` | Mira AI brief + buy/sell research notes (daily cache) |
| GET | `/query?q=` | Unified search |
| GET | `/tools/amt_*` | Agent tool aliases |

### Builder only

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/export?kind=trades\|holdings` | Larger bulk pulls |

### Auth

```bash
# Browser: signed-in Pro/Builder session cookie
# Agent:
curl -s -H "Authorization: Bearer mt_YOUR_PRO_KEY" \
  "https://agentmediatools.com/api/market-intelligence/insiders/trades?open_market=1&limit=5"
```

### Limits

- **Pro:** max `limit` 50, max `offset` 500 per request  
- **Builder:** max `limit` 200, max `offset` 5000  

## MCP tools

Require a Pro-tier agent key (`mt_…` with plan pro):

- `amt_get_insider_trades`
- `amt_get_congress_trades`
- `amt_get_whale_holdings`
- `amt_get_large_holders`
- `amt_get_form144`
- `amt_get_company_events`
- `amt_get_watchlist_matches`
- `amt_get_market_signals`
- `amt_get_daily_stock_brief`
- `amt_get_mira_stock_brief`
- `amt_market_intelligence_query`

### Watchlists (Pro+)

Create ticker lists on [/stock-intelligence](/stock-intelligence) or via API. Optional:

- **Email** to your account address when new public filings match (after ingest or `POST …/watchlists/scan`)
- **HTTPS webhook** for agents (`POST` JSON payload `stock_intel.watchlist`)
- **MCP/agent** tool `amt_get_watchlist_matches`

Limits: Pro 3 lists × 25 tickers; Builder 15 × 100. Webhooks must be public `https://` (no localhost/private IPs).

## Local stock bot (Pro auto-feed)

The free [Local AI Stock Bot](/stock-bot) does **not** need this API for paper trading. With **Pro or Builder**, Mira pulls a research pack each cycle when a key is set:

```bash
# in the bot’s private .env
AMT_AGENT_KEY=mt_your_pro_key
./launch_monitor.sh   # look for “AMT Pro key detected”
```

Manual client:

```bash
export AMT_AGENT_KEY=mt_your_pro_key
python -c "from analysis.amt_market_intel import mira_context; print(mira_context(candidates=['AAPL'])[:500])"
```

Missing keys, free-plan 402s, and network errors fail soft — the bot keeps running.

## Operator ingest

```bash
node scripts/ingest-stock-intelligence.js
```

Uses only free public HTTP. Does not grant customer data access — that remains plan-gated.

## Limitations

- Senate PTRs not automated yet  
- No invented celebrity portfolios  
- No real-time quotes / performance backtests  
- House PDF layout parsing is heuristic  

## Compliance language

Use: “publicly disclosed”, “filed”, “correlated with”, “may be relevant”.  
Avoid: “they knew”, “guaranteed signal”, “copy this trade”, “will rise”.