Skip to main content
API keys are required for authenticated operations like posting orders, viewing trades, and managing your account. This guide covers the complete lifecycle of API key management.

​
Authentication Levels

The CLOB uses two levels of authentication:
  • Level 1 (L1): Uses your wallet signature to prove ownership. Required for creating/deriving API keys.
  • Level 2 (L2): Uses API key credentials (key, secret, passphrase) for all trading operations.
Most operations require L2 authentication with API keys.

​
Creating API Keys

1

Initialize Client with Wallet

Start with just a wallet for L1 authentication:
import { ClobClient, Chain } from "@polymarket/clob-client";
import { ethers } from "ethers";

const wallet = new ethers.Wallet("your-private-key");
const host = "https://clob.polymarket.com";
const chainId = Chain.POLYGON; // 137

const clobClient = new ClobClient(host, chainId, wallet);
2

Create or Derive API Key

Use createOrDeriveApiKey() to get credentials:
// This will create a new key if none exists, or derive the existing one
const apiKeyCreds = await clobClient.createOrDeriveApiKey();

console.log("API Key:", apiKeyCreds.key);
console.log("Secret:", apiKeyCreds.secret);
console.log("Passphrase:", apiKeyCreds.passphrase);
Store these credentials securely! The secret and passphrase cannot be retrieved later.
3

Initialize Client with Credentials

Create a new client instance with your API credentials:
import { ApiKeyCreds } from "@polymarket/clob-client";

const creds: ApiKeyCreds = {
  key: "your-api-key",
  secret: "your-secret",
  passphrase: "your-passphrase",
};

const clobClient = new ClobClient(
  host,
  chainId,
  wallet,
  creds  // Add credentials for L2 auth
);

// Now you can use authenticated endpoints
const openOrders = await clobClient.getOpenOrders();

​
Create vs Derive

There are three methods for getting API keys:

​
createOrDeriveApiKey()

Recommended - Automatically creates a new key or derives the existing one: 
const creds = await clobClient.createOrDeriveApiKey();
This is the safest method because:
  • First attempts to create a new key
  • If a key already exists, derives it instead
  • Prevents accidental key duplication

​
createApiKey()

Creates a new API key. Fails if one already exists: 
try {
  const creds = await clobClient.createApiKey();
  console.log("New API key created:", creds);
} catch (error) {
  console.error("Key creation failed:", error);
  // Key might already exist - try deriving instead
}

​
deriveApiKey()

Retrieves credentials for an existing API key: 
const creds = await clobClient.deriveApiKey();
console.log("Derived existing key:", creds);
You can only have one active API key per wallet address. Use createOrDeriveApiKey() to handle both scenarios.

​
Signature Types

When initializing the client, specify your signature type based on how you’re signing: 
import { SignatureType } from "@polymarket/clob-client";

const signatureType = SignatureType.EOA; // or SignatureType.POLY_PROXY for email login

const clobClient = new ClobClient(
  host,
  chainId,
  wallet,
  creds,
  signatureType  // 0 for EOA, 1 for POLY_PROXY
);
  • SignatureType.EOA (0): For browser wallets (MetaMask, Coinbase Wallet, etc.)
  • SignatureType.POLY_PROXY (1): For Magic/email login

​
Listing API Keys

View all API keys associated with your account: 
const apiKeys = await clobClient.getApiKeys();

console.log("Your API keys:", apiKeys.apiKeys);
// Each key contains: { key, secret, passphrase }

​
Readonly API Keys

Readonly keys can only query data, not post orders. Useful for monitoring or analytics:

​
Creating Readonly Keys

// Create a readonly API key
const readonlyKey = await clobClient.createReadonlyApiKey();
console.log("Readonly API key:", readonlyKey.apiKey);

// List all readonly keys
const readonlyKeys = await clobClient.getReadonlyApiKeys();
console.log("All readonly keys:", readonlyKeys);

​
Using Readonly Keys

// Initialize client with readonly key (no secret or passphrase needed)
const readonlyClient = new ClobClient(host, chainId);

// Query open orders for any address
const openOrders = await readonlyClient.getOpenOrders({
  maker_address: "0x123...",
});

​
Validating Readonly Keys

const isValid = await clobClient.validateReadonlyApiKey(
  "0x123...",  // wallet address
  "readonly-api-key"
);

​
Deleting Readonly Keys

await clobClient.deleteReadonlyApiKey("readonly-api-key");

​
Deleting API Keys

Delete your main API key (requires L2 authentication): 
await clobClient.deleteApiKey();
console.log("API key deleted");
Deleting your API key invalidates all current sessions. You’ll need to create or derive a new key to continue trading.

​
Builder API Keys

Builder keys are for advanced integrations and order aggregation: 
// Create a builder API key
const builderKey = await clobClient.createBuilderApiKey();
console.log("Builder key:", builderKey);
// Returns: { key, secret, passphrase }

// List builder keys
const builderKeys = await clobClient.getBuilderApiKeys();
console.log("Builder keys:", builderKeys);

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

​
Environment Variables

Store credentials securely using environment variables: 
# .env file
PRIVATE_KEY=0x...
CLOB_API_KEY=your-api-key
CLOB_SECRET=your-secret
CLOB_PASS_PHRASE=your-passphrase
CHAIN_ID=137
CLOB_API_URL=https://clob.polymarket.com

import { config } from "dotenv";
config();

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!);
const creds: ApiKeyCreds = {
  key: process.env.CLOB_API_KEY!,
  secret: process.env.CLOB_SECRET!,
  passphrase: process.env.CLOB_PASS_PHRASE!,
};

const clobClient = new ClobClient(
  process.env.CLOB_API_URL!,
  parseInt(process.env.CHAIN_ID!),
  wallet,
  creds
);

​
Best Practices

Use createOrDeriveApiKey()

Always use createOrDeriveApiKey() instead of createApiKey() to avoid errors when a key already exists.

Store Credentials Securely

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

Use Readonly Keys for Analytics

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

Rotate Keys Regularly

Delete and recreate API keys periodically, especially if they may have been compromised.

​
Troubleshooting

You need to provide a signer (wallet) to the client:
const wallet = new ethers.Wallet("your-private-key");
const client = new ClobClient(host, chainId, wallet);
You need to provide API credentials:
const creds: ApiKeyCreds = {
  key: "your-key",
  secret: "your-secret",
  passphrase: "your-passphrase",
};
const client = new ClobClient(host, chainId, wallet, creds);
Use deriveApiKey() or createOrDeriveApiKey() instead of createApiKey():
const creds = await clobClient.createOrDeriveApiKey();
Ensure you’re using the correct signature type:
  • Browser wallets: SignatureType.EOA (0)
  • Magic/email login: SignatureType.POLY_PROXY (1)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us