1---
2name: grimoire-polymarket
3description: Queries Polymarket market data and CLOB state, and manages CLOB orders via the Grimoire venue CLI wrapper backed by the official Polymarket CLI.
4---
5 
6# Grimoire Polymarket Skill
7 
8Use this skill for Polymarket market discovery, CLOB market data, and order-management operations through the `polymarket` venue adapter.
9 
10Preferred invocations:
11 
12- `grimoire venue polymarket ...`
13- `npx -y @grimoirelabs/cli venue polymarket ...` (no-install)
14- `bun run packages/cli/src/index.ts venue polymarket ...` (repo-local)
15- `grimoire-polymarket ...` (direct binary from `@grimoirelabs/venues`)
16 
17Recommended preflight:
18 
19- `grimoire venue doctor --adapter polymarket --json`
20- `grimoire venue polymarket info --format json`
21 
22## Commands
23 
24Canonical agent commands:
25 
26- `grimoire venue polymarket info [--format <auto|json|table>]`
27- `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>]`
28 
29Allowed passthrough groups (official CLI surface, restricted by wrapper policy):
30 
31- `markets` (`list|get|search|tags`)
32- `data` (positions/value/leaderboards/etc.)
33 
34Blocked groups in this wrapper (intentionally not exposed for agents):
35 
36- `wallet`
37- `bridge`
38- `approve`
39- `ctf`
40- `setup`
41- `upgrade`
42- `shell`
43 
44Legacy 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.
45 
46## Examples
47 
48```bash
49# Wrapper/health
50grimoire venue polymarket info --format json
51grimoire venue polymarket status --format json
52 
53# Canonical discovery
54grimoire venue polymarket search-markets --query bitcoin --active-only true --open-only true --format json
55grimoire venue polymarket search-markets --category sports --league "la liga" --active-only true --open-only true --format json
56 
57# Official passthrough discovery/data
58grimoire venue polymarket markets list --limit 25 --format json
59grimoire venue polymarket markets search "atleti" --limit 25 --format json
60grimoire venue polymarket data positions <address> --limit 25 --format json
61grimoire venue polymarket data trades <address> --limit 25 --format json
62grimoire venue polymarket data leaderboard --period week --order-by vol --limit 25 --format json
63 
64# Legacy compatibility aliases (still supported)
65grimoire venue polymarket book --token-id <token_id> --format json
66grimoire venue polymarket price --token-id <token_id> --side buy --format json
67grimoire venue polymarket order --order-id <order_id> --format json
68grimoire venue polymarket open-orders --market <condition_id> --format json
69```
70 
71## Runtime Configuration
72 
73Adapter/runtime auth (for spell execution):
74 
75- required by default: `POLYMARKET_PRIVATE_KEY`
76- optional API creds: `POLYMARKET_API_KEY`, `POLYMARKET_API_SECRET`, `POLYMARKET_API_PASSPHRASE`
77- optional derive toggle (default true): `POLYMARKET_DERIVE_API_KEY=true|false`
78- optional signature routing: `POLYMARKET_SIGNATURE_TYPE` (`0` EOA, `1` POLY_PROXY, `2` GNOSIS_SAFE), `POLYMARKET_FUNDER`
79- `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.
80 
81Venue CLI backend:
82 
83- Official binary required: `polymarket`
84- Install: `brew tap Polymarket/polymarket-cli && brew install polymarket`
85- Optional path override: `POLYMARKET_OFFICIAL_CLI=/custom/path/polymarket`
86 
87## Spell Actions
88 
89Polymarket uses `custom` action type with `op: "order"` for order placement:
90 
91```spell
92polymarket.custom(
93  op="order",
94  token_id="TOKEN_ID",
95  price="0.55",
96  size="100",
97  side="BUY",
98  order_type="GTC",
99)
100```
101 
102The adapter does not support runtime constraints (`max_slippage`, etc.). Order routing:
103- `GTC`/`GTD` → limit order (`createAndPostOrder`)
104- `FOK`/`FAK` → market order (`createAndPostMarketOrder`)
105 
106## Metric Surface (Spell Comparisons)
107 
108Polymarket exposes `mid_price` for CLOB token midpoint comparisons:
109 
110```spell
111poly_mid = metric("mid_price", polymarket, USDC, "token_id=<clobTokenId>")
112```
113 
114Selector keys accepted: `token_id`, `tokenid`, `market_id`, `id`.
115If selector is omitted, the metric falls back to the 3rd argument value.
116 
117## Adapter Notes
118 
119- Adapter name: `polymarket`
120- Execution type: `offchain`
121- Supported chain metadata: `137` (Polygon)
122- Action type: `custom`
123- Supported custom ops: `order`, `cancel_order`, `cancel_orders`, `cancel_all`, `heartbeat`
124 
125Order argument aliases accepted:
126 
127- token: `token_id` or `tokenID` or `tokenId` or `coin`
128- amount: `size` or `amount`
129- side: `BUY`/`SELL`
130- order type: `GTC`/`GTD`/`FOK`/`FAK`
131- extra compatibility aliases: `arg0..arg5`, `reduce_only`
132 
133Order type routing:
134 
135- `GTC`/`GTD` -> limit order path (`createAndPostOrder`)
136- `FOK`/`FAK` -> market order path (`createAndPostMarketOrder`)
137 
138## Notes
139 
140- Prefer `--format json` for agent and automation workflows.
141- `search-markets` is the agent-oriented normalized discovery command; passthrough `markets search` is thinner and closer to official behavior.
142- Keep prompts/tooling on this CLI surface; do not call Polymarket HTTP APIs directly from advisory tools.
143