CLOB V2 API

Production CLOB V2 runs at https://clob.polymarket.com. The pre-cutover https://clob-v2.polymarket.com host is not the production target.

Polygolem wraps CLOB in internal/clob. The public Go SDK exposes market data and authenticated account/order DTOs through pkg/clob, read-only best-first order books through pkg/orderbook, and facade methods through pkg/universal.

Auth Boundaries

Boundary	Credentials	Used For
Public	None	Books, prices, spreads, market lists, price history
CLOB L1	EOA EIP-712 ClobAuth signature	Create or derive CLOB API credentials
CLOB L2	POLY_ADDRESS, POLY_API_KEY, POLY_PASSPHRASE, POLY_TIMESTAMP, POLY_SIGNATURE	Post orders, cancel orders, balances, user orders, trades
CLOB builder fee	L2-authenticated POST /auth/builder-api-key	V2 order builder bytes32 attribution
Relayer	RELAYER_API_KEY + RELAYER_API_KEY_ADDRESS, or legacy POLYMARKET_BUILDER_API_KEY / POLYMARKET_BUILDER_SECRET / POLYMARKET_BUILDER_PASSPHRASE	Deposit-wallet deploy and WALLET batches

Builder relayer credentials are not CLOB L2 credentials. CLOB V2 order attribution is the order’s builder bytes32 field, not POLY_BUILDER_* headers. Polygolem signs zero attribution by default and accepts a non-zero builder code through pkg/clob.Config.BuilderCode, pkg/universal.Config.BuilderCode, CLI --builder-code, or POLYMARKET_BUILDER_CODE.

Caution

Do not reuse builder relayer secrets as CLOB L2 secrets in your own integrations. Polygolem keeps these auth systems separate even when a command can derive and validate both during setup.

CLI Surface

Read-only commands:

polygolem orderbook get        --token-id <token-id>
polygolem orderbook price      --token-id <token-id>
polygolem orderbook midpoint   --token-id <token-id>
polygolem orderbook spread     --token-id <token-id>
polygolem orderbook tick-size  --token-id <token-id>
polygolem orderbook fee-rate   --token-id <token-id>
polygolem orderbook last-trade --token-id <token-id>

polygolem clob book <token-id>
polygolem clob tick-size <token-id>
polygolem clob price-history <token-id> --interval 1m
polygolem clob markets --cursor ""
polygolem clob market <condition-id>
polygolem clob market-by-token <token-id>

Authenticated commands:

polygolem clob create-api-key
polygolem clob create-api-key-for-address --owner <deposit-wallet>
polygolem clob create-builder-fee-key
polygolem clob list-builder-fee-keys
polygolem clob revoke-builder-fee-key --key <builder-code>
polygolem clob balance        --asset-type collateral
polygolem clob update-balance --asset-type collateral

polygolem clob orders
polygolem clob order          <order-id>
polygolem clob trades

polygolem clob cancel         <order-id>
polygolem clob cancel-orders  <order-id-1,order-id-2>
polygolem clob cancel-market  --market <condition-id>
polygolem clob cancel-market  --asset <token-id>
polygolem clob cancel-all

polygolem clob create-order \
  --token <token-id> --side buy --price 0.5 --size 10 \
  --builder-code "$POLYMARKET_BUILDER_CODE"

polygolem clob create-order \
  --token <token-id> --side buy --price 0.5 --size 10 \
  --post-only

polygolem clob batch-orders \
  --orders-file orders.json \
  --builder-code "$POLYMARKET_BUILDER_CODE"

polygolem clob market-order \
  --token <token-id> --side buy --amount 5 \
  --builder-code "$POLYMARKET_BUILDER_CODE"

polygolem clob heartbeat --id keepalive-1

cancel-market requires at least one filter in polygolem. Use cancel-all for the upstream “omit both filters” behavior.

REST Mapping

