Understanding Notifications

SupaScan provides comprehensive notification system for blockchain events, allowing you to receive real-time alerts via Discord, Telegram, AI agents, and custom webhooks. This guide explains how to configure and manage different types of notifications for various blockchain events.

Notification Types

🪙 Token Creation Events

What it means: New tokens have been created with specific criteria you've configured.

Example notification:

{
  "event_type": "token_creation",
  "timestamp": "2024-01-15T14:30:00Z",
  "token": {
    "mint": "So11111111111111111111111111111111111111112",
    "name": "Example Token",
    "symbol": "EXT",
    "supply": 1000000000,
    "deployer": "Deployer1234567890abcdef1234567890abcdef123456"
  },
  "liquidity": {
    "usd": 50000,
    "dex": "raydium"
  },
  "metadata": {
    "social_signals": {
      "twitter_mentions": 15,
      "telegram_members": 2500
    }
  }
}

Impact: Early detection of new token launches for trading opportunities.

💰 Large Transaction Alerts

What it means: Significant transactions exceeding your configured thresholds.

Example notification:

{
  "event_type": "large_transaction",
  "timestamp": "2024-01-15T14:30:00Z",
  "transaction": {
    "signature": "5KJp7K8XQ2w3e4r5t6y7u8i9o0p1a2s3d4f5g6h7j8k9l0z1x2c3v4b5n6m7",
    "amount_usd": 250000,
    "token": "USDC",
    "from": "Wallet1234567890abcdef1234567890abcdef123456",
    "to": "Wallet0987654321fedcba0987654321fedcba098765"
  },
  "context": {
    "wallet_type": "whale",
    "transaction_type": "transfer"
  }
}

Impact: Monitor whale movements and significant market activity.

🔄 DEX Swap Events

What it means: Large swaps or unusual trading patterns detected on DEXs.

Example notification:

{
  "event_type": "dex_swap",
  "timestamp": "2024-01-15T14:30:00Z",
  "swap": {
    "dex": "raydium",
    "token_in": "SOL",
    "token_out": "BONK",
    "amount_in": 1000,
    "amount_out": 50000000,
    "price_impact": 0.15,
    "wallet": "Trader1234567890abcdef1234567890abcdef123456"
  },
  "analysis": {
    "wallet_type": "smart_money",
    "historical_performance": 0.85
  }
}

Impact: Track smart money movements and trading patterns.

🚨 Social Signal Alerts

What it means: Significant social media activity related to specific tokens or wallets.

Example notification:

{
  "event_type": "social_signal",
  "timestamp": "2024-01-15T14:30:00Z",
  "signal": {
    "type": "twitter_mention_spike",
    "token": "BONK",
    "influencer": "@crypto_whale",
    "engagement": {
      "mentions": 500,
      "retweets": 2500,
      "likes": 10000
    },
    "onchain_impact": {
      "volume_increase": 3.5,
      "price_change": 0.25
    }
  }
}

Impact: Early detection of social media influence on token prices.

Notification Channels

SupaScan supports multiple notification channels, allowing you to receive alerts through your preferred platforms.

Discord Notifications

Configure Discord webhooks for real-time alerts:

# Create Discord notification
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "discord",
    "webhook_url": "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN",
    "event_types": ["token_creation", "large_transaction", "dex_swap"],
    "filters": {
      "min_liquidity_usd": 10000,
      "dex_protocols": ["raydium", "meteora"]
    },
    "format": "rich_embed",
    "mention_roles": ["@everyone"],
    "cooldown_minutes": 5
  }' \
  https://api.supascan.com/v1/notifications/channels

Discord Message Format:

{
  "embeds": [{
    "title": "🪙 New Token Created",
    "color": 65280,
    "fields": [
      {"name": "Token", "value": "EXT (Example Token)", "inline": true},
      {"name": "Liquidity", "value": "$50,000", "inline": true},
      {"name": "DEX", "value": "Raydium", "inline": true},
      {"name": "Deployer", "value": "Deployer1234...3456", "inline": false}
    ],
    "timestamp": "2024-01-15T14:30:00Z",
    "footer": {"text": "SupaScan Alert"}
  }]
}

Telegram Notifications

Set up Telegram bot notifications:

