polymarketz

Comprehensive Polymarket prediction market skill — browse trending markets, search events, check real-time odds & prices, view order books, analyze price his...

Security Scan

The skill's code, commands, and required resources line up with its stated Polymarket browsing and trading purpose — but trading requires a locally stored private key and the README/script should be reviewed for how that key is created/stored before you use it.

Purpose & Capability

Name/description (Polymarket browsing + trading) match the included script and SKILL.md. The script calls Polymarket domains (gamma-, data-, clob-) and only requires python3. Requesting no cloud credentials or unrelated binaries is consistent with the stated purpose.

Instruction Scope

SKILL.md instructs the agent/user to run the provided Python CLI for read-only queries and trading. It explicitly documents wallet setup and the path (~/.config/polymarket/wallet.json). The instructions do not attempt to read unrelated system files or environment variables, but they do direct creation/usage of a local wallet file (sensitive).

Install Mechanism

No install spec; this is an instruction-only skill with an included Python script. That's proportionate for a CLI utility — nothing is downloaded at install time and no third-party package installs are requested.

Credentials

The skill requires no environment variables or external credentials, which is appropriate for read-only features. However, trading operations require a private key stored at ~/.config/polymarket/wallet.json per the README. Storing an unencrypted private key on disk is sensitive; the SKILL.md warns the file contains your private key but gives no detail about encryption, permission handling, or whether the key is ever transmitted to non-Polymarket endpoints. This is a proportional need for trading, but high-risk in practice and worth reviewing before using trading features.

Persistence & Privilege

The skill does not request always:true and does not declare elevated platform privileges. It writes/reads its own config under the user's home directory (wallet.json), which is normal for a CLI wallet tool but should be considered sensitive.

Assessment

This skill appears to do what it claims: public read-only market queries plus optional trading using a local Polygon private key. Before enabling trading, review the scripts/polymarket.py wallet-setup and trade code: confirm whether the private key is stored encrypted or plaintext, check file permissions on ~/.config/polymarket/wallet.json, and inspect any network calls during trading to ensure keys/signatures are handled locally and not exfiltrated. If you prefer lower risk, use the read-only commands only (they require no keys), or create a dedicated wallet with minimal funds and gas for testing instead of using your main funds. If you want higher assurance, run the script in an isolated environment and read the full source to verify no hidden endpoints or telemetry are present.

Polymarket Council

Query, analyze, and trade on Polymarket — the world's largest prediction market.

Read-only commands work immediately — no API keys, no install, no setup.

Quick Start

# What's hot right now?
python3 {baseDir}/scripts/polymarket.py trending

# Search any topic
python3 {baseDir}/scripts/polymarket.py search "bitcoin"

# Get detailed odds for a specific market
python3 {baseDir}/scripts/polymarket.py market CONDITION_ID

# Price history
python3 {baseDir}/scripts/polymarket.py history TOKEN_ID --interval 1d --fidelity 60

Commands

Market Discovery (no setup needed)

# Trending markets by volume
python3 {baseDir}/scripts/polymarket.py trending [--limit 20]

# Search markets by keyword
python3 {baseDir}/scripts/polymarket.py search "QUERY" [--limit 10]

# Browse by category/tag
python3 {baseDir}/scripts/polymarket.py category TAG [--limit 20]
# Tags: politics, crypto, sports, pop-culture, business, science, world, ai, elections

# Get full event details (all markets in an event)
python3 {baseDir}/scripts/polymarket.py event SLUG_OR_ID

# Get a single market's details + current prices
python3 {baseDir}/scripts/polymarket.py market CONDITION_ID

# List active events
python3 {baseDir}/scripts/polymarket.py events [--limit 20] [--tag TAG]

Prices & Order Books (no setup needed)

# Current price / odds for a token
python3 {baseDir}/scripts/polymarket.py price TOKEN_ID

