Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deniszidbaev-cmyk/polyclaw-cmyk/llms.txt

Use this file to discover all available pages before exploring further.

This page walks you through the complete PolyClaw onboarding flow: installing the skill, gathering the three keys you need, wiring them into your configuration, running the one-time contract approval step, and placing your first Polymarket trade. The whole process takes under ten minutes if you already have an EVM wallet.
1

Install PolyClaw

PolyClaw is distributed via ClawHub and managed with uv. Make sure uv is available on your system before proceeding.
brew install uv
Option A — ClawHub install (recommended)
clawhub install polyclaw
cd ~/.openclaw/skills/polyclaw
uv sync
Option B — Manual install
cp -r polyclaw ~/.openclaw/skills/
cd ~/.openclaw/skills/polyclaw
uv sync
uv sync resolves and installs all Python dependencies declared in pyproject.toml (including web3, py-clob-client-v2, rich, and python-dotenv) into an isolated virtual environment.
2

Get Your Three Required Keys

PolyClaw needs three credentials to function. Collect them all before moving on.Chainstack Polygon node (required for trading)PolyClaw sends all on-chain transactions through a dedicated Polygon mainnet RPC node.
  1. Sign up at console.chainstack.com — free tier available, sign up with GitHub, X, or Google.
  2. Create a new project and deploy a Polygon mainnet node.
  3. Copy the HTTPS endpoint URL (format: https://polygon-mainnet.core.chainstack.com/YOUR_KEY).
OpenRouter API key (required for hedge commands)Hedge discovery sends market pairs to an LLM for logical-implication analysis via OpenRouter.
  1. Create a key at openrouter.ai/settings/keys.
  2. A free tier is available; no credit card required to start.
EVM wallet private key (required for trading)PolyClaw signs all on-chain transactions with an EVM private key.
  • Use a dedicated wallet — do not reuse a wallet that holds significant funds.
  • Export the private key in hex format (with or without the 0x prefix).
  • Fund it with a small amount of POL (for gas) and pUSD (for collateral).
Keep only small amounts in this wallet at all times. The private key is stored as an environment variable for automation convenience — withdraw profits regularly to a separate, secure wallet.
3

Configure Environment Variables

PolyClaw is configured entirely through environment variables. Choose the approach that matches how you are running it.OpenClaw users — openclaw.jsonAdd the following block under skills.entries in your openclaw.json:
"polyclaw": {
  "enabled": true,
  "env": {
    "CHAINSTACK_NODE": "https://polygon-mainnet.core.chainstack.com/YOUR_KEY",
    "POLYCLAW_PRIVATE_KEY": "0x...",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}
Standalone users — export directly
export CHAINSTACK_NODE="https://polygon-mainnet.core.chainstack.com/YOUR_KEY"
export POLYCLAW_PRIVATE_KEY="0x..."
export OPENROUTER_API_KEY="sk-or-v1-..."
Alternatively, create a .env file in the skill root directory (~/.openclaw/skills/polyclaw/.env). PolyClaw loads it automatically via python-dotenv on every invocation.
See the Configuration page for the full list of optional variables, including proxy settings (HTTPS_PROXY, CLOB_MAX_RETRIES) and the optional POLY_BUILDER_CODE for order attribution.
4

Set Contract Approvals (One-Time)

Before your first trade, you must authorize Polymarket’s smart contracts to move tokens on your behalf. This is a one-time step per wallet.
uv run python scripts/polyclaw.py wallet approve
This submits 6 approval transactions to Polygon mainnet contracts (CTF, CTF Exchange V2, Neg Risk CTF Exchange V2, and related contracts). Each transaction costs a small amount of POL in gas — the total is roughly ~0.01 POL.
You only need to run wallet approve once per wallet address. If you switch to a new private key, run it again for that wallet.
5

Browse Markets and Place Your First Trade

With approvals set, you are ready to trade. The typical flow looks like this:1. Check your wallet balances
uv run python scripts/polyclaw.py wallet status
Displays your wallet address, POL balance (for gas), pUSD balance (trading collateral), and USDC.e balance. Trades require pUSD — if you only have USDC.e, wrap it 1:1 via the Collateral Onramp.2. Discover trending markets
uv run python scripts/polyclaw.py markets trending
Returns the top markets by 24-hour volume, including market IDs, questions, current YES/NO prices, and volume figures.3. Buy a position
uv run python scripts/polyclaw.py buy <market_id> YES 25
Replace <market_id> with the ID from the trending output above. This command:
  • Splits $25 pUSD into 25 YES + 25 NO tokens via the CTF contract
  • Sells the 25 NO tokens on the CLOB order book at the current market price
  • Records the resulting YES position locally with entry price and token count
4. Check your positions
uv run python scripts/polyclaw.py positions
Lists all open positions with entry price, current market price, and live P&L.Full example flow
uv run python scripts/polyclaw.py wallet status
uv run python scripts/polyclaw.py markets trending
uv run python scripts/polyclaw.py buy <market_id> YES 25
uv run python scripts/polyclaw.py positions

​
What’s Next

Configuration

Full reference for all environment variables, including proxy settings and optional builder code attribution.

Browse Markets

Detailed reference for markets trending, markets search, and market <id> commands.

Trading Reference

Full reference for the buy command, split + CLOB execution flow, and the --skip-sell flag.

Trading Flow Concepts

Understand how the split mechanism and CLOB order book work together to produce a directional position.

Hedge Discovery

Use hedge scan and hedge analyze to find LLM-validated covering portfolio opportunities.

Troubleshooting

Solutions for common issues: Cloudflare CLOB blocks, insufficient pUSD, approval errors, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us