Guides

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). 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:

HTTP
GET /v1/users/{userId}/notifications?limit=20
Authorization: Bearer <session token>
X-Api-Key: fin_…
{
  "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.typeOpen
tradeGet a trade with tradeId
swapGet a swap with swapId
solana_tradea trade the user placed on the token's page: Get a Solana trade with tradeId; one the agent made: the solana item of List activity whose id is tradeId
orderGet a limit order with orderId
prediction_orderGet a prediction order with orderId
storyGet a market story with storyId
assetyour page for the coin assetId names, with the user's holding of it from Get portfolio
weekthe 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.

categoryKinds
needs_youapproval, question, and an automation_attention for an automation that waits for its owner
alerts_and_reportsautomation_report
money_movedtrade, order_filled, deposit, withdrawal
automation_problemsEvery other automation_attention
repliesreply
big_movesholding_move
big_newsmarket_story
weekly_lookweekly_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 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.kindWhat choosing it does
askStart a run with question as the user's own message. fin proposes, and the user approves in chat as always.
openOpen 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:

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:

HTTP
GET /v1/partner/notifications?after=<your saved cursor>&limit=100
X-Api-Key: fin_…
{
  "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.

Fin documentation Built from the API contract · v1

Search all documentation