Polymarket Builder codes

Polymarket’s Builder program enables apps to earn fees on trades they route through the platform. This guide demonstrates how to integrate Polymarket trading using Privy for authentication and embedded wallet provisioning—giving your users a seamless, gasless trading experience with web2-style onboarding.

Polymarket

The world’s largest prediction market platform.

Builder Program

Official builder program documentation.

Polymarket builder code example repo

Official Next.js example with Privy authentication and Polymarket trading.

Getting started

Create a Privy app

Get builder credentials

Obtain your builder API key, secret, and passphrase from Polymarket.

Get a Polygon RPC URL

Use any Polygon mainnet RPC provider (Alchemy, Infura, or a public RPC).

Setup

To get started, you’ll need to set up:

Privy authentication — Handles login and provisions embedded wallets
Builder signing endpoint — Keeps your builder credentials secure server-side
Polymarket clients — RelayClient for Safe operations, ClobClient for trading

Clone the example:

git clone https://github.com/Polymarket/privy-safe-builder-example.git
cd privy-safe-builder-example
npm install

Add your credentials to .env.local:

NEXT_PUBLIC_POLYGON_RPC_URL=your_rpc_url
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
POLYMARKET_BUILDER_API_KEY=your_builder_api_key
POLYMARKET_BUILDER_SECRET=your_builder_secret
POLYMARKET_BUILDER_PASSPHRASE=your_builder_passphrase

Run npm run dev and open localhost:3000.

Integration steps

Step 1: Set up authentication

First, wrap your app with PrivyProvider and use Privy’s hooks to handle login. When users authenticate, Privy automatically provisions an embedded wallet:

import {PrivyProvider, usePrivy, useWallets} from '@privy-io/react-auth';

function App() {
  const {login, authenticated} = usePrivy();
  const {wallets} = useWallets();

  const embeddedWallet = wallets.find((w) => w.walletClientType === 'privy');

  return (
    <button onClick={login}>
      {authenticated ? `Connected: ${embeddedWallet?.address}` : 'Login'}
    </button>
  );
}

Step 2: Configure the builder signing endpoint

Next, set up a server-side API route to keep your builder credentials secure. The example includes this at app/api/polymarket/sign/route.ts. This endpoint generates HMAC signatures for the RelayClient and ClobClient:

import {NextRequest, NextResponse} from 'next/server';
import {BuilderApiKeyCreds, buildHmacSignature} from '@polymarket/builder-signing-sdk';

const BUILDER_CREDENTIALS: BuilderApiKeyCreds = {
  key: process.env.POLYMARKET_BUILDER_API_KEY!,
  secret: process.env.POLYMARKET_BUILDER_SECRET!,
  passphrase: process.env.POLYMARKET_BUILDER_PASSPHRASE!
};

export async function POST(request: NextRequest) {
  const body = await request.json();
  const {method, path, body: requestBody} = body;

  const sigTimestamp = Date.now().toString();

  const signature = buildHmacSignature(
    BUILDER_CREDENTIALS.secret,
    parseInt(sigTimestamp),
    method,
    path,
    requestBody
  );

  return NextResponse.json({
    POLY_BUILDER_SIGNATURE: signature,
    POLY_BUILDER_TIMESTAMP: sigTimestamp,
    POLY_BUILDER_API_KEY: BUILDER_CREDENTIALS.key,
    POLY_BUILDER_PASSPHRASE: BUILDER_CREDENTIALS.passphrase
  });
}

This reference implementation exposes builder credentials to the client. For production, implement a proxy pattern where the server makes all CLOB/Relay requests, or add auth token validation before returning credentials.

Step 3: Deploy a Safe wallet

Polymarket uses Gnosis Safe wallets for trading. The hooks/useSafeDeployment.ts hook handles this. First, derive the Safe address from the user’s EOA (this is deterministic—the same EOA always gets the same Safe):

import {deriveSafe} from '@polymarket/builder-relayer-client/dist/builder/derive';
import {getContractConfig} from '@polymarket/builder-relayer-client/dist/config';
import {POLYGON_CHAIN_ID} from '@/constants/polymarket';

const config = getContractConfig(POLYGON_CHAIN_ID);
const safeAddress = deriveSafe(eoaAddress, config.SafeContracts.SafeFactory);

Then check if the Safe exists and deploy it if needed:

import {RelayClient, RelayerTransactionState} from '@polymarket/builder-relayer-client';

