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
| `POLY_ADDRESS` | yes | Polygon address |
| `POLY_SIGNATURE` | yes | CLOB EIP 712 signature |
| `POLY_TIMESTAMP` | yes | Current UNIX timestamp |
| `POLY_NONCE` | yes | Nonce. Default 0 |
The `POLY_SIGNATURE` is generated by signing the following EIP-712 struct.
Implementations exist in:
* Typescript
* Python
### Signing Example
```python
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
Header Required? Description
POLY_ADDRESS yes Polygon address
POLY_SIGNATURE yes HMAC signature for request
POLY_TIMESTAMP yes Current UNIX timestamp
POLY_API_KEY yes Polymarket API key
POLY_PASSPHRASE yes Polymarket 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