# Price alerts

Be told once when a market reaches your level, on the account stream, by webhook and in the event log. An alert never trades.

A price alert is a level on a market, set on one of your accounts. When the market's price reaches it, you are told once: an `alert.triggered` event on the [account stream](/guides/streams), to your [webhooks](/guides/webhooks) (the `alerts` group), and in `GET /v1/events`. An alert never places, changes or cancels an order, so a read-only key may set them.

## Set one

`POST /v1/accounts/{account_id}/alerts`, with an `Idempotency-Key` header:

```json
{
  "market": "BTC-USD",
  "price": "120000",
  "note": "breakout"
}
```

The answer is the alert, `armed`. Its `condition` is set from the price now: `above` when your level is above it (it fires once the price rises to the level), `below` when it is below. A level equal to the price now has no side and is refused with `alert_at_price`, which gives the price in `details.last_price`.

The price an alert watches is the market's last trade (the middle of the book until there is one): the same price trailing stops follow, the one the trade page shows.

## When it fires

- **Once.** The alert turns `triggered`, with `trigger_price` (the price that reached it) and `triggered_at`. A fast market can jump past your level: it fires on the first price at or beyond it, and `trigger_price` says which.
- **The event** carries the alert as it was when it fired:

```json
{
  "id": "evt_01JAB7Q8XK4M2N5P7R9S3T5V7W",
  "type": "alert.triggered",
  "account_id": "SANDBOX-00042-001",
  "time": 1791460800000,
  "source": "api",
  "data": { "alert": { "id": "alr_01JAB7Q8XK4M2N5P7R9S3T5V7W", "market": "BTC-USD", "price": "120000", "condition": "above", "status": "triggered", "trigger_price": "120004.5" } }
}
```

- **While market prices pause**, nothing fires; the first price after the pause fires a level it crossed meanwhile.
- **A restart** of the trading servers changes nothing: alerts live on our servers and keep waiting.

## Move, arm again, delete

| Call | What it does |
|---|---|
| `PATCH .../alerts/{alert_id}` with `price`, `note` or both | Moves an armed alert. A new level sets its condition again from the price now. An alert that fired answers `alert_not_armed`: arm it again first |
| `POST .../alerts/{alert_id}/rearm` | Arms an alert that fired (or was disabled) again at its level, its condition from the price now |
| `DELETE .../alerts/{alert_id}` | Deletes it |
| `GET .../alerts` | Lists them, newest first; filter with `status` (`armed`, `triggered`, `disabled`) and `market` |

An alert that fired, or was disabled, stays listed for 90 days. It is `disabled` when its account or its market went away before it fired (`disabled_reason`).

## Limits

An account holds 25 armed alerts at once, and you hold 100 across your accounts. Past that, a new one is refused with `alert_limit`, its `details` naming the limit. A key limited to some markets reaches the alerts on those markets only. `GET /v1/limits` gives these numbers under `alerts`.
