TypeScript SDK - Polymarket Documentation

The unified TypeScript SDK gives you a consistent surface across Polymarket discovery, market data, trading, account data, and realtime streams.

The TypeScript SDK is currently in beta. We are keeping it in this beta phase while we address issues and harden the SDK before transitioning to a more stable release.

Quickstart

Install the Package

Install the SDK from your package manager.

pnpm add @polymarket/client@beta

Create a Public Client

Create an instance of the PublicClient.

import { createPublicClient } from "@polymarket/client";

const client = createPublicClient();

Fetch Markets

Fetch a page of markets to discover active trading opportunities.

const markets = client.listMarkets({
  closed: false,
  pageSize: 5,
});

const firstPage = await markets.firstPage();

for (const market of firstPage.items) {
  // market: Market
}

SDK Patterns

The SDK normalizes data across API seams and uses consistent patterns for pagination and typed error handling across public and authenticated workflows.

Typed Primitives

Common primitives such as IDs, decimal values, date/time strings, and EVM addresses are represented with explicit SDK types so integrations can avoid treating every value as a plain string.

type Market = {
  id: MarketId;
  conditionId: ConditionId | null;
  state: {
    startDate?: IsoDateTimeString | null;
    endDate?: IsoDateTimeString | null;
  };
  outcomes: {
    yes: {
      tokenId: TokenId | null;
      price: DecimalString | null;
    };
  };
  resolution: {
    resolvedBy: EvmAddress | null;
  };
  // …
};

Market and Event Data

Market and event responses use normalized field names and TypeScript shapes instead of service-specific response formats.

type Market = {
  id: MarketId;
  slug?: string | null;
  conditionId: ConditionId | null;
  question?: string | null;
  description?: string | null;
  category?: string | null;
  image?: string | null;
  icon?: string | null;
  state: MarketState;
  outcomes: MarketOutcomes;
  metrics: MarketMetrics;
  prices: MarketPrices;
  trading: MarketTrading;
  resolution: MarketResolution;
  rewards: MarketRewards;
  sports: MarketSportsMetadata;
  tags: MarketTag[];
  // …
};

Pagination

List methods return a consistent paginator interface across paginated endpoints. Use for await to iterate through pages.

const markets = client.listMarkets({
  closed: false,
  pageSize: 10,
});

for await (const page of markets) {
  // page.items: Market[]
}

You can also fetch the first page directly and resume later from a cursor.

const firstPage = await markets.firstPage();
// firstPage.items: Market[]

for await (const page of markets.from(firstPage.nextCursor)) {
  // page.items: Market[]
}

Error Handling

Each public action exposes a matching error guard. Use it to handle expected SDK errors and rethrow anything unexpected.

Error guards make exhaustive checks easier and help surface newly added SDK error cases during upgrades.

import { ListMarketsError } from "@polymarket/client";

try {
  const markets = client.listMarkets({
    closed: false,
    pageSize: 10,
  });

  const firstPage = await markets.firstPage();
  // firstPage.items: Market[]
} catch (error) {
  if (!ListMarketsError.isError(error)) {
    throw error;
  }

  switch (error.name) {
    case "RateLimitError":
      // Retry later.
      break;
    case "UserInputError":
      // Fix the request parameters.
      break;
    default:
    // …
  }
}

Market Data

Use market data methods to fetch market and event details, order books, current prices, historical prices, and batch quotes.

const market = await client.fetchMarket({
  url: "https://polymarket.com/market/eth-flipped-in-2026",
});

const market = await client.fetchMarket({
  slug: "eth-flipped-in-2026",
});

const market = await client.fetchMarket({
  id: "12345",
});

Then fetch related tags, order books, prices, and history.

const marketTags = await client.fetchMarketTags({
  id: market.id,
});

const eventTags = await client.fetchEventTags({
  id: event.id,
});

Discovery

Use discovery methods to browse events, markets, teams, tags, comments, sports metadata, and search results. The examples below show a few common entry points.

const events = client.listEvents({
  pageSize: 10,
});

for await (const page of events) {
  // page.items: Event[]
}

const markets = client.listMarkets({
  closed: false,
  pageSize: 10,
});

for await (const page of markets) {
  // page.items: Market[]
}

const teams = client.listTeams({
  league: ["NBA"],
  pageSize: 10,
});

for await (const page of teams) {
  // page.items: Team[]
}

const tags = client.listTags({
  pageSize: 10,
});

for await (const page of tags) {
  // page.items: Tag[]
}

