Clawtrade

KO | EN

gitlite — search

#python #html #java #javascript #hacktoberfest #css #web #nodejs #cpp #swift #python3 #react

★ 30 Open GitHub ↗

AI Trading Agent Platform - Trade Crypto, Forex, Stocks & DeFi with AI agents

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Clawtrade

**AI Trading Agent Platform — Trade Crypto, Forex, Stocks & DeFi with AI agents.**

Self-hosted, open-source. One platform for Binance, Bybit, OKX, MetaTrader 5, Interactive Brokers, Hyperliquid, and Uniswap.

![Dashboard](https://raw.githubusercontent.com/Paparusi/Clawtrade/master/docs/screenshots/dashboard.png)

![Analytics](https://raw.githubusercontent.com/Paparusi/Clawtrade/master/docs/screenshots/analytics.png)

![Agent Chat](https://raw.githubusercontent.com/Paparusi/Clawtrade/master/docs/screenshots/agent-chat.png)

![Settings](https://raw.githubusercontent.com/Paparusi/Clawtrade/master/docs/screenshots/settings.png)

---

## Quick Start

```bash
# Install
npm install -g clawtrade

# Setup (interactive wizard)
clawtrade init

# Start server
clawtrade serve
```

Open **http://localhost:9090** for the web dashboard.

## Features

### Multi-Asset Trading
- **Crypto CEX** — Binance, Bybit, OKX (spot, futures, margin)
- **Crypto DEX** — Uniswap, Hyperliquid, Jupiter
- **Forex/CFD** — MetaTrader 5 (via Python API, auto-setup)
- **Stocks** — Interactive Brokers gateway
- **Paper Trading** — Simulated mode for risk-free testing

### AI Agent (Tool Use)
- **Real tool use** — Agent calls tools to fetch live data, not just chat
- 14 built-in tools: `get_price`, `get_candles`, `analyze_market`, `get_balances`, `get_positions`, `risk_check`, `calculate_position_size`, `place_order`, `cancel_order`, `get_open_orders`, `backtest`, `create_alert`, `list_alerts`, `delete_alert`
- Context injection: system prompt includes live balances, positions, risk limits, trade history
- Agent loop: LLM calls tools → executes → returns results → LLM responds with real data
- Supports all 6 LLM providers with native tool use (Anthropic, OpenAI, DeepSeek, OpenRouter, Google Gemini, Ollama)
- **MCP support** — Connect external MCP servers for custom tools (indicators, news, alerts)
- 5 sub-agents: market analyst, devil's advocate, narrative tracker, reflection engine, correlation scanner
- 5-layer memory system with learning from past trades
- Configurable confidence thresholds and confirmation modes

### Backtesting Engine
- **Strategy backtesting** via agent chat — "Backtest RSI strategy on BTC/USDT 4h"
- Built-in strategies: Price Action, SMC (Smart Money Concepts)
- Custom expression rules: `"rsi < 30 AND close > sma_50"`
- Multi-timeframe analysis (15m, 1h, 4h)
- Results include: total return, win rate, max drawdown, Sharpe ratio, trade count
- Historical candle data from connected exchanges

### Multi-Exchange Portfolio
- **Aggregated portfolio view** across all connected exchanges
- Real-time price streaming via EventBus
- Unified P&L tracking (unrealized + realized)
- Asset allocation breakdown (Crypto, Forex, Stocks, DeFi)
- Portfolio performance chart with S&P 500 / BTC benchmark comparison
- Monthly returns heatmap and drawdown analysis

### Alerting System
- **Price alerts** — Above/below threshold on any symbol
- **P&L alerts** — Portfolio-level profit/loss triggers
- **Risk alerts** — Leverage, exposure, drawdown warnings
- **Trade alerts** — Execution notifications
- **System alerts** — Connection status, errors
- **Custom expression alerts** — `"rsi < 30 AND close > sma_50"` with indicator evaluation
- Rate limiting (configurable per-alert cooldown)
- One-shot alerts (auto-disable after trigger)
- **Telegram delivery** with formatted messages
- **WebSocket delivery** for real-time dashboard updates
- **Daily briefing** — Automated portfolio snapshot via Telegram at configured UTC hour
- Manage alerts via agent chat: "Create alert when BTC drops below 60000"

### Risk Management
- Pre-trade risk checks (position size, leverage, exposure limits)
- Real-time P&L monitoring with drawdown alerts
- Circuit breaker for automatic halt on abnormal losses
- Scenario analysis and stress testing

### Web Dashboard
- **Live data** — All widgets connect to real exchange APIs with graceful fallback to demo mode
- Real-time portfolio overview with P&L tracking
- TradingView candlestick charts with technical indicators
- Market overview with 13+ instruments (crypto, forex, stocks, indices)
- Positions table across all exchanges with real-time P&L
- Portfolio performance vs benchmarks (S&P 500, BTC)
- Risk analysis panel (Sharpe ratio, Sortino ratio, volatility, max drawdown)
- Asset allocation donut chart
- Monthly returns heatmap
- Top movers (best/worst performers)
- Agent chat interface with tool use visualization
- Full settings panel (exchanges, risk, agent, notifications, general)

### Notifications
- **Telegram** bot with trade alerts, portfolio commands, and daily briefings
- **Discord** webhook notifications
- Configurable alert types: trades, risk, P&L, system events
- Rate limiting to prevent notification spam

### Security
- AES-256-GCM encrypted credential vault
- Role-based access control
- Audit logging
- Dead switch emergency shutdown

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  Web Dashboard                   │
│              React + Vite + TypeScript            │
├─────────────────────────────────────────────────┤
│                   API Server                     │
│              REST + WebSocket + GraphQL           │
├──────────┬──────────┬──────────┬────────────────┤
│ AI Agent │   Risk   │ Backtest │   Adapters      │
│ + Memory │  Engine  │  Engine  │ ┌────────────┐ │
│ + Alerts │          │          │ │ Binance    │ │
│          │          │          │ │ Bybit      │ │
│          │          │          │ │ OKX        │ │
│          │          │          │ │ MT5        │ │
│          │          │          │ │ IBKR       │ │
│          │          │          │ │ Hyperliquid│ │
│          │          │          │ │ Uniswap    │ │
│          │          │          │ └────────────┘ │
├──────────┴──────────┴──────────┴────────────────┤
│  SQLite  │  Vault (AES-256)  │  Event Bus       │
└─────────────────────────────────────────────────┘
```

- **Go** backend for performance and concurrency
- **React** web dashboard
- **TypeScript** CLI and plugin runtime
- **SQLite** for zero-config local storage

## CLI Reference

### Core
```bash
clawtrade init               # Interactive setup wizard
clawtrade serve              # Start server
clawtrade status             # System status
clawtrade version            # Version info
```

### Exchanges
```bash
clawtrade exchange list              # List configured exchanges
clawtrade exchange add binance       # Add exchange (interactive)
clawtrade exchange remove binance    # Remove exchange
clawtrade exchange test binance      # Validate config
```

Supported: `binance`, `bybit`, `okx`, `mt5`, `ibkr`, `hyperliquid`, `uniswap`

> **MetaTrader 5**: Install the [MT5 terminal](https://www.metatrader5.com/en/download) (Windows only). Clawtrade auto-installs the Python bridge and connects — just provide your login, password, and server name.

### Configuration
```bash
clawtrade config show                # Show all config
clawtrade config set server.port 8080
clawtrade risk show                  # Risk parameters
clawtrade risk set max_leverage 20
clawtrade agent show                 # Agent config
clawtrade agent set auto_trade true
clawtrade agent watchlist add SOL/USDT
```

### AI Models (LLM Provider)
```bash
clawtrade models setup               # Interactive LLM provider setup
clawtrade models set anthropic/claude-sonnet-4-6  # Set model directly
clawtrade models list                # List all providers & models
clawtrade models status              # Show current model config
```

Supported providers: **Anthropic** (Claude), **OpenAI** (GPT), **OpenRouter**, **DeepSeek**, **Google** (Gemini), **Ollama** (local/free)

API keys via environment variables or encrypted vault:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-proj-...
```

### Notifications
```bash
clawtrade telegram setup             # Setup Telegram bot
clawtrade telegram test              # Send test message
clawtrade notify show                # All notification settings
clawtrade notify set discord.webhook_url <url>
```

### Chat
```bash
clawtrade chat                       # Interactive AI chat
```

## API Endpoints

### LLM Chat
```
POST /api/v1/chat
Body: { "messages": [{ "role": "user", "content": "How is BTC doing?" }] }
```
Proxies to your configured LLM provider (Claude, GPT, Gemini, etc.)

### Market Data
```
GET /api/v1/price?symbol=BTC/USDT&exchange=binance
GET /api/v1/candles?symbol=BTC/USDT&timeframe=1h&limit=100
GET /api/v1/orderbook?symbol=BTC/USDT&depth=20
```

### Account
```
GET /api/v1/balances?exchange=binance
GET /api/v1/positions?exchange=binance
GET /api/v1/exchanges
```

### WebSocket
```
ws://localhost:9090/ws
```
Real-time streaming from connected exchanges. Event types: `market.*`, `trade.*`, `risk.*`, `portfolio.*`, `alert.*`, `system.*`

## Configuration

All config stored in `config/default.yaml`:

```yaml
server:
  host: 127.0.0.1
  port: 9090

risk:
  max_risk_per_trade: 0.02    # 2%
  max_daily_loss: 0.05        # 5%
  max_positions: 5
  max_leverage: 10
  default_mode: paper         # paper | live

agent:
  enabled: true
  auto_trade: false
  min_confidence: 0.7
  model:
    primary: "anthropic/claude-sonnet-4-6"
    max_tokens: 4096
    temperature: 0.7
  watchlist:
    - BTC/USDT
    - ETH/USDT

mcp:
  servers:
    - name: news-sentiment
      command: python
      args: [mcp_news_server.py]
      enabled: true

notifications:
  telegram:
    enabled: false
    token: ""
    chat_id: ""
  alerts:
    trade_executed: true
    risk_alert: true
    pnl_update: false
    system_alert: true
    rate_limit_minutes: 5
    daily_briefing: false
    briefing_hour_utc: 8
```

MCP servers expose custom tools to the AI agent via the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-compatible server works — the agent discovers tools automatically at startup.

API credentials are encrypted in `data/vault.enc` (AES-256-GCM).

## Development

### Prerequisites
- Go 1.21+
- Node.js 18+
- Bun (optional, for CLI development)

### Build from source
```bash
git clone https://github.com/Paparusi/Clawtrade.git
cd Clawtrade

# Build Go server
make build

# Start web dashboard (dev mode)
cd web && npm install && npm run dev

# Run server
make run
```

### Project Structure
```
├── cmd/clawtrade/     Go CLI entry point
├── internal/
│   ├── adapter/       Exchange adapters (Binance, Bybit, MT5, etc.)
│   ├── agent/         AI agent, tool registry, sub-agents
│   ├── alert/         Alerting system (manager, dispatcher, briefing)
│   ├── api/           HTTP server, WebSocket, GraphQL
│   ├── backtest/      Backtesting engine, strategies, indicators
│   ├── bot/           Telegram bot
│   ├── config/        Configuration management
│   ├── database/      SQLite storage and migrations
│   ├── engine/        Event bus
│   ├── memory/        AI 5-layer memory system
│   ├── risk/          Risk engine, circuit breaker, monitoring
│   ├── security/      Vault, audit, permissions
│   ├── streaming/     Real-time price streaming
│   └── strategy/      Strategy arena and optimizer
├── web/               React dashboard
├── cli/               TypeScript CLI
├── sdk/               Client SDKs (TypeScript, Python, Go)
└── plugins/           Plugin runtime
```

### Run tests
```bash
make test
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | Go |
| Frontend | React, TypeScript, Vite |
| Database | SQLite (WAL mode) |
| Encryption | AES-256-GCM, PBKDF2 |
| API | REST, WebSocket, GraphQL |
| CLI | Node.js + Go |

## License

[MIT](LICENSE)

Clawtrade

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README