Alerts

Alerts the user sets on prices, spreads and games, the alerts list, and the notification history (/alerts and /notifications). Built in Phase 4 against the contract in api/openapi.yaml (Alert, CreateAlertRequest, UpdateAlertRequest, Notification). How a fired alert is delivered (toast, desktop, sound, Telegram) is in notifications.md. Wireframe notation (README.md): [name] in lower case is a lucide icon, [Label] is a button, [ ] is a checkbox, (dot) is a 6 px status dot.

Alert kinds

`alert_kind`	Name in the UI	Fires when	Target
`price`, `cross_direction: above`	Price alert	The best bid reaches the threshold or higher (the outcome can be sold there)	`token_id`
`price`, `cross_direction: below`	Price alert	The best ask reaches the threshold or lower (the outcome can be bought there)	`token_id`
`spread`, `above`	Spread alert	Ask minus bid widens to the threshold or more	`token_id`
`spread`, `below`	Spread alert	Ask minus bid narrows to the threshold or less	`token_id`
`score`	Score change	Each change of the game’s score	`game_id`
`game_start`	Game start	The game goes live	`game_id`
`game_end`	Game end	The game ends	`game_id`

Trigger rules

These come from the contract; the UI states them and never works around them.

Above uses the best bid, below uses the best ask. The form labels say so (Bid at or above, Ask at or below), so the user knows which side of the book is watched.
Thresholds sit on the market’s tick. The price input steps by the tick and the backend refuses off-tick prices (validation_failed). Spread thresholds are in cents too.
Repeat. Off: the alert fires once and becomes triggered. On: it fires, then re-arms once the value moves one tick back across the threshold (a bid alert at 60¢ re-arms when the bid falls to 59¢). Repeat applies to price, spread and score alerts; game start and game end fire once by nature, so the form hides Repeat for them.
Stale feeds never fire. A price or spread alert does not fire while its book is stale, and a game alert does not fire while the sports feed is stale. The list greys the current value; nothing is filled from another source.
Restart. Alerts persist and resume from the live books after a backend restart. They do not fire on the first snapshot unless the condition newly holds.
Limit. At most 200 alerts exist at once, in any status.
Alerts work in Safe, with trading off and while geoblocked: they place no orders.

Condition text

One format everywhere: the list, the create toast, the ladder tooltip and the notification body (notifications.md).

Kind	Condition text	Example
Price, above	`{outcome} bid at or above {price}`	`Lakers bid at or above 60¢`
Price, below	`{outcome} ask at or below {price}`	`Lakers ask at or below 40¢`
Spread, above	`{outcome} spread at or above {price}`	`Lakers spread at or above 4¢`
Spread, below	`{outcome} spread at or below {price}`	`Lakers spread at or below 1¢`
Score	`Score change`	`Score change`
Game start	`Game start`	`Game start`
Game end	`Game end`	`Game end`

{outcome} is the outcome name. For Yes and No outcomes it is {market} · {outcome} (Fed decision December · Yes), with the market title truncated. The market or game title (the alert’s title) shows in its own column or line, never inside the condition.

Creating an alert

Every entry point prefills the form, so the common case is one click. Creating works in Safe and with trading off.

Entry point	Desktop	Mobile	Result
Ladder level	Hover a level: a `[bell]` icon button appears in that row’s P&L cell. Click it	Long-press a level: action sheet item `Set alert at 42¢`	Creates at once with the defaults below; toast with `Undo`
Ladder level, keyboard	`Alt+Enter` at the keyboard cursor, or Alt+click a Bid or Ask cell	none	Same
Board game	Row menu (right-click, or the hover-revealed `[ellipsis]`): `Alert on score change`, `Alert at game start`, `Alert at game end`	Long-press the card, or the card’s `[ellipsis]`: same items	Creates at once; toast with `Undo`
Market view	`[bell]` in the header (tooltip `Set alert…`)	`[ellipsis]` menu item `Set alert…`	Opens the form, prefilled with the selected outcome
Alerts screen	`Set alert…` in the header	Same	Opens the form with a market search field

From a ladder level (one click)

