Polymarket Developer Boilerplate

TypeScript starter kit for building systematic Polymarket tools - bots, strategies, and data analysis. Unified API client across all three Polymarket APIs, Telegram bot scaffold, strategy framework with pluggable logic, and pre-trade risk checks. Typed, tested against live data, working out of the box.

Save 40+ hours of setup. Start building your edge, not your infrastructure.

What's inside

| Module | What it does | Tier | |--------|-------------|------| | PolymarketClient | Unified client for Gamma, Data, and CLOB APIs. Retries, rate limiting, concurrency gating built in. | Free (Gamma) / Full (Data + CLOB) | | Telegram Bot | Working bot with /markets, /whales, /book, /search, /closing commands. Add your own in minutes. | Full | | Strategy Runner | Polling-based framework for running multiple strategies. Plug in your logic, get alerts out. | Full | | WhaleFollower | Tracks trades above a USD threshold. Deduplicates across ticks. Configurable severity tiers. | Full | | SpreadWatcher | Monitors bid-ask spread changes on top markets. Alerts when spreads widen or narrow. | Full | | RiskManager | Pre-trade checks: position size, daily volume, open position count, liquidity, spread. | Full | | License Verify | On-chain USDC payment verification on Polygon. Checks tx hash, confirms amount, returns tier. | Full |

Quick start

git clone <this-repo>
cd boilerplate
npm install
cp .env.example .env

Verify your setup (no tokens needed):

npx tsx examples/quick-start.ts

You should see the top 5 markets by volume printed to your terminal.

Examples

Five runnable examples to get you oriented:

# Minimal setup verification
npx tsx examples/quick-start.ts

# Stream large trades (default $5K threshold)
npx tsx examples/whale-alerts.ts
npx tsx examples/whale-alerts.ts 10000    # custom threshold

# Scan markets by liquidity, spread, and volume
npx tsx examples/market-scanner.ts

# Run both strategies together
npx tsx examples/run-strategy.ts

# Verify a USDC payment for license activation
npx tsx examples/verify-license.ts <tx-hash>

License verification

Verify USDC payments on Polygon for license activation:

npx tsx examples/verify-license.ts <polygon-tx-hash>

Or use the module directly:

import { verifyPayment } from "./src/license/verify.js";

const result = await verifyPayment("0x...");
if (result.verified) {
  console.log(`License: ${result.tier}, Amount: $${result.amount}`);
}

Accepts both USDC (native) and USDC.e (bridged) on Polygon.

Telegram bot

Set TELEGRAM_BOT_TOKEN in your .env file, then:

npx tsx src/bot/index.ts

Built-in commands:

| Command | Description | |---------|-------------| | /markets [n] | Top N markets by 24h volume | | /search <query> | Search markets by keyword | | /closing [hours] | Markets closing within N hours | | /whales [min_usd] | Recent large trades | | /book <slug> | Order book for a market |

Adding your own commands: create a file in src/bot/commands/, export an async handler, and register it in src/bot/index.ts. Each command gets the bot instance, chat ID, and argument string.

Strategy framework

The strategy runner polls on a configurable interval, calling each strategy's tick() method and collecting alerts.

import { StrategyRunner } from "./src/strategies/runner.js";
import { WhaleFollower } from "./src/strategies/whale-follower.js";

const runner = new StrategyRunner({
  intervalMs: 15000,
  onAlert: (alert) => {
    console.log(`[${alert.severity}] ${alert.title}: ${alert.message}`);
  },
});

runner.add(new WhaleFollower(5000));
await runner.start();

Writing your own strategy: implement the Strategy interface from src/strategies/types.ts. You need a name, description, and tick() method that returns an array of Alert objects.

import type { Strategy, Alert } from "./src/strategies/types.js";
import type { PolymarketClient } from "./src/api/client.js";

export class MyStrategy implements Strategy {
  name = "my-strategy";
  description = "Does something interesting";

  async tick(client: PolymarketClient): Promise<Alert[]> {
    // Your logic here
    return [];
  }
}

Risk management

The RiskManager runs pre-trade checks against configurable limits. All limits are set via .env or constructor overrides.

import { RiskManager } from "./src/risk/limits.js";

const risk = new RiskManager();

// Check individual constraints
risk.checkPositionSize(250);        // { passed: true, reason: "..." }
risk.checkDailyVolume(1500);        // { passed: true, reason: "..." }
risk.checkMarketLiquidity(market);  // { passed: false, reason: "..." }

// Or run all checks at once
const result = risk.preTradeCheck(250, market, currentPositions);
if (!result.passed) {
  console.log(`Blocked: ${result.reason}`);
}

Default limits (override in .env):

| Variable | Default | Description | |----------|---------|-------------| | MAX_POSITION_USD | 500 | Max single position size | | MAX_DAILY_VOLUME_USD | 2000 | Max total daily volume | | MAX_OPEN_POSITIONS | 10 | Max concurrent positions | | MIN_LIQUIDITY_USD | 50000 | Min market liquidity to trade |

API client

The PolymarketClient wraps all three Polymarket APIs in one interface. Automatic retries on 429/5xx, concurrency gating (max 5 in-flight requests), and 15s timeout per request.

import { PolymarketClient } from "./src/api/client.js";

const client = new PolymarketClient();

// Gamma API (market data)
const markets = await client.getTopMarkets(10);
const market = await client.getMarket("will-trump-win");
const closing = await client.getClosingSoon(24, 10);

// Data API (trades)
const trades = await client.getTrades({ limit: 50 });
const whales = await client.getLargeTrades(5000, 20);
const positions = await client.getPositions("0x...");

// CLOB API (order book)
const book = await client.getOrderBook(tokenId);
const mid = await client.getMidPrice(tokenId);
const spread = await client.getSpread(tokenId);
const depth = await client.getDepth(tokenId);

Project structure

boilerplate/
  src/
    config.ts           - .env loading, typed config object
    index.ts            - Public exports
    api/
      client.ts         - Unified Polymarket API client
      types.ts          - All API type definitions
    bot/
      index.ts          - Telegram bot setup + command router
      format.ts         - Message formatting helpers
      commands/
        markets.ts      - /markets, /search, /closing
        whales.ts       - /whales
        orderbook.ts    - /book
    strategies/
      types.ts          - Strategy and Alert interfaces
      runner.ts         - Polling-based strategy execution
      whale-follower.ts - Large trade detection
      spread-watcher.ts - Spread change monitoring
    risk/
      limits.ts         - Pre-trade risk checks
    license/
      verify.ts         - On-chain USDC payment verification
    utils/
      logger.ts         - Structured logging
      retry.ts          - HTTP fetch with retries
  examples/
    quick-start.ts      - Minimal setup verification
    whale-alerts.ts     - Stream large trades
    market-scanner.ts   - Scan markets by criteria
    run-strategy.ts     - Run strategies together
    verify-license.ts   - USDC payment verification

Requirements

• Node.js 18+
• TypeScript 5.0+
• Telegram bot token (for the bot module only)

Zero runtime dependencies beyond node-telegram-bot-api. Everything else uses Node's built-in fetch.

Pricing

| Tier | Price | What you get | |------|-------|-------------| | Free | $0 | PolymarketClient (Gamma API), types, utils, quick-start example | | Full | 69 USDC | Everything: Data + CLOB clients, bot framework, strategies, risk management, all examples | | Premium | 99 USDC | Full + priority Telegram support + early access to new modules |

Payment: send USDC on Polygon to 0x8A0A2E3250f7EdfE9b8a24D81D89b92085f60fc4

This is an analytical tool. Not financial advice. Past data does not predict future results.