openclaw-polymarket

OpenClaw tools & skills for Polymarket: market intel, alerts, paper trading, and guarded limit orders.

Status: WIP — starting read-only and progressively enabling live trading behind strict guardrails.

---

What this repo is

This repository adds a Polymarket integration to OpenClaw via:

• Plugins / Tools: strongly-typed functions the agent can call (read markets, fetch orderbooks, compute spread, etc.).
• Skills: the “operating manual” that teaches the assistant how to use those tools safely (read-only → paper → guarded trading).

This approach keeps credentials out of prompts and makes it possible to enforce allowlists, approvals, limits, and audit logs.

---

Roadmap (features by phase)

Phase 1 — Read-only Market Intelligence (no risk)

• Search/discover markets (Gamma)
• Fetch market details and orderbook snapshots (CLOB read endpoints)
• Metrics: midpoint, spread, depth, liquidity heuristics
• Watchlists + alerts (price / spread / volume / depth)

Phase 2 — Portfolio & Activity (still no trading)

• Positions, trades, activity (Data API)
• Daily/weekly summaries
• Audit logs of decisions and tool calls

Phase 3 — Paper trading (simulated fills with real orderbooks)

• Order simulation with slippage estimates
• Strategy prototyping (entry/exit rules)
• “Proposal-only” mode (never executes)

Phase 4 — Guarded live trading (micro size)

• Limit orders only (initially)
• Mandatory approval gates
• Daily/max exposure limits, per-market limits
• Kill-switch + cancel-all + pause watchers
• Observability + error budgets + rate limiting

---

Architecture

openclaw-polymarket/
  plugin/
    polymarket-core/        # API clients + pure read-only tools
    polymarket-watchers/    # background services: alerts, monitors
    polymarket-trade/       # guarded trading tools (Phase 4+)
  skills/
    polymarket-readonly/    # safe read-only behavior
    polymarket-paper/       # paper trading behavior
    polymarket-trading-basic/ # live trading w/ guardrails
  docs/
    threat-model.md
    runbooks.md
    api-notes.md
  infra/
    docker/
    compose/
    terraform/              # optional (Hetzner)

---

Prerequisites

• A running OpenClaw instance (local, VM, or container).
• Polymarket access:
  • Read-only can be done without secrets (depending on endpoint).
  • Trading requires auth (private key / L2 creds per Polymarket docs).

References:

OpenClaw repo:
https://github.com/openclaw/openclaw

Polymarket docs:
https://docs.polymarket.com/

---

Quickstart (read-only)

This is a template. Adjust to how you run OpenClaw (systemd, docker, k8s, etc.).

1. Clone:

git clone https://github.com/<you>/openclaw-polymarket.git
cd openclaw-polymarket

2. Install dependencies (example for Node-based plugin; adapt if you use Python):

cd plugin/polymarket-core
npm install
npm run build

3. Register the plugin in your OpenClaw config (example pseudocode):

# openclaw.yaml
plugins:
  - name: polymarket-core
    path: ./plugin/polymarket-core
skills:
  - path: ./skills/polymarket-readonly

4. Start OpenClaw and test a read-only tool call:

• Ask the agent to search a market topic and summarize spread + liquidity.

---

Configuration

Environment variables

Read-only (optional, depends on endpoint usage):

POLYMARKET_GAMMA_BASE_URL=
POLYMARKET_CLOB_BASE_URL=
POLYMARKET_DATA_BASE_URL=

Trading (Phase 4+) — DO NOT enable until you’ve completed Phases 1–3

# L1 signing (private key / wallet)
POLYMARKET_PRIVATE_KEY=

# L2 API credentials (if you use that auth flow)
POLYMARKET_API_KEY=
POLYMARKET_API_SECRET=
POLYMARKET_API_PASSPHRASE=

Guardrails (recommended defaults)

PM_MODE=readonly               # readonly | paper | live
PM_REQUIRE_APPROVAL=true       # always true for live
PM_MAX_DAILY_USD=5             # start tiny
PM_MAX_MARKET_USD=2
PM_MAX_OPEN_ORDERS=3
PM_ALLOWED_MARKET_IDS=         # comma-separated allowlist
PM_LIMIT_ORDERS_ONLY=true
PM_AUDIT_LOG_PATH=./logs/pm-audit.jsonl

---

Usage examples (chat intents)

These are examples of what your skills should support:

Read-only

• “Track these 5 markets and alert me if YES crosses 0.60.”
• “Show me top movers in my watchlist today.”
• “Explain the spread and depth for market X.”

Paper trading

• “Simulate buying YES at 0.58 for $2 and show expected slippage.”
• “Backtest this simple rule on the last N snapshots (if stored).”

Live trading (guarded)

• “Propose a limit order for $1 with max slippage 1 tick — do NOT send without my approval.”
• “Cancel all open orders and pause trading.”

---

Security model (non-negotiables)

• No secrets in prompts. Secrets live in env vars / secret manager only.
• Allowlist tools: start minimal; don’t enable shell/exec tools.
• Approval gate required for every live order.
• Limits: per-day, per-market, max open orders, and market allowlist.
• Audit logs: JSONL event log for every proposal/execution/cancellation.
• Kill switch: instant pause + cancel-all.

Read more in:

docs/threat-model.md
docs/runbooks.md

---

Development

Local dev loop (example)

# build plugin(s)
cd plugin/polymarket-core && npm run build

# run tests
npm test

Repo conventions

• Tools are versioned and backwards compatible once stable.
• Skills must include explicit “DO / DON’T” rules and reference the tools only (no direct HTTP in prompts).

---

Contributing

PRs welcome. Please:

• Keep trading features behind PM_MODE=live and PM_REQUIRE_APPROVAL=true.
• Add tests for anything that can move funds.
• Update docs/threat-model.md when adding new capabilities.

---

Disclaimer

This project is for educational and tooling purposes. It is not financial advice. Markets can be illiquid, event resolution can be non-trivial, and trading involves risk. You are responsible for understanding Polymarket rules, fees, and compliance requirements in your jurisdiction.