async function deploySafe(relayClient: RelayClient): Promise<string> {
  // Prompts signer for a signature
  const response = await relayClient.deploy();

  // Poll until the transaction is mined/confirmed (60s timeout, 3s interval)
  const result = await relayClient.pollUntilState(
    response.transactionID,
    [
      RelayerTransactionState.STATE_MINED,
      RelayerTransactionState.STATE_CONFIRMED,
      RelayerTransactionState.STATE_FAILED
    ],
    '60',
    3000
  );

  return result.proxyAddress;
}

The Safe holds the user’s USDC.e and outcome tokens. Deployment is gasless—Polymarket’s relayer covers the cost.

Step 4: Get user API credentials

User API Credentials authenticate requests to the CLOB. The hooks/useUserApiCredentials.ts hook handles this. For new users, create credentials:

import {ClobClient} from '@polymarket/clob-client';
import {CLOB_API_URL, POLYGON_CHAIN_ID} from '@/constants/polymarket';
import {useWallet} from '@/providers/WalletContext';

const {eoaAddress, ethersSigner} = useWallet();
const tempClient = new ClobClient(CLOB_API_URL, POLYGON_CHAIN_ID, ethersSigner);
const creds = await tempClient.createApiKey(); // Prompts for signature

For returning users, derive existing credentials:

const creds = await tempClient.deriveApiKey(); // Prompts for signature

Both methods require the user to sign an EIP-712 message. The example stores credentials in localStorage for convenience, but production apps should use secure httpOnly cookies or server-side session management.

Step 5: Set token approvals

Before trading, the Safe must approve Polymarket’s contracts. The hooks/useTokenApprovals.ts hook batches all approvals into a single transaction. USDC.e (ERC-20) approvals for:

CTF Contract: 0x4d97dcd97ec945f40cf65f87097ace5ea0476045
CTF Exchange: 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
Neg Risk Exchange: 0xC5d563A36AE78145C45a50134d48A1215220f80a
Neg Risk Adapter: 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296

Outcome token (ERC-1155) approvals for:

CTF Exchange: 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
Neg Risk Exchange: 0xC5d563A36AE78145C45a50134d48A1215220f80a
Neg Risk Adapter: 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296

const approvalStatus = await checkAllApprovals(safeAddress);

if (!approvalStatus.allApproved) {
  const approvalTxs = createAllApprovalTxs();
  const response = await relayClient.execute(approvalTxs, 'Set token approvals');
  await response.wait();
}

Approvals persist across sessions—users only sign once. All approval transactions are gasless via the relayer.

Step 6: Place an order

With the session initialized, place orders through the CLOB client:

const order = {
  tokenID: '0x...', // Outcome token from market
  price: 0.65, // 65 cents
  size: 10, // 10 shares
  side: 'BUY',
  feeRateBps: 0,
  expiration: 0, // Good-til-cancel
  taker: '0x0000000000000000000000000000000000000000'
};

const response = await clobClient.createAndPostOrder(order, {negRisk: false}, OrderType.GTC);
console.log('Order ID:', response.orderID);

Orders are signed by the user’s Privy EOA and executed from their Safe address. Builder attribution is automatic via the builder config.

Troubleshooting

Privy authentication failed

Verify NEXT_PUBLIC_PRIVY_APP_ID is set correctly. Check that your domain is allowed in the Privy dashboard.

Failed to initialize relay client

Check builder credentials in .env.local. Verify the /api/polymarket/sign endpoint is accessible.

Safe deployment failed

Ensure the Polygon RPC URL is valid. The user must approve the signature via Privy.

Token approval failed

The Safe must be deployed first. Verify the builder relay service is operational.

Orders not appearing

Verify the trading session is complete and the Safe has a USDC.e balance. Wait 2-3 seconds for CLOB sync.

Polymarket Builder codes

Polymarket

Builder Program

Polymarket builder code example repo

Getting started

Setup

Integration steps

Step 1: Set up authentication

Step 2: Configure the builder signing endpoint

Step 3: Deploy a Safe wallet

Step 4: Get user API credentials

Step 5: Set token approvals

Step 6: Place an order

Troubleshooting

Resources

CLOB API

Relayer client

Polymarket

Builder Program

Polymarket builder code example repo

​Getting started

​Setup

​Integration steps

​Step 1: Set up authentication

​Step 2: Configure the builder signing endpoint

​Step 3: Deploy a Safe wallet

​Step 4: Get user API credentials

​Step 5: Set token approvals

​Step 6: Place an order

​Troubleshooting

​Resources

CLOB API

Relayer client

Getting started

Setup

Integration steps

Step 1: Set up authentication

Step 2: Configure the builder signing endpoint

Step 3: Deploy a Safe wallet

Step 4: Get user API credentials

Step 5: Set token approvals

Step 6: Place an order

Troubleshooting

Resources