# blockrunai/polymarket-agent architecture

> Architecture diagram of the GitHub repository blockrunai/polymarket-agent, 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/blockrunai/polymarket-agent
- Repository: https://github.com/blockrunai/polymarket-agent

## Overview

This repository is a Polymarket prediction-market trading agent with a Flask monitoring dashboard and CLI. Its principal workflow is to discover active markets, gather smart-money trade signals, obtain AI analysis, size potential positions, and—when enabled—submit trades. Wallet management supports Polygon trading, while the README describes the agent’s separate Base-chain AI payments. Optional Google Cloud Storage persists market analyses and agent history. The graph follows documented or indexed dependencies; some runtime wiring is not visible in the excerpts, so uncertain links are omitted.

Main entry points: [`app.py`](https://github.com/blockrunai/polymarket-agent/blob/main/app.py) (Web Dashboard), [`src/agent.py`](https://github.com/blockrunai/polymarket-agent/blob/main/src/agent.py) (Agent Coordinator), [`src/analysis/ai_analyzer.py`](https://github.com/blockrunai/polymarket-agent/blob/main/src/analysis/ai_analyzer.py) (AI Consensus), [`src/trading/executor.py`](https://github.com/blockrunai/polymarket-agent/blob/main/src/trading/executor.py) (Order Execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_dashboard["Web Dashboard<br/>[app.py]"]
  node_dashboard_views["Dashboard Views<br/>[index.html]"]
  node_cli["CLI<br/>[main.py]"]
  node_agent["Agent Coordinator<br/>[agent.py]"]
end

subgraph group_analysis["Market Intelligence"]
  node_markets["Market Discovery<br/>[polymarket.py]"]
  node_whale_signals["Smart-Money Signals<br/>[trades.py]"]
  node_analyzer["AI Consensus<br/>[ai_analyzer.py]"]
end

subgraph group_trading["Trading Operations"]
  node_sizing["Kelly Sizing<br/>[kelly.py]"]
  node_executor["Order Execution<br/>[executor.py]"]
  node_wallet["Polygon Wallet<br/>[wallet.py]"]
end

subgraph group_state["Persistence"]
  node_storage[("GCS Persistence<br/>[gcs_storage.py]")]
end

node_operator(("Operator"))
node_ai_service{{"BlockRun AI"}}
node_polymarket{{"Polymarket APIs"}}
node_polygon{{"Polygon Network"}}

node_operator -->|"monitors"| node_dashboard
node_operator -->|"runs"| node_cli
node_dashboard -->|"renders"| node_dashboard_views
node_cli -->|"creates"| node_agent
node_dashboard -->|"fetches markets"| node_markets
node_dashboard -->|"requests analysis"| node_analyzer
node_dashboard -->|"requests signals"| node_whale_signals
node_dashboard -->|"uses"| node_executor
node_dashboard -->|"uses"| node_wallet
node_dashboard -->|"persists analyses"| node_storage
node_agent -->|"fetches markets"| node_markets
node_agent -->|"sizes opportunities"| node_sizing
node_agent -->|"analyzes markets"| node_analyzer
node_agent -.->|"executes trades"| node_executor
node_agent -->|"checks status"| node_wallet
node_markets -->|"fetches market data"| node_polymarket
node_whale_signals -->|"fetches trade data"| node_polymarket
node_analyzer -->|"requests model analysis"| node_ai_service
node_analyzer -.->|"uses signal context"| node_whale_signals
node_executor -->|"uses wallet"| node_wallet
node_executor -->|"places orders"| node_polymarket
node_wallet -->|"reads and signs"| node_polygon
node_storage -.->|"stores market records"| node_polymarket

click node_dashboard "https://github.com/blockrunai/polymarket-agent/blob/main/app.py"
click node_dashboard_views "https://github.com/blockrunai/polymarket-agent/blob/main/templates/index.html"
click node_cli "https://github.com/blockrunai/polymarket-agent/blob/main/main.py"
click node_agent "https://github.com/blockrunai/polymarket-agent/blob/main/src/agent.py"
click node_markets "https://github.com/blockrunai/polymarket-agent/blob/main/src/market/polymarket.py"
click node_whale_signals "https://github.com/blockrunai/polymarket-agent/blob/main/src/signals/trades.py"
click node_analyzer "https://github.com/blockrunai/polymarket-agent/blob/main/src/analysis/ai_analyzer.py"
click node_sizing "https://github.com/blockrunai/polymarket-agent/blob/main/src/utils/kelly.py"
click node_executor "https://github.com/blockrunai/polymarket-agent/blob/main/src/trading/executor.py"
click node_wallet "https://github.com/blockrunai/polymarket-agent/blob/main/src/trading/wallet.py"
click node_storage "https://github.com/blockrunai/polymarket-agent/blob/main/src/storage/gcs_storage.py"

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_dashboard,node_dashboard_views,node_cli,node_agent toneBlue
class node_markets,node_whale_signals,node_analyzer toneAmber
class node_sizing,node_executor,node_wallet,node_polymarket toneMint
class node_storage toneRose
class node_operator,node_ai_service,node_polygon toneIndigo
```

## Components

### User Interfaces

- [Web Dashboard](https://github.com/blockrunai/polymarket-agent/blob/main/app.py): `app.py`
- [Dashboard Views](https://github.com/blockrunai/polymarket-agent/blob/main/templates/index.html): `templates/index.html`
- [CLI](https://github.com/blockrunai/polymarket-agent/blob/main/main.py): `main.py`
- [Agent Coordinator](https://github.com/blockrunai/polymarket-agent/blob/main/src/agent.py): `src/agent.py`

### Market Intelligence

- [Market Discovery](https://github.com/blockrunai/polymarket-agent/blob/main/src/market/polymarket.py): `src/market/polymarket.py`
- [Smart-Money Signals](https://github.com/blockrunai/polymarket-agent/blob/main/src/signals/trades.py): `src/signals/trades.py`
- [AI Consensus](https://github.com/blockrunai/polymarket-agent/blob/main/src/analysis/ai_analyzer.py): `src/analysis/ai_analyzer.py`

### Trading Operations

- [Kelly Sizing](https://github.com/blockrunai/polymarket-agent/blob/main/src/utils/kelly.py): `src/utils/kelly.py`
- [Order Execution](https://github.com/blockrunai/polymarket-agent/blob/main/src/trading/executor.py): `src/trading/executor.py`
- [Polygon Wallet](https://github.com/blockrunai/polymarket-agent/blob/main/src/trading/wallet.py): `src/trading/wallet.py`

### Persistence

- [GCS Persistence](https://github.com/blockrunai/polymarket-agent/blob/main/src/storage/gcs_storage.py): `src/storage/gcs_storage.py`

### Other components

- **Operator**
- **BlockRun AI**
- **Polymarket APIs**
- **Polygon Network**

## Connections

- Operator → Web Dashboard: monitors (evidence: `app.py`)
- Operator → CLI: runs (evidence: `main.py`)
- Web Dashboard → Dashboard Views: renders (evidence: `app.py`)
- CLI → Agent Coordinator: creates (evidence: `main.py`)
- Web Dashboard → Market Discovery: fetches markets (evidence: `app.py`)
- Web Dashboard → AI Consensus: requests analysis (evidence: `app.py`)
- Web Dashboard → Smart-Money Signals: requests signals (evidence: `app.py`)
- Web Dashboard → Order Execution: uses (evidence: `app.py`)
- Web Dashboard → Polygon Wallet: uses (evidence: `app.py`)
- Web Dashboard → GCS Persistence: persists analyses (evidence: `app.py`)
- Agent Coordinator → Market Discovery: fetches markets (evidence: `src/agent.py`)
- Agent Coordinator → Kelly Sizing: sizes opportunities (evidence: `src/agent.py`)
- Agent Coordinator → AI Consensus: analyzes markets (evidence: `src/agent.py`)
- Agent Coordinator → Order Execution: executes trades (evidence: `src/agent.py`)
- Agent Coordinator → Polygon Wallet: checks status (evidence: `src/agent.py`)
- Market Discovery → Polymarket APIs: fetches market data (evidence: `src/market/polymarket.py`)
- Smart-Money Signals → Polymarket APIs: fetches trade data (evidence: `src/signals/trades.py`)
- AI Consensus → BlockRun AI: requests model analysis (evidence: `README.md`)
- AI Consensus → Smart-Money Signals: uses signal context
- Order Execution → Polygon Wallet: uses wallet (evidence: `src/trading/executor.py`)
- Order Execution → Polymarket APIs: places orders (evidence: `README.md`)
- Polygon Wallet → Polygon Network: reads and signs (evidence: `README.md`)
- GCS Persistence → Polymarket APIs: stores market records
