# bingkltech/polymarket-trading-bot architecture

> Architecture diagram of the GitHub repository bingkltech/polymarket-trading-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bingkltech/polymarket-trading-bot
- Repository: https://github.com/bingkltech/polymarket-trading-bot

## Overview

This is a Polymarket automated trading platform: configured strategies evaluate market data, produce orders, pass wallet-specific risk checks, and execute in paper or live wallets; the dashboard exposes trading and whale activity. The map retains the documented strategy families, whale discovery/copy simulation, learning, and reporting capabilities. Source excerpts and the SOURCE INDEX support the implementation links shown; README links cover documented workflows. Several feature implementations were not sampled, so their internal connections are omitted.

Main entry points: [`src/strategies/registry.ts`](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/registry.ts) (Strategy registry), [`src/core/engine.ts`](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/engine.ts) (Trading engine), [`src/whales/whale_service.ts`](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_service.ts) (Whale service), [`src/data/orderbook_stream.ts`](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/orderbook_stream.ts) (Orderbook stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Trading runtime"]
  node_config["Config loading<br/>[config_loader.ts]"]
  node_engine["Trading engine<br/>[engine.ts]"]
  node_scheduler["Scheduler<br/>[scheduler.ts]"]
end

subgraph group_market["Market data"]
  node_market_fetch["Market fetcher<br/>[market_fetcher.ts]"]
  node_clob["CLOB fetcher<br/>[clob_fetcher.ts]"]
  node_stream["Orderbook stream"]
end

subgraph group_strategies["Strategies"]
  node_registry["Strategy registry<br/>[registry.ts]"]
  node_strategy_contract["Strategy interface"]
  node_arb["Arbitrage strategies"]
  node_mispricing["Mispricing strategy"]
  node_convergence["Convergence strategy"]
  node_market_making["Market making<br/>[spread_strategy.ts]"]
  node_momentum["Momentum strategy"]
  node_ai_forecast["AI forecast"]
  node_web_research["Web research"]
  node_copy_trade["Copy strategy"]
  node_custom_strategy["Custom strategy"]
  node_learning["Strategy learning<br/>[critic.ts]"]
  node_memory[("Learning memory<br/>[memory_bank.ts]")]
end

subgraph group_risk_exec["Risk and execution"]
  node_wallet_manager["Wallet manager<br/>[wallet_manager.ts]"]
  node_paper_wallet["Paper wallet<br/>[paper_wallet.ts]"]
  node_live_wallet["Live wallet"]
  node_fill_sim["Paper fill simulator<br/>[fill_simulator.ts]"]
  node_risk["Risk engine<br/>[risk_engine.ts]"]
  node_kill_switch["Kill switch<br/>[kill_switch.ts]"]
  node_router["Order router<br/>[order_router.ts]"]
  node_executor["Trade executor<br/>[trade_executor.ts]"]
end

subgraph group_insight["Whales and observability"]
  node_whale_service["Whale service<br/>[whale_service.ts]"]
  node_whale_scanner["Whale scanner<br/>[whale_scanner.ts]"]
  node_whale_ingestion["Whale ingestion<br/>[whale_ingestion.ts]"]
  node_dashboard["Dashboard server"]
end

node_operator(("Operator"))
node_polymarket{{"Polymarket APIs"}}

node_operator -->|"configures"| node_config
node_config -->|"starts"| node_engine
node_engine -->|"starts"| node_scheduler
node_engine -->|"starts"| node_stream
node_engine -->|"resolves strategy"| node_registry
node_engine -->|"manages wallets"| node_wallet_manager
node_engine -->|"runs"| node_strategy_contract
node_market_fetch -->|"fetches markets"| node_polymarket
node_clob -->|"fetches books"| node_polymarket
node_stream -->|"uses"| node_market_fetch
node_stream -.->|"uses"| node_clob
node_engine -->|"reads markets"| node_stream
node_registry -->|"registers"| node_arb
node_registry -->|"registers"| node_mispricing
node_registry -->|"registers"| node_convergence
node_registry -->|"registers"| node_market_making
node_registry -->|"registers"| node_momentum
node_registry -->|"registers"| node_ai_forecast
node_registry -->|"registers"| node_copy_trade
node_registry -->|"registers"| node_custom_strategy
node_ai_forecast -.->|"uses research"| node_web_research
node_strategy_contract -->|"reads weights"| node_learning
node_learning -->|"reads memories"| node_memory
node_engine -->|"routes orders"| node_router
node_router -->|"gets wallet"| node_wallet_manager
node_router -->|"checks order"| node_risk
node_risk -->|"checks switch"| node_kill_switch
node_router -->|"executes approved"| node_executor
node_wallet_manager -->|"creates paper"| node_paper_wallet
node_wallet_manager -->|"creates live"| node_live_wallet
node_paper_wallet -->|"simulates fills"| node_fill_sim
node_paper_wallet -->|"uses prices"| node_stream
node_live_wallet -.->|"places trades"| node_polymarket
node_operator -->|"manages tracking"| node_whale_service
node_whale_service -->|"starts scanner"| node_whale_scanner
node_whale_service -->|"uses ingestion"| node_whale_ingestion
node_whale_service -->|"coordinates discovery"| node_whale_scanner
node_whale_service -.->|"feeds copy trading"| node_copy_trade
node_operator -->|"views dashboard"| node_dashboard
node_dashboard -->|"reads wallets"| node_wallet_manager
node_dashboard -->|"shows whale data"| node_whale_service

click node_config "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/config_loader.ts"
click node_engine "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/engine.ts"
click node_scheduler "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/scheduler.ts"
click node_market_fetch "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/market_fetcher.ts"
click node_clob "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/clob_fetcher.ts"
click node_stream "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/orderbook_stream.ts"
click node_registry "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/registry.ts"
click node_strategy_contract "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/strategy_interface.ts"
click node_arb "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/arbitrage/cross_market_arbitrage.ts"
click node_mispricing "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/arbitrage/mispricing_detector.ts"
click node_convergence "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/convergence/filtered_high_prob_convergence.ts"
click node_market_making "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/market_making/spread_strategy.ts"
click node_momentum "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/trend/momentum_strategy.ts"
click node_ai_forecast "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/research_ai/ai_forecast_strategy.ts"
click node_web_research "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/research_ai/web_research_pipeline.ts"
click node_copy_trade "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/copy_trading/copy_trade_strategy.ts"
click node_custom_strategy "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/custom/user_defined_strategy.ts"
click node_wallet_manager "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/wallets/wallet_manager.ts"
click node_paper_wallet "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/wallets/paper_wallet.ts"
click node_live_wallet "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/wallets/polymarket_wallet.ts"
click node_fill_sim "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/paper_trading/fill_simulator.ts"
click node_risk "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/risk/risk_engine.ts"
click node_kill_switch "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/risk/kill_switch.ts"
click node_router "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/execution/order_router.ts"
click node_executor "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/execution/trade_executor.ts"
click node_learning "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/learning/critic.ts"
click node_memory "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/learning/memory_bank.ts"
click node_whale_service "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_service.ts"
click node_whale_scanner "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_scanner.ts"
click node_whale_ingestion "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_ingestion.ts"
click node_dashboard "https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/reporting/dashboard_server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_engine,node_scheduler toneBlue
class node_market_fetch,node_clob,node_stream toneAmber
class node_registry,node_strategy_contract,node_arb,node_mispricing,node_convergence,node_market_making,node_momentum,node_ai_forecast,node_web_research,node_copy_trade,node_custom_strategy,node_learning,node_memory,node_polymarket toneMint
class node_wallet_manager,node_paper_wallet,node_live_wallet,node_fill_sim,node_risk,node_kill_switch,node_router,node_executor toneRose
class node_whale_service,node_whale_scanner,node_whale_ingestion,node_dashboard,node_operator toneIndigo
```

## Components

### Trading runtime

- [Config loading](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/config_loader.ts): `src/core/config_loader.ts`
- [Trading engine](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/engine.ts): `src/core/engine.ts`
- [Scheduler](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/core/scheduler.ts): `src/core/scheduler.ts`

### Market data

- [Market fetcher](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/market_fetcher.ts): `src/data/market_fetcher.ts`
- [CLOB fetcher](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/clob_fetcher.ts): `src/data/clob_fetcher.ts`
- [Orderbook stream](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/data/orderbook_stream.ts): `src/data/orderbook_stream.ts`

### Strategies

- [Strategy registry](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/registry.ts): `src/strategies/registry.ts`
- [Strategy interface](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/strategy_interface.ts): `src/strategies/strategy_interface.ts`
- [Arbitrage strategies](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/arbitrage/cross_market_arbitrage.ts): `src/strategies/arbitrage/cross_market_arbitrage.ts`
- [Mispricing strategy](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/arbitrage/mispricing_detector.ts): `src/strategies/arbitrage/mispricing_detector.ts`
- [Convergence strategy](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/convergence/filtered_high_prob_convergence.ts): `src/strategies/convergence/filtered_high_prob_convergence.ts`
- [Market making](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/market_making/spread_strategy.ts): `src/strategies/market_making/spread_strategy.ts`
- [Momentum strategy](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/trend/momentum_strategy.ts): `src/strategies/trend/momentum_strategy.ts`
- [AI forecast](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/research_ai/ai_forecast_strategy.ts): `src/strategies/research_ai/ai_forecast_strategy.ts`
- [Web research](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/research_ai/web_research_pipeline.ts): `src/strategies/research_ai/web_research_pipeline.ts`
- [Copy strategy](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/copy_trading/copy_trade_strategy.ts): `src/strategies/copy_trading/copy_trade_strategy.ts`
- [Custom strategy](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/strategies/custom/user_defined_strategy.ts): `src/strategies/custom/user_defined_strategy.ts`
- [Strategy learning](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/learning/critic.ts): `src/learning/critic.ts`
- [Learning memory](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/learning/memory_bank.ts): `src/learning/memory_bank.ts`

### Risk and execution

- [Wallet manager](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/wallets/wallet_manager.ts): `src/wallets/wallet_manager.ts`
- [Paper wallet](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/wallets/paper_wallet.ts): `src/wallets/paper_wallet.ts`
- [Live wallet](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/wallets/polymarket_wallet.ts): `src/wallets/polymarket_wallet.ts`
- [Paper fill simulator](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/paper_trading/fill_simulator.ts): `src/paper_trading/fill_simulator.ts`
- [Risk engine](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/risk/risk_engine.ts): `src/risk/risk_engine.ts`
- [Kill switch](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/risk/kill_switch.ts): `src/risk/kill_switch.ts`
- [Order router](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/execution/order_router.ts): `src/execution/order_router.ts`
- [Trade executor](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/execution/trade_executor.ts): `src/execution/trade_executor.ts`

### Whales and observability

- [Whale service](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_service.ts): `src/whales/whale_service.ts`
- [Whale scanner](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_scanner.ts): `src/whales/whale_scanner.ts`
- [Whale ingestion](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/whales/whale_ingestion.ts): `src/whales/whale_ingestion.ts`
- [Dashboard server](https://github.com/bingkltech/polymarket-trading-bot/blob/main/src/reporting/dashboard_server.ts): `src/reporting/dashboard_server.ts`

### Other components

- **Operator**
- **Polymarket APIs**

## Connections

- Operator → Config loading: configures
- Config loading → Trading engine: starts (evidence: `src/cli.ts`)
- Trading engine → Scheduler: starts (evidence: `src/core/engine.ts`)
- Trading engine → Orderbook stream: starts (evidence: `src/core/engine.ts`)
- Trading engine → Strategy registry: resolves strategy (evidence: `src/core/engine.ts`)
- Trading engine → Wallet manager: manages wallets (evidence: `src/core/engine.ts`)
- Trading engine → Strategy interface: runs (evidence: `src/core/engine.ts`)
- Market fetcher → Polymarket APIs: fetches markets
- CLOB fetcher → Polymarket APIs: fetches books (evidence: `src/data/clob_fetcher.ts`)
- Orderbook stream → Market fetcher: uses (evidence: `src/data/orderbook_stream.ts`)
- Orderbook stream → CLOB fetcher: uses
- Trading engine → Orderbook stream: reads markets (evidence: `src/core/engine.ts`)
- Strategy registry → Arbitrage strategies: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → Mispricing strategy: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → Convergence strategy: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → Market making: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → Momentum strategy: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → AI forecast: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → Copy strategy: registers (evidence: `src/strategies/registry.ts`)
- Strategy registry → Custom strategy: registers (evidence: `src/strategies/registry.ts`)
- AI forecast → Web research: uses research
- Strategy interface → Strategy learning: reads weights (evidence: `src/strategies/strategy_interface.ts`)
- Strategy learning → Learning memory: reads memories (evidence: `src/learning/critic.ts`)
- Trading engine → Order router: routes orders (evidence: `src/core/engine.ts`)
- Order router → Wallet manager: gets wallet (evidence: `src/execution/order_router.ts`)
- Order router → Risk engine: checks order (evidence: `src/execution/order_router.ts`)
- Risk engine → Kill switch: checks switch (evidence: `src/risk/risk_engine.ts`)
- Order router → Trade executor: executes approved (evidence: `src/execution/order_router.ts`)
- Wallet manager → Paper wallet: creates paper (evidence: `src/wallets/wallet_manager.ts`)
- Wallet manager → Live wallet: creates live (evidence: `src/wallets/wallet_manager.ts`)
- Paper wallet → Paper fill simulator: simulates fills (evidence: `src/wallets/paper_wallet.ts`)
- Paper wallet → Orderbook stream: uses prices (evidence: `src/wallets/paper_wallet.ts`)
- Live wallet → Polymarket APIs: places trades
- Operator → Whale service: manages tracking
- Whale service → Whale scanner: starts scanner (evidence: `src/whales/whale_service.ts`)
- Whale service → Whale ingestion: uses ingestion (evidence: `src/whales/whale_service.ts`)
- Whale service → Whale scanner: coordinates discovery (evidence: `src/whales/whale_service.ts`)
- Whale service → Copy strategy: feeds copy trading
- Operator → Dashboard server: views dashboard
- Dashboard server → Wallet manager: reads wallets (evidence: `src/reporting/dashboard_server.ts`)
- Dashboard server → Whale service: shows whale data (evidence: `src/cli.ts`)
