Live Wallet Telegram Monitor

This repository is a standalone Telegram monitor for Polymarket wallet trades.

It polls wallet activity directly from the Polymarket data API and sends new trade notifications to a Telegram bot. It no longer requires the full fixed-wallet-follow project for the primary use case.

What It Does

• monitor one or more wallet addresses
• poll recent trades from https://data-api.polymarket.com
• dedupe previously seen trades using a local state file
• push new trades to Telegram in near real time

Modes

wallet_trades

The primary standalone mode.

• no dependency on the main wallet project
• configure wallet addresses directly in config.yaml
• suitable for simple Telegram trade alerts

watchlist_rpc_ws

Standalone leader-signal mode copied from the live_follow_watchlist -> rpc_ws layer in fixed-wallet-follow.

• reads wallets from live_follow_watchlist.json or a custom watchlist file
• subscribes to Polygon RPC websocket logs and decodes Polymarket wallet trades
• automatically backfills missing token-to-market mappings from Gamma when a fresh market has not landed in the local event index yet
• pushes leader trade signals to Telegram without running the full execution loop

wallet_pool

A legacy compatibility mode.

• reuses the old live wallet-pool snapshot monitor
• still depends on fixed-wallet-follow
• see config.wallet_pool.example.yaml

For the rpc watchlist mode, start from config.watchlist_rpc.example.yaml.

Requirements

• Python 3.10+
• a Telegram bot token
• a Telegram chat id

Installation

git clone https://github.com/your-org/live-wallet-pool-telegram.git
cd live-wallet-pool-telegram
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

Configuration

1. Copy the example config:

cp config.example.yaml config.local.yaml

For watchlist_rpc_ws, use:

cp config.watchlist_rpc.example.yaml config.local.yaml

2. Edit config.local.yaml to match your wallets or watchlist paths.

3. Export Telegram credentials:

export TELEGRAM_BOT_TOKEN=your_bot_token
export TELEGRAM_CHAT_ID=your_chat_id

Example Config

monitor:
  mode: "wallet_trades"
  push_interval_sec: 5
  trade_limit: 50
  seed_on_first_seen: true
  max_signal_age_sec: 180
  wallets:
    - address: "0x1111111111111111111111111111111111111111"
      alias: "wallet-a"
      enabled: true

telegram:
  bot_token_env: "TELEGRAM_BOT_TOKEN"
  chat_id_env: "TELEGRAM_CHAT_ID"

Usage

Preview locally without sending Telegram messages:

python monitor.py --config config.local.yaml --once --dry-run

Run once and send real messages:

python monitor.py --config config.local.yaml --once

Run continuously:

python monitor.py --config config.local.yaml

How Dedupe Works

• the monitor stores the latest seen trade per wallet
• on first startup, it seeds state from the newest trade without notifying on historical trades
• after that, only new trades are pushed
• processed trade ids are retained in state/telegram_monitor_state.json

Notes

• default poll interval is 5 seconds
• default max accepted trade age is 180 seconds
• set notify_sell_trades: false if you only want buy-side alerts
• use allowed_market_slug_prefixes to limit which markets trigger alerts
• watchlist_rpc_ws needs an RPC websocket URL, either in config or POLY_FOLLOWER_RPC_WS_URL

Security Notes

• this repository does not store credentials by default
• pass Telegram secrets via environment variables
• runtime state, logs, virtual environments, and local config overrides are ignored by Git

Legacy Wallet Pool Mode

If you still need the older wallet-pool snapshot flow, use:

• monitor.mode: wallet_pool
• config.wallet_pool.example.yaml

That mode still requires the full fixed-wallet-follow project layout.

License

MIT. See LICENSE.