KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #dsh-plugin #deepseek-harness #windows #open-source #agent-skills #ai

polymarket-trading-bot

★ 73 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Polymarket Trading Bot

English | [简体中文](README_CN.md)

A beginner-friendly Python trading bot for Polymarket with gasless transactions and real-time WebSocket data.

> **CLOB V2 ready.** Signs orders against the V2 exchange domain (`Polymarket CTF Exchange`, version `2`) with the new `timestamp` / `metadata` / `builder` fields. Builder attribution is carried in the signed `builder` field — no more `POLY_BUILDER_*` HMAC headers for order submission. See [Polymarket CLOB V2 migration guide](https://docs.polymarket.com/migration/clob-v2) for background.

## Features

- **Simple API**: Just a few lines of code to start trading
- **CLOB V2 order format**: V2 domain + `builder` attribution field baked into every order
- **Gasless Transactions**: Relayer-backed gasless execution via Builder Program credentials
- **Real-time WebSocket**: Live orderbook updates via WebSocket
- **15-Minute Markets**: Built-in support for BTC/ETH/SOL/XRP 15-minute Up/Down markets
- **Flash Crash Strategy**: Pre-built strategy for volatility trading
- **Terminal UI**: Real-time orderbook display with in-place updates
- **Secure Key Storage**: Private keys encrypted with PBKDF2 + Fernet
- **Fully Tested**: 103 unit tests covering all functionality

## Quick Start (5 Minutes)

### Step 1: Install

```bash
git clone https://github.com/your-username/polymarket-trading-bot.git
cd polymarket-trading-bot
pip install -r requirements.txt
```

### Step 2: Configure

```bash
# Set your credentials
export POLY_PRIVATE_KEY=your_metamask_private_key
export POLY_SAFE_ADDRESS=0xYourPolymarketSafeAddress
```

> **Where to find your Safe address?** Go to [polymarket.com/settings](https://polymarket.com/settings) and copy your wallet address.

### Step 3: Run

```bash
# Run the quickstart example
python examples/quickstart.py

# Or run the Flash Crash Strategy
python strategies/flash_crash_strategy.py --coin BTC
```

That's it! You're ready to trade.

## Trading Strategies

### Flash Crash Strategy

Monitors 15-minute Up/Down markets for sudden probability drops and executes trades automatically.

```bash
# Run with default settings (0.30 drop threshold)
python strategies/flash_crash_strategy.py --coin BTC

# Custom settings
python strategies/flash_crash_strategy.py --coin ETH --drop 0.25 --size 10

# Available options
--coin      BTC, ETH, SOL, XRP (default: ETH)
--drop      Drop threshold as absolute change (default: 0.30)
--size      Trade size in USDC (default: 5.0)
--lookback  Detection window in seconds (default: 10)
--take-profit  TP in dollars (default: 0.10)
--stop-loss    SL in dollars (default: 0.05)
```

**Strategy Logic:**
1. Auto-discover current 15-minute market
2. Monitor orderbook prices via WebSocket in real-time
3. When probability drops by 0.30+ in 10 seconds, buy the crashed side
4. Exit at +$0.10 (take profit) or -$0.05 (stop loss)

## Strategy Development Guide

- See `docs/strategy_guide.md` for a step-by-step tutorial and templates.

### Real-time Orderbook TUI

View live orderbook data in a beautiful terminal interface:

```bash
python strategies/orderbook_tui.py --coin BTC --levels 5
```

## Code Examples

### Simplest Example

```python
from src import create_bot_from_env
import asyncio

async def main():
    # Create bot from environment variables
    bot = create_bot_from_env()

# Get your open orders
    orders = await bot.get_open_orders()
    print(f"You have {len(orders)} open orders")

asyncio.run(main())
```

### Place an Order

```python
from src import TradingBot, Config
import asyncio

async def trade():
    # Create configuration
    config = Config(safe_address="0xYourSafeAddress")

# Initialize bot with your private key
    bot = TradingBot(config=config, private_key="0xYourPrivateKey")

# Place a buy order
    result = await bot.place_order(
        token_id="12345...",   # Market token ID
        price=0.65,            # Price (0.65 = 65% probability)
        size=10.0,             # Number of shares
        side="BUY"             # or "SELL"
    )

if result.success:
        print(f"Order placed! ID: {result.order_id}")
    else:
        print(f"Order failed: {result.message}")

asyncio.run(trade())
```

### Real-time WebSocket Data

```python
from src.websocket_client import MarketWebSocket, OrderbookSnapshot
import asyncio

async def main():
    ws = MarketWebSocket()

@ws.on_book
    async def on_book_update(snapshot: OrderbookSnapshot):
        print(f"Mid price: {snapshot.mid_price:.4f}")
        print(f"Best bid: {snapshot.best_bid:.4f}")
        print(f"Best ask: {snapshot.best_ask:.4f}")

await ws.subscribe(["token_id_1", "token_id_2"])
    await ws.run()

asyncio.run(main())
```

### Get 15-Minute Market Info

```python
from src.gamma_client import GammaClient

gamma = GammaClient()

# Get current BTC 15-minute market
market = gamma.get_market_info("BTC")
print(f"Market: {market['question']}")
print(f"Up token: {market['token_ids']['up']}")
print(f"Down token: {market['token_ids']['down']}")
print(f"Ends: {market['end_date']}")
```

### Cancel Orders

```python
# Cancel a specific order
await bot.cancel_order("order_id_here")

# Cancel all orders
await bot.cancel_all_orders()

# Cancel orders for a specific market
await bot.cancel_market_orders(market="condition_id", asset_id="token_id")
```

## Project Structure

```
polymarket-trading-bot/
├── src/                      # Core library
│   ├── bot.py               # TradingBot - main interface
│   ├── config.py            # Configuration handling
│   ├── client.py            # API clients (CLOB, Relayer)
│   ├── signer.py            # Order signing (EIP-712)
│   ├── crypto.py            # Key encryption
│   ├── utils.py             # Helper functions
│   ├── gamma_client.py      # 15-minute market discovery
│   └── websocket_client.py  # Real-time WebSocket client
│
├── strategies/               # Trading strategies
│   ├── flash_crash_strategy.py  # Volatility trading strategy
│   └── orderbook_tui.py     # Real-time orderbook display
│
├── examples/                 # Example code
│   ├── quickstart.py        # Start here!
│   ├── basic_trading.py     # Common operations
│   └── strategy_example.py  # Custom strategies
│
├── scripts/                  # Utility scripts
│   ├── setup.py             # Interactive setup
│   ├── run_bot.py           # Run the bot
│   └── full_test.py         # Integration tests
│
└── tests/                    # Unit tests
```

## Configuration Options

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `POLY_PRIVATE_KEY` | Yes | Your wallet private key |
| `POLY_SAFE_ADDRESS` | Yes | Your Polymarket Safe address |
| `POLY_BUILDER_CODE` | For attribution | V2 builder code (bytes32 hex) stamped on every order |
| `POLY_BUILDER_API_KEY` | For gasless | Builder Program API key (Relayer HMAC) |
| `POLY_BUILDER_API_SECRET` | For gasless | Builder Program secret (Relayer HMAC) |
| `POLY_BUILDER_API_PASSPHRASE` | For gasless | Builder Program passphrase (Relayer HMAC) |
| `POLY_CLOB_HOST` | No | Override CLOB host (use `https://clob-v2.polymarket.com` to test V2 pre-cutover) |

### Config File (Alternative)

Create `config.yaml`:

```yaml
safe_address: "0xYourSafeAddress"

clob:
  host: "https://clob.polymarket.com"
  chain_id: 137
  signature_type: 2
  neg_risk: false   # true for Neg Risk markets

builder:
  # CLOB V2: builder_code attributes orders to your builder account
  builder_code: "0x...32-byte-hex..."
  # Relayer HMAC creds (only needed for gasless transactions)
  api_key: "your_api_key"
  api_secret: "your_api_secret"
  api_passphrase: "your_passphrase"
```

Then load it:

```python
bot = TradingBot(config_path="config.yaml", private_key="0x...")
```

## Builder Attribution & Gasless Trading

CLOB V2 splits builder usage into two independent pieces:

1. **Order attribution (`builder_code`)** — a bytes32 hex code copied from
   [polymarket.com/settings?tab=builder](https://polymarket.com/settings?tab=builder)
   and stamped onto every signed order. Public identifier.

```bash
   export POLY_BUILDER_CODE=0x...32-byte-hex...
   ```

When set, the bot injects it into every order's `builder` field automatically.
   Per-order overrides are supported via `bot.place_order(..., builder_code=...)`.

2. **Gasless execution (Relayer HMAC)** — the classic `POLY_BUILDER_API_KEY` /
   `SECRET` / `PASSPHRASE` credentials still authenticate against the Relayer
   for gasless Safe deployment, approvals, and cancels. These headers are no
   longer used for `POST /order` under V2.

```bash
   export POLY_BUILDER_API_KEY=your_key
   export POLY_BUILDER_API_SECRET=your_secret
   export POLY_BUILDER_API_PASSPHRASE=your_passphrase
   ```

The bot automatically enters gasless mode when all three are present.

## API Reference

### TradingBot Methods

| Method | Description |
|--------|-------------|
| `place_order(token_id, price, size, side)` | Place a limit order |
| `cancel_order(order_id)` | Cancel a specific order |
| `cancel_all_orders()` | Cancel all open orders |
| `cancel_market_orders(market, asset_id)` | Cancel orders for a specific market |
| `get_open_orders()` | List your open orders |
| `get_trades(limit=100)` | Get your trade history |
| `get_order_book(token_id)` | Get market order book |
| `get_market_price(token_id)` | Get current market price |
| `is_initialized()` | Check if bot is ready |

### MarketWebSocket Methods

| Method | Description |
|--------|-------------|
| `subscribe(asset_ids, replace=False)` | Subscribe to market data |
| `run(auto_reconnect=True)` | Start WebSocket connection |
| `disconnect()` | Close connection |
| `get_orderbook(asset_id)` | Get cached orderbook |
| `get_mid_price(asset_id)` | Get mid price |

### GammaClient Methods

| Method | Description |
|--------|-------------|
| `get_current_15m_market(coin)` | Get current 15-min market |
| `get_market_info(coin)` | Get market with token IDs |
| `get_all_15m_markets()` | List all 15-min markets |

## Security

Your private key is protected by:

1. **PBKDF2** key derivation (480,000 iterations)
2. **Fernet** symmetric encryption
3. File permissions set to `0600` (owner-only)

Best practices:
- Never commit `.env` files to git
- Use a dedicated wallet for trading
- Keep your encrypted key file private

## Testing

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `POLY_PRIVATE_KEY not set` | Run `export POLY_PRIVATE_KEY=your_key` |
| `POLY_SAFE_ADDRESS not set` | Get it from polymarket.com/settings |
| `Invalid private key` | Check key is 64 hex characters |
| `Order failed` | Check you have sufficient balance |
| `WebSocket not connecting` | Check network/firewall settings |

## Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new code
4. Run `pytest tests/ -v`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

polymarket-trading-bot

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README