> ## Documentation Index
> Fetch the complete documentation index at: https://docs.struct.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Finding market movers

> Surface markets that just moved, gauge platform-wide momentum, and chart per-bucket activity using the markets and analytics REST endpoints.

A market mover is anything that just shifted hard: a probability that jumped, platform volume that accelerated, or a bucket of activity that spiked above its neighbors. Struct exposes three REST endpoints that cover these angles. `markets.getPriceJumps` finds sharp probability moves inside one market's candle history, `analytics.getChanges` reports platform-wide percentage momentum, and `analytics.getDeltas` returns a per-bucket activity series you can render as a sparkline.

## When to use this

* Movers rails and "biggest moves today" widgets.
* Alerting when a market's implied probability swings past a threshold.
* Dashboard headline numbers that show whether the platform is heating up or cooling down.
* Sparklines that summarize recent platform activity at a glance.

## Sharp price moves in a market

Use `GET /v1/polymarket/market/price-jumps` to detect candles where a market's probability moved more than a threshold. Pass either `condition_id` or `market_slug` (one is required). The `resolution` is the candle size in minutes (`"1"`, `"5"`, `"15"`, `"30"`, `"60"`, `"240"`, default `"15"`), `min_change_pct` is the minimum move to report (default `10.0`), and `lookback` is how many candles back to scan (default `1440`, max `2500`).

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: jumps } = await client.markets.getPriceJumps({
    condition_id: "0xCONDITION",
    resolution: "15",
    min_change_pct: 10,
    lookback: 1440,
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/market/price-jumps?condition_id=0xCONDITION&resolution=15&min_change_pct=10&lookback=1440" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/market/price-jumps",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={
          "condition_id": "0xCONDITION",
          "resolution": "15",
          "min_change_pct": 10,
          "lookback": 1440,
      },
  )

  jumps = response.json()["data"]
  ```
</CodeGroup>

Each `PriceJump` row describes one move: `from` and `to` are the start and end timestamps (epoch seconds), `price_before` and `price_after` are the probabilities at each end, `change_pct` is the magnitude of the move, `direction` indicates whether it rose or fell, and `volume` and `trades_count` quantify how much trading drove it. The `condition_id` echoes the market so you can key the row in a list.

## Platform-wide momentum

Use `GET /v1/polymarket/analytics/changes` for a single snapshot of how the whole platform is trending. The only parameter is `timeframe` (`"1h"`, `"24h"`, `"7d"`, `"30d"`, `"1mo"`, `"1y"`, default `"24h"`).

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: changes } = await client.analytics.getChanges({
    timeframe: "24h",
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/analytics/changes?timeframe=24h" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/analytics/changes",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"timeframe": "24h"},
  )

  changes = response.json()["data"]
  ```
</CodeGroup>

The `AnalyticsMetricPctChange` response returns percentage changes for the headline platform metrics: `volume_usd`, `unique_traders`, `txn_count`, `fees_usd`, and related fields. Each value is the percentage move over the chosen timeframe, so positive numbers mean the platform is heating up. These map directly onto dashboard headline tiles.

## Per-bucket activity sparkline

Use `GET /v1/polymarket/analytics/deltas` for a time series of platform activity you can plot as a sparkline. The `resolution` controls bucket size (`"60"`, `"240"`, `"D"`, `"W"`, `"M"`, default `"60"`), and `from`, `to`, and `count_back` bound the window.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: deltas } = await client.analytics.getDeltas({
    resolution: "60",
    count_back: 168,
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/analytics/deltas?resolution=60&count_back=168" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/analytics/deltas",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"resolution": "60", "count_back": 168},
  )

  deltas = response.json()["data"]
  ```
</CodeGroup>

Each `AnalyticsTimeBucketRow` uses compact keys to keep the series small. They expand as follows:

| Key  | Meaning                          |
| ---- | -------------------------------- |
| `t`  | Bucket timestamp (epoch seconds) |
| `v`  | Volume in USD for the bucket     |
| `tc` | Transaction count                |
| `ut` | Unique traders                   |
| `f`  | Fees in USD                      |
| `bv` | Buy volume in USD                |
| `sv` | Sell volume in USD               |

Plot `v` for an activity sparkline, or compare `bv` against `sv` to show whether buying or selling pressure dominated each bucket.

## Push-based movers

The endpoints above are pull-based: you call them to find what already moved. For push-based movers that arrive as they happen, subscribe to the websocket spike alerts instead. The relevant alerts are [`price_spike`](/websockets/alerts/price-spike) for sharp probability moves, [`market_volume_spike`](/websockets/alerts/market-volume-spike) and [`event_volume_spike`](/websockets/alerts/event-volume-spike) for surges in trading volume, and [`position_volume_spike`](/websockets/alerts/position-volume-spike) for individual positions. Use REST to seed a movers list, then keep it live with the spike alerts.