Polygolem method	REST path	Auth	Notes
Health	GET /	Public	Reachability check
ServerTime / CLOBServerTime	GET /time	Public	Server timestamp
Markets	GET /markets	Public	Cursor pagination
Market	GET /clob-markets/{condition_id}	Public	One CLOB market with compact V2 fields expanded into SDK DTOs
SimplifiedMarkets	GET /simplified-markets	Public	Cursor-paginated simplified market feed
SamplingMarkets	GET /sampling-markets	Public	Sampling market feed
SamplingSimplifiedMarkets	GET /sampling-simplified-markets	Public	Sampling simplified feed
OrderBook	GET /book?token_id=...	Public	L2 book depth for one token
OrderBooks	POST /books	Public	Batch books
MarketByToken / CLOBMarketByToken	GET /markets-by-token/{token_id}	Public	Resolves a CLOB token ID to condition ID plus paired token IDs
Price / Prices	GET /price, POST /prices	Public	Numeric and string prices normalize to SDK strings; V2-only, no /prices-post fallback
Midpoint / Midpoints	GET /midpoint, POST /midpoints	Public	Best-effort midpoint
Spread	GET /spread	Public	Token spread
TickSize	GET /tick-size?token_id=...	Public	Includes minimum tick/order fields when upstream returns them
NegRisk	GET /neg-risk?token_id=...	Public	Selects regular vs neg-risk exchange domain
FeeRateBps	GET /fee-rate?token_id=...	Public	Accepts current base_fee and compatible fee_rate_bps response keys
LastTradePrice	GET /last-trade-price	Public	Last trade price
LastTradesPrices	POST /last-trades-prices	Public	Batch last-trade prices
PricesHistory	GET /prices-history	Public	OHLCV/history query
OrderScoring	GET /orders/scoring?order_id=...	Public	Single order reward-scoring eligibility
OrdersScoring	POST /orders/scoring	Public	Batch order reward-scoring eligibility
RewardsConfig	GET /rewards/config	Public	Liquidity reward configuration
RawRewards	GET /rewards/raw?market=...	Public	Raw reward rows for a market
UserEarnings	GET /rewards/earnings?date=...	Public	User earnings rows for a date
TotalEarnings	GET /rewards/total-earnings?date=...	Public	Total earnings for a date
RewardPercentages	GET /rewards/percentages	Public	Reward percentage rows
UserRewardsByMarket	GET /rewards/markets	Public	Rewards grouped by market
RebatedFees	GET /rebates	Public	Maker rebate rows
CreateOrDeriveAPIKey	POST /auth/api-key, then GET /auth/derive-api-key fallback	L1	Returns EOA/bootstrap L2 { apiKey, secret, passphrase }
CreateOrDeriveAPIKeyForAddress / DeriveAPIKeyForAddress	POST /auth/api-key / GET /auth/derive-api-key using EOA-bound auth	L1	Source-compatible helpers; ownerAddress is ignored in the validated V2 path
CreateAPIKeyForAddress	POST /auth/api-key using EOA-bound auth	L1	Source-compatible helper; ownerAddress is ignored in the validated V2 path
CreateBuilderFeeKey	POST /auth/builder-api-key	L2	Mints a builder fee key for V2 order attribution
ListBuilderFeeKeys	GET /auth/builder-api-keys	L2	Lists existing builder fee keys
RevokeBuilderFeeKey	DELETE /auth/builder-api-key/{key}	L2	Deletes one builder fee key
BalanceAllowance	GET /balance-allowance	L2	Uses signature_type=3 with EOA-bound L2 headers
UpdateBalanceAllowance	GET /balance-allowance/update	L2	Refreshes CLOB balance cache with EOA-bound L2 headers
CreateLimitOrder / CreateMarketOrder	POST /order	L2 + order signature	Signs V2 order locally, then posts with EOA-bound L2 headers
CreateBatchOrders	POST /orders	L2 + order signatures	Signs up to 15 V2 limit orders locally, then posts with EOA-bound L2 headers
Heartbeat / AutoHeartbeat	POST /v1/heartbeats	L2	Keepalive support for open-order heartbeat workflows
Order	GET /order/{id}	L2	One authenticated order
ListOrders	GET /data/orders	L2	Open orders for the API key owner
ListTrades	GET /data/trades	L2	Authenticated trade history
CancelOrder	DELETE /order	L2	Body: { "orderID": "..." }
CancelOrders	DELETE /orders	L2	Body: { "orderIDs": ["..."] }, max 3000
CancelMarket	DELETE /cancel-market-orders	L2	Body can include market, asset_id
CancelAll	DELETE /cancel-all	L2	Cancels all open orders

V2 Signed Order Contract

Polygolem signs the CLOB V2 Order EIP-712 type under:

name:              Polymarket CTF Exchange
version:           2
chainId:           137
verifyingContract: 0xE111180000d2663C0091e4f400237545B87B996B

Neg-risk markets use 0xe2222d279d744050d28e00520010520000310F59 as the verifying contract.

The signed V2 struct is:

Order(
  uint256 salt,
  address maker,
  address signer,
  uint256 tokenId,
  uint256 makerAmount,
  uint256 takerAmount,
  uint8 side,
  uint8 signatureType,
  uint256 timestamp,
  bytes32 metadata,
  bytes32 builder
)

V2 removed taker, nonce, and feeRateBps from the signed struct. expiration is included in the posted order object but is not part of the signed struct in polygolem’s V2 signer.

The POST body shape is:

{
  "order": {
    "salt": 12345,
    "maker": "0xDepositWallet",
    "signer": "0xDepositWallet",
    "tokenId": "123...",
    "makerAmount": "5000000",
    "takerAmount": "10000000",
    "side": "BUY",
    "expiration": "0",
    "signatureType": 3,
    "timestamp": "1770000000000",
    "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "signature": "0x..."
  },
  "owner": "<clob-api-key>",
  "orderType": "GTC",
  "postOnly": false,
  "deferExec": false
}

For signatureType = 3 (POLY_1271), maker and signer are both the deposit wallet address in the V2 order payload. The owner EOA signs an ERC-7739 TypedDataSign wrapper that the deposit wallet validates through ERC-1271. Polygolem’s wrapped signature is 0x plus 634 hex chars:

innerSig(65) || appDomainSep(32) || contents(32) || contentsType(186) || uint16BE(186)

Signature Types

Type	CLI alias	Polygolem live status
0	eoa	Parseable only; not a supported live path for new V2 accounts
1	proxy	Parseable only; not a supported live path for new V2 accounts
2	safe, gnosis-safe	Parseable only; not a supported live path for new V2 accounts
3	deposit, deposit-wallet, poly-1271	Default and supported live path

New Polymarket API users should use deposit wallets. Polygolem defaults every live CLOB order and balance command to deposit.

Current Gaps

These upstream V2 capabilities are not yet exposed as stable polygolem SDK/CLI contracts:

• Authenticated user WebSocket stream. Authenticated REST account/order/trading DTOs are public through pkg/clob.
• Sell-side market orders in CreateMarketOrder; the current implementation supports buy-side budgeted market orders.
• Recent relayer transaction list and Bridge quote/status CLI commands are documented on their own reference pages because they belong to different Polymarket API hosts.

Related

• Go SDK Contracts — public package contracts
• Smart Contracts — CTF Exchange, pUSD, and wallet factory addresses
• Deposit Wallets & Signature Types — POLY_1271 flow
• Orderbook Data — public data walkthrough
• Upstream: Polymarket CLOB V2 migration
• Upstream: Polymarket order cancellation