const tag = await client.fetchTag({
  slug: "politics",
});

const relatedTags = await client.fetchRelatedTags({
  slug: "politics",
});

const relatedResources = await client.fetchRelatedTagResources({
  slug: "politics",
  status: "active",
});

const comments = client.listComments({
  parentEntityId: "12345",
  parentEntityType: "Event",
  pageSize: 20,
});

for await (const page of comments) {
  // page.items: Comment[]
}

const thread = await client.fetchCommentsById({
  id: "456",
  getPositions: true,
});

const userComments = client.listCommentsByUserAddress({
  address: "0x1234...",
  pageSize: 10,
  order: "DESC",
});

for await (const page of userComments) {
  // page.items: Comment[]
}

const sports = await client.listSports();

// sports: SportsMetadata[]

const results = client.search({
  q: "ethereum",
  pageSize: 10,
});

for await (const page of results) {
  // page.items.events: Event[]
  // page.items.tags: SearchTag[]
  // page.items.profiles: Profile[]
}

Realtime Streams

Subscribe through one SDK interface even when events are served by different websocket surfaces. The SDK routes each subscription spec to the right stream and merges the results into one stream.

const stream = await client.subscribe([
  {
    topic: "market",
    tokenIds: [market.outcomes.yes.tokenId!],
  },
  {
    topic: "prices.crypto.binance",
    symbols: ["btcusdt"],
  },
]);

for await (const event of stream) {
  // event:
  //   | MarketBookEvent
  //   | MarketPriceChangeEvent
  //   | MarketLastTradePriceEvent
  //   | MarketTickSizeChangeEvent
  //   | CryptoPricesBinanceEvent

  if (shouldStopStreaming()) {
    await stream.close();
  }
}

Authenticated Client

Create a secure client when you need wallet-scoped reads or trading.

Wallet Integrations

The SDK is intended to support a variety of wallet libraries. At launch, we support Viem, Privy, and Ethers v5. We will expand support for more libraries based on demand.

Viem
Privy
Ethers v5

Install the Packages

Install the SDK and Viem wallet tools.

pnpm add @polymarket/client@beta viem

Create the Secure Client

Use the private-key helper, or adapt an existing viem wallet client.

import { createSecureClient } from "@polymarket/client";
import { privateKey } from "@polymarket/client/viem";

const secureClient = await createSecureClient({
  wallet: "YOUR_POLYMARKET_WALLET_ADDRESS",
  signer: privateKey(process.env.PRIVATE_KEY),
});

Install the Packages

Install the SDK and Privy Node client.

pnpm add @polymarket/client@beta @privy-io/node

Create the Secure Client

Use the Privy Node client with the SDK’s Privy signer adapter.

import { createSecureClient } from "@polymarket/client";
import { signerFrom } from "@polymarket/client/privy";
import { PrivyClient } from "@privy-io/node";

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!,
});

const secureClient = await createSecureClient({
  wallet: "YOUR_POLYMARKET_WALLET_ADDRESS",
  signer: signerFrom({
    privy,
    walletId: process.env.PRIVY_WALLET_ID!,
  }),
});

Install the Packages

Install the SDK and the Ethers v5 package alias used by the adapter.

pnpm add @polymarket/client@beta ethers-v5@npm:ethers@^5.8.0

Create the Secure Client

Use the Ethers v5 signer adapter when your integration already manages an ethers.Signer.

import { createSecureClient } from "@polymarket/client";
import { signerFrom } from "@polymarket/client/ethers-v5";
import { ethers } from "ethers-v5";

const provider = new ethers.providers.JsonRpcProvider(
  process.env.POLYGON_RPC_URL,
);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const secureClient = await createSecureClient({
  wallet: "YOUR_POLYMARKET_WALLET_ADDRESS",
  signer: signerFrom(wallet),
});

Trading Setup

Before placing orders, configure API key authentication if you need gasless wallet setup, then make sure the authenticated wallet has the required trading approvals.

Configure API Key Authentication

Configure an API key when the SDK needs to set up gasless wallet operations.

import { createSecureClient, relayerApiKey } from "@polymarket/client";

let secureClient = await createSecureClient({
  wallet: "YOUR_POLYMARKET_WALLET_ADDRESS",
  signer,
  apiKey: relayerApiKey({
    key: process.env.RELAYER_API_KEY!,
    address: process.env.RELAYER_API_KEY_ADDRESS!,
  }),
});

Builder API keys are supported for backwards compatibility with builders that still use them for gasless workflows. They are not used for order attribution. Use builderCode on orders for attribution.

