Notifications

Notifications turn a Perps account’s activity into a ready-to-display feed of position changes, canceled orders, and liquidation events. They are the same events that drive the notification bell in the Polymarket app. Read recent notifications to render the feed, then stream the live channel to keep it fresh. Mark notifications read as the user catches up. Notifications summarize activity for display. To reconcile order, fill, and position state, use Reconcile Trade State instead.

Notifications require an authenticated session.

Read Notifications

Start with a read to render the feed. It returns the account’s notifications newest first, together with the unread count for the badge.

TypeScript
Python
API

Fetch the first page of notifications.

const page = await session.listNotifications().firstPage();
// page.items: PerpsNotificationEntry[]

Each entry pairs one notification with its read state, and readAt stays null until the notification is marked read. The read is paginated, so iterate it to walk older history.

for await (const page of session.listNotifications()) {
  // page.items: PerpsNotificationEntry[]
}

For the unread badge, fetch the count directly.

const unread = await session.fetchUnreadNotificationsCount();

Output: PerpsNotificationEntry[]

type PerpsNotificationEntry = {
  notification: PerpsNotification;
  readAt: number | null;
  timestamp: number;
};

[
  {
    "notification": {
      "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
      "type": "position_opened",
      "instrumentId": 1,
      "side": "long",
      "size": "0.01",
      "avgPrice": "65000",
      "leverage": 5,
      "orderType": "market"
    },
    "readAt": null,
    "timestamp": 1767225600000
  }
]

Fetch the first page of notifications.

page = await session.list_notifications().first_page()
# page.items: tuple[PerpsNotificationEntry, ...]
# page.unread: int

Each entry pairs one notification with its read state, and read_at stays None until the notification is marked read. The page also carries the account’s unread count for the badge. The read is paginated, so iterate it to walk older history.

async for page in session.list_notifications():
    # page.items: tuple[PerpsNotificationEntry, ...]
    pass

Output: tuple[PerpsNotificationEntry, ...]

[
  {
    "notification": {
      "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
      "type": "position_opened",
      "instrument_id": 1,
      "side": "long",
      "size": "0.01",
      "avg_price": "65000",
      "leverage": 5,
      "order_type": "market"
    },
    "read_at": null,
    "timestamp": 1767225600000
  }
]

Fetch the account’s notifications, newest first.

curl -G "https://api.perpetuals.polymarket.com/v1/account/notifications" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>" \
  --data-urlencode "limit=50"

Each item pairs one notification with its read state, and read_at stays null until the notification is marked read. unread counts the account’s unread notifications. While has_more is true, pass next_cursor back as cursor to fetch the next, older page.

Output: Notifications

{
  "items": [
    {
      "notification": {
        "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
        "type": "position_opened",
        "instrument_id": 1,
        "side": "long",
        "size": "0.01",
        "avg_price": "65000",
        "leverage": 5,
        "order_type": "market"
      },
      "read_at": null,
      "ts": 1767225600000
    }
  ],
  "unread": 3,
  "durable_source_seq": 1234567890,
  "has_more": true,
  "next_cursor": "eyJ0cyI6MTc2NzIyNTYwMDAwMCwiaWQiOiIwYTVkOGYxZS0zYjJjLTVlNGEtOWY4Yi0xYzJkM2U0ZjVhNmIifQ"
}

Stream Notifications

Subscribe to the live channel to append new notifications and bump the unread badge without polling.

TypeScript
Python
API

Notification events arrive on the session stream alongside the other private session updates.

for await (const event of session) {
  if (event.type === "notification") {
    // event.payload: PerpsNotification
  }
}

The stream yields PerpsNotificationUpdateEvent objects like this.

type PerpsNotificationUpdateEvent = {
  type: "notification";
  channel: "notifications";
  timestamp: number;
  sequence: number;
  payload: PerpsNotification;
};

{
  "type": "notification",
  "channel": "notifications",
  "timestamp": 1767225600000,
  "sequence": 1234567890,
  "payload": {
    "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
    "type": "position_opened",
    "instrumentId": 1,
    "side": "long",
    "size": "0.01",
    "avgPrice": "65000",
    "leverage": 5,
    "orderType": "market"
  }
}

Notification events arrive on the session stream alongside the other private session updates.

async for event in session:
    if event.type == "notification":
        # event.payload: PerpsNotification
        pass

The stream yields PerpsNotificationEvent objects like this.

Example

