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. Usefor await to iterate through pages.
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.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.- Events
- Markets
- Teams
- Comments
- Sports
- Search
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.- Viem
- Privy
- Ethers v5
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. Checkresponse.ok before reading order details.
Place Orders
- Limit Order
- Expiring Limit Order
- Partial-Fill Market Order
- All-Or-Nothing Market Order
- Builder Code
Create, Then Post
Create signed orders separately when you want to review, store, or batch them before submitting.- Single Order
- Batch Orders
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.- Split Position
- Merge Positions
- Redeem Positions
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 assumeorderId comes from an accepted order response.
- Fetch Order
- List Open Orders
- Cancel Order
- Cancel Market Orders
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
Account Data
Secure clients can read account-scoped data for the authenticated wallet.- Positions
- Portfolio Value
- Activity
- Trades
- Notifications
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
Changelog
0.1.0-beta.16
- Added
RESOLVED_PARTIALtoComboPositionStatusso 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
typefield 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
outcomeandredeemableon Combo positions. - Branded Combo activity row IDs.
- Breaking beta change: Combo activity and position fields now use
wallet,amount, andpayout; Combo activity rows no longer exposemoduleKind.
0.1.0-beta.13
- Added
listMarketClarificationsfor 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.005and0.0025. - Pagination request cursors now infer the branded pagination cursor type.
0.1.0-beta.10
- Preserve already-deployed legacy UUPS Deposit Wallets when
createSecureClientresolves the default wallet, while new Deposit Wallet deployments use the beacon factory path.
0.1.0-beta.9
- Added
PriceHistoryIntervalandSearchSortexports, preservedgroupItemTitleon normalized markets, and publishedexpectPrivateKeyfrom@polymarket/types.
0.1.0-beta.8
- RFQ quoter sessions now emit typed
tradeevents for confirmed Combos fills. - RFQ rejection errors now expose
errorIdvalues and parseINVALID_SIGNATUREandINTERNAL_ERRORcodes.
0.1.0-beta.7
- Added
parentEventIdtoEventso child events can link back to their parent event. - Added
maxPriceandminPriceprotection fields to market order requests. - Handle legacy multi-outcome markets more safely:
listMarketsskips markets that cannot be represented by the binary market model, andfetchMarketreturns 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 becomenull, and missing trade or position market icons becomenull. - Parse Combo trade activity rows with an
isCombodiscriminated 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_callbatches 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) andcombos-rfq-gateway-quoter.polymarket.com(quoter WebSocket).
0.1.0-beta.5
- Added
listComboMarketsfor fetching the Combo market catalog with typed bindings and SDK-owned pagination. See Combos. - Parse RFQ quote rejections that use the
SUBMISSION_WINDOW_CLOSEDgateway 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.
ConditionIdis now deprecated in favor ofCtfConditionId; existingConditionIdexports 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.
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.
isGaslessReady() or setupGaslessWallet() in the
normal setup path. Create the secure client, then set up trading approvals.