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

> Fire a webhook when a position's raw trade price moves sharply within a look-back window.

<Note>
  **Event:** `price_spike` \
  **Cost:** 0.2 credits per delivery
</Note>

The `price_spike` event fires when a position's raw trade price (not enriched probability) changes by at least your configured percentage within a look-back window. The full payload schema is in the auto-generated [Price Spike callback](/api-reference/webhook-callbacks/price-spike-callback) reference; this page documents the filters and matching behavior.

## When to use this

* Track abrupt moves in the underlying trade price rather than the enriched probability.
* Alert on price swings only within a probability band you care about.
* Filter out thin moves by requiring minimum transaction and volume activity.

## Subscription filters

Add these to the `filters` object when you create the subscription.

| Filter                      | Type      | Description                                                                                   |
| --------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `position_ids`              | string\[] | Restrict to specific outcome tokens by position ID (max 500).                                 |
| `condition_ids`             | string\[] | Restrict to specific markets by condition ID (max 500).                                       |
| `event_slugs`               | string\[] | Restrict to specific events by slug (max 500).                                                |
| `outcomes`                  | string\[] | Restrict by outcome name, e.g. `["Yes", "No"]` (max 500).                                     |
| `tags`                      | string\[] | Restrict to markets carrying any of these tags or category names, case-insensitive (max 500). |
| `series_slugs`              | string\[] | Restrict to markets in any of these series by slug, case-insensitive (max 500).               |
| `min_price_change_pct`      | number    | Minimum price change, as a percentage.                                                        |
| `min_price`                 | number    | Minimum outcome probability, `0.0`–`1.0`.                                                     |
| `max_price`                 | number    | Maximum outcome probability, `0.0`–`1.0`.                                                     |
| `min_txns`                  | integer   | Minimum transaction count.                                                                    |
| `min_volume_usd`            | number    | Minimum traded volume in USD.                                                                 |
| `spike_direction`           | string    | Direction to match: `up`, `down`, or `both`.                                                  |
| `window_secs`               | integer   | Look-back window in seconds (`1`–`600`).                                                      |
| `exclude_shortterm_markets` | boolean   | Exclude short-term Up/Down markets.                                                           |

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

## Example

```json theme={null}
{
  "url": "https://your-server.com/webhooks",
  "event": "price_spike",
  "filters": {
    "min_price_change_pct": 8,
    "spike_direction": "up",
    "window_secs": 120,
    "min_txns": 5
  }
}
```

## Notes

* `window_secs` sets the look-back window (`1`–`600` seconds) over which the change is measured.
* `spike_direction` controls which moves match: `up`, `down`, or `both`. Defaults to `up` when omitted.