{
  "type": "notification",
  "channel": "notifications",
  "timestamp": 1767225600000,
  "sequence": 1234567890,
  "payload": {
    "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
    "type": "position_opened",
    "instrument_id": 1,
    "side": "long",
    "size": "0.01",
    "avg_price": "65000",
    "leverage": 5,
    "order_type": "market"
  }
}

Authenticate the WebSocket connection first, then subscribe to the notifications channel.

{
  "id": 1,
  "req": "sub",
  "chs": ["notifications"]
}

After subscribing, the stream emits notification data frames like this.

{
  "ch": "notifications",
  "ts": 1767225600000,
  "sq": 1234567890,
  "data": {
    "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
    "type": "position_opened",
    "instrument_id": 1,
    "side": "long",
    "size": "0.01",
    "avg_price": "65000",
    "leverage": 5,
    "order_type": "market"
  }
}

Use req: "unsub" with the same chs value to unsubscribe. See Authenticated Sessions for the authentication frame and connection lifecycle.

Mark Notifications Read

Read state drives the unread count. Mark notifications read when the user views them, either one by one or everything up to the newest one they have seen. Read state is scoped to the account, so a session can only mark its own notifications read.

TypeScript
Python
API

Mark specific notifications read by id, or mark everything up to an entry read.

await session.markNotificationsRead({
  ids: [entry.notification.id],
});

await session.markNotificationsRead({
  upTo: { id: entry.notification.id, timestamp: entry.timestamp },
});

upTo marks the given notification and every earlier one read, inclusive. Pass the newest entry the user has seen to clear the feed in one call.

Mark specific notifications read by id, or mark everything up to an entry read.

await session.mark_notifications_read(ids=[entry.notification.id])

await session.mark_notifications_read(up_to=entry)

up_to takes a PerpsNotificationEntry and marks it and every earlier notification read, inclusive. Pass the newest entry the user has seen to clear the feed in one call.

Mark specific notifications read by id, or mark everything at or before a cursor read.

curl -X POST "https://api.perpetuals.polymarket.com/v1/account/notifications/read" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>" \
  -H "content-type: application/json" \
  -d '{"ids": ["0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b"]}'

curl -X POST "https://api.perpetuals.polymarket.com/v1/account/notifications/read" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>" \
  -H "content-type: application/json" \
  -d '{"before": "eyJ0cyI6MTc2NzIyNTYwMDAwMCwiaWQiOiIwYTVkOGYxZS0zYjJjLTVlNGEtOWY4Yi0xYzJkM2U0ZjVhNmIifQ"}'

before takes a keyset cursor (base64url-encoded JSON {"ts": <unix_ms>, "id": "<notification_id>"}) and marks every notification at or before it read, inclusive. next_cursor values returned by the notifications read use the same format.The response confirms the read markers were accepted.

{
  "status": "ok"
}

Backfill Missed Notifications

The live channel can miss notifications. A reconnect leaves a gap, and under load the server can drop frames. The notifications read closes these gaps. Pass a sequence lower bound and it returns every notification from that point forward, so the feed catches up with stored history. Anchor the bound at the sequence of the last notification you processed, not at the sequence of the signal that told you to resync. The bound is inclusive and one event can emit several notifications that share one sequence, so the backfill re-covers the boundary. Deduplicate merged results by notification id, which is identical across the read and the live channel.

TypeScript
Python
API

Track the sequence of the last notification event you processed. When the session signals a resync, run the backfill from that anchor.

let lastSequence: number | undefined;

for await (const event of session) {
  if (event.type === "notification") {
    // Apply event.payload to the local feed.
    lastSequence = event.sequence;
  }

  if (event.type === "resync") {
    for await (const page of session.listNotifications({
      sinceSeq: lastSequence,
    })) {
      // Merge page.items into the local feed, deduplicated by notification id.
    }
  }
}

Follow-up pages keep the same sinceSeq bound automatically. If you have not processed any notifications yet, leave sinceSeq unset and the read returns the newest notifications.

Track the sequence of the last notification event you processed. When the session signals a resync, run the backfill from that anchor.

last_sequence = None

async for event in session:
    if event.type == "notification":
        # Apply event.payload to the local feed.
        last_sequence = event.sequence
    elif event.type == "resync":
        async for page in session.list_notifications(since_seq=last_sequence):
            # Merge page.items into the local feed, deduplicated by notification id.
            pass