The [bell] shows only on the hovered row (or the keyboard-cursor row), at the left edge of the P&L cell: a 16 × 16 icon button holding the 16 px icon with no padding, --muted-foreground, on the row’s hover background. A 20 px button overlapped the P&L value in narrow ladders, so the button is the icon’s size. The P&L value keeps its place on the right of the cell; the bell is absolutely positioned and takes no width from it. On touch the marker is 32 px with a 44 px hit area.
Tooltip and accessible name: Set alert at 42¢.
Defaults: alert_kind: price, the ladder’s outcome, price = the level, repeat: false, and the direction from the level’s side of the book:
- level above the midpoint: above (fires when the bid rises to it);
- level at or below the midpoint: below (fires when the ask falls to it). So the condition never holds at the moment it is set. With one side of the book empty, the last trade stands in for the midpoint; with no book, the bell is hidden.
The toast reads Alert set · Lakers bid at or above 60¢ with Undo (5 s). Undo deletes the alert.
Level marker. A level with an active or paused alert shows the [bell] permanently in the same place (--muted-foreground; paused uses bell-off). Clicking it opens the edit form. Tooltip: Edit alert · Lakers bid at or above 60¢. A triggered one-shot alert shows no marker. The space is always reserved, so a marker never moves the row.
A level with two alerts (above and below) shows one marker; clicking it opens the first, and the form lists the other as 1 more alert at this price with a link to the list.
Mobile. The ladder sheet has no hover, so levels carry no bell until an alert exists. Long-press a level opens the action sheet: Set alert at 42¢ is its first item. Markers show as on desktop and a tap on the marker opens the edit sheet.

From the board (game alerts)

The game’s menu gets three checkbox items after Pin, separated by a divider: Alert on score change, Alert at game start, Alert at game end.
Choosing an unchecked item creates that alert (repeat: true for score change, since it exists to follow the game) and shows Alert set · Score change · Lakers v Celtics with Undo. Choosing a checked item deletes it, with the same undo toast as the list.
Alert at game start is disabled once the game is live (tooltip Game already live), and every item is disabled when the game has ended (Game ended).
Desktop: the menu opens from right-click on the game block and from an [ellipsis] icon button that appears on hover or focus at the right end of the game’s first line (in the +N column). Mobile: long-press the card, or the [ellipsis] in the card header, which touch keeps visible.

From the market view

The [bell] icon button in the market header opens the form, prefilled with the selected outcome; on mobile it is Set alert… in the [ellipsis] menu.
The price chart beside it labels its time axis in local 24-hour time (14:05; the day of the month, Sep or 2026 at day, month and year boundaries), the same clock as the Triggered and Set columns, so a triggered alert can be found on the chart. A label the plot’s edge would cut is left out rather than drawn in half. The same axis rule applies to the P&L chart on the portfolio.

The form (edit, and create from the market view or this screen)

A popover on desktop (360 px, anchored to the control that opened it), a bottom sheet on mobile. Controls are --control-h (32 px) on desktop and 44 px on touch, one per row, labels in a 72 px column on desktop and above the control on mobile.

 ┌────────────────────────────────────────────────┐
 │ Set alert                                  [x] │ 44 title
 │ Market   [Lakers v Celtics · ML              ] │ 32 search field (only from this screen)
 │ Type     [Price                [chevron-down]] │ 32 select
 │ Outcome  [ Lakers        | Celtics           ] │ 32 segmented
 │ When     [ Bid at or above | Ask at or below ] │ 32 segmented
 │ Price    [−] [   60¢   ] [+]   now 43¢         │ 32 tick stepper, current value
 │ Repeat   [ ] After one tick back               │ 32 checkbox
 │ Note     [                                   ] │ 32 text, 200 characters
 │                                    [Set alert] │ 44 footer, primary
 └────────────────────────────────────────────────┘

Every control spans the same 264 px field column, so the segments of one control share its width equally.

