Polymarket Arbitrage Trading Bot (TypeScript)

Production-style TypeScript bot for Polymarket binary crypto markets.
The bot continuously tracks selected markets, evaluates configured strategy rules, and executes buy/sell orders through the latest Polymarket CLOB API client (@polymarket/clob-client-v2).

What this bot does

• Selects active market contracts by coin and period (5m, 15m, 1h, 4h, 1d)
• Polls bid/ask prices for both UP and DOWN tokens
• Runs strategy logic from trade.toml (trade_1 or trade_2)
• Posts market orders with retry handling and balance confirmation
• Prints live status with trend/position legend for operator visibility

Strategy model

This repository is positioned as an arbitrage trading bot and currently implements two configurable rule sets:

trade_1 (time/price-driven exit model)

• Tracks market progress and UP price ratio
• Exits existing position when either:
  • elapsed time ratio exceeds trade_1.exit_time_ratio, or
  • UP price ratio exceeds trade_1.exit_price_ratio

trade_2 (entry/exit range model with emergency swap)

• Enters only when:
  • elapsed time ratio exceeds trade_2.entry_time_ratio, and
  • UP ratio is within trade_2.entry_price_ratio
• Exits when UP ratio falls into any configured trade_2.exit_price_ratio_range
• Optionally performs opposite-side immediate buy on successful exit if trade_2.emergency_swap_price matches

Requirements

• Node.js >= 20.6.0
• Polymarket signer private key
• Polymarket funder wallet address (proxy/deposit wallet)

Quick start

1. Install dependencies:

npm install

2. Create .env in the project root:

POLYMARKET_PRIVATE_KEY=your_private_key
POLYMARKET_FUNDER_ADDRESS=your_funder_wallet_address
# optional (defaults to POLY_PROXY): EOA | POLY_PROXY | POLY_GNOSIS_SAFE | POLY_1271
POLYMARKET_SIGNATURE_TYPE=POLY_PROXY

3. Configure runtime behavior in trade.toml:

• strategy: trade_1 or trade_2
• trade_usd: order amount in USD
• max_retries: retry count for order execution
• [market].market_coin: btc | eth | sol | xrp
• [market].market_period: 5 | 15 | 60 | 240 | 1440

4. Start the bot:

npm run dev

Runtime output legend

• Trend:
  • UP 🟢
  • DOWN 🔴
  • FLAT ⚪
• Position:
  • UP 🟩
  • DOWN 🟥
  • NONE ⬛

The startup header also prints:

• Current public key
• Active strategy
• Selected market window
• Trade USD amount

Scripts

Command	Description
npm run dev	Run bot in dev mode (tsx src/index.ts)
npm run build	Compile TypeScript to dist/
npm start	Run compiled output (node dist/index.js)

Project structure

• src/index.ts - startup flow, market loop, and strategy execution cycle
• src/config/ - environment and TOML config loading/validation
• src/services/ - CLOB and Gamma API integrations
• src/trade/ - strategy decision methods, price processing, and order execution
• trade.toml - strategy and market configuration

Security and operations

• Never commit .env or wallet keys.
• Use a dedicated wallet and risk-limited balance.
• Test with low trade_usd before increasing position size.

Docs alignment

• Trading client/auth flow follows Polymarket's latest docs and the v2 CLOB client (createOrDeriveApiKey for L1, then pass creds for L2).
• Funder configuration uses POLYMARKET_FUNDER_ADDRESS to support current funded wallet patterns (proxy/deposit wallet setups).
• Startup auth now tries supported signature modes (POLY_PROXY, EOA, POLY_GNOSIS_SAFE, POLY_1271) and uses the first one that can create/derive API credentials.