# Notifications

Fin tells your users when something they would want to know happens while they are not looking:
an approval or a question waiting for them, an alert or report from one of their automations, money
that moved, a problem with an automation, or fin's reply in a chat they left. For a user with the
`proactive` feature on, fin also tells them what it noticed in their money: a fall, big news about
a coin they hold, and a look at their week ([fin's notices](#fins-notices)). Each notification is
about one thing, with its text ready to show, and records when the user read it.

Your app shows them in two places: an inbox, read with the user's session, and a ping on the user's
devices, which your server sends from a feed it reads with your partner key. Fin never sends an
email, a text or a push itself, and a notification grants nothing: approving still happens on the
approval card, with the user's own signature.

## Show the inbox

Read the user's inbox with their session, through
[List notifications](/api-reference/notifications/list):

```http
GET /v1/users/{userId}/notifications?limit=20
Authorization: Bearer <session token>
X-Api-Key: fin_…
```

```jsonc
{
  "data": [
    {
      "id": "…",
      "kind": "approval",
      "category": "needs_you",
      "title": "fin needs your OK",
      "body": "Swap 100 USDC for NEAR",
      "withoutAmounts": { "title": "fin needs your OK", "body": "A request is waiting for your approval." },
      "subject": { "type": "approval", "approvalId": "…", "conversationId": "…" },
      "status": "waiting",
      "expiresAt": "2026-10-19T09:54:00.000Z",
      "createdAt": "2026-10-19T09:41:00.000Z",
      "readAt": null
    }
  ],
  "nextCursor": "…",
  "unreadCount": 3
}
```

- **Newest first.** Pass `nextCursor` back as `cursor` for older ones. `unread=true` lists only the
  unread, and `conversationId` only those about one conversation.
- **`unreadCount`** is for a badge: every unread notification of the user's, whatever page you read.
- **`title` and `body`** are plain text that Fin writes, with no links or markdown, and a token a
  chat card named by its whole mint reads shortened (`Use BONK, mint DezX…B263`). Show them as
  they are. `withoutAmounts` is the same notification without amounts or the user's own words, for
  a lock screen or anywhere the user asked you to hide them.
- **`tokenId`**, on a trade, a filled order, a deposit or a withdrawal, is the token it is about,
  and on one of fin's notices the coin it is about: draw its icon beside the text.
- **`tone`** says how it reads, to tint its icon: `needs_you` while it waits on the user,
  `problem` when something went wrong or fin noticed a fall in the user's money, `resolved` when an
  automation's problem is over, and `neutral` otherwise.
- **`subject`** says what the notification is about. Open that thing's page when the user taps it:
  the approval or question in its conversation, the automation run, the agent's trade, the user's
  own swap, a Solana buy or sale, the limit order, the Polymarket order, the deposit, the
  withdrawal, the automation, or the conversation at fin's reply.

  | `subject.type` | Open |
  | --- | --- |
  | `trade` | [Get a trade](/api-reference/wallets/get-trade) with `tradeId` |
  | `swap` | [Get a swap](/api-reference/wallets/get-swap) with `swapId` |
  | `solana_trade` | a trade the user placed on the token's page: [Get a Solana trade](/api-reference/solana/get-trade) with `tradeId`; one the agent made: the `solana` item of [List activity](/api-reference/activity/list) whose `id` is `tradeId` |
  | `order` | [Get a limit order](/api-reference/wallets/get-order) with `orderId` |
  | `prediction_order` | [Get a prediction order](/api-reference/prediction/get-order) with `orderId` |
  | `story` | [Get a market story](/api-reference/market/stories-get) with `storyId` |
  | `asset` | your page for the coin `assetId` names, with the user's holding of it from [Get portfolio](/api-reference/portfolio/get) |
  | `week` | the inbox itself: the week's look says all it has to say |

  `subject.type` can grow too: open one you do not know as the inbox, never as a broken link.
- **`status`** is there for an approval or a question: `waiting` while the user can still answer,
  with `expiresAt`; `expired` once it ran out; `done` once it was answered. An approval or question
  that stopped waiting counts as read. `waiting` also marks an `automation_attention` for an
  automation fin paused until its owner acts. It has no `expiresAt`, and reads `done`, and read, once
  they resume it, change it or delete it.
- **`action`** is on that paused automation only, and says what moves it on: `add_funds` or
  `edit_automation`. Absent, the owner moves it on from the automation's page: by a choice, or by
  resuming it when its `waitingForOwner.action` is `resume`.
- **`kind` and `category`** can grow. Show a notification of a kind you do not know by its `title`
  and `body`, and open its `subject` if you know its `type`.

Financial figures may be absent when settlement receipts do not establish an actual amount.
Show Fin's supplied text; never fill an unknown amount from the request, quote or a zero default.
A notification that requires a monetary amount waits until suitable settlement evidence is
available. Missing figures do not mean no money moved.

| `category` | Kinds |
| --- | --- |
| `needs_you` | `approval`, `question`, and an `automation_attention` for an automation that waits for its owner |
| `alerts_and_reports` | `automation_report` |
| `money_moved` | `trade`, `order_filled`, `deposit`, `withdrawal` |
| `automation_problems` | Every other `automation_attention` |
| `replies` | `reply` |
| `big_moves` | `holding_move` |
| `big_news` | `market_story` |
| `weekly_look` | `weekly_look` |

Money that moved is told however it was started. A `trade` comes when a trade ends: one an
automation made, one fin made in chat, the user's own swap, or a Solana buy or sale, the user's own
on the token's page included; a sale of several coins under one approval is told once, as a sale
of that many coins, with `tokenId` its first coin's. An `order_filled` comes once when part of a limit order or a
Polymarket order first fills and once when all of it has. A `withdrawal` comes when one ends, and a
`deposit` when one arrives or goes back.

The categories are the switches to offer if your app lets users choose what pings them. Leave
`big_moves`, `big_news` and `weekly_look` off until the user turns them on: they are fin's own
notices, new to the user, and the inbox lists them either way.

## fin's notices

With the `proactive` feature on for a user ([List the user's features](/api-reference/users/list-features)
says whether it is), fin watches their money and records three notices of its own, from plain rules
over prices, the market's stories and the user's holdings; no model writes them:

- **`holding_move`** (`big_moves`): a coin worth at least $50 and 10% of the user's money fell far
  more than it usually does in a day (at least 8%, more for a coin that usually moves more), or
  their whole money fell 5% or more in a day. Its `subject` is the coin (`asset`).
- **`market_story`** (`big_news`): a story at least six publishers carried in the last 12 hours is
  about a coin like that. Its `title` is the story's headline as the market desk titled it, plain
  and without links; `withoutAmounts` leaves it out. Its `subject` is the story (`story`).
- **`weekly_look`** (`weekly_look`): from Monday 14:00 UTC, once a week, what price moves did to the
  user's money, with idle dollars in the agent wallet and one coin that is most of the money. Its
  `subject` is the week (`week`).

Fin records at most one `holding_move` or `market_story` for a user in a day and three in a week,
and never two stories about the same coin within 48 hours; the weekly look is outside those caps.

Each of these carries **`options`**: up to three ways to act on it, best first, each with a
`title`, a one-line `detail` and a `button` label. Show them where the user opens the notification,
never in a push or on a lock screen, under a line saying they are options, not recommendations,
and that doing nothing is fine. An option grants nothing; its `review` says what choosing it does:

| `review.kind` | What choosing it does |
| --- | --- |
| `ask` | [Start a run](/api-reference/runs/start) with `question` as the user's own message. fin proposes, and the user approves in chat as always. |
| `open` | Open your own form for `targetId`, filled in: `earn` is Earn, with `amount` to put in. |

`options` is absent on every other notification. Ping a user's devices for these only once they
have turned the category on, and hold a ping that would arrive at night on their device until
morning.

## Mark them read

When the user has seen the inbox, mark everything up to the newest notification they saw with
[Mark notifications read](/api-reference/notifications/mark-read):

```http
POST /v1/users/{userId}/notifications/read
Authorization: Bearer <session token>
X-Api-Key: fin_…

{ "through": "<the newest notification's id>" }
```

That marks it and everything older, and leaves unread a notification that arrived since. To mark
some, send `notificationIds` instead (up to 100). The answer is the notifications this call
changed (the newest 100 at most) and the new `unreadCount`. A `through` request still marks every
older notification even when more than 100 change; refresh the inbox to read their current state.
Reading is shared: a notification marked read on one device is
read on all of them. Marking again is safe and changes nothing, so the call takes no
`Idempotency-Key`.

## Deliver pings from your server

Read the feed with your partner key alone, every few seconds, from one place on your server, through
[List notifications to deliver](/api-reference/partner/notifications):

```http
GET /v1/partner/notifications?after=<your saved cursor>&limit=100
X-Api-Key: fin_…
```

```jsonc
{
  "data": [
    { "id": "…", "userId": "user-7", "kind": "deposit", "title": "1,000 USDC arrived",
      "body": "In your wallet", "push": true, "…": "…" }
  ],
  "nextCursor": "…"
}
```

- **Oldest first, every user of yours.** Each item names its user by your own `userId` for them.
- **Keep `nextCursor`**, even from an empty page, and pass it back as `after`, including after a
  restart. Omit `after` only the first time. A notification takes its place in the feed once it is
  committed and its short wait has passed, so a cursor never skips one.
- **`push: true`** means show it on the user's devices now. It is `false` when the user already
  saw it, or when its approval or question was answered or ran out before this feed read, even
  when its place was assigned earlier. An approval, a
  question or a reply waits a little before it takes its place (20 to 30 seconds), in case the user
  sees it in your app first; everything else takes its place at once.
- **Skip what is stale.** After an outage, don't ping for an approval or question whose `expiresAt`
  has passed, or for anything long past; advance your cursor over them anyway.
- **Respect the user's choices**: their category switches (fin's own notices start off), whether
  to show amounts (use `withoutAmounts` when they said no), and a device they are using right now,
  which already shows the inbox.

Tell Fin's operators once your app delivers the feed: they turn on the `notifications` feature
for your users, and fin then promises pings only on devices where they have turned notifications
on. It must not imply permission is already granted or a push was delivered. Until then fin makes
no such promise and says where a result will be instead.
