Managing Subscriptions

Alert subscriptions define what to monitor and when to notify you. Each subscription watches a specific condition (price, volume, wallet activity, etc.) and fires triggered alerts when that condition is met.

Creating a subscription

Pass an AlertConfig object to subscriptions.create(). The alert_type field determines which parameters are required:

create-price-threshold.ts

import { Chaos } from '@chaoslabs/ai-sdk';
import type { CreateSubscriptionParams } from '@chaoslabs/ai-sdk';
 
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
 
// Price threshold alert
const sub = await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'price_change',
    asset: 'ETH',
    target_price: 4000,
    condition: 'above',
  },
});
 
console.log(sub.id);           // 'ua-d7309261...'
console.log(sub.status);       // 'active'
console.log(sub.alertType);    // 'price_change'
console.log(sub.channels);     // { inApp: true, push: false, ... }

Alert type examples

Each alert type has its own configuration shape:

alert-type-examples.ts

// Price percentage change — alert when BTC drops 10%+
await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'price_change',
    asset: 'BTC',
    change_percent: 10,
    direction: 'down',
  },
});
 
// Volume spike — alert when SOL 1h volume jumps 200%+
await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'volume',
    asset: 'SOL',
    threshold_percent: 200,
    time_window: '1h',
  },
});
 
// Dormant wallet — alert when a wallet inactive for 90 days transacts
await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'dormant_wallet',
    wallet: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    dormant_days: 90,
  },
});
 
// Whale watch — alert on large wallet movements
await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'whale_watch',
    chain: 'ethereum',
    min_balance: 1000000,
    profit_type: 'realized',
  },
});
 
// Token transfer — alert on large USDC transfers
await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'token_transfer',
    symbol: 'USDC',
    min_amount: 1000000,
    chain: 'ethereum',
  },
});
 
// Balance change — alert when wallet balance changes by $50k+
await chaos.alerts.subscriptions.create({
  alert: {
    alert_type: 'balance_change',
    wallet: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    min_usd_value: 50000,
  },
});

Listing subscriptions

Retrieve all subscriptions for the authenticated user:

list-subscriptions.ts

const subs = await chaos.alerts.subscriptions.list();
 
for (const sub of subs) {
  console.log(`${sub.name} [${sub.status}] — ${sub.alertType}`);
  console.log(`  Last fired: ${sub.lastFiredAt ?? 'never'}`);
  console.log(`  Fire count (7d): ${sub.fireCount7d}`);
}

Getting subscription details

The getDetail() method returns the subscription along with its resolved parameters:

get-detail.ts

const { subscription, params } = await chaos.alerts.subscriptions.getDetail('ua-abc123');
 
console.log(subscription.name);
console.log('Resolved params:', params);

Updating a subscription

Update any combination of config, channels, severity policy, or webhook. Only include the fields you want to change:

update-subscription.ts

// Update notification channels
const updated = await chaos.alerts.subscriptions.update('ua-abc123', {
  channels: { inApp: true, push: true, telegram: false, email: true },
});
 
// Change the alert config
const updated2 = await chaos.alerts.subscriptions.update('ua-abc123', {
  alertConfig: {
    alert_type: 'price_change',
    asset: 'ETH',
    target_price: 5000,
    condition: 'above',
  },
});
 
// Update cooldown
const updated3 = await chaos.alerts.subscriptions.update('ua-abc123', {
  cooldownSeconds: 7200,
});

Snooze, mute, and resume

Temporarily pause alerts without deleting the subscription:

snooze-mute.ts

// Snooze for 1 hour, 1 day, or 1 week
await chaos.alerts.subscriptions.snooze('ua-abc123', '1h');
await chaos.alerts.subscriptions.snooze('ua-abc123', '1d');
await chaos.alerts.subscriptions.snooze('ua-abc123', '1w');
 
// Mute indefinitely (until manually resumed)
await chaos.alerts.subscriptions.mute('ua-abc123');
 
// Resume by updating status back to 'active'
await chaos.alerts.subscriptions.update('ua-abc123', {
  status: 'active',
});

Trigger history

Get the list of times a subscription has fired:

trigger-history.ts

const { events, total } = await chaos.alerts.subscriptions.getEvents('ua-abc123');
 
console.log(`${total} total triggers`);
for (const event of events) {
  console.log(`  [${event.severity}] ${event.title} at ${event.triggeredAt}`);
}

Mark read and delete

mark-read-delete.ts

// Mark all events for a subscription as read
const { markedCount } = await chaos.alerts.subscriptions.markRead('ua-abc123');
console.log(`Marked ${markedCount} events as read`);
 
// Delete the subscription
await chaos.alerts.subscriptions.delete('ua-abc123');

Natural language creation

Use fromQuery() to create an alert from a plain English description. The AI workflow parses the intent and creates a typed subscription:

from-query.ts

const result = await chaos.alerts.fromQuery({
  query: 'Notify me if ETH drops below $3000',
  userId: 'user-123',
  chain: 'ethereum',
});
 
switch (result.mode) {
  case 'created':
    console.log('Alert created:', result.alert!.name);
    break;
  case 'interactive':
    console.log('Needs confirmation:', result.blocks);
    break;
  case 'form':
    console.log('Needs additional parameters');
    break;
  case 'error':
    console.error('Failed:', result.error);
    break;
}

Next steps

Alert Inbox — Poll and manage triggered events
Real-time Alerts — Stream alerts via WebSocket
Webhook Delivery — Push alerts to your server
Alerts API Reference — Full type definitions

Was this helpful?

Managing Subscriptions

On this page