Skip to main content

​
Client Initialization

L1 methods require the client to initialize with a signer. 
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers";

const signer = new Wallet(process.env.PRIVATE_KEY);

const client = new ClobClient(
  "https://clob.polymarket.com",
  137,
  signer // Signer required for L1 methods
);

// Ready to create user API credentials
const apiKey = await client.createApiKey();
Never commit private keys to version control. Always use environment variables or a secure key management system.

​
API Key Management

​
createApiKey

Creates a new API key (L2 credentials) for the wallet signer. Each wallet can only have one active API key at a time — creating a new key invalidates the previous one.
Signature
async createApiKey(nonce?: number): Promise<ApiKeyCreds>
​
nonce
number
Optional custom nonce for deterministic key generation. Optional.
​
apiKey
string
The generated API key string.
​
secret
string
The secret associated with the API key.
​
passphrase
string
The passphrase associated with the API key.

​
deriveApiKey

Derives an existing API key using a specific nonce. If you’ve already created credentials with a particular nonce, this returns the same credentials.
Signature
async deriveApiKey(nonce?: number): Promise<ApiKeyCreds>
​
nonce
number
The nonce used when originally creating the key. Optional.
​
apiKey
string
The derived API key string.
​
secret
string
The secret associated with the API key.
​
passphrase
string
The passphrase associated with the API key.

​
createOrDeriveApiKey

Convenience method that attempts to derive an API key with the default nonce, or creates a new one if it doesn’t exist. Recommended for initial setup.
Signature
async createOrDeriveApiKey(nonce?: number): Promise<ApiKeyCreds>
​
apiKey
string
The API key string, either derived or newly created.
​
secret
string
The secret associated with the API key.
​
passphrase
string
The passphrase associated with the API key.

​
Order Signing

​
createOrder

Create and sign a limit order locally without posting it to the CLOB. Use this when you want to sign orders in advance or implement custom submission logic. Submit via postOrder() or postOrders().
Signature
async createOrder(
  userOrder: UserOrder,
  options?: Partial<CreateOrderOptions>
): Promise<SignedOrder>
​
tokenID
string
The token ID of the market outcome to trade.
​
price
number
The limit price for the order.
​
size
number
The size (number of shares) for the order.
​
side
Side
The side of the order (buy or sell).
​
feeRateBps
number
Optional fee rate in basis points. Optional.
​
nonce
number
Optional nonce for the order. Optional.
​
expiration
number
Optional expiration timestamp for the order. Optional.
​
taker
string
Optional taker address for the order. Optional.
​
tickSize
TickSize
The tick size used for order validation (CreateOrderOptions).
​
negRisk
boolean
Optional flag for negative risk markets (CreateOrderOptions). Optional.
​
salt
string
A random salt value for the signed order.
​
maker
string
The maker’s address.
​
signer
string
The signer’s address.
​
taker
string
The taker’s address in the signed order.
​
tokenId
string
The token ID in the signed order.
​
makerAmount
string
The maker amount as a string.
​
takerAmount
string
The taker amount as a string.
​
side
number
The side of the order as a number (0 = BUY, 1 = SELL).
​
expiration
string
The expiration timestamp as a string.
​
nonce
string
The nonce as a string.
​
feeRateBps
string
The fee rate in basis points as a string.
​
signatureType
number
The type identifier for the signature scheme used.
​
signature
string
The cryptographic signature of the order.

​
createMarketOrder

Create and sign a market order locally without posting it to the CLOB. Submit via postOrder() or postOrders().
Signature
async createMarketOrder(
  userMarketOrder: UserMarketOrder,
  options?: Partial<CreateOrderOptions>
): Promise<SignedOrder>
​
tokenID
string
The token ID of the market outcome to trade.
​
amount
number
The order amount. For BUY orders this is a dollar amount; for SELL orders this is the number of shares.
​
side
Side
The side of the order (buy or sell).
​
price
number
Optional price limit for the market order. Optional.
​
feeRateBps
number
Optional fee rate in basis points. Optional.
​
nonce
number
Optional nonce for the order. Optional.
​
taker
string
Optional taker address for the order. Optional.
​
orderType
OrderType.FOK | OrderType.FAK
Optional order type, either FOK (Fill-Or-Kill) or FAK (Fill-And-Kill). Optional.
​
salt
string
A random salt value for the signed order.
​
maker
string
The maker’s address.
​
signer
string
The signer’s address.
​
taker
string
The taker’s address in the signed order.
​
tokenId
string
The token ID in the signed order.
​
makerAmount
string
The maker amount as a string.
​
takerAmount
string
The taker amount as a string.
​
side
number
The side of the order as a number (0 = BUY, 1 = SELL).
​
expiration
string
The expiration timestamp as a string.
​
nonce
string
The nonce as a string.
​
feeRateBps
string
The fee rate in basis points as a string.
​
signatureType
number
The type identifier for the signature scheme used.
​
signature
string
The cryptographic signature of the order.

​
Troubleshooting

Your wallet’s private key is incorrect or improperly formatted.Solution:
  • 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
The nonce you provided has already been used to create an API key.Solution:
  • Use deriveApiKey() with the same nonce to retrieve existing credentials
  • Or use a different nonce with createApiKey()
Your funder address is incorrect or doesn’t match your wallet.Solution: Check your proxy wallet address at polymarket.com/settings. If it doesn’t exist, the user has never logged in to Polymarket.com — deploy the proxy wallet first before creating L2 credentials.
// Use deriveApiKey with the original nonce
const recovered = await client.deriveApiKey(originalNonce);
There’s no way to recover lost credentials without the nonce. Create new ones:
// Create fresh credentials with a new nonce
const newCreds = await client.createApiKey();
// Save the nonce this time!

​
See Also

Authentication

Deep dive into L1 and L2 authentication.

Trading Quickstart

Initialize the client and place your first order.

Public Methods

Access market data, orderbooks, and prices without auth.

L2 Methods

Place and manage orders with API credentials.