⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

polyclaw

chainstacklabs@chainstacklabs⭐ 360 stars· last commit 6mo ago· 2 open issues

Trade on Polymarket via split + CLOB execution. Browse markets, track positions with P&L, discover hedges via LLM. Polygon/Web3.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

β€”/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 360 on GitHubGitHub β†—

Popular

🟒ProSkills Score
β€”
πŸ“

Not yet listed on ClawHub or SkillsMP

// README

PolyClaw

Trading-enabled Polymarket skill for OpenClaw.

Browse prediction markets, execute trades on-chain, and discover hedging opportunities using LLM-powered analysis. Full trading capability via split + CLOB execution on Polygon.

Disclaimer: This software is provided as-is for educational and experimental purposes. It is not financial advice. Trading prediction markets involves risk of loss. This code has not been audited. Use at your own risk and only with funds you can afford to lose.

πŸ“Ί Watch the video explainer

Features

Market browsing

  • polyclaw markets trending β€” Top markets by 24h volume
  • polyclaw markets search "query" β€” Search markets by keyword
  • polyclaw market <id> β€” Market details with prices

Trading

  • polyclaw buy <market_id> YES <amount> β€” Buy YES position
  • polyclaw buy <market_id> NO <amount> β€” Buy NO position
  • Split + CLOB execution (split pUSD β†’ YES+NO, sell unwanted side)

Position tracking

  • polyclaw positions β€” List open positions with live P&L
  • polyclaw position <id> β€” Detailed position view
  • Positions tracked locally in ~/.openclaw/polyclaw/positions.json

Wallet management

  • polyclaw wallet status β€” Show address, POL / pUSD / USDC.e balances
  • polyclaw wallet approve β€” Set Polymarket contract approvals (one-time)

Hedge discovery

  • polyclaw hedge scan β€” Scan trending markets for hedging opportunities
  • polyclaw hedge scan --query "topic" β€” Scan markets matching a query
  • polyclaw hedge analyze <id1> <id2> β€” Analyze specific market pair

Uses LLM-powered contrapositive logic to find covering portfolios. Only logically necessary implications are accepted β€” correlations and "likely" relationships are rejected.

Coverage tiers: T1 (β‰₯95%), T2 (90-95%), T3 (85-90%)

Quick start

1. Install skill