Type: Price, Spread, Score change, Game start, Game end. The game types are offered only when the market belongs to a game.
When (price and spread): price shows Bid at or above / Ask at or below; spread shows At or above / At or below. Game types hide When, Price and Outcome.
Price: a tick stepper and a typed input, in cents. now 43¢ shows the value the condition watches (the bid for above, the ask for below, the spread for spread alerts), muted, and greys with the book when stale.
Repeat: a checkbox labelled After one tick back (the re-arm rule). Hidden for game start and game end.
Footer: create shows one primary button, Set alert. Edit is titled Edit alert and shows Delete (ghost, left) and Save (primary, right). Esc and [x] close without saving; there is no Cancel button (Cancel is reserved for orders).
Validation under the field in --destructive body-sm: Price must be on the 1¢ tick, Price must be between 1¢ and 99¢. The server’s 400 message maps to the same lines.
Submit: the button shows its loading state; on success the popover closes and the toast Alert set · {condition} appears. On failure the popover stays with the error line reserved under the footer (20 px), e.g. Not set · 200 alerts, the maximum.

Create and update errors

Response	Text (toast for one-click, form line otherwise)
429 `limit_exceeded`	`Alert not set · 200 alerts, the maximum`
404 `not_found`	`Alert not set · market not found`
400 `validation_failed`	`Alert not set · {field message}`
Network or 5xx	`Alert not set · no response from server`
Pause, resume or save failed	`Alert not paused · {reason}`, `Alert not resumed · {reason}`, `Alert not saved · {reason}`

Alerts list (desktop, 1376 px content)

Route /alerts, document.title Alerts · sesame. One panel on the page surface: a header bar, a divider, the table. No cards, no nested boxes.

 x: 64                                                                                          1440
 ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
 │ Alerts   Notifications 3                                                       [Set alert…]  │ 48 header
 ├──────────────────────────────────────────────────────────────────────────────────────────────┤
 │ Status   Condition                      Market                  Now  Triggered      Set      │ 32 column headers
 │ Active   Lakers bid at or above 60¢     Lakers v Celtics · ML   43¢                 2m ago   │ 36
 │ Active Repeat  Lakers spread at or above 4¢  Lakers v Celt…     2¢   1h ago · 5¢    5h ago   │ 36
 │ Paused   Score change                   Lakers v Celtics  Q3 4:12 88–84             1h ago   │ 36
 │ Triggered  Fed decisi… · Yes ask at or below 55¢  Fed deci…     54¢  2m ago · 54¢   30 Sep   │ 36
 └──────────────────────────────────────────────────────────────────────────────────────────────┘
   hovered row: every cell stays; [Pause] [Delete] appear in the 168 px actions slot

Header (48 px)

48 px, the same height as the Orders and Portfolio headers, so the three screens line up when switching between them. 16 px side padding, a divider under it.
Left: the tab strip Alerts / Notifications, sitting on the surface (no filled group). Notifications carries the unread count badge (the rail’s count badge component) when unread > 0.
Right: Set alert… (primary, --control-h; the only filled button on the screen), vertically centred. Disabled at 200 alerts with the tooltip 200 alerts, the maximum. It shows only on the Alerts tab.

Columns

Column	Width	Content
Status	112	`Active`, `Paused` or `Triggered` (the last two `--muted-foreground`), then `Repeat` in muted body-sm when `repeat` is on. Words only, no coloured dots: status is quiet
Condition	flex (min 200)	The condition text. When the row has no free space, only the market part of a `Yes`/`No` condition truncates (`Fed decisi… · Yes ask at or below 55¢`); the side and price never do. Full text in a tooltip, with the note if there is one
Market	flex	The alert’s `title`, muted. Truncates like Condition. Click: open the market view
Now	128	The watched value: bid for above, ask for below, spread for spread alerts, the compact score badge for game alerts. Live, no flash, never truncated. Greyed when its feed is stale, tooltip `Stale 6s · the alert does not fire while stale`
Triggered	136	When the alert last triggered and, for price and spread alerts, the value that triggered it (`triggered_value`): `2m ago · 54¢`, then `30 Sep 14:05 · 54¢`. Game alerts show the time only. Blank until it first triggers; a repeating alert keeps its last time here while its status stays `Active`. Muted, exact local time in a tooltip
Set	88	`created_at` relative (`2m ago`), then `30 Sep 14:05`; exact local time in a tooltip
Actions	168	Empty until row hover or keyboard focus, then `Pause` or `Resume` and `Delete`, ghost text buttons at `--control-h`. Reserved width, so nothing shifts

Rows are 36 px, --border divider between rows, hover --accent. Sorted newest first (the contract’s order). Structure changes defer while the list is in use (interactions.md, “Deferred list changes”).
Price alerts in the list subscribe the book topics of their visible rows, as every list does (§3.7); the Now value is display-only.
Row click (not on a control) opens the edit popover anchored to the row.
A triggered alert shows Resume (makes it active again, per the contract) and Delete.