Check Gasless Readiness

Check whether the authenticated wallet is already ready for gasless transactions.

const isGaslessReady = await secureClient.isGaslessReady();

Set Up Gasless Wallet

If needed, set up the gasless wallet and continue with the returned secure client.

if (!isGaslessReady) {
  secureClient = await secureClient.setupGaslessWallet();
}

Set Up Trading Approvals

Set up the approvals required for trading and wait for the setup transaction to complete.

const handle = await secureClient.setupTradingApprovals();
await handle.wait();

Trading

Use a secure client to create, sign, and submit orders. Limit orders specify the price and size you want to trade. Market orders execute against resting liquidity immediately. Order placement returns a discriminated response. Check response.ok before reading order details.

Place Orders

Limit Order
Expiring Limit Order
Partial-Fill Market Order
All-Or-Nothing Market Order
Builder Code

import { OrderSide } from "@polymarket/client";

const response = await secureClient.placeLimitOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.BUY,
  price: 0.52,
  size: 10,
});

if (response.ok) {
  // response.orderId: string
} else {
  // response.code: OrderResponseErrorCode
  // response.message: string
}

import { OrderSide } from "@polymarket/client";

const response = await secureClient.placeLimitOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.SELL,
  price: 0.52,
  size: 10,
  expiration: Math.floor(Date.now() / 1000) + 60 * 60,
});

if (response.ok) {
  // response.orderId: string
} else {
  // response.code: OrderResponseErrorCode
  // response.message: string
}

import { OrderSide, OrderType } from "@polymarket/client";

const response = await secureClient.placeMarketOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.BUY,
  amount: 10,
  maxSpend: 11,
  orderType: OrderType.FAK,
});

if (response.ok) {
  // response.orderId: string
} else {
  // response.code: OrderResponseErrorCode
  // response.message: string
}

import { OrderSide, OrderType } from "@polymarket/client";

const response = await secureClient.placeMarketOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.SELL,
  shares: 10,
  orderType: OrderType.FOK,
});

if (response.ok) {
  // response.orderId: string
} else {
  // response.code: OrderResponseErrorCode
  // response.message: string
}

import { OrderSide } from "@polymarket/client";

const response = await secureClient.placeLimitOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.BUY,
  price: 0.52,
  size: 10,
  builderCode: "0xabc123...",
});

if (response.ok) {
  // response.orderId: string
} else {
  // response.code: OrderResponseErrorCode
  // response.message: string
}

Create, Then Post

Create signed orders separately when you want to review, store, or batch them before submitting.

Single Order
Batch Orders

import { OrderSide } from "@polymarket/client";

const order = await secureClient.createLimitOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.BUY,
  price: 0.52,
  size: 10,
});

const response = await secureClient.postOrder(order);

if (response.ok) {
  // response.orderId: string
} else {
  // response.code: OrderResponseErrorCode
  // response.message: string
}

import { OrderSide } from "@polymarket/client";

const firstOrder = await secureClient.createLimitOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.BUY,
  price: 0.52,
  size: 10,
});

const secondOrder = await secureClient.createLimitOrder({
  tokenId: market.outcomes.yes.tokenId!,
  side: OrderSide.SELL,
  price: 0.58,
  size: 5,
});

const responses = await secureClient.postOrders([firstOrder, secondOrder]);

for (const response of responses) {
  if (response.ok) {
    // response.orderId: string
  } else {
    // response.code: OrderResponseErrorCode
    // response.message: string
  }
}

Position Lifecycle

Use position lifecycle methods to split collateral into outcome tokens, merge complete sets back into collateral, or redeem resolved positions. These examples assume the secure client is configured with API key authentication as shown in Trading Setup.

Split Position
Merge Positions
Redeem Positions

const handle = await secureClient.splitPosition({
  conditionId: market.conditionId!,
  amount: 1n,
});

const outcome = await handle.wait();

// outcome.transactionHash: TxHash

const handle = await secureClient.mergePositions({
  conditionId: market.conditionId!,
  amount: "max",
});

const outcome = await handle.wait();

// outcome.transactionHash: TxHash

const handle = await secureClient.redeemPositions({
  marketId: market.id,
});

const outcome = await handle.wait();

// outcome.transactionHash: TxHash

Wallet Operations

Use wallet operation methods for direct token movements from the authenticated wallet. These examples assume the secure client is configured with API key authentication as shown in Trading Setup.

