Unusual Whales API - Politician Portfolios endpoints
Layer mapping: L3 only. Companion / complement to uw-api-congress. The Congress controller returns trade disclosures (per-transaction); this Politician Portfolios controller returns portfolio snapshots (current holdings) plus the politician directory.
Same STOCK Act constraints as Congress: 45-day max filing lag, weekly-to-monthly signal horizon at best, wrong cadence for 0DTE. Filed for L3 future work.
1. Base contract
| Property | Value |
|---|---|
| Base URL | https://api.unusualwhales.com |
| Auth | Authorization: Bearer <token> header |
| Response envelope | { "data": [...] } |
| Status codes | 200, 422, 500 |
2. Endpoint matrix
| # | Path | Purpose |
|---|---|---|
| 1 | GET /api/politician-portfolios/{politician_id} | Per-politician portfolio snapshot (stocks + options + crypto) |
| 2 | GET /api/politician-portfolios/disclosures | Cross-politician disclosures feed |
| 3 | GET /api/politician-portfolios/holds-ticker | Politicians holding a specific ticker |
| 4 | GET /api/politician-portfolios/people | Politician directory + metadata |
| 5 | GET /api/politician-portfolios/recent-trades | Recent transactions across politicians |
Relationship to uw-api-congress:
| Concern | Politician Portfolios | Congress |
|---|---|---|
| Current holdings snapshot | Yes (/portfolios, /holds-ticker) | No |
| Per-trade history | /recent-trades, /disclosures | /recent-trades, /congress-trader |
| Politician directory | /people | /politicians |
| Late filings flag | (inferred, not documented) | /late-reports |
Overlap is significant. Treat Politician Portfolios as the positional view, Congress as the flow view.
3. GET /api/politician-portfolios/{politician_id} - Per-politician
Snapshot of one politician’s declared holdings across asset classes.
Path parameter:
| Param | Required | Notes |
|---|---|---|
politician_id | yes | UUID |
Query parameter:
| Param | Type | Required | Default |
|---|---|---|---|
aggregate_all_portfolios | bool | no | false |
When aggregate_all_portfolios=true, the response collapses self,
spouse, and dependent-child portfolios into a single “aggregated”
portfolio.
Response per portfolio:
| Field | Type | Description |
|---|---|---|
id | string | Portfolio ID |
owner | string | self, spouse, dependent, or aggregated |
last_annual_disclosure | int | Year of most recent filing |
stock_holdings | array | Stock positions |
option_holdings | array | Option positions |
crypto_holdings | array | Crypto positions |
Per holding (stocks; options + crypto follow similar pattern):
| Field | Type | Description |
|---|---|---|
ticker | string | Symbol |
type | string | E.g. stock |
min_amount | int | Lower bound on valuation ($K) |
mid_amount | int | Midpoint valuation ($K) |
max_amount | int | Upper bound on valuation ($K) |
Valuation in ranges, not exact dollars - same STOCK Act range
disclosure pattern as Congress amounts.
4. GET /api/politician-portfolios/disclosures
Cross-politician disclosures feed.
Query parameters (inferred from pattern): politician_id,
ticker, start_date, end_date, limit, page.
Response per record: filing details linking a politician to a disclosed position or transaction.
5. GET /api/politician-portfolios/holds-ticker
Inverse lookup: which politicians hold a specific ticker.
Query parameters (inferred): ticker (required), min_amount
(filter to holdings of size N+), limit, page.
Use: “which Congress members are long NVDA?” - useful for L3 sector-rotation signals and political-position-clustering analyses.
6. GET /api/politician-portfolios/people
Politician directory + metadata.
Response per politician (inferred): id, name,
member_type (house/senate), party, state,
first_filing_date, last_filing_date, total_positions_count.
Use: roster construction. Cross-reference with party affiliation and committee membership (likely not in UW’s data directly - need external source like the House Clerk or Senate ethics office).
7. GET /api/politician-portfolios/recent-trades
Recent transaction feed across politicians.
Response: identical or near-identical to
uw-api-congress/recent-trades. Likely the same underlying
data with a different controller routing.
8. MK3 use
Not in current scope. Filed for L3 trend strategies.
Plausible L3 plays once built:
- Ticker-concentration signal: 5+ politicians acquire the same name in the same week. Strong cluster signal.
- Portfolio-overlap basket: “stocks held by the top-20 most- active Congressional traders” - a thematic basket with documented bias to political-economy plays.
- New-entrant detection: politician with no prior holdings in ticker X just disclosed a position. Stronger signal than adding to existing position.
9. Nautilus integration shape (when L3 lands)
Single daily polling Actor: UWPoliticianActor pulls
/recent-trades once per day. The portfolio snapshots (/portfolios,
/holds-ticker) update on filing cycles (irregular), so polling
weekly is enough.
10. Known gaps
- Significant overlap with uw-api-congress. Document the
exact semantic differences on first real fetch:
- Is
/politician-portfolios/recent-tradesthe same data as/congress/recent-tradeswith different routing? - Does
/portfoliosgive cleaner inventory than aggregating/congress/congress-traderover time?
- Is
amountsis a range ($K min / mid / max), same as Congress.- Asset classes: includes options + crypto unlike Congress.
/disclosuresresponse shape inferred - first fetch should confirm.
11. Source URLs
https://api.unusualwhales.com/docs/operations/PublicApi.PoliticianPortfoliosController.portfolioshttps://api.unusualwhales.com/docs/operations/PublicApi.PoliticianPortfoliosController.disclosureshttps://api.unusualwhales.com/docs/operations/PublicApi.PoliticianPortfoliosController.holds_tickerhttps://api.unusualwhales.com/docs/operations/PublicApi.PoliticianPortfoliosController.peoplehttps://api.unusualwhales.com/docs/operations/PublicApi.PoliticianPortfoliosController.recent_trades
cortana-north-star uw-api-congress uw-api-insiders uw-api-institutional