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>

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
OrderBook	GET /book?token_id=...	Public	L2 book depth for one token
OrderBooks	POST /books	Public	Batch books
Price / Prices	GET /price, POST /prices	Public	Numeric and string prices normalize to SDK strings
Midpoint / Midpoints	GET /midpoint, POST /midpoints	Public	Best-effort midpoint
Spread	GET /spread	Public	Token spread
TickSize	GET /tick-size?token_id=... or GET /tick-size/{token_id}	Public	Includes minimum tick/order fields when upstream returns them
NegRisk	GET /neg-risk	Public	Selects regular vs neg-risk exchange domain
FeeRateBps	GET /fee-rate	Public	Accepts current base_fee and legacy fee_rate_bps response keys
LastTradePrice	GET /last-trade-price	Public	Last trade price
PricesHistory	GET /prices-history	Public	OHLCV/history query
Markets	GET /markets	Public	Cursor pagination
Market	GET /clob-markets/{condition_id}	Public	One CLOB market with compact V2 fields expanded into SDK DTOs
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 with owner override	L1 + ERC-1271 owner	Creates or derives L2 credentials owned by a deployed deposit/smart wallet
CreateAPIKeyForAddress	POST /auth/api-key with owner override	L1 + ERC-1271 owner	Creates L2 credentials owned by a deployed deposit/smart wallet
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 and deposit-wallet-owned L2 headers
UpdateBalanceAllowance	GET /balance-allowance/update	L2	Refreshes CLOB balance cache with deposit-wallet-owned L2 headers
CreateLimitOrder / CreateMarketOrder	POST /order	L2 + order signature	Signs V2 order locally, then posts with deposit-wallet-owned L2 headers
CreateBatchOrders	POST /orders	L2 + order signatures	Signs up to 15 V2 limit orders locally, then posts with deposit-wallet-owned 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, legacy upstream path
1	proxy	Parseable, legacy upstream path
2	safe, gnosis-safe	Parseable, legacy upstream path
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.
• getClobMarketInfo()-style consolidated V2 market parameters. Polygolem currently exposes tick size, neg-risk, and fee-rate lookups separately.

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