const handle = await secureClient.transferErc20({
  amount: 1n,
  recipientAddress: "RECIPIENT_ADDRESS",
  tokenAddress: secureClient.environment.collateralToken,
});

const outcome = await handle.wait();

// outcome.transactionHash: TxHash

Order Management

Manage open orders for the authenticated wallet after placement. These examples assume orderId comes from an accepted order response.

Fetch Order
List Open Orders
Cancel Order
Cancel Market Orders

const order = await secureClient.fetchOrder({
  orderId,
});

// order: OpenOrder

const openOrders = secureClient.listOpenOrders({
  market: market.id, // Or market.conditionId
});

for await (const page of openOrders) {
  // page.items: OpenOrder[]
}

const response = await secureClient.cancelOrder({
  orderId,
});

// response.canceled: string[]

const response = await secureClient.cancelMarketOrders({
  tokenId: market.outcomes.yes.tokenId!,
});

// response.canceled: string[]

Rewards and Scoring

Use rewards methods to inspect active reward programs and scoring methods to check whether orders are eligible for scoring.

Current Rewards
Market Rewards
Order Scoring
Batch Order Scoring

const rewards = client.listCurrentRewards();

for await (const page of rewards) {
  // page.items: CurrentReward[]
}

const rewards = client.listMarketRewards({
  conditionId: market.conditionId!,
});

for await (const page of rewards) {
  // page.items: MarketReward[]
}

const scoring = await secureClient.fetchOrderScoring({
  orderId,
});

// scoring: boolean

const scoring = await secureClient.fetchOrdersScoring({
  orderIds: [firstOrderId, secondOrderId],
});

// scoring: OrdersScoringResponse

Account Data

Secure clients can read account-scoped data for the authenticated wallet.

Positions
Portfolio Value
Activity
Trades
Notifications

const positions = secureClient.listPositions({
  market: [market.id], // Or market.conditionId
  pageSize: 10,
});

for await (const page of positions) {
  // page.items: Position[]
}

const value = await secureClient.fetchPortfolioValue({
  market: [market.id], // Or market.conditionId
});

// value: Value[]

import { ActivityType } from "@polymarket/client";

const activity = secureClient.listActivity({
  market: [market.id], // Or market.conditionId
  pageSize: 10,
});

for await (const page of activity) {
  for (const item of page.items) {
    switch (item.type) {
      case ActivityType.TRADE:
        // item.tokenId: TokenId
        // item.shares: DecimalString
        break;
      case ActivityType.REWARD:
        // item.amount: DecimalString
        break;
      default:
      // …
    }
  }
}

const yesTokenId = market.outcomes.yes.tokenId!;

const trades = secureClient.listAccountTrades({
  tokenId: yesTokenId,
});

for await (const page of trades) {
  // page.items: ClobTrade[]
}

const notifications = await secureClient.fetchNotifications();

// notifications: Notification[]

Authentication Sessions

Secure clients expose the API credentials created for the authenticated session. Store them securely if you want to reuse the session later without requiring a new authentication signature while the credentials remain valid.

Save Credentials
Reuse Credentials

const secureClient = await createSecureClient({
  wallet: "YOUR_POLYMARKET_WALLET_ADDRESS",
  signer,
});

await storage.set("polymarketCredentials", secureClient.credentials);

const credentials = await storage.get("polymarketCredentials");

const secureClient = await createSecureClient({
  wallet: "YOUR_POLYMARKET_WALLET_ADDRESS",
  signer,
  credentials,
});

Overview

Developer Tools

Events

Markets

Orderbook & Pricing

Orders

Trades

CLOB Markets

Rebates

Rewards

Profile

Leaderboard

Builders

Search

Tags

Series

Comments

Sports

Bridge

Relayer

WebSocket

Documentation Index

​Quickstart

​SDK Patterns

​Typed Primitives

​Market and Event Data

​Pagination

​Error Handling

​Market Data

​Discovery

​Realtime Streams

​Authenticated Client

​Wallet Integrations

​Trading Setup

​Trading

​Place Orders

​Create, Then Post

​Position Lifecycle

​Wallet Operations

​Order Management

​Rewards and Scoring

​Account Data

​Authentication Sessions

Quickstart

SDK Patterns

Typed Primitives

Market and Event Data

Pagination

Error Handling

Market Data

Discovery

Realtime Streams

Authenticated Client

Wallet Integrations

Trading Setup

Trading

Place Orders

Create, Then Post

Position Lifecycle

Wallet Operations

Order Management

Rewards and Scoring

Account Data

Authentication Sessions