polymarket-paper-trader

Name: polymarket-paper-trader
Author: mjunaidca

170installs10forks

How to install polymarket-paper-trader?

mjunaidca/polymarket-skills/polymarket-paper-trader

$npx -y skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader

Installs into the current project.

Summary

Use this skill whenever the user wants to paper trade, simulate trades, virtual trading, demo mode, practice trading, backtest strategies, test strategy performance, use paper money, manage a virtual portfolio, track simulated P&L, or do risk-free trading on Polymarket prediction

Files · 1

View on GitHub

SKILL.md

1	# Polymarket Paper Trading Engine
2
3	Simulate trades against live Polymarket prices with zero financial risk. No wallet, no keys, no money at stake. Portfolio persists across sessions in SQLite.
4
5	## Quick Start
6
7	### Initialize a Portfolio
8	```bash
9	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000
10	```
11
12	### Buy Shares (Market Order)
13	```bash
14	# Buy $50 of YES shares using live order book prices
15	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
16	--action buy --token TOKEN_ID --side YES --size 50 \
17	--reason "High confidence based on news analysis"
18	```
19
20	### Buy Shares (Limit Order)
21	```bash
22	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
23	--action buy --token TOKEN_ID --side YES --size 50 --price 0.45 \
24	--reason "Value buy below fair price estimate"
25	```
26
27	### Check Portfolio
28	```bash
29	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio
30	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio --json
31	```
32
33	### Close a Position
34	```bash
35	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
36	--action close --token TOKEN_ID --reason "Taking profit"
37	```
38
39	### View Trade History
40	```bash
41	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action trades
42	```
43
44	### Performance Report
45	```bash
46	python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py
47	python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py --json
48	```
49
50	### Portfolio Health Check (Session Start)
51	```bash
52	python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py
53	python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py --json
54	```
55	Runs the full session-start workflow in one command: loads portfolio, fetches live prices, updates DB, calculates drawdown, checks stop losses, evaluates all risk limits. Returns GREEN/YELLOW/RED status.
56
57	## Finding Token IDs
58
59	Token IDs come from the Polymarket Gamma API. To find them for a market:
60
61	```bash
62	# Search for markets
63	curl -s 'https://gamma-api.polymarket.com/markets?limit=5&active=true&closed=false&order=volume24hr&ascending=false' \| python3 -c "
64	import sys, json
65	for m in json.load(sys.stdin):
66	tokens = json.loads(m['clobTokenIds'])
67	prices = json.loads(m['outcomePrices'])
68	print(f\"{m['question'][:60]}\")
69	print(f\" YES token: {tokens[0]} price: {prices[0]}\")
70	print(f\" NO token: {tokens[1]} price: {prices[1]}\")
71	print()
72	"
73	```
74
75	Or use the polymarket-scanner skill to discover markets first.
76
77	## Execute Strategy Recommendations
78
79	The executor takes structured recommendations from strategy advisors:
80
81	```bash
82	python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
83	--recommendation '{
84	"token_id": "TOKEN_ID",
85	"side": "YES",
86	"action": "BUY",
87	"size_usd": 50,
88	"confidence": 0.75,
89	"reasoning": "Momentum signal detected",
90	"strategy": "momentum"
91	}'
92	```
93
94	Dry run (validates without executing):
95	```bash
96	python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
97	--recommendation '{"token_id":"TOKEN","side":"YES","size_usd":50}' --dry-run
98	```
99
100	## Risk Rules (Built In)
101
102	\| Rule \| Default \| Purpose \|
103	\|------\|---------\|---------\|
104	\| Max position size \| 10% of portfolio \| No single bet too large \|
105	\| Max drawdown \| 30% \| Stop trading if losing too much \|
106	\| Max concurrent positions \| 5 \| Diversification \|
107	\| Daily loss limit \| 5% of starting balance \| Prevent tilt \|
108	\| Max single market exposure \| 20% of portfolio \| No concentration \|
109	\| Human approval threshold \| 15% of portfolio \| Large trades need confirmation \|
110
111	Override with `--force` flag or by passing custom risk_config on init.
112
113	## How It Works
114
115	1. Real prices: Fetches live order book from `clob.polymarket.com`
116	2. Book walking: Market orders simulate fills by walking the order book (not mid-price)
117	3. Fee modeling: Default 0% (most markets), configurable for crypto markets
118	4. SQLite persistence: Portfolio at `~/.polymarket-paper/portfolio.db`
119	5. Risk engine: Every trade validated against configurable risk rules
120
121	## API Reference
122
123	All scripts support `--json` for machine-readable output. Key Python functions:
124
125	- `paper_engine.init_portfolio(balance, name)` — Create portfolio
126	- `paper_engine.place_order(token_id, side, size, price)` — Ex

