alchemist-x/all-polymarket-skill/poly-position-monitor

Polymarket Position Monitor

Monitor wallet positions on Polymarket in real time. Detects 5 types of anomalies across all held markets and delivers alerts through console, Telegram, and email.

Anomaly Types

1. Price volatility — relative price change exceeds threshold on 5/15/60/240 min windows
2. Volume anomaly — trading volume spikes or drops vs rolling average
3. Large inflows — new positions or significant size changes
4. Whale activity — watched addresses trade on the user's held markets
5. Order changes — open orders filled, partially filled, or cancelled

Workflow

Execute the following 6 steps in order.

Step 1: Configure

Copy the example config and fill in credentials:

cp scripts/config.example.json ~/polymarket-monitoring/config.json

Edit ~/polymarket-monitoring/config.json:

1. user_addresses: Add the user's Polymarket wallet address(es)
2. watched_addresses: Add whale/notable addresses to monitor (with labels)
3. clob_auth: Add API credentials for order monitoring (see below)
4. thresholds: Adjust alert thresholds if needed (see references/alert-thresholds.md)
5. notifications: Enable Telegram and/or email

Getting CLOB API credentials:

from py_clob_client.client import ClobClient
client = ClobClient("https://clob.polymarket.com", chain_id=137, key="YOUR_PRIVATE_KEY")
creds = client.create_or_derive_api_creds()
print(creds)  # {"apiKey": "...", "secret": "...", "passphrase": "..."}

Setting up Telegram Bot:

1. Message @BotFather on Telegram, create a bot, get the token
2. Send a message to your bot, then call https://api.telegram.org/bot<TOKEN>/getUpdates to find your chat_id
3. Set telegram.enabled: true, fill in bot_token and chat_id

Step 2: Install Dependencies

pip install py-clob-client

Only required for open order monitoring. Position tracking, price analysis, volume tracking, and whale detection use standard library only.

Step 3: Initial Snapshot

Run the position fetcher to verify connectivity and see current holdings:

python scripts/fetch_positions.py <wallet_address>

This shows all active positions, their markets, current values, and PnL. Confirm the output looks correct before starting the monitor.

Step 4: Verify Connections

Test each component individually:

# Test price history (use an asset_id from Step 3 output)
python scripts/fetch_price_history.py <token_id>
 
# Test market trades (use a condition_id from Step 3 output)
python scripts/fetch_market_activity.py trades --market <condition_id>
 
# Test order fetching (requires auth)
python scripts/fetch_orders.py --config ~/polymarket-monitoring/config.json

If Telegram is configured, the monitor will send a test alert on first run.

Step 5: Start Monitor

python scripts/monitor.py --config ~/polymarket-monitoring/config.json

The monitor runs continuously, checking every interval_seconds (default: 60s).

Options:

• --once — Run a single cycle and exit (useful for cron jobs)
• --interval 30 — Override check interval to 30 seconds

Cron setup (alternative to continuous mode):

# Check every 2 minutes
*/2 * * * * cd ~/.claude/skills/poly-position-monitor && python scripts/monitor.py --config ~/polymarket-monitoring/config.json --once >> ~/polymarket-monitoring/cron.log 2>&1

Graceful shutdown: Ctrl-C saves final state and exits cleanly.

Step 6: Manage

View alert history:

# Recent alerts (JSON lines)
tail -20 ~/polymarket-monitoring/alerts.jsonl
 
# Filter by type
grep '"CRITICAL"' ~/polymarket-monitoring/alerts.jsonl
grep '"whale"' ~/polymarket-monitoring/alerts.jsonl

View state snapshots:

ls ~/polymarket-monitoring/snapshot-*.json
cat ~/polymarket-monitoring/monitor-state.json

Add/remove watched addresses: Edit watched_addresses in config.json. Changes take effect on next cycle.

Adjust thresholds: Edit thresholds in config.json. See references/alert-thresholds.md for tuning guide.

Troubleshooting

• No positions found: Verify the wallet address is correct and has active (non-redeemed) positions on Polymarket
• Price history empty: The token_id (asset_id) might be invalid. Check that the position's asset_id matches a valid CLOB token
• Order fetch fails: Verify API credentials. Re-derive with create_or_derive_api_creds() if needed
• Telegram not sending: Check bot token and chat_id. Ensure the bot has received at least one message from the user first
• Too many alerts: Increase thresholds in config.json. Set notification min_level to "ALERT" or "CRITICAL"
• Rate limiting: Increase interval_seconds. The monitor makes ~3 API calls per market per cycle

Reference Files

• references/polymarket-api.md — API endpoint documentation
• references/alert-thresholds.md — Threshold tuning guide
• references/output-template.md — Alert format specifications