capitoltrades-cli

name

capitoltrades-cli

description

Use cli-web-capitoltrades to query US congressional stock trades, politicians, issuers, and insight articles from capitoltrades.com. Invoke this skill whenever the user asks about congressional trading, senator/representative stock trades, STOCK Act filings, insider trades by politicians, specific tickers (e.g. "what did Pelosi buy"), or US Capitol Trades data. Always prefer cli-web-capitoltrades over manually fetching the website — no auth is required and the CLI returns structured JSON.

cli-web-capitoltrades

Browse US congressional stock trades tracked on capitoltrades.com (by 2iQ Research). Installed at: cli-web-capitoltrades.

The site is a fully public data aggregator covering STOCK Act disclosures: ~35,000 trades, ~200 politicians, ~3,000 issuers. No authentication required.

Quick Start

# Latest trades across Congress
cli-web-capitoltrades --json trades list --page-size 20

# Trades by a specific politician (bioguide ID)
cli-web-capitoltrades --json trades list --politician P000197

# Trades for a ticker (auto-resolves via BFF)
cli-web-capitoltrades --json trades by-ticker NVDA --page-size 20

# Only large-size trades ($1M-$5M)
cli-web-capitoltrades --json trades list --size 1M-5M

# Top politicians by trade volume
cli-web-capitoltrades --json politicians top --by volume --page-size 10

# Aggregate stats (total trades, volume, politicians)
cli-web-capitoltrades --json trades stats

# Rich issuer data (sector, market cap, 1-year price history, #politicians holding)
cli-web-capitoltrades --json issuers search nvidia

Always pass --json when parsing output programmatically.

---

Commands

trades list

List trades, paginated and filterable.

cli-web-capitoltrades trades list [options] --json

Key options:

• --page N / --page-size N — pagination (default 1, 12)
• --politician <bioguide_id> — e.g. P000197 (Pelosi)
• --issuer <issuer_id> — e.g. 429725 (Amgen)
• --party republican|democrat|independent
• --chamber house|senate
• --tx-type buy|sell|exchange
• --sector <name> (e.g. health-care, information-technology)
• --size <bracket> — one of <1K, 1K-15K, 15K-50K, 50K-100K, 100K-250K, 250K-500K, 500K-1M, 1M-5M, 5M-25M, 25M-50M
• --sort traded|pubDate|filedAfter|tradeSize — sort column
• --sort-direction asc|desc (default desc)

Output fields: trade_id, politician_id, politician_name, politician_party, politician_chamber, politician_state, issuer_id, issuer_name, ticker, tx_type, size, price, traded, published, filed_after_days, owner.

trades get <trade_id>

Get full detail for a single trade (adds price, shares, filing_url, comment, reporting_gap).

trades by-ticker <SYM>

Convenience: resolve a ticker (e.g. NVDA, AMGN) via BFF search, then list trades for that issuer. Accepts --party, --tx-type, --page, --page-size. Returned meta.resolved_issuer includes name, ticker, sector, issuer_id.

trades stats

Overview stats from the /trades landing page. Returns trades, filings, volume, politicians, issuers.

politicians list

List politicians with filters.

Key options: --party republican|democrat|independent, --chamber house|senate, --state <ST>.

Output fields: politician_id (bioguide), name, party, state, trades_count, issuers_count, volume, last_traded.

politicians top

Leaderboard of politicians ranked by recent activity.

Key options: --by trades|volume (default trades), --page-size N, --party, --chamber.

politicians get <bioguide_id>

Politician detail + recent trades table. Example: cli-web-capitoltrades politicians get Y000067.

issuers list

List issuers (companies, funds, treasuries). Output: issuer_id, name, ticker.

issuers get <issuer_id>

Issuer detail + recent trades. Example: cli-web-capitoltrades issuers get 435544 (US Treasury Bills).

issuers search <query>

Richest endpoint. Uses the BFF JSON API — returns sector, market cap, 1-year price history (performance.eodPrices), trailing returns, and stats.countPoliticians / countTrades / volume / dateFirstTraded. Use --full to include the full eodPrices array.

articles list / articles get <slug>

List or view insight articles. Slug format: kebab-title-YYYY-MM-DD.

buzz list / buzz get <slug>

Third-party news snippets curated by Capitol Trades (Twitter, external articles about companies and politicians). Same slug format as articles.

press list / press get <slug>

Press coverage about Capitol Trades data and congressional trading news (articles published by external publications like CNN, Forbes, Politico).

---

Agent Patterns

# Find all buys of NVIDIA this year by Republicans
cli-web-capitoltrades --json issuers search nvidia | \
  python -c "import json, sys; d=json.load(sys.stdin); print(d['data'][0]['_issuerId'])"
# → take the issuer_id, then:
cli-web-capitoltrades --json trades list --issuer 433382 --party republican --tx-type buy --page-size 50

# Summary of a politician's most active tickers
cli-web-capitoltrades --json politicians get P000197 | \
  python -c "import json, sys, collections; d=json.load(sys.stdin); \
    trades=d['data']['recent_trades']; \
    print(collections.Counter(t['ticker'] for t in trades).most_common(5))"

# Today's biggest trades
cli-web-capitoltrades --json trades list --page-size 50 | \
  python -c "import json, sys; d=json.load(sys.stdin); \
    for t in d['data'][:10]: print(f\"{t['traded']}  {t['tx_type']:<5} {t['politician_name']:<25} {t['ticker']:<10} {t['size']}\")"

---

Data Model Notes

• Bioguide IDs (politician_id): 7 chars, [A-Z]\d{6}, the same ID used by bioguide.congress.gov
• Issuer IDs: numeric strings assigned by 2iQ Research
• Trade IDs: 11-digit numeric strings
• Trade sizes are ranges (1K–15K, 15K–50K, 50K–100K, 100K–250K, 250K–500K, 500K–1M, 1M–5M, 5M–25M, 25M–50M, >50M) — the STOCK Act only requires range disclosure, not exact amounts
• owner = Self, Spouse, Child, Joint, Undisclosed, Dependent, etc.
• filed_after_days = days between trade and disclosure (45 days = late, per STOCK Act)

Notes

• Auth: None — fully public site
• Rate limits: Site is served via AWS CloudFront; the CLI uses curl_cffi with Chrome 136 TLS fingerprinting, which is what makes the BFF accessible. No observed rate limits in normal use.
• Freshness: Data is typically <24h behind actual filings. Politician disclosures may lag up to 45 days (legal requirement) after the trade date.
• Exit codes: 0 success, 1 user error (not found / invalid arg), 2 system error (network / 5xx).
• BFF quirks: Only /issuers?search=... is exposed publicly. Other endpoints on bff.capitoltrades.com return 503.

Known limitations

• No full politician search in the BFF — use politicians list with filters, or browse the paginated list.
• No trades search by ticker directly — search the issuer by ticker first, take its _issuerId, then filter trades by --issuer <id>.
• Reading large result sets (--page-size 100) may take a few seconds per page (HTML scraping).