Trading
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, to your 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:
{
"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, withtrigger_price(the price that reached it) andtriggered_at. A fast market can jump past your level: it fires on the first price at or beyond it, andtrigger_pricesays which. - The event carries the alert as it was when it fired:
{
"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.