Buzz

Buzz Skill

Install, run, and manage a real-time news aggregator with Discord & Telegram push notifications. All configuration is done via REST API with hot-reload — no restarts needed.

Base URL: http://localhost:3848 (default, configurable via dashboard.port)

Quick Setup

git clone https://github.com/zxcnny930/buzz.git
cd buzz
npm install
cp config.example.json config.json
npm start

The dashboard is at http://localhost:3848, settings page at /settings.html?lang=en.

Authentication

If a dashboard password is set, all /api/* endpoints require ?pw=PASSWORD:

curl -s "http://localhost:3848/api/config?pw=YOUR_PASSWORD"

If password is empty string, no authentication is needed.

IMPORTANT: All curl examples below omit ?pw= for brevity. If the server has a password configured, append ?pw=PASSWORD to every URL.

Auth failure response (HTTP 401):

{ "ok": false, "error": "Unauthorized" }

API Endpoints

1. Get Current Config

curl -s http://localhost:3848/api/config

Returns the full configuration JSON. Sensitive fields (apiKey, token, botToken, password) are redacted as "••••••" in the response.

2. Update Config (Partial, Hot-Reload)

POST /api/config accepts partial updates. Only send the sections you want to change.

Enable Jin10 with 10-second polling:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"jin10": {"enabled": true, "pollIntervalMs": 10000}}'

Disable Polymarket:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"polymarket": {"enabled": false}}'

Set Discord webhook:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"discord": {"webhookUrl": "https://discord.com/api/webhooks/..."}}'

Enable Telegram:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"telegram": {"enabled": true, "botToken": "123456:ABC-DEF", "chatId": "-1001234567890"}}'

Add an RSS source:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"rssFeeds": [{"enabled": true, "name": "CoinDesk", "feedUrl": "https://www.coindesk.com/arc/outboundfeeds/rss/?outputType=xml", "pollIntervalMs": 300000, "color": 3447003}]}'

Note: rssFeeds is an array — sending it replaces the entire array, not appends.

Configure OpenNews AI filtering:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"opennews": {"enabled": true, "pollIntervalMs": 60000, "minScore": 70, "signals": ["long"], "coins": ["BTC", "ETH"], "engineTypes": ["news", "listing"]}}'

Configure Polymarket alerts:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"polymarket": {"enabled": true, "minChangePp": 5, "zThreshold": 2.5, "volSpikeThreshold": 2.0, "minLiquidity": 10000, "tagIds": [21, 120], "excludeTagIds": [100639]}}'

Set AI translation model:

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"grok": {"apiKey": "xai-...", "model": "grok-4.1-fast", "baseUrl": "https://api.x.ai/v1"}}'

Success response:

{ "ok": true }

Validation error response:

{
  "ok": false,
  "errors": ["polymarket.zThreshold must be > 0", "dashboard.port must be 1024-65535"]
}

3. Get Source Status

curl -s http://localhost:3848/api/status

Response:

{
  "jin10": { "active": true, "interval": 15000 },
  "blockbeats": { "active": true, "interval": 30000 },
  "polymarket": { "active": true, "interval": 180000 },
  "x6551": { "active": true, "interval": 3600000 },
  "opennews": { "active": false, "interval": 60000 },
  "rss:https://www.blocktempo.com/feed/": { "active": true, "interval": 300000 }
}

Each key is a source identifier. RSS sources are prefixed with rss: followed by their feed URL.

4. Manage KOL Tracking List

List all tracked accounts:

curl -s -X POST http://localhost:3848/api/kols \
  -H "Content-Type: application/json" \
  -d '{"action": "list"}'

Response:

{ "ok": true, "kols": ["elonmusk", "VitalikButerin"] }

Add a KOL:

curl -s -X POST http://localhost:3848/api/kols \
  -H "Content-Type: application/json" \
  -d '{"action": "add", "username": "caboronli"}'

Response:

{ "ok": true, "kols": ["elonmusk", "VitalikButerin", "caboronli"] }

If already exists:

{ "ok": true, "message": "already exists", "kols": ["elonmusk", "VitalikButerin", "caboronli"] }

Remove a KOL:

curl -s -X POST http://localhost:3848/api/kols \
  -H "Content-Type: application/json" \
  -d '{"action": "remove", "username": "elonmusk"}'

Response:

{ "ok": true, "kols": ["VitalikButerin", "caboronli"] }

If username not found:

{ "ok": false, "error": "not found", "kols": ["VitalikButerin", "caboronli"] }

Username strings are trimmed and @ prefix is automatically stripped.

5. Health Check

curl -s http://localhost:3848/health

Response:

{ "ok": true, "clients": 2, "history": 150 }

• clients: number of active SSE connections
• history: number of events in memory

No authentication required.

6. Server-Sent Events (Live Stream)

curl -s -N http://localhost:3848/sse

Streams real-time news events as SSE. On connection, all historical events are sent first, then new events arrive in real-time. Heartbeat every 15 seconds.

Full Configuration Schema

jin10

blockbeats

rssFeeds (array)

x6551

opennews

polymarket

Polymarket Tag IDs:

grok (AI Translation)

Supported models: grok-4.1-fast, gpt-4o-mini, gpt-4.1-mini, claude-sonnet-4-6, claude-haiku-4-5-20251001, gemini-2.0-flash, or any OpenAI-compatible model.

discord

Use either webhookUrl or botToken + channelId, not both.

telegram

dashboard

Common Workflows

Check what's currently running

curl -s http://localhost:3848/api/status | jq 'to_entries[] | select(.value.active) | .key'

Enable a source and verify

# Enable Jin10
curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"jin10": {"enabled": true, "pollIntervalMs": 15000}}'

# Verify it's active
curl -s http://localhost:3848/api/status | jq '.jin10'

Set up Discord + Telegram dual push

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "discord": {"webhookUrl": "https://discord.com/api/webhooks/..."},
    "telegram": {"enabled": true, "botToken": "123456:ABC-DEF", "chatId": "-1001234567890"}
  }'

Add a new RSS feed (without losing existing ones)

IMPORTANT: rssFeeds is an array. POSTing it replaces the entire list. You must GET first, append, then POST back.

Step 1 — Get current feeds:

curl -s http://localhost:3848/api/config | jq '.rssFeeds'

Step 2 — POST the full array with the new feed appended:

# Example: existing feeds are BlockTempo and PTS News, adding CoinDesk
curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"rssFeeds": [
    {"enabled": true, "name": "BlockTempo", "feedUrl": "https://www.blocktempo.com/feed/", "pollIntervalMs": 300000, "color": 16746496},
    {"enabled": true, "name": "PTS News", "feedUrl": "https://news.pts.org.tw/xml/newsfeed.xml", "pollIntervalMs": 300000, "color": 3447003},
    {"enabled": true, "name": "CoinDesk", "feedUrl": "https://www.coindesk.com/arc/outboundfeeds/rss/?outputType=xml", "pollIntervalMs": 300000, "color": 2067276}
  ]}'

Same pattern applies when removing or editing an RSS feed — always send the complete updated array.

Remove an RSS feed

GET current list, remove the target, POST back the remaining array.

# Get current feeds, then POST without the one you want to remove
curl -s http://localhost:3848/api/config | jq '.rssFeeds'
# POST back the array minus the removed feed
curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"rssFeeds": [
    {"enabled": true, "name": "BlockTempo", "feedUrl": "https://www.blocktempo.com/feed/", "pollIntervalMs": 300000, "color": 16746496}
  ]}'

Add an item to any array field (general pattern)

When the user says "also add X", always follow GET → modify → POST:

# Step 1: GET current value
CURRENT=$(curl -s http://localhost:3848/api/config | jq '.polymarket.tagIds')
# Example result: [21, 120]

# Step 2: Append and POST back
# Adding Sports (100639) to existing [21, 120]
curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"polymarket": {"tagIds": [21, 120, 100639]}}'

Same pattern applies to opennews.signals, opennews.coins, opennews.engineTypes, polymarket.excludeTagIds.

Monitor high-impact crypto news only

curl -s -X POST http://localhost:3848/api/config \
  -H "Content-Type: application/json" \
  -d '{"opennews": {"enabled": true, "minScore": 80, "signals": ["long", "short"], "coins": ["BTC", "ETH", "SOL"], "engineTypes": ["news", "listing"]}}'

Track new KOL and verify

# Add
curl -s -X POST http://localhost:3848/api/kols \
  -H "Content-Type: application/json" \
  -d '{"action": "add", "username": "VitalikButerin"}'

# List all
curl -s -X POST http://localhost:3848/api/kols \
  -H "Content-Type: application/json" \
  -d '{"action": "list"}'

Important Rules

Array fields are REPLACED, never merged

The config deep-merge only merges plain objects. All array fields are completely replaced when you POST them. If the user wants to add an item to an existing list, you MUST GET the current config first, modify the array, then POST back.

Array fields that require GET-first when adding/removing items:

Exception — KOLs have a safe endpoint: Use POST /api/kols with action: "add" or "remove". This does NOT require GET-first. Do NOT modify x6551.kols via POST /api/config — use the dedicated endpoint instead.

When the user says "set to" (replace entire list) instead of "add", you can POST directly without GET-first. Example: "I only want Crypto and Finance" → {"polymarket": {"tagIds": [21, 120]}} is fine.

Other rules

1. Object sections support partial update. You can POST just {"jin10": {"enabled": false}} without affecting other jin10 fields or other sections.
2. Sensitive fields are redacted in GET responses as "••••••". When POSTing, redacted values are automatically preserved (not overwritten).
3. All changes are hot-reloaded — no restart needed, except dashboard.port.
4. The x6551.token is shared between X tweet monitor and OpenNews.
5. Get your 6551 API token at https://6551.io/mcp

Error Responses