# Batch prices for multiple tokens
python3 {baseDir}/scripts/polymarket.py prices TOKEN_ID1 TOKEN_ID2 ...

# Spread (best ask - best bid)
python3 {baseDir}/scripts/polymarket.py spread TOKEN_ID

# Full order book (bids + asks)
python3 {baseDir}/scripts/polymarket.py book TOKEN_ID

# Price history over time
python3 {baseDir}/scripts/polymarket.py history TOKEN_ID [--interval 1d] [--fidelity 60]
# intervals: 1m, 5m, 1h, 1d, 1w  |  fidelity: minutes between data points

# Last trade price
python3 {baseDir}/scripts/polymarket.py last-trade TOKEN_ID

Analytics (no setup needed)

# Open interest for a market
python3 {baseDir}/scripts/polymarket.py open-interest CONDITION_ID

# Top holders of a token
python3 {baseDir}/scripts/polymarket.py holders TOKEN_ID [--limit 10]

# Live volume for an event
python3 {baseDir}/scripts/polymarket.py volume EVENT_ID

# Leaderboard
python3 {baseDir}/scripts/polymarket.py leaderboard [--limit 20]

# Public profile of a trader
python3 {baseDir}/scripts/polymarket.py profile ADDRESS

# Trader's activity / trade history
python3 {baseDir}/scripts/polymarket.py activity ADDRESS [--limit 20]

Trading (requires wallet setup)

First-time setup:

python3 {baseDir}/scripts/polymarket.py wallet-setup

This creates ~/.config/polymarket/wallet.json with your private key (Polygon).

# Check wallet balance
python3 {baseDir}/scripts/polymarket.py balance

# Buy limit order — preview only (no --confirm)
python3 {baseDir}/scripts/polymarket.py trade buy --token TOKEN_ID --price 0.50 --size 10

# Buy limit order — EXECUTE (with --confirm)
python3 {baseDir}/scripts/polymarket.py trade buy --token TOKEN_ID --price 0.50 --size 10 --confirm

# Sell limit order
python3 {baseDir}/scripts/polymarket.py trade sell --token TOKEN_ID --price 0.70 --size 10 --confirm

# Market order — buy $5 worth at best available price
python3 {baseDir}/scripts/polymarket.py trade buy --token TOKEN_ID --amount 5 --market-order --confirm

# View open orders
python3 {baseDir}/scripts/polymarket.py orders [--address ADDRESS]

# Cancel an order
python3 {baseDir}/scripts/polymarket.py cancel ORDER_ID --confirm

# Cancel all orders
python3 {baseDir}/scripts/polymarket.py cancel-all --confirm

# View positions
python3 {baseDir}/scripts/polymarket.py positions [--address ADDRESS]

Example Chat Usage

• "What are the odds Trump wins the 2028 election?"
• "Show me trending markets on Polymarket"
• "Search Polymarket for Bitcoin price predictions"
• "What are the current crypto markets on Polymarket?"
• "Show the order book for [token]"
• "What's the price history for this market over the last week?"
• "Who are the top traders on Polymarket?"
• "Show me open interest for [market]"
• "Buy 10 shares of YES at $0.45 on [market]"
• "What are my positions?"

API Reference

Read-only commands use public APIs (no auth required):

API	Base URL	Purpose
Gamma	https://gamma-api.polymarket.com	Markets, events, tags, search, profiles
Data	https://data-api.polymarket.com	Positions, trades, activity, leaderboards
CLOB	https://clob.polymarket.com	Order books, prices, spreads, price history

Trading commands use authenticated CLOB API endpoints.

Safety Notes

• Real money. Polymarket trades use real USDC on Polygon. Double-check before confirming.
• All trades require --confirm. Without it, you only see a preview.
• Private key security. Your key is stored in ~/.config/polymarket/wallet.json. Protect it.
• Gas fees. On-chain operations require MATIC/POL for gas on Polygon.
• Not financial advice. This tool provides market data. Make your own decisions.