Building Notification Streams

This guide walks through setting up a notification stream from scratch — choosing signal types, tuning quality gates, and integrating delivery into your app.

Step 1: Review Your Configuration

Every account starts with a default configuration. Check yours:

curl https://api.mbd.xyz/v3/alpha/config \
  -H "Authorization: Bearer mbd-YOUR_KEY"

Key defaults to review:

Setting	Default	Description
`chains`	all	Which chains generate signals
`signal_types`	all	Which signal types are enabled
`daily_budget`	15-30	Max notifications per day
`convergence_min_wallets`	3	Wallets needed for convergence
`whale_min_trade_usd`	50000	Min trade size for whale alerts
`cooldown_hours`	2	Hours between same-token signals

Step 2: Tune Your Configuration

Update only the fields you want to change:

For high-conviction signals only

curl -X PUT https://api.mbd.xyz/v3/alpha/config \
  -H "Authorization: Bearer mbd-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "min_trader_score": 0.3,
    "min_trigger_win_rate": 0.5,
    "min_trigger_closed": 3,
    "convergence_min_wallets": 4,
    "priority_filter": "P0,P1",
    "daily_budget": 20
  }'

For a specific chain

curl -X PUT https://api.mbd.xyz/v3/alpha/config \
  -H "Authorization: Bearer mbd-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chains": ["base"],
    "signal_types": ["convergence_p0", "convergence_p1", "whale_move"]
  }'

Quality Gates Reference

Setting	What it filters	Recommended for production
`min_trader_score`	Minimum composite score (0-1) for triggering wallets	0.2 - 0.4
`min_trigger_win_rate`	Minimum win rate for triggering wallets	0.4 - 0.6
`min_trigger_closed`	Minimum closed positions for triggering wallets	3 - 5
`min_token_liquidity_usd`	Minimum 24h volume for the token	10000 - 50000
`min_token_holders`	Minimum holder count for the token	50 - 100
`convergence_min_wallets`	Wallets needed for convergence signals	3 - 5
`whale_min_trade_usd`	Minimum trade size for whale alerts	25000 - 100000

Step 3: Integrate Delivery

Option A: Polling

Poll GET /notifications every 10-30 seconds using the since parameter:

const API_KEY = 'mbd-YOUR_KEY'
let since = new Date(Date.now() - 3600000).toISOString() // start 1 hour ago

setInterval(async () => {
  const res = await fetch(
    `https://api.mbd.xyz/v3/alpha/notifications?since=${since}&limit=50`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  )
  const { notifications, count } = await res.json()

  for (const signal of notifications) {
    // Process the signal
    console.log(`[${signal.priority}] ${signal.headline}`)
    console.log(`  Token: ${signal.token.symbol} on ${signal.chain}`)
    console.log(`  ${signal.summary.trader_count} traders, $${signal.summary.total_usd_inflow} inflow`)

    // Use signal.cta for deep-linking to swap UI
    // { action: "swap", token_address: "0x...", chain: "base" }

    // Update since to avoid re-processing
    since = signal.timestamp
  }
}, 30000) // every 30 seconds

Option B: Webhook

Set a webhook URL to receive signals via POST:

curl -X PUT https://api.mbd.xyz/v3/alpha/config \
  -H "Authorization: Bearer mbd-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-app.com/webhooks/smart-money"}'

Your webhook receives the same signal payload as GET /notifications. Handle it like:

// Express.js webhook handler
app.post('/webhooks/smart-money', (req, res) => {
  const signal = req.body

  // Deduplicate using signal_id
  if (alreadyProcessed(signal.signal_id)) {
    return res.sendStatus(200)
  }

  // Process the signal
  processSignal(signal)

  res.sendStatus(200)
})

Step 4: Use the Leaderboard

The leaderboard powers the wallet rankings that drive signals. You can also use it directly:

Show top traders to users

const res = await fetch(
  'https://api.mbd.xyz/v3/alpha/leaderboard?chain=base&rank_by=trader_score&limit=20',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
)
const { wallets, total } = await res.json()

// Display in your app
wallets.forEach(w => {
  console.log(`#${w.rank} ${w.wallet_address} — score: ${w.trader_score}, PnL: $${w.net_pnl_usd}`)
})

Filter for experienced traders

?min_trades=50&min_tokens=10&min_closed=5&max_buy_vol=500000

Step 5: Test with Budget Reset

During development, reset your daily budget to receive signals again:

curl -X DELETE https://api.mbd.xyz/v3/alpha/notifications \
  -H "Authorization: Bearer mbd-YOUR_KEY"

This deletes today's notification log and resets the counter.

Signal Anatomy

Every notification includes these fields:

{
  "signal_id": "conv-base-TOSHI-20260323-0845",
  "notification_type": "convergence_p0",
  "priority": "P0",
  "chain": "base",
  "headline": "5 top-ranked traders bought $TOSHI in last 6h",
  "token": {
    "symbol": "$TOSHI",
    "current_price_usd": 0.000812,
    "price_change_pct": 12.4,
    "first_smart_entry_price": 0.000722
  },
  "traders": [
    { "wallet": "0x7a3f...9e2d", "leaderboard_rank": 4, "trade_size_usd": 8420.50, "win_rate": 0.72 }
  ],
  "summary": { "trader_count": 5, "total_usd_inflow": 34200.00, "highest_rank": 4 },
  "why": {
    "reasons": [
      { "text": "3 of these traders have >70% win rate" },
      { "text": "Token price up +12% since first smart entry" }
    ]
  },
  "cta": { "action": "swap", "token_address": "0xac17...", "chain": "base" }
}

Field	Use
`signal_id`	Deduplicate signals
`headline`	Display to users
`why.reasons`	Explain why this signal matters
`cta`	Deep-link to swap UI
`token.price_change_pct`	Show momentum since smart money entry

What's Next

Smart Money Signals → Full API reference with all endpoints
API Reference: Notifications — endpoint specification
API Reference: Configuration — config endpoint specification