Polymarket Relayer Client Tutorial

This guide shows how to use the Polymarket Relayer Client in TypeScript to build gasless flows: wallet deployment, ERC-20 approval handling, CTF split/merge/redeem operations, and order placement on the CLOB. If you want a working, gasless integration with Polymarket, the Polymarket Relayer Client is the developer-facing SDK you will use first.

Key takeaways

• The Polymarket Relayer Client provides TypeScript and Python SDKs to handle wallet deployment, approvals, CTF ops, and order placement through the Polymarket Relayer.
• Polymarket transactions are gasless for end users: the Relayer sponsors gas and abstracts wallet deployment and approvals.
• Common flows are: wallet onboarding → approval check/approval → split (mint) a complete set → create order (limit or FAK) → merge/redeem after resolution.
• Always design for resolution and settlement risks: UMA disputes, partial fills/slippage, and timing are real considerations.

Who this guide is for

You are a developer building integrations, bots, or UX components that place trades on Polymarket's CLOB and interact with the CTF. You should be comfortable with TypeScript, EVM wallets (MetaMask, Rabby, etc.), and basic web3 concepts.

Quick overview of what the SDK covers

• Wallet onboarding: deploy Proxy wallets on first use or use a Gnosis Safe if available.
• ERC-20 approvals management for pUSD and other tokens used in split/merge.
• CTF operations: split, merge, redeem of outcome tokens (ERC-1155).
• Order placement and cancellation against the CLOB through the Relayer.
• Builder attribution headers when you act as a Builder (see Builder Program docs).

