Polymarket US TypeScript SDK

Official TypeScript SDK for the Polymarket US API.

Installation

npm install polymarket-us

Usage

Public Endpoints (No Authentication)

import { PolymarketUS } from 'polymarket-us';

const client = new PolymarketUS();

// Get events with pagination
const events = await client.events.list({ limit: 10, offset: 0, active: true });
const nextPage = await client.events.list({ limit: 10, offset: 10, active: true });

// Get a specific event
const event = await client.events.retrieve(123);
const eventBySlug = await client.events.retrieveBySlug('super-bowl-2025');

// Get markets
const markets = await client.markets.list();
const market = await client.markets.retrieveBySlug('btc-100k');

// Get order book
const book = await client.markets.book('btc-100k');

// Get best bid/offer
const bbo = await client.markets.bbo('btc-100k');

// Search
const results = await client.search.query({ query: 'bitcoin' });

// Series and sports
const series = await client.series.list();
const sports = await client.sports.list();

Authenticated Endpoints (Trading)

import { PolymarketUS } from 'polymarket-us';

const client = new PolymarketUS({
  keyId: process.env.POLYMARKET_KEY_ID,
  secretKey: process.env.POLYMARKET_SECRET_KEY,
});

// Create an order
const order = await client.orders.create({
  marketSlug: 'btc-100k-2025',
  intent: 'ORDER_INTENT_BUY_LONG',
  type: 'ORDER_TYPE_LIMIT',
  price: { value: '0.55', currency: 'USD' },
  quantity: 100,
  tif: 'TIME_IN_FORCE_GOOD_TILL_CANCEL',
});

// Get open orders
const openOrders = await client.orders.list();

// Cancel an order
await client.orders.cancel(order.id, { marketSlug: 'btc-100k-2025' });

// Cancel all orders
await client.orders.cancelAll();

// Get positions
const positions = await client.portfolio.positions();

// Get activity history
const activities = await client.portfolio.activities();

// Get account balances
const balances = await client.account.balances();

Authentication

Polymarket US uses Ed25519 signature authentication. Generate API keys at polymarket.us/developer.

The SDK automatically signs requests with your credentials:

const client = new PolymarketUS({
  keyId: 'your-api-key-id',      // UUID
  secretKey: 'your-secret-key',  // Base64-encoded Ed25519 private key
});

Error Handling

import {
  PolymarketUS,
  AuthenticationError,
  BadRequestError,
  NotFoundError,
  RateLimitError,
} from 'polymarket-us';

try {
  await client.orders.create({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else if (error instanceof BadRequestError) {
    console.error('Invalid order parameters');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, retry later');
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  }
}

Configuration

const client = new PolymarketUS({
  keyId: 'your-key-id',
  secretKey: 'your-secret-key',
  timeout: 30000,  // Request timeout in ms (default: 30000)
});

WebSocket (Real-Time Data)

import { PolymarketUS } from 'polymarket-us';

const client = new PolymarketUS({
  keyId: process.env.POLYMARKET_KEY_ID,
  secretKey: process.env.POLYMARKET_SECRET_KEY,
});

// Private WebSocket (orders, positions, balances)
const privateWs = client.ws.private();

privateWs.on('orderSnapshot', (data) => {
  console.log('Open orders:', data.orderSubscriptionSnapshot.orders);
});

privateWs.on('orderUpdate', (data) => {
  console.log('Order execution:', data.orderSubscriptionUpdate.execution);
});

privateWs.on('positionUpdate', (data) => {
  console.log('Position changed:', data.positionSubscriptionUpdate);
});

privateWs.on('error', (error) => {
  console.error('WebSocket error:', error);
});

await privateWs.connect();
privateWs.subscribeOrders('order-sub-1');
privateWs.subscribePositions('pos-sub-1');
privateWs.subscribeAccountBalance('balance-sub-1');

// Markets WebSocket (order book, trades)
const marketsWs = client.ws.markets();

marketsWs.on('marketData', (data) => {
  console.log('Order book:', data.marketData.bids, data.marketData.offers);
});

marketsWs.on('trade', (data) => {
  console.log('Trade:', data.trade);
});

await marketsWs.connect();
marketsWs.subscribeMarketData('md-sub-1', ['btc-100k-2025']);
marketsWs.subscribeTrades('trade-sub-1', ['btc-100k-2025']);

// Unsubscribe and close
marketsWs.unsubscribe('md-sub-1');
marketsWs.close();

API Reference

Events

Method	Description
events.list(params?)	List events with filtering
events.retrieve(id)	Get event by ID
events.retrieveBySlug(slug)	Get event by slug

Markets

Method	Description
markets.list(params?)	List markets with filtering
markets.retrieve(id)	Get market by ID
markets.retrieveBySlug(slug)	Get market by slug
markets.book(slug)	Get order book
markets.bbo(slug)	Get best bid/offer
markets.settlement(slug)	Get settlement price

Orders (Authenticated)

Method	Description
orders.create(params)	Create a new order
orders.list(params?)	Get open orders
orders.retrieve(orderId)	Get order by ID
orders.cancel(orderId, params)	Cancel an order
orders.modify(orderId, params)	Modify an order
orders.cancelAll(params?)	Cancel all open orders
orders.preview(params)	Preview an order
orders.closePosition(params)	Close a position

Portfolio (Authenticated)

Method	Description
portfolio.positions(params?)	Get trading positions
portfolio.activities(params?)	Get activity history

Account (Authenticated)

Method	Description
account.balances()	Get account balances

Series

Method	Description
series.list(params?)	List series
series.retrieve(id)	Get series by ID

Sports

Method	Description
sports.list()	List sports
sports.teams(params?)	Get teams for provider

Search

Method	Description
search.query(params?)	Search events (includes nested markets)

WebSocket (Authenticated)

Method	Description
ws.private()	Create private WebSocket connection
ws.markets()	Create markets WebSocket connection

Private WebSocket Events:

• orderSnapshot - Initial orders snapshot
• orderUpdate - Order execution updates
• positionSnapshot - Initial positions snapshot
• positionUpdate - Position changes
• accountBalanceSnapshot - Initial balance
• accountBalanceUpdate - Balance changes
• heartbeat - Connection keepalive
• error - Error events
• close - Connection closed

Markets WebSocket Events:

• marketData - Full order book updates
• marketDataLite - Lightweight price data
• trade - Trade notifications
• heartbeat - Connection keepalive
• error - Error events
• close - Connection closed

Requirements

• Node.js 18+
• For WebSocket support on Node.js < 22, install the ws package:

npm install ws

License

MIT