Skip to main content
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

1

Install the Package

Install the SDK from your package manager.
2

Create a Public Client

Create an instance of the PublicClient.
3

Fetch Markets

Fetch a page of markets to discover active trading opportunities.

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.

Market and Event Data

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

Pagination

List methods return a consistent paginator interface across paginated endpoints. Use for await to iterate through pages.
You can also fetch the first page directly and resume later from a cursor.

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.

Market Data

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

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.

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.

Authenticated Client

Create a secure client when you need wallet-scoped reads or trading. By default, createSecureClient uses the signer’s deterministic Deposit Wallet as the account wallet. The SDK deploys that wallet if needed during client creation. Pass wallet only when you want to authenticate an existing wallet, such as an existing Deposit Wallet, Poly Safe, Poly Proxy, or the signer address itself for EOA trading. The examples below pass wallet to make account selection explicit. Omit wallet to use the default Deposit Wallet flow.

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.
1

Install the Packages

Install the SDK and Viem wallet tools.
2

Create the Secure Client

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

Trading Setup

Before placing orders, make sure the authenticated wallet is deployed and has the required trading approvals. createSecureClient resolves the signer’s deterministic Deposit Wallet by default and deploys it if needed.
1

Configure API Key Authorization

Configure API key authorization when the SDK needs to deploy a Deposit Wallet or submit approval transactions.
Builder API keys are supported for backwards compatibility with builders that still use them for wallet operations. They are not used for order attribution. Use builderCode on orders for attribution.
2

Set Up Trading Approvals

Then set up trading approvals.
setupTradingApprovals() waits for the setup transaction internally and is idempotent. If the wallet already has the required approvals, it returns without submitting a transaction.

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

Create, Then Post

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

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 you created a secure client and set up trading approvals as shown above.

Wallet Operations

Use wallet operation methods for direct token movements from the authenticated wallet. These examples assume you created a secure client as shown above.

Order Management

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

Rewards and Scoring

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

Account Data

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

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.

Changelog

0.1.0-beta.16

  • Added RESOLVED_PARTIAL to ComboPositionStatus so Combo positions that resolve at a fractional payout (for example a voided leg) parse correctly instead of failing validation.

0.1.0-beta.15

  • Combo activity now parses the canonical type field returned by the Data API, instead of deriving lifecycle actions from legacy fields.

0.1.0-beta.14

  • Added SDK pagination for Combo lifecycle activity and server-cursor pagination for Combo positions.
  • Added Combo position sync request fields and exposed outcome and redeemable on Combo positions.
  • Branded Combo activity row IDs.
  • Breaking beta change: Combo activity and position fields now use wallet, amount, and payout; Combo activity rows no longer expose moduleKind.

0.1.0-beta.13

  • Added listMarketClarifications for reading market clarification text with SDK-owned pagination and market, event, state, question, and transaction filters.
  • Fixed legacy Proxy wallet gasless execution and added live Safe and Proxy wallet coverage.
  • Resolve closed markets when preparing market position redemptions.
  • Gasless transaction handles now wait for relayer transactions to reach confirmed state before resolving.

0.1.0-beta.12

  • Require GTD limit order expirations to be at least 3 minutes in the future.

0.1.0-beta.11

  • Support CLOB order tick sizes 0.005 and 0.0025.
  • Pagination request cursors now infer the branded pagination cursor type.

0.1.0-beta.10

  • Preserve already-deployed legacy UUPS Deposit Wallets when createSecureClient resolves the default wallet, while new Deposit Wallet deployments use the beacon factory path.

0.1.0-beta.9

  • Added PriceHistoryInterval and SearchSort exports, preserved groupItemTitle on normalized markets, and published expectPrivateKey from @polymarket/types.

0.1.0-beta.8

  • RFQ quoter sessions now emit typed trade events for confirmed Combos fills.
  • RFQ rejection errors now expose errorId values and parse INVALID_SIGNATURE and INTERNAL_ERROR codes.

0.1.0-beta.7

  • Added parentEventId to Event so child events can link back to their parent event.
  • Added maxPrice and minPrice protection fields to market order requests.
  • Handle legacy multi-outcome markets more safely: listMarkets skips markets that cannot be represented by the binary market model, and fetchMarket returns a typed SDK error for unsupported markets.
  • Normalize empty-string order and activity fields to SDK values: decimal amounts become "0", missing maker order fee rates become null, and missing trade or position market icons become null.
  • Parse Combo trade activity rows with an isCombo discriminated union.
  • Support new Combos RFQ websocket error codes for balance, allowance, and pre-execution reservation failures.
  • Broad user websocket subscriptions now omit market filters so all-market streams receive trade events.
  • Retry rejected JSON-RPC eth_call batches by splitting them into smaller batches.

0.1.0-beta.6

  • Point Combos RFQ endpoints at the production domains: combos-rfq-api.polymarket.com (REST) and combos-rfq-gateway-quoter.polymarket.com (quoter WebSocket).

0.1.0-beta.5

  • Added listComboMarkets for fetching the Combo market catalog with typed bindings and SDK-owned pagination. See Combos.
  • Parse RFQ quote rejections that use the SUBMISSION_WINDOW_CLOSED gateway error code.

0.1.0-beta.4

  • Added Combos support for multi-leg RFQ positions. See Combos.
  • Reject whitespace-only search queries and trim leading or trailing search input.
  • ConditionId is now deprecated in favor of CtfConditionId; existing ConditionId exports remain available as deprecated aliases.

0.1.0-beta.3

Secure client setup now defaults to the Deposit Wallet flow createSecureClient can now derive and use the signer’s deterministic Deposit Wallet when you omit wallet. If you already know which Polymarket wallet you want to use, keep passing wallet.
If you want to keep account selection explicit, no change is required:
setupTradingApprovals() now waits internally You no longer need to wait on the returned handle. Call the method once before trading; it is safe to call again if approvals are already set.
Gasless setup helpers are deprecated You no longer need to call isGaslessReady() or setupGaslessWallet() in the normal setup path. Create the secure client, then set up trading approvals.

0.1.0-beta.2

First beta release of the unified TypeScript SDK. Install the beta package with your package manager: