# polymarket-paper-trader

polymarket-paper-trader simulates Polymarket prediction market trading using live order books without using real funds.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 208 installs · ★ 100 repo stars
- Author: mjunaidca
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mjunaidca/polymarket-skills/tree/HEAD/polymarket-paper-trader/SKILL.md
- Updated: 2026-02-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/polymarket-paper-trader

## What it does

This skill provides a local engine for simulated trading on prediction markets. Instead of relying on midpoint values, market buy orders walk the actual order book from `clob.polymarket.com` to compute fills. All virtual balances and transaction logs remain saved between runs inside an SQLite database at `~/.polymarket-paper/portfolio.db`.

A built-in guard monitors drawdowns and position exposure. It enforces constraints such as a 10% maximum stake per bet and a 5% daily loss cutoff, which require the `--force` flag to override.

The tool relies on local Python and network reachability to Polymarket endpoints. Trading calls require specific market token identifiers, which you query from the Gamma API or feed in via JSON payload to `execute_paper.py`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/polymarket-paper-trader/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/polymarket-paper-trader/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/polymarket-paper-trader/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/polymarket-paper-trader/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mjunaidca/polymarket-skills polymarket-paper-trader
```

2. **Manually: put the files in place**
- File: `.github/skills/polymarket-paper-trader/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mjunaidca/polymarket-skills --path polymarket-paper-trader
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/polymarket-paper-trader/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mjunaidca/polymarket-skills/tree/HEAD/polymarket-paper-trader/SKILL.md

## When to use it
- test market prediction tactics against live order books without financial loss
- maintain a persistent demo portfolio in a local SQLite database
- enforce systematic drawdown limits and maximum position sizes
- generate structured performance and position summary reports

## Example prompts
- Initialize a paper trading portfolio with a 1000 balance
- Simulate buying 50 dollars worth of YES shares for token TOKEN_ID
- Run the health check script to evaluate drawdowns and risk limits

## Similar
- [Polymarket Paper Trader](https://affpapa.org/en/nevibecode/mcp/polymarket-paper-trader.md) — MCP server · ★ 509 repo stars
- [polymarket-api](https://affpapa.org/en/nevibecode/skills/polymarket-api.md) — skill · 973 installs
- [nothing-ever-happens-polymarket-bot](https://affpapa.org/en/nevibecode/skills/nothing-ever-happens-polymarket-bot.md) — skill · 433 installs
- [grimoire-polymarket](https://affpapa.org/en/nevibecode/skills/grimoire-polymarket.md) — skill · 11900 installs
- [Polymarket Data by PolymarketScan](https://affpapa.org/en/nevibecode/mcp/polymarket-data-by-polymarketscan.md) — MCP server · 39483 installs
- [polymarket](https://affpapa.org/en/nevibecode/skills/polymarket.md) — skill · 1400 installs

From the same set: [mjunaidca/polymarket-skills](https://affpapa.org/en/nevibecode/by/mjunaidca/polymarket-skills.md) — 6 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
