Authentication

The CLOB API uses two levels of authentication: L1 (Private Key) and L2 (API Key). Either can be accomplished using the CLOB client or REST API.

Public vs Authenticated

Public (No Auth)

The Gamma API, Data API, and CLOB read endpoints (orderbook, prices, spreads) require no authentication.

Authenticated (CLOB)

CLOB trading endpoints (placing orders, cancellations, heartbeat) require all 5 POLY_* L2 HTTP headers.

Two-Level Authentication Model

The CLOB uses two levels of authentication: L1 (Private Key) and L2 (API Key). Either can be accomplished using the CLOB client or REST API

L1 Authentication

L1 authentication uses the wallet’s private key to sign an EIP-712 message used in the request header. It proves ownership and control over the private key. The private key stays in control of the user and all trading activity remains non-custodial. Used for:

Creating API credentials
Deriving existing API credentials
Signing and creating user’s orders locally

L2 Authentication

L2 uses API credentials (apiKey, secret, passphrase) generated from L1 authentication. These are used solely to authenticate requests made to the CLOB API. Requests are signed using HMAC-SHA256. Used for:

Cancel or get user’s open orders
Check user’s balances and allowances
Post user’s signed orders

Even with L2 authentication headers, methods that create user orders still require the user to sign the order payload.

Getting API Credentials

Before making authenticated requests, you need to obtain API credentials using L1 authentication.

Using the SDK

TypeScript
Python

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

const client = new ClobClient(
  "https://clob.polymarket.com",
  137, // Polygon mainnet
  new Wallet(process.env.PRIVATE_KEY)
);

// Creates new credentials or derives existing ones
const credentials = await client.createOrDeriveApiKey();

console.log(credentials);
// {
//   apiKey: "550e8400-e29b-41d4-a716-446655440000",
//   secret: "base64EncodedSecretString",
//   passphrase: "randomPassphraseString"
// }

from py_clob_client.client import ClobClient
import os

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,  # Polygon mainnet
    key=os.getenv("PRIVATE_KEY")
)

# Creates new credentials or derives existing ones
credentials = client.create_or_derive_api_creds()

print(credentials)
# {
#     "apiKey": "550e8400-e29b-41d4-a716-446655440000",
#     "secret": "base64EncodedSecretString",
#     "passphrase": "randomPassphraseString"
# }

Never commit private keys to version control. Always use environment variables or secure key management systems.

Using the REST API

While we highly recommend using our provided clients to handle signing and authentication, the following is for developers who choose NOT to use our Python or TypeScript clients. Create API Credentials

POST https://clob.polymarket.com/auth/api-key

Derive API Credentials

GET https://clob.polymarket.com/auth/derive-api-key

Required L1 headers:

Header	Description
`POLY_ADDRESS`	Polygon signer address
`POLY_SIGNATURE`	CLOB EIP-712 signature
`POLY_TIMESTAMP`	Current UNIX timestamp
`POLY_NONCE`	Nonce (default: 0)

The POLY_SIGNATURE is generated by signing the following EIP-712 struct:

EIP-712 Signing Example

const domain = {
  name: "ClobAuthDomain",
  version: "1",
  chainId: chainId, // Polygon Chain ID 137
};

const types = {
  ClobAuth: [
    { name: "address", type: "address" },
    { name: "timestamp", type: "string" },
    { name: "nonce", type: "uint256" },
    { name: "message", type: "string" },
  ],
};

const value = {
  address: signingAddress, // The Signing address
  timestamp: ts,            // The CLOB API server timestamp
  nonce: nonce,             // The nonce used
  message: "This message attests that I control the given wallet",
};

const sig = await signer._signTypedData(domain, types, value);

Reference implementations:

Response:

{
  "apiKey": "550e8400-e29b-41d4-a716-446655440000",
  "secret": "base64EncodedSecretString",
  "passphrase": "randomPassphraseString"
}

You’ll need all three values for L2 authentication.

L2 Authentication Headers

All trading endpoints require these 5 headers:

Header	Description
`POLY_ADDRESS`	Polygon signer address
`POLY_SIGNATURE`	HMAC signature for request
`POLY_TIMESTAMP`	Current UNIX timestamp
`POLY_API_KEY`	User’s API `apiKey` value
`POLY_PASSPHRASE`	User’s API `passphrase` value

The POLY_SIGNATURE for L2 is an HMAC-SHA256 signature created using the user’s API credentials secret value. Reference implementations can be found in the TypeScript and Python clients.

CLOB Client

TypeScript
Python

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

