Skip to main content
The SDK provides utilities for creating authentication headers for both L1 (wallet-based) and L2 (API key-based) requests.

​
L1 Headers (EIP-712 Authentication)

​
createL1Headers

Creates authentication headers using EIP-712 wallet signatures for L1 authentication. 
import { createL1Headers, Chain } from "@polymarket/clob-client";

const headers = await createL1Headers(
  signer,
  chainId,
  nonce,
  timestamp
);
​
signer
ClobSigner
required
The wallet signer (ethers Wallet/JsonRpcSigner or viem WalletClient)
​
chainId
Chain
required
The chain ID (e.g., Chain.POLYGON, Chain.AMOY)
​
nonce
number
Optional nonce value (defaults to 0)
​
timestamp
number
Optional Unix timestamp in seconds (defaults to current time)
​
headers
L1PolyHeader
Object containing authentication headers

​
L1PolyHeader Structure

The L1 headers object contains the following fields: 
interface L1PolyHeader {
  POLY_ADDRESS: string;      // Wallet address
  POLY_SIGNATURE: string;    // EIP-712 signature
  POLY_TIMESTAMP: string;    // Unix timestamp
  POLY_NONCE: string;        // Nonce value
}

​
Example: Creating L1 Headers

import { createL1Headers, Chain } from "@polymarket/clob-client";
import { Wallet } from "ethers";

const wallet = new Wallet(privateKey);

// Create headers with default nonce (0) and current timestamp
const headers = await createL1Headers(wallet, Chain.POLYGON);

console.log(headers);
// Output:
// {
//   POLY_ADDRESS: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
//   POLY_SIGNATURE: "0xf62319a987514da40e57e2f4d7529f7bac38f0355bb88bb5adbb3768d80de6c1...",
//   POLY_TIMESTAMP: "1700000000",
//   POLY_NONCE: "0"
// }

​
Example: Custom Nonce and Timestamp

import { createL1Headers, Chain } from "@polymarket/clob-client";
import { Wallet } from "ethers";

const wallet = new Wallet(privateKey);
const customNonce = 42;
const customTimestamp = Math.floor(Date.now() / 1000);

const headers = await createL1Headers(
  wallet,
  Chain.POLYGON,
  customNonce,
  customTimestamp
);

console.log(headers.POLY_NONCE); // "42"

​
L2 Headers (API Key Authentication)

​
createL2Headers

Creates authentication headers using API key credentials and HMAC signatures for L2 authentication. 
import { createL2Headers } from "@polymarket/clob-client";

const headers = await createL2Headers(
  signer,
  creds,
  l2HeaderArgs,
  timestamp
);
​
signer
ClobSigner
required
The wallet signer
​
creds
ApiKeyCreds
required
API key credentials object
​
l2HeaderArgs
L2HeaderArgs
required
Request details for HMAC signature
​
timestamp
number
Optional Unix timestamp in seconds (defaults to current time)
​
headers
L2PolyHeader
Object containing authentication headers

​
ApiKeyCreds Structure

interface ApiKeyCreds {
  key: string;         // API key
  secret: string;      // Base64-encoded secret
  passphrase: string;  // API passphrase
}

​
L2HeaderArgs Structure

interface L2HeaderArgs {
  method: string;       // HTTP method ("GET", "POST", "DELETE")
  requestPath: string;  // API endpoint path
  body?: string;        // Optional JSON body as string
}

​
L2PolyHeader Structure

The L2 headers object contains the following fields: 
interface L2PolyHeader {
  POLY_ADDRESS: string;      // Wallet address
  POLY_SIGNATURE: string;    // HMAC signature
  POLY_TIMESTAMP: string;    // Unix timestamp
  POLY_API_KEY: string;      // API key
  POLY_PASSPHRASE: string;   // API passphrase
}

​
Example: Creating L2 Headers (GET Request)

import { createL2Headers } from "@polymarket/clob-client";
import { Wallet } from "ethers";

const wallet = new Wallet(privateKey);

const creds = {
  key: "00000000-0000-0000-0000-000000000000",
  secret: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
  passphrase: "your-passphrase"
};

