The TEE server creates notifications when significant events happen to an agent — for example, when an invoice is paid, when a payment is received to a stealth address, or when a scheduled payment runs. Use these endpoints to surface alerts in your application UI. All endpoints require a Bearer token in the Authorization header.
GET /agent/:id/notifications Fetch all notifications for an agent along with the count of unread ones.
Path parameters Response An array of notification objects, ordered from newest to oldest. Unique numeric identifier for this notification.
The notification category, e.g., "invoice_paid", "payment_received", "schedule_ran".
A short summary of the event.
A longer description with details about the event.
false until you call POST /agent/:id/notifications/read.
ISO 8601 timestamp when the notification was created.
The number of notifications with read: false. Use this to render a badge in your UI.
Example curl https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000/notifications \ -H "Authorization: Bearer wraith_live_abc123"
import { Wraith } from "@wraith-protocol/sdk" ; const wraith = new Wraith ({ apiKey: "wraith_live_abc123" }); const agent = wraith . agent ( "550e8400-e29b-41d4-a716-446655440000" ); const { notifications , unreadCount } = await agent . getNotifications (); console . log ( ` ${ unreadCount } unread notifications` ); for ( const n of notifications ) { const status = n . read ? " " : "* " ; console . log ( ` ${ status } [ ${ n . type } ] ${ n . title } ` ); console . log ( ` ${ n . body } ` ); }
The Notification interface import type { Notification } from "@wraith-protocol/sdk" ; interface Notification { id : number ; type : string ; title : string ; body : string ; read : boolean ; createdAt : string ; }
POST /agent/:id/notifications/read Mark all notifications as read. The unreadCount will be 0 after this call.
Path parameters Response Returns 200 OK with no body on success.
Example curl -X POST \ https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000/notifications/read \ -H "Authorization: Bearer wraith_live_abc123"
import { Wraith } from "@wraith-protocol/sdk" ; const wraith = new Wraith ({ apiKey: "wraith_live_abc123" }); const agent = wraith . agent ( "550e8400-e29b-41d4-a716-446655440000" ); await agent . markNotificationsRead ();
DELETE /agent/:id/notifications Delete all notifications for an agent. This is permanent — deleted notifications cannot be recovered.
Path parameters Response Returns 200 OK with no body on success.
Example curl -X DELETE \ https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000/notifications \ -H "Authorization: Bearer wraith_live_abc123"
import { Wraith } from "@wraith-protocol/sdk" ; const wraith = new Wraith ({ apiKey: "wraith_live_abc123" }); const agent = wraith . agent ( "550e8400-e29b-41d4-a716-446655440000" ); await agent . clearNotifications ();
Polling for notifications Notifications are not pushed — poll the endpoint on a schedule to surface updates in your UI:
import { Wraith } from "@wraith-protocol/sdk" ; const wraith = new Wraith ({ apiKey: "wraith_live_abc123" }); const agent = wraith . agent ( "550e8400-e29b-41d4-a716-446655440000" ); async function pollNotifications () { const { notifications , unreadCount } = await agent . getNotifications (); if ( unreadCount > 0 ) { // Surface unread notifications in your UI const unread = notifications . filter (( n ) => ! n . read ); displayAlerts ( unread ); // Mark as read after displaying await agent . markNotificationsRead (); } } // Poll every 30 seconds setInterval ( pollNotifications , 30_000 );
