Polymarket API Keys Explained: Reads, Trading and Auth

Do you need a Polymarket API key?

It depends on the operation. "Polymarket API key" can refer to several unrelated credentials, which is why this question often produces contradictory answers.

The current Polymarket API overview separates Gamma, CLOB, Data, Relayer and WebSocket services. Authentication is specific to the service and action. There is no single universal key that automatically authorizes all of them.

Which Polymarket reads are public?

The following examples send no key or signature:

# Discover active markets through Gamma
curl -s \
  "https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=5"

# Read one CLOB order book
curl -s \
  "https://clob.polymarket.com/book?token_id=TOKEN_ID"

# Read public wallet positions through Data API v2
curl -s \
  "https://data-api.polymarket.com/v2/positions?user=ACCOUNT_WALLET&limit=20"

# Read public wallet activity
curl -s \
  "https://data-api.polymarket.com/v2/activity?user=ACCOUNT_WALLET&limit=20"

Public does not mean unlimited or suitable for every jurisdiction. Rate limits, availability rules and geographic restrictions still apply. It also does not mean that private account state, order placement or order management is keyless. The read limits are fixed per endpoint, while order and cancel budgets move with volume, which is covered in how to increase your Polymarket rate limit.

What is Polymarket L1 authentication?

L1 authentication is a signed EIP-712 message proving control of the signer address. The current Polymarket flow signs a ClobAuth message containing the signer address, timestamp, nonce and an attestation message.

{
  "domain": {
    "name": "ClobAuthDomain",
    "version": "1",
    "chainId": 137
  },
  "primaryType": "ClobAuth",
  "message": {
    "address": "0xSIGNER",
    "timestamp": "UNIX_SECONDS",
    "nonce": "0",
    "message": "This message attests that I control the given wallet"
  }
}

The private key signs this typed data locally. The private key itself must never be sent to Polymarket, Predictefy or an application server that does not need custody. The resulting L1 signature is then used to create or derive L2 credentials.

What are Polymarket L2 credentials?

L2 credentials are a three-part CLOB credential set:

• apiKey
• secret
• passphrase

They are created or deterministically derived by presenting the L1 proof to the CLOB authentication endpoints:

# Create a credential set
curl -X POST "https://clob.polymarket.com/auth/api-key" \
  -H "POLY_ADDRESS: 0xSIGNER" \
  -H "POLY_SIGNATURE: L1_SIGNATURE" \
  -H "POLY_TIMESTAMP: UNIX_SECONDS" \
  -H "POLY_NONCE: NONCE"

# Derive the existing credential set
curl "https://clob.polymarket.com/auth/derive-api-key" \
  -H "POLY_ADDRESS: 0xSIGNER" \
  -H "POLY_SIGNATURE: L1_SIGNATURE" \
  -H "POLY_TIMESTAMP: UNIX_SECONDS" \
  -H "POLY_NONCE: NONCE"

The L2 triple authenticates private CLOB requests, including order operations. An order still carries the appropriate wallet signature. API authentication and order signing solve different problems: the former authenticates the request, while the latter authorizes the order.

Polymarket's current wallet and authentication guide documents both steps and distinguishes the signer from the account wallet that holds funds and positions.

What are Relayer API keys?

A Relayer key authorizes gasless wallet operations for an existing Polymarket account. The current account-connection flow asks for the account wallet, its signer and a Relayer API key. It is used for supported wallet actions such as approvals, transfers and position-management transactions through the Relayer.

A Relayer key is not the same as the CLOB L2 credential triple. Do not insert it into POLY_API_KEY or POLY_PASSPHRASE headers and expect order authentication to work. The L2 secret is never sent as a header at all: it is the HMAC key used to compute POLY_SIGNATURE.

What are Builder API keys?

Builder credentials identify an application participating in Polymarket's builder workflow. The current documentation describes a Builder API key, secret and passphrase used server-side for tasks such as creating Deposit Wallets and signing supported Relayer requests for users.

Builder credentials belong on a trusted server. Polymarket explicitly warns not to expose or share them. They do not replace each user's signer and they do not transfer control of a user's Deposit Wallet to the builder.

How is a Predictefy API key different?

A Predictefy key authenticates requests to Predictefy, not requests sent directly to Polymarket.

