🌉 Bridge — Agent Framework

BRIDGE — Broadcast Relay for Inter-platform Distribution of Group Events

Outbound message relay from Coin Communities token chats to Telegram, with a live Bun-served web dashboard.

Configure one or more tokenAddress → Telegram chatId routes. Bridge subscribes to each community's realtime socket using server-key auth, forwards every new message to the mapped Telegram chat, and surfaces live status + recent events on a local dashboard at http://localhost:4317.

---

Why Bridge

Project teams almost always run a Telegram group alongside their token community. Without a relay, the two are silos: your alpha holders post on-chain on Coin Communities, your TG mods miss it, and your Telegram chat goes quiet while the actual conversation happens elsewhere.

Bridge ends that — the moment a message lands in the Coin Communities feed, it appears in your Telegram group with attribution and optional moderation filtering.

Features

• Realtime — uses the Coin Communities WebSocket (CommunityRealtimeClient) for sub-second relay
• Multi-route — bridge many communities to many chats from one process
• Server-key auth — no user JWT required; bot runs unattended
• Markdown formatting — configurable template with {username}, {content}, {tokenShort}, {followerCount}
• Built-in filters — drop spam, harmful content, and low-follower noise before it hits your group
• Live dashboard — Bun-native, zero-frontend-deps, dark-mode HTML page at :4317 showing per-route status, totals, and the last 50 bridged events
• Single-binary install — Bun + 3 dependencies

Quickstart

git clone https://github.com/NewSoulOnTheBlock/Bridge-Agent-Framework
cd Bridge-Agent-Framework
bun install
bun setup       # interactive: CC creds, TG bot token, routes
bun start       # bridges + serves dashboard

Telegram setup

1. Talk to @BotFather, /newbot, save the token.
2. Add the bot to your group/channel and promote to admin (required to post in channels).
3. Get the chat_id:
   • For groups: forward a message from the group to @RawDataBot, look for forward_from_chat.id (negative number like -1001234567890).
   • For channels: same flow.

Coin Communities setup

Needs three credentials (mint them in your business dashboard):

• x-api-key (cc_…)
• x-server-key (cck_…)
• x-server-secret (ccs_…)

Architecture

Coin Communities WS ──┐
                      ├─→ filter ─→ format ─→ Telegram Bot API
Coin Communities WS ──┤              │
                      │              └─→ BridgeStore ─→ /api/status ─→ dashboard
Coin Communities WS ──┘

Single Bun process. One CommunityRealtimeClient per route, shared TelegramClient and BridgeStore. Dashboard is Bun.serve() reading from the in-memory store.

Configuration

bridge.config.json (created by bun setup):

{
  "cc": { "baseUrl": "...", "apiKey": "cc_…", "serverKey": "cck_…", "serverSecret": "ccs_…" },
  "telegram": {
    "botToken": "123:ABC",
    "formatTemplate": "💬 *{username}* in *{tokenShort}*\n{content}",
    "disablePreview": true
  },
  "routes": [
    { "tokenAddress": "FWz9h3eD…pump", "chatId": "-1001234567890", "label": "$TOKEN" }
  ],
  "dashboard": { "port": 4317, "enable": true },
  "filters": { "skipSpam": true, "skipHarmful": true, "minFollowers": 0 }
}

Template variables

Token	Meaning
{username}	Poster's Twitter handle
{content}	Message text
{tokenAddress}	Full mint address
{tokenShort}	abcd…wxyz short form
{messageId}	CC message UUID
{followerCount}	Poster's follower count

All values are auto-escaped for Telegram MarkdownV2.

Roadmap

• Inbound: Telegram → Coin Communities mirror (needs server posting enrollment)
• Discord routes
• X / Twitter routes
• Per-route format templates
• Reply threading (group TG replies into forum topics)
• Persistent SQLite store (currently in-memory)

Related

• Chance — AI residents for token chats. Pairs naturally with Bridge: Chance replies in CC, Bridge relays both sides to your TG.
• CoinCommunities.org Agent Skill — comprehensive reference for the underlying platform.

License

MIT