Grimoire Polymarket
Discover Polymarket markets and read or manage CLOB state from your coding agent via the Grimoire `polymarket` venue CLI wrapper.
Overview
Grimoire Polymarket is an agent skill for the Build phase that queries Polymarket markets and CLOB-related data and drives order workflows through the Grimoire `polymarket` venue CLI wrapper.
Install
npx skills add https://github.com/franalgaba/grimoire --skill grimoire-polymarketWhat is this skill?
- Canonical commands: `info`, `search-markets` with rich filters (slug, tag, league, tradable-only, pagination)
- Passthrough to official CLI `markets` and `data` groups; order paths governed by wrapper policy
- Preflight: `grimoire venue doctor --adapter polymarket` and `info --format json`
- Invocations via `grimoire venue polymarket`, `npx @grimoirelabs/cli`, repo-local bun, or `grimoire-polymarket` binary
- JSON/table/auto output formats for agent-parseable market discovery
- Documented passthrough CLI groups: `markets` and `data`
- Primary discovery command: `search-markets` with multi-filter and pagination flags
Adoption & trust: 11.7k installs on skills.sh; 5 GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need Polymarket discovery and CLOB state from an agent without re-implementing the official CLI surface and output formats every time.
Who is it for?
Indie builders automating Polymarket research or CLOB-backed tools via Claude Code, Cursor, or Codex with Grimoire already on PATH or npx.
Skip if: Builders who only need static market pages in a browser with no CLI agent workflow, or teams that require full unrestricted Polymarket CLI groups blocked by this wrapper policy without reviewing upstream docs.
When should I use this skill?
You need Polymarket market discovery, CLOB market data, or order-management operations through the Grimoire polymarket venue adapter.
What do I get? / Deliverables
Your agent runs documented `grimoire venue polymarket` commands (with doctor preflight) and gets structured market/search or passthrough `markets`/`data` results ready for downstream trading or analysis logic.
- JSON or table market search results from `search-markets`
- Venue health output from `venue doctor --adapter polymarket`
- Passthrough `markets`/`data` CLI responses for agent parsing
Recommended Skills
Journey fit
Canonical shelf is Build → integrations because the skill wires an external trading venue into agent workflows through a CLI adapter, not a one-off research task. Polymarket access is an external API/CLI integration surfaced as `grimoire venue polymarket` commands and restricted passthrough to official CLI groups.
How it compares
Use as a Grimoire-governed CLI integration skill, not a raw REST snippet or a generic finance MCP you have not audited.
Common Questions / FAQ
Who is grimoire-polymarket for?
Solo and indie developers building agent or CLI workflows that need Polymarket market search, CLOB-oriented data, and wrapper-approved order operations through Grimoire.
When should I use grimoire-polymarket?
During Build integrations when wiring prediction-market data into a bot or dashboard; at Operate when re-running doctor/info and data commands against live markets; and during Validate when scouting tradable markets before committing to a trading feature.
Is grimoire-polymarket safe to install?
Treat it like any trading CLI: it can touch real funds and secrets. Review the Security Audits panel on this Prism page and run `grimoire venue doctor --adapter polymarket` before trusting credentials on your machine.
SKILL.md
READMESKILL.md - Grimoire Polymarket
# Grimoire Polymarket Skill Use this skill for Polymarket market discovery, CLOB market data, and order-management operations through the `polymarket` venue adapter. Preferred invocations: - `grimoire venue polymarket ...` - `npx -y @grimoirelabs/cli venue polymarket ...` (no-install) - `bun run packages/cli/src/index.ts venue polymarket ...` (repo-local) - `grimoire-polymarket ...` (direct binary from `@grimoirelabs/venues`) Recommended preflight: - `grimoire venue doctor --adapter polymarket --json` - `grimoire venue polymarket info --format json` ## Commands Canonical agent commands: - `grimoire venue polymarket info [--format <auto|json|table>]` - `grimoire venue polymarket search-markets [--query <text>] [--slug <slug|url>] [--question <text>] [--event <text>] [--tag <text>] [--category <text>] [--league <text>] [--sport <text>] [--open-only <true|false>] [--active-only <true|false>] [--ignore-end-date <true|false>] [--tradable-only <true|false>] [--all-pages <true|false>] [--max-pages <n>] [--stop-after-empty-pages <n>] [--limit <n>] [--format <auto|json|table>]` Allowed passthrough groups (official CLI surface, restricted by wrapper policy): - `markets` (`list|get|search|tags`) - `data` (positions/value/leaderboards/etc.) Blocked groups in this wrapper (intentionally not exposed for agents): - `wallet` - `bridge` - `approve` - `ctf` - `setup` - `upgrade` - `shell` Legacy compatibility aliases are still supported (`market`, `book`, `midpoint`, `spread`, `price`, `last-trade-price`, `tick-size`, `neg-risk`, `fee-rate`, `price-history`, `order`, `trades`, `open-orders`, `balance-allowance`, `closed-only-mode`, `server-time`) but should not be used for new agent flows. ## Examples ```bash # Wrapper/health grimoire venue polymarket info --format json grimoire venue polymarket status --format json # Canonical discovery grimoire venue polymarket search-markets --query bitcoin --active-only true --open-only true --format json grimoire venue polymarket search-markets --category sports --league "la liga" --active-only true --open-only true --format json # Official passthrough discovery/data grimoire venue polymarket markets list --limit 25 --format json grimoire venue polymarket markets search "atleti" --limit 25 --format json grimoire venue polymarket data positions <address> --limit 25 --format json grimoire venue polymarket data trades <address> --limit 25 --format json grimoire venue polymarket data leaderboard --period week --order-by vol --limit 25 --format json # Legacy compatibility aliases (still supported) grimoire venue polymarket book --token-id <token_id> --format json grimoire venue polymarket price --token-id <token_id> --side buy --format json grimoire venue polymarket order --order-id <order_id> --format json grimoire venue polymarket open-orders --market <condition_id> --format json ``` ## Runtime Configuration Adapter/runtime auth (for spell execution): - required by default: `POLYMARKET_PRIVATE_KEY` - optional API creds: `POLYMARKET_API_KEY`, `POLYMARKET_API_SECRET`, `POLYMARKET_API_PASSPHRASE` - optional derive toggle (default true): `POLYMARKET_DERIVE_API_KEY=true|false` - optional signature routing: `POLYMARKET_SIGNATURE_TYPE` (`0` EOA, `1` POLY_PROXY, `2` GNOSIS_SAFE), `POLYMARKET_FUNDER` - `grimoire cast` / `grimoire resume` key-based flows inject the same wallet-manager key into the Polymarket adapter, so a separate `POLYMARKET_PRIVATE_KEY` env is not required there. Venue CLI backend: - Official binary required: `polymarket` - Install: `brew tap Polymarket/polymarket-cli && brew install polymarket` - Optional path override: `POLYMARKET_OFFICIAL_CLI=/custom/path/polymarket` ## Spell Actions Polymarket uses `custom` action type with `op: "order"` for order placement: ```spell polymarket.cus