Notifications

The notification system encompasses three related APIs: in-app notifications, price alerts, and push notification device registration. Notifications are also delivered in real-time via the user:notifications WebSocket channel.

Notification Endpoints

Method	Path	Auth	Description
GET	`/api/v1/notifications`	Bearer	List user notifications
PATCH	`/api/v1/notifications/mark-all-read`	Bearer	Mark all notifications as read
PATCH	`/api/v1/notifications/:id`	Bearer	Mark a single notification as read
DELETE	`/api/v1/notifications/:id`	Bearer	Dismiss a notification

Price Alert Endpoints

Method	Path	Auth	Description
GET	`/api/v1/alerts`	Bearer	Get all user alerts
POST	`/api/v1/alerts`	Bearer	Create a price alert
PUT	`/api/v1/alerts/:id`	Bearer	Update an alert
DELETE	`/api/v1/alerts/:id`	Bearer	Delete an alert

Push Notification Endpoints

Method	Path	Auth	Description
POST	`/api/v1/push/register`	Bearer	Register a device for push notifications
DELETE	`/api/v1/push/unregister`	Bearer	Unregister a device
PUT	`/api/v1/push/preferences`	Bearer	Update push notification preferences

List Notifications

Fetch the user's in-app notifications with optional filters.

Query Parameters:

Parameter	Type	Description
`read`	boolean	Filter by read status
`type`	string	Filter by notification type

// GET /api/v1/notifications?read=false

// Response 200
{
  "notifications": [
    {
      "id": "notif-uuid-123",
      "type": "order_filled",
      "title": "Order Filled",
      "message": "Your YES order on 'Will the Fed cut rates?' was filled at $0.63",
      "read": false,
      "data": {
        "orderId": "order-uuid-456",
        "marketId": "mkt-uuid-789"
      },
      "createdAt": "2026-03-27T14:30:00.000Z"
    }
  ],
  "unreadCount": 3
}

Create Price Alert

Set up an alert that triggers when a market's price crosses a specified threshold.

// POST /api/v1/alerts
{
  "marketId": "mkt-uuid-789",
  "targetPrice": 0.75,
  "condition": "above",
  "side": "yes"
}

// Response 201
{
  "id": "alert-uuid-123",
  "marketId": "mkt-uuid-789",
  "marketTitle": "Will the Fed cut rates in June 2026?",
  "targetPrice": 0.75,
  "condition": "above",
  "side": "yes",
  "active": true,
  "createdAt": "2026-03-27T15:00:00.000Z"
}

Register Device for Push

// POST /api/v1/push/register
{
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "platform": "ios"
}

// Response 201
{
  "message": "Device registered"
}

Notes

Notifications are generated by the backend for events like order fills, position resolutions, copy-trade executions, price alert triggers, and mission completions
The user:notifications WebSocket channel pushes new notifications in real-time
Price alerts are checked during each price-sync cycle (every 60 seconds)
Push notifications are delivered via Expo's push notification service for mobile devices
Dismissing a notification permanently removes it; marking as read keeps it in the list