Skip to main content
The Polymarket CLOB API uses a two-level authentication system to secure operations. Level 1 (L1) authentication uses EIP-712 signatures for critical operations like API key creation, while Level 2 (L2) authentication uses HMAC signatures with API credentials for day-to-day trading operations.

​
Authentication Levels

​
Level 1 (L1) Authentication

L1 authentication uses EIP-712 signatures signed by your wallet’s private key. This is required for sensitive operations like creating API keys.
L1 authentication provides the highest level of security by requiring wallet signatures. It’s used sparingly for operations that establish trust.

​
L1 Header Structure

interface L1PolyHeader {
    POLY_ADDRESS: string;      // Your wallet address
    POLY_SIGNATURE: string;    // EIP-712 signature
    POLY_TIMESTAMP: string;    // Unix timestamp
    POLY_NONCE: string;        // Nonce for replay protection
}

​
L1 Operations

  • Create API Key - Generate new API credentials
  • Derive API Key - Retrieve existing API credentials

​
Level 2 (L2) Authentication

L2 authentication uses HMAC-SHA256 signatures with your API credentials. This is used for all trading and account operations.

​
L2 Header Structure

interface L2PolyHeader {
    POLY_ADDRESS: string;      // Your wallet address
    POLY_SIGNATURE: string;    // HMAC signature
    POLY_TIMESTAMP: string;    // Unix timestamp
    POLY_API_KEY: string;      // Your API key
    POLY_PASSPHRASE: string;   // Your API passphrase
}

​
L2 Operations

All trading operations require L2 authentication:
  • Posting and canceling orders
  • Querying trades and open orders
  • Managing account balances
  • Accessing market data for authenticated users

​
API Key Management

​
Creating API Keys

API keys consist of three components: 
interface ApiKeyCreds {
    key: string;        // API key identifier
    secret: string;     // Secret for HMAC signing
    passphrase: string; // Additional authentication factor
}
1

Initialize the client with a signer

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

const wallet = new Wallet("your-private-key");
const client = new ClobClient(
  "https://clob.polymarket.com",
  137, // Polygon mainnet
  wallet
);
2

Create or derive API credentials

// Recommended: Create or derive existing key
const creds = await client.createOrDeriveApiKey();

// Or create a new key explicitly
const newCreds = await client.createApiKey();

// Or derive existing key
const existingCreds = await client.deriveApiKey();
3

Initialize authenticated client

const authenticatedClient = new ClobClient(
  "https://clob.polymarket.com",
  137,
  wallet,
  creds  // Add credentials for L2 auth
);
Store your API credentials securely. The secret is used to sign requests and should never be exposed publicly.

​
Readonly API Keys

Readonly API keys provide read-only access to your account data without the ability to create or cancel orders. 
// Create readonly key
const readonlyKey = await client.createReadonlyApiKey();
console.log(readonlyKey.apiKey);

// List readonly keys
const keys = await client.getReadonlyApiKeys();

// Delete readonly key
await client.deleteReadonlyApiKey(readonlyKey.apiKey);

// Validate readonly key
const result = await client.validateReadonlyApiKey(
  "0x1234...",  // address
  "readonly-key-string"
);

​
Builder API Keys

Builder API keys are specialized credentials for market makers and trading firms that need enhanced functionality. 
// Create builder API key (requires L2 auth)
const builderKey = await client.createBuilderApiKey();

// List builder keys
const builderKeys = await client.getBuilderApiKeys();

// Revoke builder key
await client.revokeBuilderApiKey();

​
Signature Types

The CLOB supports different signature types depending on your wallet setup: 
enum SignatureType {
    // ECDSA EIP712 signatures signed by EOAs
    EOA = 0,
    
    // EIP712 signatures signed by EOAs that own Polymarket Proxy wallets
    POLY_PROXY = 1,
    
    // EIP712 signatures signed by EOAs that own Polymarket Gnosis safes
    POLY_GNOSIS_SAFE = 2,
}

​
Setting Signature Type

import { SignatureType } from "@polymarket/clob-client";

const client = new ClobClient(
  host,
  chainId,
  signer,
  creds,
  SignatureType.POLY_PROXY,  // Specify signature type
  funderAddress              // Required for proxy wallets
);
  • EOA (0): Standard Ethereum wallets (MetaMask, hardware wallets)
  • POLY_PROXY (1): Polymarket’s smart contract proxy wallets (email login via Magic)
  • POLY_GNOSIS_SAFE (2): Gnosis Safe multisig wallets

​
Security Best Practices

Store Credentials Securely

Never commit API secrets to version control. Use environment variables or secure secret management systems.

Use Server Time

Enable useServerTime: true to prevent timestamp-related authentication failures due to clock skew.

Rotate Keys Regularly

Periodically delete and recreate API keys, especially if you suspect they may have been compromised.

Limit Key Scope

Use readonly API keys for monitoring and analytics tools that don’t need trading permissions.

​
Example: Complete Authentication Flow

import { ClobClient, SignatureType } from "@polymarket/clob-client";
import { Wallet } from "ethers";

// Step 1: Initialize with wallet
const wallet = new Wallet(process.env.PRIVATE_KEY!);
const host = "https://clob.polymarket.com";
const chainId = 137; // Polygon

// Step 2: Get or create API credentials
const tempClient = new ClobClient(host, chainId, wallet);
const creds = await tempClient.createOrDeriveApiKey();

// Step 3: Create authenticated client
const client = new ClobClient(
  host,
  chainId,
  wallet,
  creds,
  SignatureType.EOA,
  undefined,  // funderAddress (not needed for EOA)
  undefined,  // geoBlockToken
  true        // useServerTime (recommended)
);

// Step 4: Use authenticated operations
const balance = await client.getBalanceAllowance({
  asset_type: "COLLATERAL"
});

const openOrders = await client.getOpenOrders();
console.log(`Balance: ${balance.balance}`);
console.log(`Open orders: ${openOrders.length}`);

​
Troubleshooting

​
Common Authentication Errors

“L1 auth unavailable”
  • Ensure you’ve provided a signer when creating the ClobClient
  • Verify your private key is valid
“L2 auth not available”
  • You need to create or derive API credentials first
  • Pass the credentials when initializing the client
“Signature verification failed”
  • Check that your signature type matches your wallet setup
  • Verify timestamp is recent (within acceptable window)
  • Ensure useServerTime: true if experiencing clock skew
“Invalid API key”
  • API credentials may have been revoked
  • Recreate credentials using createOrDeriveApiKey()

Orders

Learn how to create and manage orders

Client Reference

Complete API reference for authentication methods

Build docs developers (and LLMs) love

Get started for freeTalk to us