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

# Bond-zone alerts

> Get notified the moment an outcome becomes near-certain, trading at the extremes of the probability range, over webhooks or websockets.

A "bond zone" is the near-certain end of a market: an outcome trading at, say, ≥ 95¢ (almost certain to win) or ≤ 5¢ (almost certain to lose). The `close_to_bond` event fires when a trade prints inside a zone you define, so you can react to outcomes that are effectively resolved before the oracle settles them.

The same event and filters are available two ways:

| Transport | How it arrives                | Reference                                                 |
| --------- | ----------------------------- | --------------------------------------------------------- |
| Webhook   | HTTP `POST` to your endpoint  | [`close-to-bond` callback](/webhooks/close-to-bond)       |
| Websocket | Pushed over a live connection | [`close_to_bond` alert](/websockets/alerts/close-to-bond) |

## When to use this

* **Resolution front-running:** surface markets the crowd already treats as decided, ahead of on-chain settlement.
* **Risk / exit signals:** alert when a position you hold flips to near-certain-loss so you can exit the remaining size.
* **Mispricing scans:** watch one side of a market for prints at the opposite extreme of where you think it should trade.

## Defining the bond zone

The bond zone is defined entirely by how you combine `min_price` and `max_price`. The **relationship between the two values** selects one of four modes:

| You set                    | Mode             | Fires when                                     | `bond_side`         |
| -------------------------- | ---------------- | ---------------------------------------------- | ------------------- |
| `min_price` only           | Single high edge | `price ≥ min_price`                            | `"high"`            |
| `max_price` only           | Single low edge  | `price ≤ max_price`                            | `"low"`             |
| Both, with **`min < max`** | Bounded range    | `min_price ≤ price ≤ max_price`                | `"high"`            |
| Both, with **`min > max`** | Two edges        | `price ≥ min_price` **or** `price ≤ max_price` | `"high"` or `"low"` |

<Warning>
  **`min < max` is a band, not a bond.** If you set `min_price: 0.75` and `max_price: 0.90`, you do **not** get "fires above 90% or below 75%". Because `min < max`, it switches to bounded-range mode and fires only when the price lands **inside** the 75–90% band. To alert on the two near-certain extremes, you must set `min > max` (see below).
</Warning>

## Alerting on near-certain outcomes

To get notified when an outcome becomes near-certain in **either** direction (at or above 90% **or** at or below 10%), set `min_price` **higher** than `max_price`:

```json theme={null}
{
  "min_price": 0.90,
  "max_price": 0.10
}
```

Because `0.90 > 0.10`, this is read as two separate edges. A trade at 96¢ fires with `bond_side: "high"`; a trade at 4¢ fires with `bond_side: "low"`. For a single edge, set just one of the two.

## How price is read

* The traded position's own `price` is used: the price of the exact outcome token (`position_id`) that printed.
* Trades at a price of exactly `0` or `1` are skipped, since there is no remaining risk to alert on.
* `price` is on a `0.0`–`1.0` scale (so 95¢ = `0.95`).

## Picking the right side

On a binary market, "YES at ≤10%" and "NO at ≥90%" are the **same** event priced from opposite tokens. If you add `position_outcome_indices: [0]` you will only ever see trades that print on the **Yes/Up** token (index `0`); trades on the No token (index `1`) won't fire even when they hit the same bond zone. Omit `position_outcome_indices` to catch the zone regardless of which side the trade prints on.

## Examples

A near-certain-win alert for one specific market, Yes side only:

```json theme={null}
{
  "condition_ids": ["0x19b3cbe24efa387cac21271dd869cb1121432cd212308f3a6e3ec2f7a8614b9d"],
  "min_price": 0.95,
  "position_outcome_indices": [0]
}
```

Near-certain wins across whole categories, scoped by `tags`:

```json theme={null}
{
  "min_price": 0.95,
  "tags": ["Sports", "Crypto Prices"],
  "position_outcome_indices": [0]
}
```

`tags` matches a market's tags or its category by display label (for example `"Sports"`, `"Crypto Prices"`), case-insensitive.

Both extremes, scoped to the Yes/Up token so each event alerts once:

```json theme={null}
{
  "min_price": 0.90,
  "max_price": 0.10,
  "position_outcome_indices": [0],
  "exclude_shortterm_markets": true
}
```

<Warning>
  **Two-edge mode (`min_price` > `max_price`) fires from both tokens.** On a near-certain market the Yes token near 90¢ triggers `bond_side: "high"` and the No token near 10¢ triggers `bond_side: "low"`, so each event arrives as two separate deliveries. Add `position_outcome_indices: [0]` (Yes/Up only) to watch one side and get one delivery per extreme.
</Warning>

## Reading the payload

Every delivery tells you which zone was hit and the threshold it breached:

* `bond_side`: `"high"` (near-certain) or `"low"` (near-zero).
* `threshold`: the filter value that was breached. In bounded-range mode this is `min_price`.
* `price`: the value that triggered the alert, on a `0.0`–`1.0` scale.

See the full field list on the [websocket alert page](/websockets/alerts/close-to-bond#response).

## Available filters

| Filter                      | Type      | Description                                                                                   |
| --------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `min_price`                 | number    | High-edge / lower bound of the zone, `0.0`–`1.0`.                                             |
| `max_price`                 | number    | Low-edge / upper bound of the zone, `0.0`–`1.0`.                                              |
| `condition_ids`             | string\[] | Restrict to specific markets (max 500).                                                       |
| `position_ids`              | string\[] | Restrict to specific outcome tokens (max 500).                                                |
| `outcomes`                  | string\[] | Restrict by outcome name, e.g. `["Yes", "No"]` (max 500).                                     |
| `position_outcome_indices`  | number\[] | Restrict by outcome index: `0` (Yes/Up) or `1` (No).                                          |
| `event_slugs`               | string\[] | Restrict to specific events (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).               |
| `exclude_shortterm_markets` | boolean   | Exclude short-term Up/Down markets.                                                           |

<Note>At least one of `min_price` or `max_price` is required. Without either, every trade in every market would fire.</Note>

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