Note: Polymarket uses Polygon (chain ID 137), and the settlement asset for trading is pUSD (Polymarket's wrapped USDC). All user transactions are gasless via the Relayer.

Install and first steps

Install the TypeScript package and a standard web3 provider package. Exact package names vary by release; the examples below use the canonical import path common in relayer SDKs. If package names differ in your project, consult the SDK README.

Shell

npm install @polymarket/relayer-client ethers

Basic initialization (TypeScript)

import { RelayerClient } from '@polymarket/relayer-client';
import { ethers } from 'ethers';

// Use a wallet provider exposed in the browser (MetaMask, Rabby, etc.)
const provider = new ethers.providers.Web3Provider((window as any).ethereum);
const signer = provider.getSigner();

const relayer = new RelayerClient({
  signer,
  network: 'polygon', // Polymarket runs on Polygon (chainId 137)
});

Notes on the example above: the RelayerClient constructor and options object are illustrative. Check the SDK README for the exact constructor signature and available options.

Onboarding: wallet deployment and approvals

Polymarket supports two wallet models: pre-deployed Gnosis Safes and Proxy wallets that are auto-deployed on first transaction. The Relayer SDK handles both flows and sponsors deployment gas.

Common onboarding steps you should implement in UX:

1. Detect whether the user already has a Proxy or Safe. If not, call the SDK's deploy-on-first-use helper.
2. Ensure the user has pUSD in their wallet. If not, instruct them how to bridge or deposit (see Polymarket's funding guide).
3. Check ERC-20 approval status for pUSD and prompt a gasless approval via the Relayer if required.

Example: check & request approval (TypeScript)

// Pseudocode — adapt to SDK methods
const pUsdAddress = '0x...'; // use SDK constant if provided
const allowance = await relayer.checkAllowance(pUsdAddress);
if (allowance.lt(requiredAmount)) {
  await relayer.requestApproval(pUsdAddress, requiredAmount);
}

Because the Relayer sponsors gas, the approval call is sent through the Relayer rather than the user signing a direct on-chain gas transaction.

CTF flows: split, merge, redeem

The Conditional Token Framework (CTF) is how Polymarket represents outcomes (ERC-1155 tokens). Typical sequence when you want to buy a complete set:

• split: burn pUSD and mint a complete set of outcome tokens
• after trading, merge: convert leftover outcome tokens back to a common position
• redeem: after resolution, burn winning outcome tokens for $1.00 each

Example split (TypeScript)

// Pseudocode using the Relayer SDK
const conditionId = '0x...';
const amount = ethers.utils.parseUnits('1.0', 6); // pUSD has 6 decimals
await relayer.split(conditionId, amount);

The SDK will handle the necessary approvals and relayer submission. After split, you will receive ERC-1155 outcome tokens in the user's Proxy or Safe.

Placing orders on the CLOB

The CLOB exposes order placement and orderbook reads. The Relayer Client routes order placement through the Relayer, handling builder attribution headers if you are a Builder.

Important order types:

• Limit orders: post to the book and potentially sit as maker (maker fees are zero).
• Market orders (FAK): the SDK exposes helpers to create FAK orders that execute immediately or cancel.

Example: place a FAK market order (TypeScript)

// Conceptual example
const instrumentId = 'POLY_MARKET_INSTRUMENT_ID';
const side = 'buy';
const size = ethers.utils.parseUnits('10', 6);

const result = await relayer.createMarketOrder({
  instrumentId,
  side,
  size,
  slippageTolerance: 0.01, // 1% slippage protection
});

console.log('fill result', result);

If you are operating as a Builder, include attribution headers or builder credentials as required by the Builder Program. The Builder Program offers tiered relayer limits and rewards; obtain credentials at https://polymarket.com/settings.

Reading market data & the WebSocket

For non-trading reads, use Polymarket's public REST and WebSocket surfaces:

• Gamma API: https://gamma-api.polymarket.com (markets, events)
• Data API: https://data-api.polymarket.com (positions, trades, open interest)
• CLOB API: https://clob.polymarket.com (orderbook and order placement APIs)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market for real-time book updates

When you subscribe to market WS feeds, request custom_feature_enabled: true to receive best_bid_ask events and limit subscription to 500 instruments per connection.

Error handling and common pitfalls

• Partial fills: market orders (FAK) can partially fill. Always inspect the result and handle leftovers.
• Slippage: protect aggressive market orders with slippage limits. The SDK often exposes slippage settings on market helpers.
• Resolution and settlement timing: UMA disputes can pause settlement. Design UIs and accounting to reflect unsettled funds until redeem completes.
• Tick size changes: tick size moves from $0.01 to $0.001 near price extremes; handle tick_size_change WebSocket events.

Testing strategies

• End-to-end sandbox: exercise full onboarding — deploy Proxy wallet, request approval, split, place an order, and merge/redeem.
• Unit test wrapper functions: mock relayer methods to assert correct approval and split sequences.
• Rate-limit awareness: Gamma /markets has rate limits (300 req / 10 s for /markets) — batch and cache reads.

How this affects your trading or bot logic

Using the Polymarket Relayer Client removes the need to manage gas for end users and simplifies onboarding by automating Proxy deployments and approvals. For bots, this means you can focus on strategy and market data: the SDK reduces integration surface area for executing split/merge and order flows. However, you must still handle non-execution risks like slippage, partial fills, and oracle disputes.

References and next steps

• Polymarket API base URLs: Gamma (https://gamma-api.polymarket.com), Data (https://data-api.polymarket.com), CLOB (https://clob.polymarket.com)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Builder Program details and credentials at https://polymarket.com/settings

Closing note: Polymarket sponsors gas via the Relayer and provides TypeScript and Python SDKs to streamline typical wallet and CTF workflows. The Polymarket Relayer Client is the recommended path for building gasless integrations that interact with the CLOB and CTF.

Frequently asked questions

What is the Polymarket Relayer Client?

The Polymarket Relayer Client is the SDK (TypeScript and Python) that routes user transactions through Polymarket's Relayer, handling wallet deployment, ERC-20 approvals, CTF operations, and order placement so end users experience gasless trading.

Do users still need pUSD to trade?

Yes. Polymarket's settlement asset is pUSD (wrapped USDC). The Relayer sponsors gas, but users must hold pUSD to perform split operations and place orders.

Can I act as a Builder through the Relayer Client?

Yes. The Builder Program lets third parties route orders with attribution headers and earn builder fees. Obtain credentials at https://polymarket.com/settings and include builder headers as required by the SDK.

Does the Relayer Client handle approvals and wallet deployment automatically?

The SDK provides helpers for automatic Proxy wallet deployment on first use and for requesting gasless ERC-20 approvals through the Relayer, simplifying onboarding.

Where can I read real-time orderbook updates?

Subscribe to the Market WebSocket at wss://ws-subscriptions-clob.polymarket.com/ws/market. Request custom_feature_enabled: true to receive best_bid_ask events and note the 500-instrument subscription limit.