---
title: "GET /v1/notifications"
method: GET
path: "/v1/notifications"
tags: ["Notifications"]
---

# GET /v1/notifications

`GET /v1/notifications`

## Request

- Base URL: `https://api.arbital.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.arbital.xyz/v1/notifications`
- Auth: HTTP bearer

Returns the authenticated user's durable in-app inbox newest first. Pages may be short or empty while next_cursor is non-null; continue until next_cursor is null. Visibility checks examine a bounded history window per request. Read state combines individual acknowledgements with the user's mark-all cutoff. Older activity covered by that cutoff stays read if it later becomes visible; newer activity can make an existing group unread. Current visibility is always checked independently. Contract 2 supports 18 kinds. Legacy responses preserve 11 kinds and omit unsupported new-only rows while advancing the cursor; pure mentions never masquerade as direct replies.

## Query parameters

- `cursor` string
- `contract` '2'

## Response `200`

Authorized notification response

- union
  - NotificationPage
    - `next_cursor` string, nullable, required: Continue while this is non-null, including when notifications is empty or shorter than 20 items. Each page examines a bounded window of history and applies current visibility checks.
    - `notifications` NotificationItem[], required
      - `body` string, required
      - `created_at_unix_ms` integer, required
      - `id` string, uuid, required
      - `kind` 'deposit_transfer_completed' | 'direct_message_received' | 'group_invite_received' | 'group_message_received' | 'withdrawal_completed' | 'followed_trader_bought' | 'followed_trader_sold' | 'comment_reply_received' | 'post_reply_received' | 'post_reaction_received' | 'comment_reaction_received', required
      - `read_at_unix_ms` integer: Present only when currently visible activity is read. Uses a valid individual or legacy acknowledgement timestamp when available, or the latest applicable global mark-all cutoff time. The global time can change when a later cutoff advances; it is not a historical per-notification write timestamp.
      - `route` object, required: Where the client should open the notification. token_comments and posts routes carry the exact thread identifiers (for reactions: the post or comment that received them); other keys carry only the key.
        - `address` string: Present for token_comments: canonical token address of the thread.
        - `chain_id` string: Present for token_comments: canonical chain of the thread.
        - `comment_id` string, uuid: Present for token_comments: the recipient's own comment that received the reply.
        - `key` 'messages' | 'portfolio' | 'posts' | 'social_activity' | 'token_comments', required
        - `parent_reply_id` string, uuid: Present for posts when the reply answered the recipient's own reply: that reply.
        - `post_id` string, uuid: Present for posts: the community post the reply belongs to.
        - `reply_id` string, uuid: Present for token_comments and posts: the reply that triggered the notification.
      - `schema_version` 1, required
      - `title` string, required
  - NotificationPageV2
    - `unread_count` string, required
    - `inbox_revision` string, required
    - `read_watermark` string, uuid, required
    - `read_watermark_expires_at_unix_ms` integer, required
    - `contract` 2, required
    - `notifications` NotificationActivityV2[], required
      - `id` string, uuid, required
      - `kind` 'deposit_transfer_completed' | 'direct_message_received' | 'group_invite_received' | 'group_message_received' | 'withdrawal_completed' | 'followed_trader_bought' | 'followed_trader_sold' | 'comment_reply_received' | 'post_reply_received' | 'post_reaction_received' | 'comment_reaction_received' | 'message_reaction_received' | 'group_invite_accepted' | 'post_activity_received' | 'comment_activity_received' | 'new_watcher_received' | 'withdrawal_failed' | 'trader_post_received', required: Contract 2 supports these 18 kinds. The strict legacy item and legacy installation payload retain their original 11 kinds; unsupported new-only kinds are omitted while cursors advance.
      - `title` string, required
      - `body` string, required
      - `reasons` string[], required: Currently authorized native creation reasons. Reply, mention and selected-author publication reasons can share one notification and initial alert.
      - `created_at_unix_ms` integer, required
      - `presentation_revision` string, required: Current row presentation revision including any applicable global read-state revision. A change need not represent a per-row write or new positive activity.
      - `activity_revision` string, required
      - `read_activity_revision` string, required: Greatest acknowledged activity revision for this row, combining individual evidence and the global mark-all cutoff. Individual acknowledgements can leave hidden holes; this maximum alone is not an unread-state oracle.
      - `read_state` 'read' | 'unread', required: Unread when a currently authorized, unsuppressed activity has neither an individual acknowledgement nor coverage by the global mark-all cutoff.
      - `target` union, required
        - object
          - `type` 'post', required
          - `post_id` string, uuid, required
        - object
          - `type` 'post_reply', required
          - `post_id` string, uuid, required
          - `reply_id` string, uuid, required
          - `parent_reply_id` string, uuid, nullable, required
        - object
          - `type` 'chat_message', required
          - `chat_id` string, uuid, required
          - `message_id` string, uuid, required
          - `sequence` string, required
        - object
          - `type` 'chat_invite', required
          - `chat_id` string, uuid, required
          - `invite_id` string, uuid, required
        - object
          - `type` 'token_comment', required
          - `chain_id` string, required
          - `address` string, required
          - `comment_id` string, uuid, required
        - object
          - `type` 'token_comment_reply', required
          - `chain_id` string, required
          - `address` string, required
          - `comment_id` string, uuid, required
          - `parent_comment_id` string, uuid, required
          - `root_comment_id` string, uuid, required
        - object
          - `type` 'financial_transaction', required
          - `source_kind` 'withdrawal' | 'user_transfer' | 'confirmed_transfer', required: confirmed_transfer identifies retained verified receipt evidence. The withdrawal locator is reserved for compatibility; historical withdrawal-ID notifications without matching exact receipt evidence are omitted from lists/counts and resolve source_unavailable. Unsupported source kinds resolve unavailable.
          - `source_id` string, uuid, required
        - object
          - `type` 'trade', required
          - `trade_id` string, uuid, required
        - object
          - `type` 'native_profile', required
          - `user_id` string, uuid, required
        - object
          - `type` 'imported_post', required
          - `post_id` string, uuid, required
    - `next_cursor` string, nullable, required
    - `page_snapshot_revision` string, required
    - `has_newer_activity` boolean, required

## Other responses

- `400`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `401`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `503`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.

---

[API](https://skmtc.dev/arbital/apis/arbital-api.md) - [All operations](https://skmtc.dev/arbital/apis/arbital-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arbital/apis/arbital-api/revisions/bb0185edf43a?raw)