People who liked this also viewed

6 picks

Type

polymarket-paper-trader

170installs10forks

View on GitHub

How to install polymarket-paper-trader?

mjunaidca/polymarket-skills/polymarket-paper-trader

$npx -y skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Polymarket Paper Trading Engine
2
3	Simulate trades against live Polymarket prices with zero financial risk. No wallet, no keys, no money at stake. Portfolio persists across sessions in SQLite.
4
5	## Quick Start
6
7	### Initialize a Portfolio
8	```bash
9	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000
10	```
11
12	### Buy Shares (Market Order)
13	```bash
14	# Buy $50 of YES shares using live order book prices
15	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
16	--action buy --token TOKEN_ID --side YES --size 50 \
17	--reason "High confidence based on news analysis"
18	```
19
20	### Buy Shares (Limit Order)
21	```bash
22	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
23	--action buy --token TOKEN_ID --side YES --size 50 --price 0.45 \
24	--reason "Value buy below fair price estimate"
25	```
26
27	### Check Portfolio
28	```bash
29	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio
30	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio --json
31	```
32
33	### Close a Position
34	```bash
35	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
36	--action close --token TOKEN_ID --reason "Taking profit"
37	```
38
39	### View Trade History
40	```bash
41	python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action trades
42	```
43
44	### Performance Report
45	```bash
46	python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py
47	python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py --json
48	```
49
50	### Portfolio Health Check (Session Start)
51	```bash
52	python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py
53	python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py --json
54	```
55	Runs the full session-start workflow in one command: loads portfolio, fetches live prices, updates DB, calculates drawdown, checks stop losses, evaluates all risk limits. Returns GREEN/YELLOW/RED status.
56
57	## Finding Token IDs
58
59	Token IDs come from the Polymarket Gamma API. To find them for a market:
60
61	```bash
62	# Search for markets
63	curl -s 'https://gamma-api.polymarket.com/markets?limit=5&active=true&closed=false&order=volume24hr&ascending=false' \| python3 -c "
64	import sys, json
65	for m in json.load(sys.stdin):
66	tokens = json.loads(m['clobTokenIds'])
67	prices = json.loads(m['outcomePrices'])
68	print(f\"{m['question'][:60]}\")
69	print(f\" YES token: {tokens[0]} price: {prices[0]}\")
70	print(f\" NO token: {tokens[1]} price: {prices[1]}\")
71	print()
72	"
73	```
74
75	Or use the polymarket-scanner skill to discover markets first.
76
77	## Execute Strategy Recommendations
78
79	The executor takes structured recommendations from strategy advisors:
80
81	```bash
82	python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
83	--recommendation '{
84	"token_id": "TOKEN_ID",
85	"side": "YES",
86	"action": "BUY",
87	"size_usd": 50,
88	"confidence": 0.75,
89	"reasoning": "Momentum signal detected",
90	"strategy": "momentum"
91	}'
92	```
93
94	Dry run (validates without executing):
95	```bash
96	python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
97	--recommendation '{"token_id":"TOKEN","side":"YES","size_usd":50}' --dry-run
98	```
99
100	## Risk Rules (Built In)
101
102	\| Rule \| Default \| Purpose \|
103	\|------\|---------\|---------\|
104	\| Max position size \| 10% of portfolio \| No single bet too large \|
105	\| Max drawdown \| 30% \| Stop trading if losing too much \|
106	\| Max concurrent positions \| 5 \| Diversification \|
107	\| Daily loss limit \| 5% of starting balance \| Prevent tilt \|
108	\| Max single market exposure \| 20% of portfolio \| No concentration \|
109	\| Human approval threshold \| 15% of portfolio \| Large trades need confirmation \|
110
111	Override with `--force` flag or by passing custom risk_config on init.
112
113	## How It Works
114
115	1. Real prices: Fetches live order book from `clob.polymarket.com`
116	2. Book walking: Market orders simulate fills by walking the order book (not mid-price)
117	3. Fee modeling: Default 0% (most markets), configurable for crypto markets
118	4. SQLite persistence: Portfolio at `~/.polymarket-paper/portfolio.db`
119	5. Risk engine: Every trade validated against configurable risk rules
120
121	## API Reference
122
123	All scripts support `--json` for machine-readable output. Key Python functions:
124
125	- `paper_engine.init_portfolio(balance, name)` — Create portfolio
126	- `paper_engine.place_order(token_id, side, size, price)` — Ex

People who liked this also viewed

6 picks

Type