Skip to main content

​
Client Initialization

L2 methods require the client to initialize with a signer, signature type, API credentials, and funder address. 
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers";

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

const apiCreds = {
  apiKey: process.env.API_KEY,
  secret: process.env.SECRET,
  passphrase: process.env.PASSPHRASE,
};

const client = new ClobClient(
  "https://clob.polymarket.com",
  137,
  signer,
  apiCreds,
  2, // GNOSIS_SAFE
  process.env.FUNDER_ADDRESS
);

// Ready to send authenticated requests
const order = await client.postOrder(signedOrder);

​
Order Creation and Management

​
createAndPostOrder

Convenience method that creates, signs, and posts a limit order in a single call. Use when you want to buy or sell at a specific price.
Signature
async createAndPostOrder(
  userOrder: UserOrder,
  options?: Partial<CreateOrderOptions>,
  orderType?: OrderType.GTC | OrderType.GTD, // Defaults to GTC
): Promise<OrderResponse>
Params
​
tokenID
string
The token ID of the outcome to trade.
​
price
number
The limit price for the order.
​
size
number
The size of the order.
​
side
Side
The side of the order (buy or sell).
​
feeRateBps
number
Optional fee rate in basis points.
​
nonce
number
Optional nonce for the order.
​
expiration
number
Optional expiration timestamp for the order.
​
taker
string
Optional taker address.
​
tickSize
TickSize
Tick size for the order. One of "0.1", "0.01", "0.001", "0.0001".
​
negRisk
boolean
Optional. Whether the market uses negative risk.
Response
​
success
boolean
Whether the order was successfully placed.
​
errorMsg
string
Error message if the order was not successful.
​
orderID
string
The ID of the placed order.
​
transactionsHashes
string[]
Array of transaction hashes associated with the order.
​
status
string
The current status of the order.
​
takingAmount
string
The amount being taken in the order.
​
makingAmount
string
The amount being made in the order.

​
createAndPostMarketOrder

Convenience method that creates, signs, and posts a market order in a single call. Use when you want to buy or sell at the current market price.
Signature
async createAndPostMarketOrder(
  userMarketOrder: UserMarketOrder,
  options?: Partial<CreateOrderOptions>,
  orderType?: OrderType.FOK | OrderType.FAK, // Defaults to FOK
): Promise<OrderResponse>
Params
​
tokenID
string
The token ID of the outcome to trade.
​
amount
number
The amount for the market order.
​
side
Side
The side of the order (buy or sell).
​
price
number
Optional price hint for the market order.
​
feeRateBps
number
Optional fee rate in basis points.
​
nonce
number
Optional nonce for the order.
​
taker
string
Optional taker address.
​
orderType
OrderType.FOK | OrderType.FAK
Optional order type override. Defaults to FOK.
Response
​
success
boolean
Whether the order was successfully placed.
​
errorMsg
string
Error message if the order was not successful.
​
orderID
string
The ID of the placed order.
​
transactionsHashes
string[]
Array of transaction hashes associated with the order.
​
status
string
The current status of the order.
​
takingAmount
string
The amount being taken in the order.
​
makingAmount
string
The amount being made in the order.

​
postOrder

Posts a pre-signed order to the CLOB. Use with createOrder() or createMarketOrder() from L1 methods.
Signature
async postOrder(
  order: SignedOrder,
  orderType?: OrderType, // Defaults to GTC
  postOnly?: boolean,    // Defaults to false
): Promise<OrderResponse>

​
postOrders

Posts up to 15 pre-signed orders in a single batch.
Signature
async postOrders(
  args: PostOrdersArgs[],
): Promise<OrderResponse[]>
Params
​
order
SignedOrder
The pre-signed order to post.
​
orderType
OrderType
The order type (e.g. GTC, FOK, FAK).
​
postOnly
boolean
Optional. Whether to post the order as post-only. Defaults to false.

​
cancelOrder

Cancels a single open order.
Signature
async cancelOrder(orderID: string): Promise<CancelOrdersResponse>
Response
​
canceled
string[]
Array of order IDs that were successfully canceled.
​
not_canceled
Record<string, any>
Map of order IDs to reasons why they could not be canceled.

​
cancelOrders

Cancels multiple orders in a single batch.
Signature
async cancelOrders(orderIDs: string[]): Promise<CancelOrdersResponse>

​
cancelAll

Cancels all open orders.
Signature
async cancelAll(): Promise<CancelOrdersResponse>

​
cancelMarketOrders

Cancels all open orders for a specific market.
Signature
async cancelMarketOrders(
  payload: OrderMarketCancelParams
): Promise<CancelOrdersResponse>
Params
​
market
string
Optional. The market condition ID to cancel orders for.
​
asset_id
string
Optional. The token ID to cancel orders for.

​
Order and Trade Queries

​
getOrder

Get details for a specific order by ID.
Signature
async getOrder(orderID: string): Promise<OpenOrder>
Response
​
id
string
The unique order ID.
​
status
string
The current status of the order.
​
owner
string
The API key of the order owner.
​
maker_address
string
The on-chain address of the order maker.
​
market
string
The market condition ID the order belongs to.
​
asset_id
string
The token ID the order is for.
​
side
string
The side of the order (BUY or SELL).
​
original_size
string
The original size of the order when it was placed.
​
size_matched
string
The amount of the order that has been matched so far.
​
price
string
The limit price of the order.
​
associate_trades
string[]
Array of trade IDs associated with this order.
​
outcome
string
The outcome label for the order’s token.
​
created_at
number
Unix timestamp of when the order was created.
​
expiration
string
The expiration time of the order.
​
order_type
string
The order type (e.g. GTC, FOK, FAK, GTD).

