Authentication

The CLOB API uses two authentication levels: L1 (wallet signature) and L2 (API credentials).

Public vs Authenticated

Public (No Auth)

Market discovery, order book snapshots, prices, spreads, and most analytics endpoints are public.

Authenticated (CLOB)

Trading and account-management endpoints require all L2 `KUEST_*` headers.

Two-Level Authentication Model

L1 Authentication

L1 uses an EIP-712 wallet signature to prove ownership of the Polygon address.

Use L1 to:

create API credentials
derive existing API credentials
bootstrap authenticated trading sessions

L2 Authentication

L2 uses API credentials (apiKey, secret, passphrase) generated from L1. Requests are authenticated with HMAC-SHA256 signatures.

Use L2 to:

list and revoke API keys
place/cancel orders
call private account/trading routes

Even with L2 headers, order placement still requires the order payload to be signed client-side before submission.

Getting API Credentials

Using SDKs

Use the official SDKs whenever possible:

Using the REST API

POST {CLOB_URL}/auth/api-key
GET  {CLOB_URL}/auth/derive-api-key

Required L1 headers:

Header	Description
`KUEST_ADDRESS`	Polygon signer address
`KUEST_SIGNATURE`	EIP-712 signature over auth payload
`KUEST_TIMESTAMP`	Current UNIX timestamp (seconds)
`KUEST_NONCE`	Nonce (commonly `0`)

Optional L1 header:

Header	Description
`KUEST_REFERRAL`	Referral identifier for attribution

EIP-712 payload shape:

{
  "domain": {
    "name": "ClobAuthDomain",
    "version": "1",
    "chainId": 137
  },
  "types": {
    "ClobAuth": [
      { "name": "address", "type": "address" },
      { "name": "timestamp", "type": "string" },
      { "name": "nonce", "type": "uint256" },
      { "name": "message", "type": "string" }
    ]
  },
  "message": {
    "address": "<signing address>",
    "timestamp": "<unix timestamp>",
    "nonce": "<nonce>",
    "message": "This message attests that I control the given wallet"
  }
}

Credential response:

{
  "apiKey": "550e8400-e29b-41d4-a716-446655440000",
  "secret": "<generated-secret>",
  "passphrase": "<generated-passphrase>"
}

Store secret and passphrase securely. They are not recoverable later.

L2 Authentication Headers

All authenticated trading/account routes require these 5 headers:

Header	Description
`KUEST_ADDRESS`	Polygon signer address
`KUEST_SIGNATURE`	HMAC signature for the request
`KUEST_TIMESTAMP`	Current UNIX timestamp (seconds)
`KUEST_API_KEY`	API key UUID
`KUEST_PASSPHRASE`	Passphrase paired with the API key

For timestamp drift protection, sync with Get Server Time before signing.

Public (No Auth)

Authenticated (CLOB)

On this page