Skip to main content

​
Overview

The terminal is composed of five independent Python modules that communicate through a shared SQLite database. The Telegram bot layer handles all user interaction; the monitoring engine runs in a background asyncio task per active user.

​
Architecture Diagram

┌─────────────────────────────────────────────────────┐
│                   Telegram Bot Layer                 │
│         (user commands, notifications, menus)        │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│              Per-User Monitoring Task                │
│          asyncio background task · 30s cycle         │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │  Intersection│  │  Pre-News    │  │Quick Flip │  │
│  │  Detector    │  │  Detector    │  │ Detector  │  │
│  └──────────────┘  └──────────────┘  └───────────┘  │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │  Contrarian  │  │Position      │                  │
│  │  Detector    │  │Growth Det.   │                  │
│  └──────────────┘  └──────────────┘                  │
└─────────────────────┬───────────────────────────────┘
                      │
          ┌───────────┴───────────┐
          ▼                       ▼
┌──────────────────┐   ┌─────────────────────┐
│  Gamma API       │   │  SQLite Database     │
│  (market data,   │   │  (users, positions,  │
│   user activity) │   │   signal_history,    │
└──────────────────┘   │   watchlist)         │
                       └─────────────────────┘
                                │
                       ┌────────┴────────┐
                       ▼                 ▼
              ┌──────────────┐  ┌──────────────┐
              │  CLOB API    │  │ Position     │
              │  (order exec,│  │ Monitor      │
              │   position   │  │ 60s cycle    │
              │   mgmt)      │  │ SL/TP exits  │
              └──────────────┘  └──────────────┘

​
Data Flow

Each active user spawns an independent asyncio monitoring task. Every 30 seconds the task calls check_new_trades(), which fans out to all enabled pattern detectors in parallel. Pattern detectors call search_markets() and get_user_activity() against the Polymarket Gamma API, apply detection logic, score the signal, and write results to the database.

​
Module Responsibilities

ModuleResponsibility
bot.pyTelegram interface, command routing, notification delivery
monitor.pyPer-user asyncio task, 30s cycle orchestration
detectors.pyFive pattern detector implementations
execution.pyCLOB API order placement and position management
database.pySQLite schema, migrations, query helpers

​
Caching Strategy

CacheTTLPurpose
Market data (_market_cache)SessionKeyed on conditionId, id, and slug
Whale analysis6 hoursPer wallet, limits Gamma API calls
Signal deduplication (seen_trades)24 hoursPrevents re-firing same market/pattern