​
getOpenOrders

Get all your open orders.
Signature
async getOpenOrders(
  params?: OpenOrderParams,
  only_first_page?: boolean,
): Promise<OpenOrder[]>
Params
​
id
string
Optional. Filter by order ID.
​
market
string
Optional. Filter by market condition ID.
​
asset_id
string
Optional. Filter by token ID.

​
getTrades

Get your trade history (filled orders).
Signature
async getTrades(
  params?: TradeParams,
  only_first_page?: boolean,
): Promise<Trade[]>
Params
​
id
string
Optional. Filter by trade ID.
​
maker_address
string
Optional. Filter by maker address.
​
market
string
Optional. Filter by market condition ID.
​
asset_id
string
Optional. Filter by token ID.
​
before
string
Optional. Return trades before this timestamp.
​
after
string
Optional. Return trades after this timestamp.
Response
​
id
string
The unique trade ID.
​
taker_order_id
string
The order ID of the taker side.
​
market
string
The market condition ID for the trade.
​
asset_id
string
The token ID for the trade.
​
side
Side
The side of the trade (BUY or SELL).
​
size
string
The size of the trade.
​
fee_rate_bps
string
The fee rate in basis points.
​
price
string
The price at which the trade was matched.
​
status
string
The current status of the trade.
​
match_time
string
The time at which the trade was matched.
​
last_update
string
The time of the last update to this trade.
​
outcome
string
The outcome label for the traded token.
​
bucket_index
number
The bucket index for the trade.
​
owner
string
The API key of the trade owner.
​
maker_address
string
The on-chain address of the maker.
​
maker_orders
MakerOrder[]
Array of maker order objects that participated in this trade. Each MakerOrder contains the following fields:
​
maker_orders[].order_id
string
The maker order ID.
​
maker_orders[].owner
string
The API key of the maker order owner.
​
maker_orders[].maker_address
string
The on-chain address of the maker order maker.
​
maker_orders[].matched_amount
string
The amount matched for this maker order.
​
maker_orders[].price
string
The price of the maker order.
​
maker_orders[].fee_rate_bps
string
The fee rate in basis points for the maker order.
​
maker_orders[].asset_id
string
The token ID for the maker order.
​
maker_orders[].outcome
string
The outcome label for the maker order’s token.
​
maker_orders[].side
Side
The side of the maker order (BUY or SELL).
​
transaction_hash
string
The on-chain transaction hash for the trade.
​
trader_side
"TAKER" | "MAKER"
Whether the authenticated user is the taker or a maker in this trade.

​
getTradesPaginated

Get trade history with pagination for large result sets.
Signature
async getTradesPaginated(
  params?: TradeParams,
): Promise<TradesPaginatedResponse>
Response
​
trades
Trade[]
Array of trade objects for the current page.
​
limit
number
The maximum number of trades returned per page.
​
count
number
The total number of trades matching the query.

​
Balance and Allowances

​
getBalanceAllowance

Get your balance and allowance for specific tokens.
Signature
async getBalanceAllowance(
  params?: BalanceAllowanceParams
): Promise<BalanceAllowanceResponse>
Params
​
asset_type
AssetType
The type of asset to query. One of "COLLATERAL" or "CONDITIONAL".
​
token_id
string
Optional. The token ID to query (required when asset_type is CONDITIONAL).
Response
​
balance
string
The current balance for the specified asset.
​
allowance
string
The current allowance for the specified asset.

​
updateBalanceAllowance

Updates the cached balance and allowance for specific tokens.
Signature
async updateBalanceAllowance(
  params?: BalanceAllowanceParams
): Promise<void>

​
API Key Management

​
getApiKeys

Get all API keys associated with your account.
Signature
async getApiKeys(): Promise<ApiKeysResponse>
Response
​
apiKeys
ApiKeyCreds[]
Array of API key credential objects associated with the account.

​
deleteApiKey

Deletes (revokes) the currently authenticated API key.
Signature
async deleteApiKey(): Promise<any>

​
Notifications

​
getNotifications

Retrieves all event notifications for the authenticated user. Records are automatically removed after 48 hours.
Signature
async getNotifications(): Promise<Notification[]>
Response
​
id
number
Unique notification ID.
​
owner
string
The user’s API key, or an empty string for global notifications.
​
payload
any
Type-specific payload data for the notification.
​
timestamp
number
Optional Unix timestamp of when the notification was created.
​
type
number
Notification type (see below).
NameValueDescription
Order Cancellation1User’s order was canceled
Order Fill2User’s order was filled (maker or taker)
Market Resolved4Market was resolved

​
dropNotifications

Mark notifications as read/dismissed.
Signature
async dropNotifications(params?: DropNotificationParams): Promise<void>
Params
​
ids
string[]
Array of notification IDs to dismiss.

​
See Also

Authentication

Deep dive into L1 and L2 authentication.

L1 Methods

Sign orders and derive API credentials with your private key.

Public Methods

Read market data and orderbooks without auth.

WebSocket

Real-time market data streaming.