x402-insider-mcp

# x402-insider-mcp

MCP (Model Context Protocol) server exposing **SEC Form 4 insider-trading data** as tools,
backed by a live x402 pay-per-call API.

## What it is
- 3 tools: `search_insider_trades(ticker, limit)`, `top_insiders(days)`, `owner_history(name)`.
- Each returns **free preview rows (max 3)** straight from the API.
- **Full result sets require x402 payment** — the wrapper never signs or holds payments.
  Payments: x402 scheme=exact, USDC on Base, **$0.02/call raw endpoints**,
  payTo `0xcC3c1E564fF534CD1913f19dB3880cAb44563AE3` (receive-only). See https://x402.org
- Dataset: SEC EDGAR Form 4 insider transactions, 2025Q4–2026Q1 (~5,000 rows preview set).

## NEW: derived signal endpoints on the upstream API ($0.05/call)
The backing API now sells **derived signals**, not just raw rows (added 2026-09-13):
- `GET /signals/cluster?ticker=&days=` — insider **cluster-buy detection**
  (≥3 unique insiders buying open-market at one issuer within the window; conviction-scored).
- `GET /signals/momentum?days=[&ending_at=YYYY-MM-DD]` — issuers with **accelerating
  insider buying** (2 consecutive up-weeks + volume z-score); `ending_at` re-anchors for
  backtesting.
Both: free 1-line preview without payment, full results $0.05/call via the same x402 flow
(`X-PAYMENT` header, Coinbase facilitator). These are plain HTTP endpoints — call them
from any x402 client, or wire them into your own MCP tools.

## Run (no Docker needed)
```bash
./run.sh            # stdio MCP server; point your MCP client at it
```
Requires Python 3.8+, stdlib only. Requires network access to the API host.

## API endpoint
Currently CT-local: http://127.0.0.1:8790 (set `X402_API_URL` to override).
Public URL rotates (Cloudflare quick tunnel) — see the fleet lead for the current one.

## Honest limits
- Preview rows are capped at 3 by the upstream API by design (that is the free tier).
- No payment logic in this repo: bring your own x402 client to pay for full rows.