Row actions

Action	Request	Feedback
`Pause`	`PUT /alerts/{id}` `{paused: true}`	Button shows its loading state; the row updates from the `alerts` WS delta
`Resume`	`PUT /alerts/{id}` `{paused: false}`	Same
`Delete`	`DELETE /alerts/{id}`, sent when the undo toast closes	The row leaves at once (no ghost row: the user removed it). Toast `Alert deleted · Lakers bid at or above 60¢` with `Undo`, 5 s

Undo on delete. The DELETE is held for the 5 s of the toast. Undo puts the row back with its status unchanged and no request is sent. When the toast closes (timeout or [x]), the DELETE is sent; if it fails, the row returns and the toast reads Alert not deleted · {reason}. If the tab closes within the 5 s, the alert stays; that is the safe side. No confirm dialog.
Several deletes in a row each get their own toast (stacking rules in notifications.md).

Keys	Action
`↑` / `↓`	Move the row cursor
`Enter`	Edit the alert under the cursor
`P`	Pause or resume it
`Delete`, `Backspace`	Delete it (undo toast)
`g` then `a` / `n`	Go to Alerts / Notifications

States (alerts list and notification history)

Each state has the loaded dimensions: header, column headers and 36 px row slots stay.

State	Alerts	Notifications
Loading (cold)	Skeleton: 8 rows with the real column widths, static `--muted` blocks	Skeleton: 5 rows, a title bar and a body bar each
Empty	`No alerts` and one line `Set one with the bell on a ladder price or from a game’s menu`. No extra action (the header has `Set alert…`)	`No notifications in the last 30 days`
Error	`Alerts not loaded · {reason}` and `Retry` (ghost)	`History unavailable · {reason}` and `Retry`. When rows are already loaded and an older page fails: `Older history unavailable · {reason}` under the last row
Stale (the `alerts` or `notifications` topic lost)	Rows stay, Now values grey, the header shows the small `Stale 6s` pill. Pause, Resume and Delete still work (they are REST calls)	Rows stay and dim; the line `Stale · new notifications paused` sits above the list until the socket resubscribes
Book or game feed stale for one row	That row’s Now cell greys with the tooltip above	none
At the limit	`Set alert…` disabled, tooltip `200 alerts, the maximum`; ladder bells stay and a click gives the 429 toast	none

Notification history

Route /notifications, the second tab of the Alerts screen, document.title Notifications · sesame. Every notification is kept here for 30 days, whatever the channel rules say (in_app only controls the toast). The tab shows the same list component as the desktop top-bar [inbox] popover and the phone’s notifications sheet (NotificationHistory in app/shell/notifications-panel.tsx), so the history looks and behaves the same wherever it opens. It is not a separate day-grouped table. On desktop the list sits in a centred column at most 768 px wide under the 48 px header; on the phone it fills the width.

Unread count

unread_count comes with the notifications topic snapshot; each delta adds one while the history is not open.
It shows on the desktop top bar’s [inbox] button, on the Notifications tab, and on the phone’s logo menu button and its notifications item (3 unread): the count badge, 16 px, --secondary, never red or green. Above 99 it reads 99+.
Unread notifications are the only count; triggered alerts have no separate count.

Marking read

Opening the history (the tab, the popover or the sheet) sends POST /notifications/read with up_to = the newest loaded notification’s id, once the first page has loaded and anything is unread. The server re-sends the snapshot, so the count clears in every tab. On failure the count stays and the next change tries again.
New notifications that arrive while the history is open are marked read the same way.
There is no Mark all read button: opening the history is the action.
Rows that were unread when the history opened, and rows that arrive while it is open, keep the unread style until it closes, so the new ones stay recognisable.

Rows

 ┌────────────────────────────────────────────────────────┐
 │ (dot) Order filled                              2m ago │ 56 min: title line, time on the right
 │       Lakers · Buy 25 sh at 42¢                        │    body, muted, up to 2 lines
 ├────────────────────────────────────────────────────────┤
 │       Price alert                              14m ago │
 │       Lakers bid 61¢ · at or above 60¢                 │
 ├────────────────────────────────────────────────────────┤
 │ (dot) Feed disconnected                         1h ago │ critical: title in --destructive
 │       Polymarket market data · no connection for 30s   │
 ├────────────────────────────────────────────────────────┤
 │                     [Load older]                       │ only when there is an older page
 └────────────────────────────────────────────────────────┘

