# StockLeaderboard Agent API

StockLeaderboard.com exposes read-only market-scanner data for agents. The data is informational and time-sensitive. It is not investment advice and does not place trades.

## Recommended Workflow

1. Fetch the live unusual-volume leaderboard with `limit=100`.
2. Build a balanced shortlist of at most 10 symbols from multiple setup types:
   - Steady leaders with elevated relative volume and a durable gain.
   - Newly accelerating movers with a fresh volume inflection.
   - Larger-cap event-driven names when the catalyst is material.
   - Smaller speculative names when the user explicitly accepts their additional risk.
3. Fetch detailed relative-volume series, company profile, recent news, and earnings context for that shortlist.
4. Identify sector or industry clusters, possible catalysts, contradictory evidence, and names that were considered but excluded.
5. Return a ranked watchlist with timestamps, rationale, risks, uncertainty, and the confirmation needed before entry.

When evidence is otherwise comparable, prefer larger market-capitalization companies because a similar move generally requires more money flow. Do not treat the displayed market-cap score as a complete size comparison: that component is capped at $1 billion.

Do not over-weight the newest or most dramatic microcap spike. A stock with a stable elevated relative-volume profile and a manageable pullback can be a better candidate than a headline mover that is already extended. When the user asks for repeated scans during the same morning, compare the new snapshot with earlier snapshots and explain meaningful rotation.

## Premarket Interpretation

During premarket analysis:

- Use `previous_close_pnl` for the daily move relative to the prior regular-session close.
- Use `open_pnl` to describe the move since the first current-session bar.
- Distinguish a stock that is extended versus the prior close from one that is extended within its current-session range.
- Use detailed relative-volume points to classify attention as steadily building, newly accelerating, stable, or fading.
- Treat missing bid/ask spread, chart support, float, halt status, and execution-quality data as explicit uncertainty.
- Use limit-order language for speculative premarket names. Do not provide a blind market-order instruction.

The scanner is a discovery tool. It does not determine an entry by itself.

## Suggested Morning Prompt

```text
Scan the live stock leaderboard for the best premarket day-trade watchlist candidates. Fetch the top 100 first, then inspect detailed volume trends and research news for a balanced shortlist of at most 10 symbols. Include both steady leaders and newly accelerating movers. Rank the best setups now, explain the catalyst and tape behavior, identify related sector clusters, and call out important names you considered but excluded. Use previous_close_pnl for the daily move and open_pnl for the move since the first current-session bar. Separate observed data from your judgment. Include the snapshot timestamp, risks, and what confirmation would be needed before entry. Do not place trades or imply certainty.
```

## JSON API

### Live Leaderboard

`GET https://trends.swamppond.com/api/leaderboard?limit=100`

Returns the current leaderboard with score components, cumulative volume, historical average volume, relative-volume ratio, daily gain relative to the prior regular-session close, gain since the first current-session bar, raw market capitalization, recent relative-volume points, snapshot age, and stale-data status.

Use `previous_close_pnl` for the TradingView-style daily move. `open_pnl` is retained
for intraday context and measures the move since the first current-session bar.

`limit` is clamped to `1..100`.

### Shortlist Research

`GET https://trends.swamppond.com/api/research?symbols=AAPL,TSLA&news_limit=5`

Returns cached company profiles plus recent ticker-specific news and earnings data. At most 10 ticker symbols are accepted. `news_limit` is clamped to `0..10`.

### OpenAPI

`GET https://trends.swamppond.com/openapi.json`

## MCP

Connect ChatGPT or Codex to:

`https://trends.swamppond.com/mcp`

The MCP server advertises:

- `scan_live_volume_leaders(limit = 100)`
- `get_volume_leader_details(symbols)`
- `research_stocks(symbols, news_limit = 5)`

Use `scan_live_volume_leaders` first, then call `get_volume_leader_details` and
`research_stocks` for a bounded shortlist of at most 10 symbols.