Polymarket Setup Guide

Enables your agent to read markets, place bets, cancel orders, and check positions on Polymarket prediction markets.

Overview

Polymarket uses the CLOB (Central Limit Order Book) API on Polygon (chain ID 137). Trading requires two layers of authentication: CLOB API credentials (api_key, api_secret, passphrase) for HTTP request signing, and a wallet private key for EIP-712 order signing. The CLOB credentials are deterministically derived from your wallet — you generate them once using the CLOB API.

Prerequisites

• An Ethereum wallet with a private key (MetaMask, Rabby, or any standard wallet)
• Funds deposited on Polymarket (USDC on Polygon)
• A non-geo-blocked IP address — the CLOB API blocks requests from the US, UK, and certain other jurisdictions. You must use a VPN (Switzerland and Japan are known to work) when deriving credentials.
• Python environment with py-clob-client (included in the enclave's Poetry dependencies)

Step 1: Determine Your Signature Type

How you signed up for Polymarket determines your signature_type:

If you're unsure, check the Polymarket UI under Settings > Wallet. If you see a "Proxy Wallet" address that differs from your main wallet, you're type 1 or 2.

Step 2: Derive CLOB API Credentials

The api_key, api_secret, and passphrase are derived from your wallet's private key using the CLOB API. This must be done from a non-restricted IP.

Using the helper script

# Connect to a VPN in a non-restricted region first (e.g., Switzerland, Japan)

cd apps/enclave
poetry run python ../../scripts/derive_polymarket_creds.py

The script will prompt for your private key (input is hidden) and output:

=== Your Polymarket API Credentials ===
API Key:    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API Secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Passphrase: xxxxxxxxxxxxxxxx

Manual derivation (if you prefer)

from py_clob_client.client import ClobClient

client = ClobClient("https://clob.polymarket.com", key="0xYOUR_PRIVATE_KEY", chain_id=137)
creds = client.create_or_derive_api_creds()

print(f"API Key:    {creds.api_key}")
print(f"API Secret: {creds.api_secret}")
print(f"Passphrase: {creds.api_passphrase}")

Finding your proxy wallet address (types 1 and 2 only)

1. Go to polymarket.com
2. Click your profile icon > Settings
3. Under Wallet, find the "Proxy Wallet" or "Trading Wallet" address
4. Copy this Ethereum address (0x...)

Step 3: Connect in Carapace

1. Go to Dashboard > Connections
2. Find Polymarket and click Connect
3. Fill in all fields:
   • API Key — from the derivation step
   • API Secret — from the derivation step
   • Passphrase — from the derivation step
   • Private Key — your EOA wallet private key (64 hex characters, with or without 0x prefix)
   • Signature Type — 0, 1, or 2 based on your signup method
   • Proxy Wallet Address — only if signature type is 1 or 2
4. Click Save Credentials

Credential Fields Reference

Gotchas

Geo-blocking: The CLOB API blocks requests from restricted jurisdictions (US, UK, and others). You must be connected to a VPN in a non-restricted region to derive credentials. Switzerland and Japan are known to work. After credentials are derived, the Carapace enclave handles geo-bypass at trade time via POLYMARKET_PROXY_URL if configured.

CLOB keys vs wallet key: The api_key, api_secret, and passphrase are CLOB-layer API keys used for HTTP request authentication. The private_key is your Ethereum wallet key used for EIP-712 order signing. These are completely separate — losing one doesn't compromise the other, but you need both to trade.

Deterministic derivation: CLOB credentials are derived deterministically from your private key. Running the derivation script multiple times with the same key will produce the same credentials. You cannot rotate CLOB keys without changing wallets.

Private key format: The private key should be 64 hex characters. The derivation script accepts it with or without the 0x prefix. In the dashboard, either format works.

Proxy wallet confusion: For signature types 1 and 2, the proxy_wallet_address is the Polymarket-created proxy contract, not your EOA address. The EOA address is derived from your private_key. The proxy address is what actually holds your Polymarket positions.

Troubleshooting

"Failed to derive credentials. Are you on a VPN?"

The CLOB API returned an error, likely due to geo-blocking. Verify your VPN is active and connected to a non-restricted region. Try Switzerland or Japan.

Orders rejected with signature error

Check that your signature_type matches how you signed up. If you used email signup, you need type 1 and must provide the proxy wallet address. Using type 0 with a proxy account will fail.

"Insufficient balance" but you have funds

Ensure your funds are on Polymarket (deposited through their UI), not just in your wallet on Polygon. Polymarket uses a separate contract balance.

See Also

• Polymarket CLOB API docs
• py-clob-client GitHub
• Helper script: scripts/derive_polymarket_creds.py