Follow-up pages keep the same since_seq bound automatically. If you have not processed any notifications yet, leave since_seq unset and the read returns the newest notifications.A resync with event.reason == "server" means the server dropped notification frames, and its event.sequence is the highest sequence among the dropped notifications. The store can persist those notifications slightly after the drop signal, so if a page still reports page.durable_source_seq below that target, wait briefly and run the same backfill again. The since_seq bound and id-based deduplication make retries safe.

Track the Last Processed Frame

Keep the sq of the last notifications data frame you processed. When the server drops frames under load, it sends a resync control frame instead. Its sq is the highest sequence among the dropped notifications.

{
  "ch": "notifications",
  "ts": 1767225600000,
  "sq": 1234568100,
  "type": "resync"
}

A resync frame carries no data. Never anchor the backfill on its sq, which can be later than the dropped notifications and would skip them.

Backfill From the Anchor

Request the notifications read with since_seq set to the sq of the last data frame you processed. The bound is inclusive, so deduplicate the results by notification id.

curl -G "https://api.perpetuals.polymarket.com/v1/account/notifications" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>" \
  --data-urlencode "since_seq=1234567890"

While has_more is true, pass next_cursor back as cursor together with the same since_seq, so follow-up pages stay inside the gap window. If you have no processed data frame to anchor on, use the durable_source_seq of your most recent read instead. If you have neither, fetch the first page without since_seq.

Confirm the Store Caught Up

Each response reports durable_source_seq, the highest sequence the store has persisted for the account. Compare it against the catch-up target: the resync frame’s sq after a drop, or the sq of the first data frame received on the new connection after a reconnect. Buffer live frames from the moment you subscribe so you do not lose that target.While durable_source_seq is below the target, the store has not caught up yet. Retry the same backfill until it reaches the target and deduplicate the merged results by notification id.

Notification Types

Every notification carries a type and a small type-specific payload.

Type	Sent when
`position_opened`	A fill opens a new position.
`position_increased`	A fill adds to an existing position.
`position_reduced`	A fill shrinks a position without closing it.
`position_closed`	A fill fully closes a position and realizes its PnL.
`limit_order_canceled`	A resting limit order is canceled.
`liquidation_warning`	A position (isolated margin) or the whole account (cross margin) is approaching liquidation.
`position_liquidated`	A liquidation closes part or all of a position.

Fill-driven position notifications (position_opened, position_increased, position_reduced, and position_closed) can include an order_type field that names the kind of order behind the fill: market, limit, take_profit, or stop_loss. An order fired by a take-profit or stop-loss trigger reports the trigger that fired it. Otherwise an aggressing order submitted without a limit price reports market, and everything else reports limit, including fills on a resting maker order. The field is omitted when the fill cannot be attributed to an order, so treat it as optional display metadata. A liquidation_warning for an isolated-margin position names the instrument and its liquidation price. A cross-margin warning covers the whole account instead. It has no single instrument or liquidation price and lists the affected instruments. See Liquidation Mechanics for how liquidations work.

TypeScript
Python
API

The PerpsNotificationType and PerpsNotificationOrderType enums export the type and order_type values. Each notification type carries these fields.

{
  "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
  "type": "position_opened",
  "instrumentId": 1,
  "side": "long",
  "size": "0.01",
  "avgPrice": "65000",
  "leverage": 5,
  "orderType": "market"
}

{
  "id": "1b6e9f2a-4c3d-5f5b-8a9c-2d3e4f5a6b7c",
  "type": "position_closed",
  "instrumentId": 1,
  "side": "long",
  "size": "0.01",
  "avgPrice": "66500",
  "pnl": "15",
  "orderType": "take_profit"
}

{
  "id": "2c7fa03b-5d4e-5a6c-9b8d-3e4f5a6b7c8d",
  "type": "limit_order_canceled",
  "instrumentId": 1,
  "side": "long",
  "size": "0.01",
  "price": "64000"
}

{
  "id": "3d8ab14c-6e5f-5b7d-8c9e-4f5a6b7c8d9e",
  "type": "liquidation_warning",
  "marginType": "isolated",
  "instrumentId": 1,
  "markPrice": "53040",
  "liquidationPrice": "52000"
}

{
  "id": "4e9bc25d-7f6a-5c8e-9d8f-5a6b7c8d9e0f",
  "type": "liquidation_warning",
  "marginType": "cross",
  "markPrice": "53040",
  "affectedInstruments": [1, 2]
}

{
  "id": "5fa0d36e-8a7b-5d9f-8e9a-6b7c8d9e0f1a",
  "type": "position_liquidated",
  "instrumentId": 1,
  "side": "long",
  "sizeClosed": "0.01",
  "pnl": "-130",
  "marginType": "isolated",
  "viaBackstop": false
}