Rows have dividers, 16 px side padding and 8 px vertical padding; minimum height 56 px, 64 px on touch. Newest first.
Unread marker: a 6 px --ring dot at the left, in a slot every row reserves, so the text never moves when it clears. Unread titles are weight 600 and carry the screen-reader prefix Unread:.
Title line: the title, truncated with the full text in a tooltip, and the time on the right (2m ago, then 30 Sep 14:05, 24-hour local; exact time in a tooltip). A critical notification’s title is --destructive; info and warning titles are --foreground. Severity has no other mark in the list.
Body: 13 px, --muted-foreground, clamped to two lines with the full text in a tooltip. notify keeps bodies within 120 characters (notifications.md), so the figures are rarely cut.
Rows with a target are links: a click opens it (notifications.md, “Targets”) and, in the popover or sheet, closes that overlay. A row without a target is not interactive and has no hover.
Paging: 50 per page. Load older (ghost, --control-h) under the last row fetches the next page with before = next_before; it shows its loading state and is gone on the last page. New notifications from the topic insert at the top.

Alerts list, mobile (390 px)

Reached from the logo menu (Alerts, with the unread count) or > alerts in the palette. A full-screen route: the app header stays, with a back button in place of the logo.

 ┌──────────────────────────────────────┐
 │ Alerts   Notifications 3 [Set alert…]│ 44 tab row, primary on the right
 ├──────────────────────────────────────┤
 │ Lakers bid at or above 60¢ [ellipsis]│ 64 line 1: condition, overflow button (44 × 44)
 │ Lakers v Celtics · ML · 43¢   Active │    line 2: market, now, status
 ├──────────────────────────────────────┤
 │ Score change               [ellipsis]│ 64
 │ Lakers v Celtics · Q3 4:12 88–84     │
 │                               Paused │
 └──────────────────────────────────────┘

Rows are 64 px, separated by dividers, not cards. Line 1: condition (body), line 2: market and the watched value (body-sm, muted). Status (Active, Paused, or Triggered 2m ago · 54¢, which folds in the desktop Triggered column; then · Repeat when on) sits right-aligned on line 2; the value never truncates, the market does.
The [ellipsis] button is always visible on touch and opens the action sheet: Edit, Pause or Resume, Delete. Long-press the row opens the same sheet. Tap the row: edit sheet.
Set alert… opens the form as a bottom sheet, with the market search field first.
Delete uses the same undo toast (bottom of the screen, above the tab bar).

Start here

Architecture

Decision records

Venue

Design

QA

Alerts

Alerts

Alert kinds

Trigger rules

Condition text

Creating an alert

From a ladder level (one click)

From the board (game alerts)

From the market view

The form (edit, and create from the market view or this screen)

Create and update errors

Alerts list (desktop, 1376 px content)

Header (48 px)

Columns

Row actions

Keys (navigation class, work in Safe)

States (alerts list and notification history)

Notification history

Unread count

Marking read

Rows

Alerts list, mobile (390 px)

​Alerts

​Alert kinds

​Trigger rules

​Condition text

​Creating an alert

​From a ladder level (one click)

​From the board (game alerts)

​From the market view

​The form (edit, and create from the market view or this screen)

​Create and update errors

​Alerts list (desktop, 1376 px content)

​Header (48 px)

​Columns

​Row actions

​Keys (navigation class, work in Safe)

​States (alerts list and notification history)

​Notification history

​Unread count

​Marking read

​Rows

​Alerts list, mobile (390 px)

Alerts

Alert kinds

Trigger rules

Condition text

Creating an alert

From a ladder level (one click)

From the board (game alerts)

From the market view

The form (edit, and create from the market view or this screen)

Create and update errors

Alerts list (desktop, 1376 px content)

Header (48 px)

Columns

Row actions

Keys (navigation class, work in Safe)

States (alerts list and notification history)

Notification history

Unread count

Marking read

Rows

Alerts list, mobile (390 px)