const client = new ClobClient(
  "https://clob.polymarket.com",
  137,
  new Wallet(process.env.PRIVATE_KEY),
  apiCreds, // Generated from L1 auth, API credentials enable L2 methods
  1, // signatureType explained below
  funderAddress // funder explained below
);

// Now you can trade!
const order = await client.createAndPostOrder(
  { tokenID: "123456", price: 0.65, size: 100, side: "BUY" },
  { tickSize: "0.01", negRisk: false }
);

from py_clob_client.client import ClobClient
import os

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,
    key=os.getenv("PRIVATE_KEY"),
    creds=api_creds,  # Generated from L1 auth, API credentials enable L2 methods
    signature_type=1,  # signatureType explained below
    funder=os.getenv("FUNDER_ADDRESS") # funder explained below
)

# Now you can trade!
order = client.create_and_post_order(
    {"token_id": "123456", "price": 0.65, "size": 100, "side": "BUY"},
    {"tick_size": "0.01", "neg_risk": False}
)

Even with L2 authentication headers, methods that create user orders still require the user to sign the order payload.

Signature Types and Funder

When initializing the L2 client, you must specify your wallet signatureType and the funder address which holds the funds:

Signature Type	Value	Description
EOA	`0`	Standard Ethereum wallet (MetaMask). Funder is the EOA address and will need POL to pay gas on transactions.
POLY_PROXY	`1`	A custom proxy wallet only used with users who logged in via Magic Link email/Google. Using this requires the user to have exported their PK from Polymarket.com and imported into your app.
GNOSIS_SAFE	`2`	Gnosis Safe multisig proxy wallet (most common). Use this for any new or returning user who does not fit the other 2 types.

The wallet address displayed to the user on Polymarket.com is the proxy wallet and should be used as the funder. These can be deterministically derived or you can deploy them on behalf of the user. These proxy wallets are automatically deployed for the user on their first login to Polymarket.com.

Security Best Practices

Never expose private keys

Store private keys in environment variables or secure key management systems. Never commit them to version control.

# .env (never commit this file)
PRIVATE_KEY=0x...

Implement request signing on the server

Never expose your API secret in client-side code. All authenticated requests should originate from your backend.

Troubleshooting

Error - INVALID_SIGNATURE

Your wallet’s private key is incorrect or improperly formatted.Solutions:

Verify your private key is a valid hex string (starts with “0x”)
Ensure you’re using the correct key for the intended address
Check that the key has proper permissions

Error - NONCE_ALREADY_USED

The nonce you provided has already been used to create an API key.Solutions:

Use deriveApiKey() with the same nonce to retrieve existing credentials
Or use a different nonce with createApiKey()

Error - Invalid Funder Address

Your funder address is incorrect or doesn’t match your wallet.Solution: Check your Polymarket profile address at polymarket.com/settings.If it does not exist or user has never logged into Polymarket.com, deploy it first before creating L2 authentication.

Lost both credentials and nonce

Unfortunately, there’s no way to recover lost API credentials without the nonce. You’ll need to create new credentials:

// Create fresh credentials with a new nonce
const newCreds = await client.createApiKey();
// Save the nonce this time!

Overview

Events

Markets

Orderbook & Pricing

Orders

Trades

CLOB Markets

Profile

Leaderboard

Builders

Search

Tags

Series

Comments

Sports

Bridge

WebSocket

Public vs Authenticated

Public (No Auth)

Authenticated (CLOB)

Two-Level Authentication Model

L1 Authentication

L2 Authentication

Getting API Credentials

Using the SDK

Using the REST API

L2 Authentication Headers

CLOB Client

Signature Types and Funder

Security Best Practices

Troubleshooting

Next Steps

Place Your First Order

Geographic Restrictions

Overview

Events

Markets

Orderbook & Pricing

Orders

Trades

CLOB Markets

Profile

Leaderboard

Builders

Search

Tags

Series

Comments

Sports

Bridge

WebSocket

​Public vs Authenticated

Public (No Auth)

Authenticated (CLOB)

​Two-Level Authentication Model

​L1 Authentication

​L2 Authentication

​Getting API Credentials

​Using the SDK

​Using the REST API

​L2 Authentication Headers

​CLOB Client

​Signature Types and Funder

​Security Best Practices

​Troubleshooting

​Next Steps

Place Your First Order

Geographic Restrictions

Public vs Authenticated

Two-Level Authentication Model

L1 Authentication

L2 Authentication

Getting API Credentials

Using the SDK

Using the REST API

L2 Authentication Headers

CLOB Client

Signature Types and Funder

Security Best Practices

Troubleshooting

Next Steps