On position_liquidated, pnl is null when no fill produced a realized figure, for example a backstop close. viaBackstop reports whether an insurance-fund backstop applied to the liquidation.

Each notification type carries these fields.

{
  "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
  "type": "position_opened",
  "instrument_id": 1,
  "side": "long",
  "size": "0.01",
  "avg_price": "65000",
  "leverage": 5,
  "order_type": "market"
}

{
  "id": "1b6e9f2a-4c3d-5f5b-8a9c-2d3e4f5a6b7c",
  "type": "position_closed",
  "instrument_id": 1,
  "side": "long",
  "size": "0.01",
  "avg_price": "66500",
  "pnl": "15",
  "order_type": "take_profit"
}

{
  "id": "2c7fa03b-5d4e-5a6c-9b8d-3e4f5a6b7c8d",
  "type": "limit_order_canceled",
  "instrument_id": 1,
  "side": "long",
  "size": "0.01",
  "price": "64000"
}

{
  "id": "3d8ab14c-6e5f-5b7d-8c9e-4f5a6b7c8d9e",
  "type": "liquidation_warning",
  "margin_type": "isolated",
  "instrument_id": 1,
  "mark_price": "53040",
  "liquidation_price": "52000"
}

{
  "id": "4e9bc25d-7f6a-5c8e-9d8f-5a6b7c8d9e0f",
  "type": "liquidation_warning",
  "margin_type": "cross",
  "mark_price": "53040",
  "affected_instruments": [1, 2]
}

{
  "id": "5fa0d36e-8a7b-5d9f-8e9a-6b7c8d9e0f1a",
  "type": "position_liquidated",
  "instrument_id": 1,
  "side": "long",
  "size_closed": "0.01",
  "pnl": "-130",
  "margin_type": "isolated",
  "via_backstop": false
}

On position_liquidated, pnl is None when no fill produced a realized figure, for example a backstop close. via_backstop reports whether an insurance-fund backstop applied to the liquidation.

Each notification type carries these fields.

{
  "id": "0a5d8f1e-3b2c-5e4a-9f8b-1c2d3e4f5a6b",
  "type": "position_opened",
  "instrument_id": 1,
  "side": "long",
  "size": "0.01",
  "avg_price": "65000",
  "leverage": 5,
  "order_type": "market"
}

{
  "id": "1b6e9f2a-4c3d-5f5b-8a9c-2d3e4f5a6b7c",
  "type": "position_closed",
  "instrument_id": 1,
  "side": "long",
  "size": "0.01",
  "avg_price": "66500",
  "pnl": "15",
  "order_type": "take_profit"
}

{
  "id": "2c7fa03b-5d4e-5a6c-9b8d-3e4f5a6b7c8d",
  "type": "limit_order_canceled",
  "instrument_id": 1,
  "side": "long",
  "size": "0.01",
  "price": "64000"
}

{
  "id": "3d8ab14c-6e5f-5b7d-8c9e-4f5a6b7c8d9e",
  "type": "liquidation_warning",
  "margin_type": "isolated",
  "instrument_id": 1,
  "mark_price": "53040",
  "liq_price": "52000"
}

{
  "id": "4e9bc25d-7f6a-5c8e-9d8f-5a6b7c8d9e0f",
  "type": "liquidation_warning",
  "margin_type": "cross",
  "instrument_id": null,
  "mark_price": "53040",
  "affected_instruments": [1, 2]
}

{
  "id": "5fa0d36e-8a7b-5d9f-8e9a-6b7c8d9e0f1a",
  "type": "position_liquidated",
  "instrument_id": 1,
  "side": "long",
  "size_closed": "0.01",
  "pnl": "-130",
  "margin_type": "isolated",
  "via_backstop": false
}

On position_liquidated, pnl is null when no fill produced a realized figure, for example a backstop close. via_backstop reports whether an insurance-fund backstop applied to the liquidation. Notification ids are deterministic: the same event yields the same id on the live channel and in the notifications read.

Getting Started

Build With Perps

Learn About Trading

Resources

Read Notifications

Stream Notifications

Mark Notifications Read

Backfill Missed Notifications

Notification Types

​Read Notifications

​Stream Notifications

​Mark Notifications Read

​Backfill Missed Notifications

​Notification Types

Read Notifications

Stream Notifications

Mark Notifications Read

Backfill Missed Notifications

Notification Types