polymarket-trading-sdk

A comprehensive SDK for building Polymarket trading bots.

Installation

npm install polymarket-trading-sdk
# or
pnpm add polymarket-trading-sdk

Quick Start

import {
  MarketDataClient,
  OrderManager,
  registerStrategy,
  type Strategy,
  type Signal,
} from "polymarket-trading-sdk";

// Fetch market data (no auth required)
const marketData = new MarketDataClient();
const data = await marketData.getMarketData("your-token-id");
console.log(`Midpoint: ${data.midpoint}, Spread: ${data.spread}`);

// Create an order manager
const orderManager = new OrderManager({
  mode: "paper", // or "live"
  executorUrl: "https://...",
  executorApiKey: "exk_...",
  executorWalletId: "my-wallet",
});

// Place an order
const result = await orderManager.placeOrder({
  slug: "my-market",
  label: "YES",
  tokenId: "123...",
  side: "buy",
  price: 0.5,
  size: 10,
});

Features

Market Data Client

Read-only access to Polymarket market data (no authentication required):

const client = new MarketDataClient();

// Price data
const midpoint = await client.getMidpoint(tokenId);
const price = await client.getPrice(tokenId, "buy");
const spread = await client.getSpread(tokenId);

// Order book
const book = await client.getOrderBook(tokenId);

// Search markets
const markets = await client.searchMarkets("bitcoin");

Order Manager

Unified interface for placing orders in paper or live mode:

const manager = new OrderManager({
  mode: "live",
  executorUrl: process.env.EXECUTOR_URL,
  executorApiKey: process.env.EXECUTOR_API_KEY,
  executorWalletId: process.env.EXECUTOR_WALLET_ID,
});

// Place order
await manager.placeOrder({ ... });

// Cancel order
await manager.cancelOrder("order-id");

// Get balance
const balance = await manager.getBalance();

Strategy System

Create plug-and-play trading strategies:

import {
  registerStrategy,
  getStrategy,
  type Strategy,
  type StrategyContext,
  type Signal,
} from "polymarket-trading-sdk";

const myStrategy: Strategy = {
  name: "my-strategy",

  async scan(ctx: StrategyContext): Promise<Signal[]> {
    // Find trading opportunities
    return [];
  },

  calculatePrice(signal, data, config): number | null {
    // Calculate limit price
    return data.bid ? data.bid + 0.01 : null;
  },
};

registerStrategy(myStrategy);

Pricing Utilities

Pure functions for price calculations:

import {
  roundToTick,
  calculateBid,
  isWideSpread,
} from "polymarket-trading-sdk";

// Round to tick size
roundToTick(0.567, 0.01); // 0.57

// Calculate smart bid
const bid = calculateBid({
  midpoint: 0.50,
  offset: 0.01,
  floor: 0.45,
  min: 0.40,
  max: 0.55,
});

// Check spread
isWideSpread(0.45, 0.55, 0.08); // true

Signing Utilities

HMAC and EIP-712 signing for Polymarket API:

import {
  createLevel2Headers,
  signOrder,
  getAddress,
} from "polymarket-trading-sdk";

// Get wallet address
const address = getAddress("0x...");

// Create authenticated headers
const headers = await createLevel2Headers({
  address,
  apiKey: "...",
  apiSecret: "...",
  apiPassphrase: "...",
  method: "POST",
  path: "/order",
  body: JSON.stringify({ ... }),
});

Auth Middleware

API key authentication for workers:

import { checkAuth, unauthorizedResponse } from "polymarket-trading-sdk";

// In your worker
const auth = checkAuth(request, env);
if (!auth.authorized) {
  return unauthorizedResponse(auth.error || "Unauthorized");
}

API Reference

Clients

• MarketDataClient - Read-only market data access
• ExecutorClient - Order executor Lambda client
• TradingClient - Direct CLOB API client (requires auth)

Order Management

• OrderManager - Unified order interface (paper/live modes)
• createOrderManager(config) - Create from config
• createOrderManagerFromEnv(env) - Create from env vars

Strategy

• Strategy<TEnv> - Strategy interface
• StrategyContext<TEnv> - Context passed to strategies
• registerStrategy(strategy) - Register a strategy
• getStrategy(name) - Get registered strategy
• listStrategies() - List all strategies

Pricing

• roundToTick(price, tickSize) - Round to tick
• floorToTick(price, tickSize) - Floor to tick
• ceilToTick(price, tickSize) - Ceil to tick
• calculateBid(config) - Calculate smart bid
• calculateAsk(config) - Calculate smart ask
• calculateSpread(bid, ask) - Calculate spread
• isWideSpread(bid, ask, threshold) - Check spread

Signing

• buildHmacSignature(...) - HMAC-SHA256 signature
• createLevel2Headers(...) - Level 2 auth headers
• signOrder(...) - EIP-712 order signature
• getAddress(privateKey) - Get wallet address

Auth

• checkAuth(request, env) - Validate API key
• unauthorizedResponse(error) - Create 401 response

License

MIT