> ## 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.

# Price Spike

> Get notified when a position's raw trade price changes rapidly.

<Note>
  **Event:** `price_spike` \
  **Endpoint:** `wss://api.struct.to/ws/alerts` \
  **Cost:** 0.2 credits per event
</Note>

Get notified when a position's raw trade price changes rapidly. Configure the observation window and minimum change percentage to control sensitivity.

## Filters

| Filter                      | Type      | Required | Description                                                                                                        |
| --------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `condition_ids`             | string\[] | No       | Restrict to specific conditions (max 500)                                                                          |
| `event_slugs`               | string\[] | No       | Restrict to specific events (max 500)                                                                              |
| `position_ids`              | string\[] | No       | Restrict to specific positions (max 500)                                                                           |
| `outcomes`                  | string\[] | No       | Filter by outcome name, e.g. `["Yes", "No"]` (max 500)                                                             |
| `tags`                      | string\[] | No       | Restrict to markets carrying any of these tags or category names, case-insensitive (max 500)                       |
| `series_slugs`              | string\[] | No       | Restrict to markets in any of these series by slug, case-insensitive (max 500)                                     |
| `min_price`                 | number    | No       | Lower bound for both baseline and current price (0.0-1.0). Useful for excluding moves into resolution extremes     |
| `max_price`                 | number    | No       | Upper bound for both baseline and current price (0.0-1.0)                                                          |
| `min_price_change_pct`      | number    | No       | Minimum price change percentage (0-100)                                                                            |
| `min_txns`                  | integer   | No       | Minimum number of trades accumulated in the current window before a spike can fire                                 |
| `min_volume_usd`            | number    | No       | Minimum USD volume accumulated in the current window before a spike can fire                                       |
| `spike_direction`           | string    | No       | Direction filter: `up`, `down`, or `both`. Defaults to `up` when omitted                                           |
| `window_secs`               | number    | No       | Observation window in seconds (1-600). Also acts as the cooldown between fires for the same position (minimum 30s) |
| `exclude_shortterm_markets` | boolean   | No       | Exclude short-term `updown` markets from results                                                                   |

<Tip>
  **Scope by market taxonomy.** `tags` matches a market's own tags **or** its category, given as the display label shown on Polymarket (for example `"Sports"`, `"Politics"`, or `"FIFA World Cup"`), not a slug. `series_slugs` matches the market's parent series by slug (for example `"nba-finals"`). Both are case-insensitive, accept up to 500 values each, and an empty or omitted list applies no taxonomy restriction.
</Tip>

## Subscribe

```json theme={null}
{
  "op": "subscribe",
  "event": "price_spike",
  "min_price_change_pct": 15,
  "spike_direction": "up",
  "window_secs": 120
}
```

## Response

```json theme={null}
{
  "event": "price_spike",
  "timestamp": 1775913505260,
  "data": {
    "position_id": "0xabc123",
    "condition_id": "0x1234567890abcdef",
    "question": "Will the Fed cut rates in December?",
    "market_slug": "fed-decision-december-2028",
    "event_slug": "us-presidential-election-2028",
    "image_url": "https://polymarket-upload.s3.us-east-2.amazonaws.com/example.png",
    "outcome": "Yes",
    "outcome_index": 0,
    "previous_price": 0.52,
    "current_price": 0.68,
    "spike_direction": "up",
    "spike_pct": 30.77
  }
}
```