const headers = await createL2Headers(
  wallet,
  creds,
  {
    method: "GET",
    requestPath: "/orders"
  }
);

console.log(headers);
// Output:
// {
//   POLY_ADDRESS: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
//   POLY_SIGNATURE: "ZwAdJKvoYRlEKDkNMwd5BuwNNtg93kNaR_oU2HrfVvc=",
//   POLY_TIMESTAMP: "1700000000",
//   POLY_API_KEY: "00000000-0000-0000-0000-000000000000",
//   POLY_PASSPHRASE: "your-passphrase"
// }

​
Example: Creating L2 Headers (POST Request with Body)

import { createL2Headers } from "@polymarket/clob-client";
import { Wallet } from "ethers";

const wallet = new Wallet(privateKey);

const creds = {
  key: "00000000-0000-0000-0000-000000000000",
  secret: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
  passphrase: "your-passphrase"
};

const orderData = {
  tokenID: "123",
  price: "0.55",
  size: "100"
};

const headers = await createL2Headers(
  wallet,
  creds,
  {
    method: "POST",
    requestPath: "/orders",
    body: JSON.stringify(orderData)
  }
);

// Use headers in your HTTP request

​
Builder Headers

​
injectBuilderHeaders

Injects builder API headers into existing L2 headers for builder-authenticated requests. 
import { injectBuilderHeaders } from "@polymarket/clob-client";

const headersWithBuilder = injectBuilderHeaders(
  l2Headers,
  builderHeaders
);
​
l2Headers
L2PolyHeader
required
Existing L2 headers object
​
builderHeaders
BuilderHeaderPayload
required
Builder authentication headers from the Builder Signing SDK
​
headers
L2WithBuilderHeader
Combined headers with builder authentication

​
L2WithBuilderHeader Structure

The combined headers object extends L2PolyHeader with builder-specific fields: 
interface L2WithBuilderHeader extends L2PolyHeader {
  POLY_BUILDER_API_KEY: string;
  POLY_BUILDER_TIMESTAMP: string;
  POLY_BUILDER_PASSPHRASE: string;
  POLY_BUILDER_SIGNATURE: string;
}

​
Example: Adding Builder Headers

import { createL2Headers, injectBuilderHeaders } from "@polymarket/clob-client";
import { createBuilderHeaders } from "@polymarket/builder-signing-sdk";

const wallet = new Wallet(privateKey);
const creds = { /* API credentials */ };

// Create base L2 headers
const l2Headers = await createL2Headers(
  wallet,
  creds,
  {
    method: "POST",
    requestPath: "/orders"
  }
);

// Get builder headers from the Builder SDK
const builderHeaders = await createBuilderHeaders(/* ... */);

// Combine them
const headers = injectBuilderHeaders(l2Headers, builderHeaders);

// Now use headers for builder-authenticated requests

​
Using Headers with the Client

The CLOB client automatically creates the appropriate headers internally. These utilities are exposed for advanced use cases or custom request handling: 
import { ClobClient } from "@polymarket/clob-client";

// The client handles header creation automatically
const client = new ClobClient(
  host,
  chainId,
  signer,
  creds // Optional: for L2 authentication
);

// Headers are created internally for each request
await client.getOrders();
For most use cases, you don’t need to create headers manually. The ClobClient handles authentication automatically. These utilities are useful for:
  • Custom request handling
  • Debugging authentication issues
  • Building custom clients or integrations

​
Header Lifecycle

  1. L1 Headers: Used for wallet-based authentication
    • Created with EIP-712 signature
    • Typically used for initial authentication or sensitive operations
    • Does not require API keys
  2. L2 Headers: Used for API key-based authentication
    • Created with HMAC signature
    • Requires API key credentials from deriveApiKey()
    • More efficient for frequent requests
    • Each request generates a new HMAC signature based on the request details
  3. Builder Headers: Used for builder-specific operations
    • Extends L2 headers with builder authentication
    • Requires separate builder API credentials

Build docs developers (and LLMs) love

Get started for freeTalk to us