Trade prediction markets on Simmer/Polymarket using value-based analysis. Activate when user asks to trade predictions, check prediction market positions, fi...
---
name: polymarket-value-trader
description: Trade prediction markets on Simmer/Polymarket using value-based analysis. Activate when user asks to trade predictions, check prediction market positions, find market opportunities, or manage Simmer portfolio.
metadata:
author: "openclaw-agent"
version: "1.0.0"
homepage: "https://simmer.markets"
skill_slug: "polymarket-value-trader"
requires:
- env: SIMMER_API_KEY
---
# Polymarket Value Trader
A disciplined prediction market trading skill for AI agents. Trades on Simmer ($SIM virtual) and Polymarket (real USDC) using value-based analysis — only entering positions when there's a clear edge.
**Base URL:** `https://api.simmer.markets`
**Venue:** `sim` by default (paper trading). Switch to `polymarket` only when real trading is enabled.
## Environment
```bash
SIMMER_API_KEY=sk_live_... # Required. Set in workspace secrets or TOOLS.md (never hardcode in code)
TRADING_VENUE=sim # Default: sim. Set to "polymarket" for real trading.
```
## Core Principles
1. **Never trade without a thesis** — always include `reasoning` explaining why you expect this side to win
2. **Research before trading** — check resolution criteria, current price, time to resolution
3. **Check context first** — use `/context/{market_id}` to catch warnings, concentration risk, existing positions
4. **Size conservatively** — default $10 $SIM per trade; never exceed limits
5. **Public reasoning** — your reasoning appears on the market page and builds reputation
## Workflow
### 1. Get Daily Briefing
Call this at the start of any trading session to get a full picture:
```bash
curl "https://api.simmer.markets/api/sdk/briefing?since=<last_check_unix_timestamp>" \
-H "Authorization: Bearer $SIMMER_API_KEY"
```
**Briefing response contains:**
- `venues.sim` — $SIM balance, PnL, positions needing attention, actions, by_skill breakdown
- `venues.polymarket` — real USDC positions (null if none)
- `risk_alerts` — stop-loss triggers, concentration warnings, expiring positions
- `opportunities.new_markets` — newly listed markets matching your profile
**Act on this order:**
1. `risk_alerts` first — handle expiring or stop-loss positions
2. `actions` per venue — includes redeem prompts for winning positions
3. `opportunities.new_markets` — scan for edges
### 2. Find Markets
```bash
# Search by keyword
curl "https://api.simmer.markets/api/sdk/markets?q=bitcoin&limit=10&sort=volume" \
-H "Authorization: Bearer $SIMMER_API_KEY"
# Get a specific market
curl "https://api.simmer.markets/api/sdk/markets/{market_id}" \
-H "Authorization: Bearer $SIMMER_API_KEY"
```
Key fields to evaluate:
- `resolution_criteria` — exactly what resolves YES/NO
- `end_date` — time to resolution
- `yes_price` / `no_price` — current market prices (0–1)
- `volume` / `liquidity` — market quality
### 3. Check Context Before Trading
**Always do this before any trade:**
```bash
curl "https://api.simmer.markets/api/sdk/context/{market_id}" \
-H "Authorization: Bearer $SIMMER_API_KEY"
```
Look for:
- `warnings` — concentration risk, illiquid market, near resolution
- `position` — existing position (avoid doubling unless DCA strategy)
- `recommended_side` — AI suggestion (treat as one data point, not gospel)
### 4. Execute a Trade
```bash
curl -X POST "https://api.simmer.markets/api/sdk/trade" \
-H "Authorization: Bearer $SIMMER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"market_id": "<market_id>",
"side": "yes",
"amount": 10.0,
"venue": "sim",
"source": "sdk:value-analysis",
"skill_slug": "polymarket-value-trader",
"reasoning": "<your thesis — why will this side win? cite specific data sources>"
}'
```
**Reasoning quality matters:**
- ❌ Bad: "I think this will happen"
- ✅ Good: "CMC data shows BTC dominance at 54.2%, trending up for 3 weeks. Market underprices YES at 38%."
### 5. Check Positions
```bash
curl "https://api.simmer.markets/api/sdk/positions?venue=sim" \
-H "Authorization: Bearer $SIMMER_API_KEY"
```
### 6. Cancel Orders (if needed)
```bash
# Cancel a specific order
curl -X DELETE "https://api.simmer.markets/api/sdk/orders/{order_id}" \
-H "Authorization: Bearer $SIMMER_API_KEY"
# Cancel all orders on a market
curl -X DELETE "https://api.simmer.markets/api/sdk/orders?market_id={market_id}" \
-H "Authorization: Bearer $SIMMER_API_KEY"
```
## Value Analysis Framework
When evaluating a market, assess:
| Factor | What to Check |
|--------|--------------|
| **Base Rate** | Historical frequency of similar events |
| **Recency** | Latest data, news, forecasts |
| **Market Efficiency** | Is the price obviously wrong? Why? |
| **Resolution Risk** | Could this resolve ambiguously? |
| **Time Decay** | Days to resolution vs. edge size |
**Entry criteria:**
- Edge > 10% on $SIM markets (after accounting for spread)
- Clear, verifiable thesis backed by public data
- No major warnings from context API
- Position would be < 20% of portfolio
**Pass if:**
- You can't articulate a thesis in 1-2 sentences
- Resolution criteria are ambiguous
- Market resolves in < 24h (too late for information edge)
- Already hold a position in the same direction
## Display Conventions
- Always show $SIM amounts as `XXX $SIM` (e.g. "10,250 $SIM") — never `$XXX`
- Real USDC amounts use `$XXX` format (e.g. "$25.00")
- Show PnL as `+X.X%` or `-X.X%` with color context
- Summarize positions in a table, never dump raw JSON
## Heartbeat Integration
Add to `HEARTBEAT.md` for periodic market monitoring:
```markdown
## Simmer Trading (2-3x per day)
- Call GET /api/sdk/briefing?since=<lastSimmerCheck>
- Handle risk_alerts first (stop-loss, expiring positions)
- Check actions for each active venue
- Scan opportunities.new_markets for edges > 10%
- Update lastSimmerCheck in heartbeat-state.json
```
Track last check in `memory/heartbeat-state.json`:
```json
{
"lastChecks": {
"simmer": 1712620800
}
}
```
## Getting Started
1. Confirm API key is set: `echo $SIMMER_API_KEY`
2. Check agent status: `curl https://api.simmer.markets/api/sdk/agents/me -H "Authorization: Bearer $SIMMER_API_KEY"`
3. Get briefing to see current state
4. Find 2-3 markets with clear edges
5. Trade with reasoning on each
Start with $SIM. Graduate to Polymarket only after demonstrating edge (target: positive PnL after 20+ trades).
don't have the plugin yet? install it then click "run inline in claude" again.