ts-subscription-client

TypeScript client for the Marinade notification subscription API. Allows users to subscribe/unsubscribe to notifications and list active subscriptions.

Usage

import {
  createSubscriptionClient,
  subscribeMessage,
  unsubscribeMessage,
  listSubscriptionsMessage,
} from '@marinade.finance/ts-subscription-client'

const client = createSubscriptionClient({
  base_url: 'https://notifications.marinade.finance',
})

The message format is built by helper functions (subscribeMessage, unsubscribeMessage, listSubscriptionsMessage). Each request includes a signature and message for server-side authentication.

For local development and testing subscriptions end-to-end, see notification-service/DEV_GUIDE.md.

Channels

A "channel" is a delivery medium for notifications. Each subscription binds a user to a channel + address pair.

telegram

Telegram subscriptions use a two-phase activation flow:

1. Subscribe — the client sends a POST /subscriptions request with channel=telegram. The server creates a pending activation record and returns a deep_link in the response (e.g., https://t.me/MarinadeBot?start=<token>). At this point the subscription exists but cannot receive messages.

2. Activate — the user opens the deep link in Telegram and presses "Start". The bot receives the token via its webhook, links the user's Telegram chat to the subscription, and confirms activation. From this point on, notifications are delivered as Telegram messages.

If the user has already activated, the response returns telegram_status: 'already_activated' instead of a new deep link.

Blocking the bot automatically unsubscribes all Telegram subscriptions for that chat.

api

The API channel stores notifications in a server-side outbox. Clients pull them via the read API (notifications endpoint). No activation step is needed — subscribing is sufficient.

Notification types

bonds

Bond risk notifications for validators in the SAM auction. Subscribing requires proof of authority over a bond — the signer must be the bond authority, validator identity, or vote account owner. The server verifies this against on-chain bond accounts.

The additional_data field for subscribe/unsubscribe should include:

{
  config_address: string // bonds program config
  vote_account: string // validator vote account
  bond_pubkey: string // derived bond PDA
}

For listing subscriptions (GET /subscriptions), no additional_data is needed — the server performs a reverse lookup from the pubkey.