Authorization: Bearer pk_live_YOUR_KEY

Every Predictefy data and execution route requires a key, with the open health and status endpoints the exception. Anonymous requests return 401 UNAUTHORIZED. Create one at the Predictefy developer portal. Copy the raw value when it appears. Only a hash authenticates requests, and the console keeps an encrypted copy so the API keys page can reveal the full key again. Store it in a secret manager or server environment variable and never put it in a URL.

curl -s \
  "https://data.predictefy.com/api/polymarket/fetchMarkets?query=election&limit=5" \
  -H "Authorization: Bearer $PREDICTEFY_API_KEY"

The Predictefy OpenAPI contract assigns read scope to catalog, books, trades, Trader Intelligence and account reads. Execution operations under /v1/exec require trade scope. A key can therefore authenticate the platform request without granting a remote service possession of the user's wallet private key.

Does the Predictefy key let you trade on Polymarket?

Not by itself. Predictefy and Polymarket credentials authorize different layers.

1. The Predictefy key authenticates the build or submit request to Predictefy and must have the required scope.
2. Predictefy builds a bounded, venue-shaped order artifact.
3. The caller inspects and signs that artifact in its own process.
4. Polymarket L2 credentials authenticate the private CLOB submission where that path requires them.
5. The caller confirms the resulting order state rather than treating an accepted relay as a guaranteed fill.

The current Predictefy order guide states the boundary plainly: Predictefy builds and relays, while the caller signs. There is no generic hosted signing endpoint and Predictefy does not hold the user's private key.

What happens to Polymarket credentials during Predictefy execution?

Predictefy supports caller-direct and hosted relay patterns. The caller-direct SDK path keeps the wallet and CLOB credential triple in the caller's process and submits directly to the CLOB. The hosted submit path can accept the caller's L2 key, secret and passphrase for the one authenticated relay request. The official contract says these values are consumed in-process and are not persisted in the submitted artifact.

That boundary reduces custody, but it does not make secret handling optional. Use TLS, redact request bodies and error traces, avoid analytics capture on execution routes and rotate credentials after suspected exposure.

TypeScript: configure public Polymarket reads and Predictefy reads

import Predictefy from '@predictefy/sdk';

// Public Polymarket read. No Polymarket key is sent.
const gammaResponse = await fetch(
  'https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=5',
);
if (!gammaResponse.ok) {
  throw new Error('Gamma returned ' + gammaResponse.status);
}
const gammaMarkets = await gammaResponse.json();

// Predictefy read. The Predictefy key is required.
const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
});

const normalizedMarkets = await client.polymarket.fetchMarkets({
  status: 'active',
  limit: 5,
});

console.log({
  gammaCount: gammaMarkets.length,
  normalizedCount: normalizedMarkets.length,
});

The browser can call a public Polymarket read, subject to the service's CORS and rate-limit behavior. The Predictefy bearer key should remain on a trusted server. Do not embed it into client JavaScript, a mobile bundle or a public repository.

Python: load the Predictefy key safely

import os

from predictefy import Predictefy

api_key = os.environ["PREDICTEFY_API_KEY"]

with Predictefy(api_key=api_key) as client:
    markets = client.polymarket.fetch_markets({
        "status": "active",
        "limit": 5,
    })

    for market in markets:
        print(market["title"])

Keep separate environment variables for separate authorities. Names such as PREDICTEFY_API_KEY, POLYMARKET_CLOB_API_KEY, POLYMARKET_CLOB_SECRET and POLYMARKET_CLOB_PASSPHRASE make accidental credential substitution less likely.

What are the most common authentication mistakes?

How should keys be stored and rotated?

• Store secrets in a managed secret store or protected server environment.
• Use separate development and production credentials.
• Restrict scopes and origins where the provider supports it.
• Never commit .env files, private keys or credential exports.
• Redact headers and bodies from logs, error monitoring and support screenshots.
• Rotate credentials immediately after accidental disclosure.
• Revoke credentials that are no longer used.

The safest architecture minimizes how many components can read each secret. Public data collectors need no Polymarket trading credentials. A discovery service using Predictefy needs only its read-scoped platform key. The signing component should be isolated from ordinary web and analytics services.

Frequently Asked Questions