Skip to main content
There are two levels of authentication to be considered when using Polymarket’s CLOB.
All signing can be handled directly by the client libraries.
This is information for advanced users who are NOT using our Python or Typescript Clients. Our provided clients handle signing and authentication for you.

​
L1: Private Key Authentication

The highest level of authentication is via an account’s Polygon private key.
The private key remains in control of a user’s funds and all trading is non-custodial.
The operator never has control over users’ funds. Private key authentication is required for:
  • Placing an order (for signing the order)
  • Creating or revoking API keys

​
L1 Header

HeaderRequired?Description
POLY_ADDRESSyesPolygon address
POLY_SIGNATUREyesCLOB EIP 712 signature
POLY_TIMESTAMPyesCurrent UNIX timestamp
POLY_NONCEyesNonce. Default 0
The POLY_SIGNATURE is generated by signing the following EIP-712 struct. Implementations exist in:

​
Signing Example

domain = {
    "name": "ClobAuthDomain",
    "version": "1",
    "chainId": chainId,  # Polygon Chain ID 137
}

types = {
    "ClobAuth": [
        {"name": "address", "type": "address"},
        {"name": "timestamp", "type": "string"},
        {"name": "nonce", "type": "uint256"},
        {"name": "message", "type": "string"},
    ]
}

value = {
    "address": signingAddress,  # The signing address
    "timestamp": ts,            # The CLOB API server timestamp
    "nonce": nonce,             # The nonce used
    "message": "This message attests that I control the given wallet",
}

sig = await signer._signTypedData(domain, types, value)

​
L2: API Key Authentication

The next level of authentication consists of the API key, secret, and passphrase.
These are used solely to authenticate API requests made to Polymarket’s CLOB, such as posting/canceling orders or retrieving an account’s orders and fills. When a user on-boards via: 
POST /auth/api-key
the server uses the signature as a seed to deterministically generate credentials.
An API credential includes:
  • key: UUID identifying the credentials
  • secret: Secret string used to generate HMACs (not sent with requests)
  • passphrase: Secret string sent with each request, used to encrypt/decrypt the secret (never stored)
All private endpoints require an API key signature (L2 Header).

​
L2 Header

HeaderRequired?Description
POLY_ADDRESSyesPolygon address
POLY_SIGNATUREyesHMAC signature for request
POLY_TIMESTAMPyesCurrent UNIX timestamp
POLY_API_KEYyesPolymarket API key
POLY_PASSPHRASEyesPolymarket API key passphrase

​
API Key Operations

​
Create API Key

This endpoint requires an L1 Header.
Create new API key credentials for a user. HTTP Request: 
POST {clob-endpoint}/auth/api-key

​
Derive API Key

This endpoint requires an L1 Header.
Derive an existing API key for an address and nonce. HTTP Request: 
GET {clob-endpoint}/auth/derive-api-key

​
Get API Keys

This endpoint requires an L2 Header.
Retrieve all API keys associated with a Polygon address. HTTP Request: 
GET {clob-endpoint}/auth/api-keys

​
Delete API Key

This endpoint requires an L2 Header.
Delete an API key used to authenticate a request. HTTP Request: 
DELETE {clob-endpoint}/auth/api-key

​
Access Status

Check the value of cert_required by signer address. HTTP Request: 
GET {clob-endpoint}/auth/access-status

​
Get Closed Only Mode Status

This endpoint requires an L2 Header.
Retrieve the closed-only mode flag status. HTTP Request: 
GET {clob-endpoint}/auth/ban-status/closed-only