# Create Telegram notification
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "bot_token": "YOUR_BOT_TOKEN",
    "chat_id": "YOUR_CHAT_ID",
    "event_types": ["token_creation", "social_signal"],
    "filters": {
      "min_volume_24h_usd": 100000,
      "social_signals": {
        "min_twitter_mentions": 50
      }
    },
    "format": "markdown",
    "parse_mode": "MarkdownV2",
    "disable_web_page_preview": true
  }' \
  https://api.supascan.com/v1/notifications/channels

Telegram Message Format:

🪙 **New Token Alert**

**Token**: EXT \(Example Token\)
**Symbol**: EXT
**Liquidity**: $50,000
**DEX**: Raydium
**Deployer**: `Deployer1234...3456`

📊 **Social Signals**
• Twitter Mentions: 15
• Telegram Members: 2,500

🔗 [View on SupaScan](https://supascan.com/token/So11111111111111111111111111111111111111112)

AI Agent Notifications

Configure AI agents to receive and process notifications:

# Create AI Agent notification
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ai_agent",
    "agent_config": {
      "name": "Trading Bot",
      "endpoint": "https://your-trading-bot.com/webhook",
      "authentication": {
        "type": "bearer_token",
        "token": "YOUR_AGENT_TOKEN"
      }
    },
    "event_types": ["token_creation", "large_transaction", "dex_swap"],
    "filters": {
      "min_liquidity_usd": 25000,
      "exclude_known_scams": true,
      "require_social_signals": true
    },
    "action_triggers": {
      "token_creation": "analyze_and_trade",
      "large_transaction": "monitor_wallet",
      "dex_swap": "track_pattern"
    },
    "evaluation_criteria": {
      "liquidity_threshold": 25000,
      "social_signal_weight": 0.3,
      "deployer_reputation_weight": 0.4,
      "technical_analysis_weight": 0.3
    }
  }' \
  https://api.supascan.com/v1/notifications/channels

AI Agent Payload Format:

{
  "notification_id": "notif_123456789",
  "event_type": "token_creation",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "token": {
      "mint": "So11111111111111111111111111111111111111112",
      "name": "Example Token",
      "symbol": "EXT",
      "supply": 1000000000
    },
    "liquidity": {
      "usd": 50000,
      "dex": "raydium"
    },
    "social_signals": {
      "twitter_mentions": 15,
      "telegram_members": 2500
    }
  },
  "evaluation_score": 0.85,
  "recommended_actions": [
    "monitor_price_movement",
    "check_deployer_history",
    "analyze_liquidity_depth"
  ],
  "risk_assessment": "medium",
  "confidence_level": 0.75
}

AI Agent Programming

Event-Based Actions

Configure AI agents to perform specific actions based on notification types:

// Example AI Agent Handler
const handleNotification = async (notification) => {
  const { event_type, data, evaluation_score } = notification;
  
  switch (event_type) {
    case 'token_creation':
      if (evaluation_score > 0.8) {
        await analyzeToken(data.token);
        await checkDeployerHistory(data.token.deployer);
        await monitorLiquidity(data.liquidity);
      }
      break;
      
    case 'large_transaction':
      if (data.amount_usd > 100000) {
        await trackWallet(data.transaction.from);
        await analyzeTransactionPattern(data.transaction);
      }
      break;
      
    case 'dex_swap':
      if (data.analysis.wallet_type === 'smart_money') {
        await followSmartMoney(data.swap.wallet);
        await analyzeSwapPattern(data.swap);
      }
      break;
  }
};

Evaluation and Scoring

AI agents receive evaluation scores to help determine appropriate actions:

{
  "evaluation_criteria": {
    "liquidity_score": 0.9,
    "social_signal_score": 0.7,
    "deployer_reputation_score": 0.8,
    "technical_analysis_score": 0.6,
    "overall_score": 0.75
  },
  "risk_factors": [
    "new_deployer",
    "low_liquidity",
    "no_social_signals"
  ],
  "opportunity_indicators": [
    "high_liquidity",
    "reputable_deployer",
    "strong_social_signals",
    "good_technical_analysis"
  ]
}

Action Triggers

Define specific actions based on notification evaluation:

# Configure action triggers
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "trading_bot_001",
    "action_triggers": {
      "token_creation": {
        "conditions": {
          "min_evaluation_score": 0.8,
          "min_liquidity_usd": 25000,
          "require_social_signals": true
        },
        "actions": [
          "analyze_token_metrics",
          "check_deployer_reputation",
          "monitor_price_movement",
          "calculate_entry_point"
        ]
      },
      "large_transaction": {
        "conditions": {
          "min_amount_usd": 100000,
          "wallet_types": ["whale", "smart_money"]
        },
        "actions": [
          "track_wallet_activity",
          "analyze_transaction_pattern",
          "update_wallet_profiling"
        ]
      },
      "social_signal": {
        "conditions": {
          "min_engagement": 1000,
          "influencer_verified": true
        },
        "actions": [
          "monitor_sentiment",
          "track_price_correlation",
          "analyze_market_impact"
        ]
      }
    }
  }' \
  https://api.supascan.com/v1/notifications/agents/configure

Notification Delivery

Real-time Delivery

All notifications are delivered in real-time with configurable delivery options:

  • Instant: Immediate delivery (default)
  • Batched: Grouped delivery every 30 seconds
  • Scheduled: Delivery at specific intervals

Reliability Features

  • Retry Logic: Automatic retry for failed deliveries
  • Fallback Channels: Alternative delivery methods
  • Delivery Confirmation: Webhook confirmation system
  • Rate Limiting: Built-in rate limiting protection

Message Formatting

Customizable message formats for each channel:

  • Discord: Rich embeds with color coding
  • Telegram: Markdown formatting with inline keyboards
  • AI Agents: Structured JSON with evaluation data
  • Webhooks: Custom payload formats

Managing Notifications

Customizing Notifications

SupaScan provides extensive customization options for all notification types:

# Update notification preferences
curl -X PUT \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_id": "notif_123456789",
    "filters": {
      "min_liquidity_usd": 50000,
      "dex_protocols": ["raydium", "meteora", "orca"],
      "exclude_known_scams": true,
      "require_social_signals": true,
      "min_twitter_mentions": 100
    },
    "cooldown_minutes": 10,
    "max_notifications_per_hour": 20,
    "enabled": true
  }' \
  https://api.supascan.com/v1/notifications/channels/update

Notification History

Access your notification history and analytics:

# Get notification history
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/history?limit=100&offset=0"

# Get notification analytics
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/analytics?period=7d"

Batch Processing

Configure batch processing for high-frequency events:

# Configure batch processing
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_config": {
      "batch_size": 50,
      "batch_interval_seconds": 60,
      "max_events_per_batch": 100,
      "batch_format": "grouped",
      "include_summary": true
    },
    "notification_channels": ["discord", "telegram", "ai_agent"]
  }' \
  https://api.supascan.com/v1/notifications/batch/configure

Advanced Features

Smart Filtering

Use AI-powered smart filtering to reduce noise:

# Enable smart filtering
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "smart_filtering": {
      "enabled": true,
      "ai_model": "supascan_v2",
      "filtering_criteria": {
        "relevance_threshold": 0.7,
        "quality_score_threshold": 0.8,
        "noise_reduction": 0.9
      },
      "learning_enabled": true,
      "feedback_loop": true
    }
  }' \
  https://api.supascan.com/v1/notifications/smart-filtering

Multi-Channel Routing

Route different events to different channels:

# Configure multi-channel routing
curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_rules": [
      {
        "event_types": ["token_creation"],
        "channels": ["discord", "ai_agent"],
        "priority": "high"
      },
      {
        "event_types": ["large_transaction"],
        "channels": ["telegram"],
        "priority": "medium"
      },
      {
        "event_types": ["social_signal"],
        "channels": ["discord"],
        "priority": "low"
      }
    ]
  }' \
  https://api.supascan.com/v1/notifications/routing

Troubleshooting

Not receiving notifications?

  1. Check notification status:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/status"

  2. Verify channel configuration:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/channels"

  3. Test webhook endpoints:

    curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/test"

Delayed notifications?

  1. Check system status:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/system/status"

  2. Monitor notification queue:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/queue-status"

  3. Check delivery logs:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/delivery-logs"

AI Agent Issues?

  1. Check agent configuration:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/agents/status"

  2. Review evaluation scores:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/agents/evaluations"

  3. Test agent endpoints:

    curl -X POST \
  -H "Authorization: Bearer $SUPASCAN_API_KEY" \
  "https://api.supascan.com/v1/notifications/agents/test"
Previous
API Reference
Next
Architecture