Unusual Whales API - Unusual Trades endpoints (UnusualTradesController)

Unusual Whales API - Unusual Trades endpoints

Important naming clarification. Despite the controller name “UnusualTradesController”, these endpoints serve Congressional unusual trades, not unusual options trades. The actual paths are under /api/congress/unusual-trades/*.

This is NOT the options-flow unusual activity feed - that lives in uw-api-option-trade (/api/option-trades/flow-alerts).

Layer mapping: L3 only. This is yet another view on Congressional disclosures, with the added layer of UW’s “unusual” classification on top of the raw uw-api-congress and uw-api-politician-portfolios data.

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": [...] } or { "data": {...} }
Status codes	200, 422, 500

2. Endpoint matrix

#	Path	Purpose
1	GET /api/congress/unusual-trades	Congressional trades flagged unusual
2	GET /api/congress/unusual-trades/by-tickers	Filtered to specific tickers
3	GET /api/congress/unusual-trades/chart-data	Time-series for charting
4	GET /api/congress/unusual-trades/stats	Aggregate statistics across politicians, parties, chambers, committees, industries, top tickers

3. GET /api/congress/unusual-trades - Recent

Cross-politician feed of trades flagged unusual.

Query parameters:

Param	Type	Default	Range
types	string	all	Comma-separated unusual-activity tag filter
limit	int	100	1 to 500
page	int	1	1-indexed

Response per record:

Field	Type	Description
amount	string	Range, e.g. "$1,001 - $15,000"
asset	string	Full asset name (e.g. "NVIDIA Corp - Common Stock")
asset_type	string	E.g. "stock"
company_name	string	Company name
description	string	Trade details

Use: filtered subset of uw-api-congress /recent-trades, restricted to politically-noteworthy trades by some UW criteria. The types taxonomy (what makes a trade “unusual” here) is NOT enumerated in the docs - first real fetch must catalog.

4. GET /api/congress/unusual-trades/by-tickers

Same shape, filtered by ticker.

Query parameters (inferred): tickers (comma-separated), limit, page.

Use: “show me unusual congressional trades in NVDA, AAPL, TSLA”. Drill-in tool.

5. GET /api/congress/unusual-trades/chart-data

Time-series for charting.

Response (inferred): aggregated counts or notionals over time buckets, suitable for plotting.

Use: for dashboards / visualizations of congressional unusual activity volume over time. Not a signal feed.

6. GET /api/congress/unusual-trades/stats

Aggregate statistics across multiple dimensions.

Response per record:

Field	Type	Description
data	object	Aggregated stats payload
date	string	Date of snapshot
type	string	Stat type (e.g. "overview")

Statistics dimensions (per docs):

• Top politicians by activity
• Party + chamber breakdowns
• Committee group classifications
• Industry sector groupings
• Most-traded tickers
• Biggest individual trades
• Daily trading volumes (with SPY benchmark comparison)

Use: L3 dashboard / context only. The SPY benchmark comparison is mildly interesting (does aggregate congressional buying lead SPY?), but the cadence and aggregation kill realtime utility.

7. MK3 use

Not in current scope. Filed for L3 future.

When L3 trend strategies are built, this controller adds a pre- classified layer on top of uw-api-congress - someone (UW) already flagged the “unusual” patterns, saving the work of building a classifier on raw Congress data.

Potential L3 use:

• Subscribe to /recent weekly, filter to asset_type=stock and large amount bands, build a “high-conviction unusual Congress trades” watchlist.
• Use /stats to identify trending industries / tickers across the Congress signal cohort - if multiple unusual trades cluster in one sector, that’s stronger than any single transaction.

8. Distinction from neighbors

Endpoint	Scope	What’s added
uw-api-congress /recent-trades	All Congress trades	Raw transaction feed, no UW filtering
uw-api-politician-portfolios /recent-trades	All Congress trades (overlap with above)	Positional context (current holdings)
uw-api-unusual-trades (this page)	Congress trades flagged unusual	Pre-classified subset
uw-api-option-trade /flow-alerts	Options market	Unrelated despite similar naming

9. Nautilus integration shape (when L3 lands)

• Daily polling Actor: UWCongressUnusualActor pulls /recent once per day. Cross-references with the raw /api/congress/recent-trades feed for full context.
• Stats endpoint pulled weekly for dashboard / postmortem use.

10. Known gaps

• types enum not documented. What makes a Congress trade “unusual” by UW’s criteria is unclear. First fetch should pull with types= empty and inspect the response - records might tag their own classification.
• /stats response shape mostly opaque. data: null in the example.
• Significant overlap with uw-api-congress and uw-api-politician-portfolios. Three controllers now expose Congress data with different framings. Document the exact semantic boundaries on first real fetch.
• Naming hazard. Controller is “UnusualTradesController” but it’s all Congress-scoped. Anyone reading the endpoint list looking for the options unusual-activity feed will land here by mistake - redirect them to uw-api-option-trade’s /flow-alerts.

11. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.recent
• https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.by_tickers
• https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.chart_data
• https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.stats

cortana-north-star uw-api-congress uw-api-politician-portfolios uw-api-option-trade