Option A: Install from ClawHub (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

2. Configure environment variables

Add the following to your openclaw.json under skills.entries.polyclaw.env:

"polyclaw": {
  "enabled": true,
  "env": {
    "CHAINSTACK_NODE": "https://polygon-mainnet.core.chainstack.com/YOUR_KEY",
    "POLYCLAW_PRIVATE_KEY": "0x...",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

Where to get the keys:

Security warning: Keep only small amounts in this wallet. Withdraw regularly to a secure wallet.

Looking for standalone CLI usage? This skill is designed for OpenClaw. For standalone CLI usage without OpenClaw, see polymarket-alpha-bot.

3. First-time setup (required for trading)

Before your first trade, set Polymarket contract approvals (one-time, costs ~0.01 POL in gas):

uv run python scripts/polyclaw.py wallet approve

This submits 6 approval transactions to Polygon. You only need to do this once per wallet.

4. Run commands

# Browse markets
uv run python scripts/polyclaw.py markets trending
uv run python scripts/polyclaw.py markets search "election"

# Find hedging opportunities
uv run python scripts/polyclaw.py hedge scan --limit 10

# Check wallet and trade
uv run python scripts/polyclaw.py wallet status
uv run python scripts/polyclaw.py buy <market_id> YES 50

Example prompts

Natural language prompts you can use with OpenClaw:

1. Browse trending markets

What's trending on Polymarket?

Returns market IDs, questions, prices, and volume.

2. Get market details

Show me details for market <market_id>

Use the market ID from Polymarket URL or from the trending markets response above.

Returns full market info with link to Polymarket.

3. Check wallet status

What's my PolyClaw wallet balance?

Shows address, POL balance (for gas), pUSD balance (collateral), and USDC.e balance (wrap into pUSD via the Collateral Onramp if you need it).

4. Direct trading

If you have your own conviction on a market:

Buy $50 YES on market <market_id>

Executes split + CLOB flow and records position.

5. Hedge discovery flow

Find LLM-analyzed arbitrage opportunities:

Find me some hedging opportunities on Polymarket

or more specifically:

Run hedge scan limit 10

Note: This takes a few minutes. The skill fetches open markets and sends pairs to the LLM for logical implication analysis.

Review the results β€” you'll see coverage tiers (T1 = 95%+, T2 = 90-95%, T3 = 85-90%) and the market pairs where you can take hedged positions.

6. Check positions

Show my PolyClaw positions

Lists open positions with entry price, current price, and P&L.

7. Sell early

To exit a position before the market resolves:

Sell my YES position on market <market_id>

Sells your tokens on the CLOB order book at current market price.

Full flow example

  1. "What's trending on Polymarket?" β†’ Get market IDs
  2. "Run hedge scan limit 10" β†’ Wait for LLM analysis
  3. Review hedge opportunities with coverage tiers
  4. "Buy $25 YES on market abc123" β†’ Take position on target market
  5. "Buy $25 NO on market xyz789" β†’ Take position on covering market
  6. "Show my PolyClaw positions" β†’ Verify entries and track P&L

Environment variables

VariableRequiredDescription
CHAINSTACK_NODEYes (trading)Polygon RPC URL
OPENROUTER_API_KEYYes (hedge)OpenRouter API key for LLM
POLYCLAW_PRIVATE_KEYYes (trading)EVM private key (hex)
HTTPS_PROXYNoOnly needed if CLOB orders fail (see troubleshooting)
CLOB_MAX_RETRIESNoMax retries for CLOB orders (default: 5)

Directory structure

polyclaw/
β”œβ”€β”€ SKILL.md                     # OpenClaw skill manifest
β”œβ”€β”€ README.md                    # This file
β”œβ”€β”€ pyproject.toml               # Python dependencies (uv)
β”‚
β”œβ”€β”€ scripts/
β”‚   β”œβ”€β”€ polyclaw.py              # CLI dispatcher
β”‚   β”œβ”€β”€ markets.py               # Market browsing (Gamma API)
β”‚   β”œβ”€β”€ wallet.py                # Wallet management
β”‚   β”œβ”€β”€ trade.py                 # Split + CLOB execution
β”‚   β”œβ”€β”€ positions.py             # Position tracking + P&L
β”‚   └── hedge.py                 # LLM hedge discovery
β”‚
└── lib/
    β”œβ”€β”€ __init__.py              # Package marker
    β”œβ”€β”€ clob_client.py           # py-clob-client wrapper
    β”œβ”€β”€ contracts.py             # CTF ABI + addresses
    β”œβ”€β”€ coverage.py              # Coverage calculation + tiers
    β”œβ”€β”€ gamma_client.py          # Polymarket Gamma API client
    β”œβ”€β”€ llm_client.py            # OpenRouter LLM client
    β”œβ”€β”€ position_storage.py      # Position JSON storage
    └── wallet_manager.py        # Wallet lifecycle

Trading flow

  1. Set approvals (one-time): polyclaw wallet approve
  2. Execute trade: polyclaw buy <market_id> YES 50
    • Split $50 pUSD β†’ 50 YES + 50 NO tokens
    • Sell 50 NO tokens via CLOB β†’ recover ~$15 (at 30Β’)
    • Result: 50 YES tokens, net cost ~$35
  3. Track position: polyclaw positions

Understanding the split mechanism

Polymarket uses a Conditional Token Framework (CTF). You can't directly "buy YES tokens" β€” instead:

  1. Split: Deposit pUSD into the CTF contract, which mints equal amounts of YES + NO tokens
  2. Sell unwanted: Sell the side you don't want via the CLOB order book
  3. Result: You hold your desired position, having recovered partial cost from selling the other side

Example (buying YES at $0.65):

Split:  $2 pUSD β†’ 2 YES + 2 NO tokens
Sell:   2 NO tokens @ $

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream β†—
    ---
    name: polyclaw
    description: "Trade on Polymarket via split + CLOB execution. Browse markets, track positions with P&L, discover hedges via LLM. Polygon/Web3."
    metadata: {"openclaw":{"emoji":"🦞","homepage":"https://polymarket.com","primaryEnv":"POLYCLAW_PRIVATE_KEY","requires":{"bins":["uv"],"env":["CHAINSTACK_NODE","POLYCLAW_PRIVATE_KEY"]},"install":[{"id":"uv-brew","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]},"clawdbot":{"emoji":"🦞","homepage":"https://polymarket.com","primaryEnv":"POLYCLAW_PRIVATE_KEY","requires":{"bins":["uv"],"env":["CHAINSTACK_NODE","POLYCLAW_PRIVATE_KEY"]},"install":[{"id":"uv-brew","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]}}
    ---
    
    # PolyClaw
    
    Trading-enabled Polymarket skill for OpenClaw. Browse markets, manage wallets, execute trades, and track positions.
    
    ## Features
    
    - **Market Browsing** - Search and browse Polymarket prediction markets
    - **Wallet Management** - Env-var based wallet configuration
    - **Trading** - Buy YES/NO positions via split + CLOB execution
    - **Position Tracking** - Track entry prices, current prices, and P&L
    - **Hedge Discovery** - LLM-powered covering portfolio discovery via logical implications
    
    ## Quick Start
    
    First, install dependencies (from skill directory):
    
    ```bash
    cd {baseDir}
    uv sync
    ```
    
    ### First-Time Setup (Required for Trading)
    
    Before your first trade, set Polymarket contract approvals (one-time, costs ~0.01 POL in gas):
    
    ```bash
    uv run python scripts/polyclaw.py wallet approve
    ```
    
    This submits 6 approval transactions to Polygon. You only need to do this once per wallet.
    
    ### Browse Markets
    
    ```bash
    # Trending markets by volume
    uv run python scripts/polyclaw.py markets trending
    
    # Search markets
    uv run python scripts/polyclaw.py markets search "election"
    
    # Market details (returns full JSON with all fields)
    uv run python scripts/polyclaw.py market <market_id>
    ```
    
    **Output options:**
    - Default output is a formatted table (good for display)
    - Use `--full` flag for full question text without truncation
    - Use `--json` flag via `scripts/markets.py --json trending` for structured JSON output
    
    ### Wallet Management
    
    ```bash
    # Check wallet status (address, balances)
    uv run python scripts/polyclaw.py wallet status
    
    # Set contract approvals (one-time)
    uv run python scripts/polyclaw.py wallet approve
    ```
    
    The wallet is configured via the `POLYCLAW_PRIVATE_KEY` environment variable.
    
    ### Trading
    
    ```bash
    # Buy YES position for $50
    uv run python scripts/polyclaw.py buy <market_id> YES 50
    
    # Buy NO position for $25
    uv run python scripts/polyclaw.py buy <market_id> NO 25
    ```
    
    ### Positions
    
    ```bash
    # List all positions with P&L
    uv run python scripts/polyclaw.py positions
    ```
    
    ### Hedge Discovery
    
    Find covering portfolios - pairs of market positions that hedge each other via contrapositive logic.
    
    ```bash
    # Scan trending markets for hedges
    uv run python scripts/polyclaw.py hedge scan
    
    # Scan markets matching a query
    uv run python scripts/polyclaw.py hedge scan --query "election"
    
    # Analyze specific markets for hedging relationship
    uv run python scripts/polyclaw.py hedge analyze <market_id_1> <market_id_2>
    ```
    
    **Output options:**
    - Default output is a formatted table showing Tier, Coverage, Cost, Target, and Cover
    - Use `--json` flag for structured JSON output
    - Use `--min-coverage 0.90` to filter by minimum coverage (default 0.85)
    - Use `--tier 1` to filter by tier (1=best, default 2)
    
    **Coverage tiers:**
    - **Tier 1 (HIGH):** >=95% coverage - near-arbitrage opportunities
    - **Tier 2 (GOOD):** 90-95% - strong hedges
    - **Tier 3 (MODERATE):** 85-90% - decent but noticeable risk
    - **Tier 4 (LOW):** <85% - speculative (filtered by default)
    
    **LLM model:** Uses `nvidia/nemotron-nano-9b-v2:free` via OpenRouter. Model selection matters β€” some models find spurious correlations while others (like DeepSeek R1) have output format issues. Override with `--model <model_id>` if needed.
    
    ## Security
    
    For the MVP, the private key is stored in an environment variable for simplicity and Claude Code compatibility.
    
    **Security Warning:** Keep only small amounts in this wallet. Withdraw regularly to a secure wallet.
    
    ## Environment Variables
    
    | Variable | Required | Description |
    |----------|----------|-------------|
    | `CHAINSTACK_NODE` | Yes (trading) | Polygon RPC URL |
    | `OPENROUTER_API_KEY` | Yes (hedge) | OpenRouter API key for LLM hedge discovery |
    | `POLYCLAW_PRIVATE_KEY` | Yes (trading) | EVM private key (hex, with or without 0x prefix) |
    | `HTTPS_PROXY` | Recommended | Rotating residential proxy for CLOB (e.g., IPRoyal) |
    | `CLOB_MAX_RETRIES` | No | Max CLOB retries with IP rotation (default: 5) |
    | `POLY_BUILDER_CODE` | No | Bytes32 builder code for attribution (from polymarket.com/settings?tab=builder). Attached to every order when set. |
    
    **Security Warning:** Keep only small amounts in this wallet. Withdraw regularly to a secure wallet. The private key in an env var is convenient for automation but less secure than encrypted storage.
    
    ## Trading Flow
    
    1. **Split Position** - pUSD is split into YES + NO tokens via CTF contract
    2. **Sell Unwanted** - The unwanted side is sold via CLOB order book (V2)
    3. **Result** - You hold the wanted position, recovered partial cost from selling unwanted
    
    Example: Buy YES at $0.70
    - Split $100 pUSD β†’ 100 YES + 100 NO tokens
    - Sell 100 NO tokens at ~$0.30 β†’ recover ~$27 pUSD
    - Net cost: ~$73 for 100 YES tokens (entry: $0.73)
    
    If you only have USDC.e, wrap it 1:1 into pUSD via the Collateral Onramp's `wrap()` function before trading.
    
    ## Polymarket Contracts (Polygon Mainnet, CLOB V2)
    
    - **pUSD (collateral):** `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB`
    - **USDC.e (onramp input):** `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
    - **Collateral Onramp:** `0x93070a847efEf7F70739046A929D47a521F5B8ee`
    - **CTF (Conditional Tokens):** `0x4D97DCd97eC945f40cF65F87097ACe5EA0476045`
    - **CTF Exchange (V2):** `0xE111180000d2663C0091e4f400237545B87B996B`
    - **Neg Risk CTF Exchange (V2):** `0xe2222d279d744050d28e00520010520000310F59`
    
    ## Dependencies
    
    Install with uv (from skill directory):
    ```bash
    cd {baseDir}
    uv sync
    ```
    
    ## Limitations
    
    - Trading requires wallet approval setup (one-time)
    - CLOB sells may fail if liquidity is insufficient
    
    ### CLOB Cloudflare Blocking
    
    Polymarket's CLOB API uses Cloudflare protection that blocks POST requests from many IPs, including datacenter IPs and some residential ISPs. This affects the "sell unwanted tokens" step.
    
    **Solution: Residential proxy with retry logic**
    
    The recommended setup uses a rotating residential proxy (e.g., IPRoyal, BrightData). The CLOB client automatically retries with new IPs until one works:
    
    ```bash
    export HTTPS_PROXY="http://user:[email protected]:12321"
    export CLOB_MAX_RETRIES=10  # Default is 5
    ```
    
    With this setup, CLOB orders typically succeed within 5-10 retries as the proxy rotates through IPs until finding an unblocked one.
    
    **Alternative workarounds:**
    1. **Use `--skip-sell`** β€” Keep both YES and NO tokens, sell manually on polymarket.com
    2. **No proxy** β€” Split still works; only CLOB sell is affected
    
    If CLOB fails after all retries, your split still succeeded. The output tells you how many tokens to sell manually.
    
    ## Troubleshooting
    
    ### "No wallet available"
    Set the `POLYCLAW_PRIVATE_KEY` environment variable:
    ```bash
    export POLYCLAW_PRIVATE_KEY="0x..."
    ```
    
    ### "Insufficient pUSD"
    Check balance with `uv run python scripts/polyclaw.py wallet status`. Trades require pUSD (Polymarket USD). If you have USDC.e, wrap it 1:1 via the Collateral Onramp (`0x9307...B8ee`) β€” the polymarket.com UI does this automatically; API users wrap manually.
    
    ### "CLOB order failed"
    The CLOB sell may fail due to:
    - Insufficient liquidity at the sell price
    - IP blocked by Cloudflare (try proxy)
    
    Your split still succeeded - you have the tokens, just couldn't sell unwanted side.
    
    ### "Approvals not set"
    First trade requires contract approvals. Run:
    ```bash
    uv run python scripts
  • README.mdupstream β†—

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/chainstacklabs-polyclaw.md

// REPO STATS

360 stars
2 open issues
Last commit: 6mo ago