PhoenixPerpetualsDocs API v1
Get an API key

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.

View as Markdown

On this page
  1. Set one
  2. When it fires
  3. Move, arm again, delete
  4. Limits

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, 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:
{
  "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#

CallWhat it does
PATCH .../alerts/{alert_id} with price, note or bothMoves 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}/rearmArms an alert that fired (or was disabled) again at its level, its condition from the price now
DELETE .../alerts/{alert_id}Deletes it
GET .../alertsLists 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.

Guides, endpoints, fields and error codes.