Prediction Markets¶
Discover and browse Polymarket prediction markets and view positions with P&L tracking.
Discover Markets¶
The discover command supports 8 lenses that provide different views into prediction markets.
Lenses¶
| Lens | Description | Key Flags |
|---|---|---|
all |
Browse all active markets (default) | --search, --category, --sort |
sports |
Sports markets (auto-filtered by tag) | --category, --limit |
crypto |
Crypto markets (auto-filtered by tag) | --category |
pulse |
Biggest price movers | --category |
traders |
Leaderboard by volume and P&L | --limit, --offset |
walletscope |
Markets a specific wallet holds | --address (required) |
flow |
Recent trade activity for a wallet | --address (required) |
eventscope |
Deep-dive into a specific event | --search |
Examples¶
Browse trending markets:
Search for a topic:
View sports markets:
See biggest price movers:
View top traders:
See what a wallet holds:
View a wallet's recent trades:
Filters and Sorting¶
Apply filters across lenses:
bullpen prediction polymarket discover --min-liquidity 10000 --min-volume 50000
bullpen prediction polymarket discover --sort ending-soon --limit 5
bullpen prediction polymarket discover --min-odds 80 --status active
Sort options: volume, volume24h, liquidity, newest, ending-soon
Output¶
Table output (default):
Market Odds Vol 24h Liquidity Ends
--------------------------------------------------------------------------------------------
Will BTC reach $100K by March? Yes 65¢ / No 35¢ $1.2M $500.0K Mar 31
Will ETH flip SOL in TVL? Yes 42¢ / No 58¢ $800.5K $320.0K Apr 15
JSON output for scripts:
Positions¶
View active, closed, or redeemable prediction market positions for a wallet.
Active Positions¶
Output:
Portfolio Value: $1234.56 | Cash: $500.00 | Unrealized P&L: +$123.45
Redeemable: 2 positions ($45.00)
Market Outcome Shares Avg Value P&L P&L %
----------------------------------------------------------------------------------------------
Will BTC reach $100K? Yes 50.0 60¢ $32.50 +$2.50 +8.3%
Will ETH merge succeed? No 100.0 30¢ $35.00 +$5.00 +16.7%
Closed Positions¶
Output:
Portfolio Value: $1234.56 | Cash: $500.00 | Unrealized P&L: +$123.45
Market Outcome Result Shares Invested Payout P&L P&L %
------------------------------------------------------------------------------------------------------
Did BTC hit $50K in 2024? Yes Won 80.0 $48.00 $80.00 +$32.00 +66.7%
Will SOL reach $500? No Lost 20.0 $14.00 $0.00 -$14.00 -100.0%
Redeemable Positions¶
Show only positions ready to redeem (resolved markets with winning outcomes):
JSON Output¶
Search¶
Search across prediction markets and trader profiles.
bullpen prediction polymarket search "bitcoin"
bullpen prediction polymarket search "trump" --type market --status active
bullpen prediction polymarket search "vitalik" --type user --limit 5
Results include both matching markets and trader profiles by default. Use --type market or --type user to filter.
Event Details¶
Get comprehensive details about a specific prediction market event, including all outcomes and their current prices.
Price History¶
View price history charts for specific market outcomes.
bullpen prediction polymarket price-history will-bitcoin-hit-100k --outcome Yes
bullpen prediction polymarket price-history will-bitcoin-hit-100k --outcome No --interval 1w
Intervals: 1h, 6h, 1d (default), 1w
Market Activity¶
Recent Trades¶
View the latest trades on a market:
Top Holders¶
See the biggest position holders:
Leaderboard¶
View top traders ranked by volume and P&L.
bullpen prediction polymarket leaderboard
bullpen prediction polymarket leaderboard --period week --limit 10
Time periods: day, week, month, all (default)
Trader Profiles¶
Look up detailed statistics for any trader by wallet address.
bullpen prediction polymarket profile 0xABC...
bullpen prediction polymarket profile 0xABC... --trades
Shows volume, trade count, win rate, biggest win, and account age. Add --trades for recent trade history.
Smart Money Signals¶
View smart money trading signals and discover top traders. Requires authentication.
bullpen prediction polymarket smart-money
bullpen prediction polymarket smart-money --type top_traders --category crypto
bullpen prediction polymarket smart-money --type new_wallet --limit 10
Signal types:
- aggregated (default) — Aggregated smart money signals
- top_traders — Discover top traders by category
- new_wallet — New wallet activity
Limit Orders¶
Place limit buy and sell orders at a specific price.
bullpen prediction polymarket limit-buy will-bitcoin-hit-100k Yes --price 0.45 --shares 100
bullpen prediction polymarket limit-sell will-bitcoin-hit-100k Yes --price 0.65 --shares 50
Price range: 0.01–0.99 (in dollars). Expiration: gtc (good til canceled, default) or eod (end of day).
Social & Community¶
Comments¶
View comments on markets, events, series, or by a specific user.
# Comments on a market
bullpen prediction polymarket comments will-bitcoin-hit-100k
# Comments on an event or series
bullpen prediction polymarket comments my-event-slug --event
bullpen prediction polymarket comments my-series-slug --series
# Comments from a specific user
bullpen prediction polymarket comments --user 0xABC...
# Replies to a specific comment
bullpen prediction polymarket comments will-bitcoin-hit-100k --replies <comment-id>
Filter to high-quality comments using --filtered with trader quality thresholds:
bullpen prediction polymarket comments --filtered --min-pnl 5000 --min-volume 50000
bullpen prediction polymarket comments --filtered --category crypto --following-only
bullpen prediction polymarket comments --filtered --min-predictions 10
Available --filtered filters: --min-pnl, --min-volume, --min-predictions, --category, --following-only.
Pagination: use --page and --limit (default 20 per page).
Filtered Feeds¶
The feed command provides a filtered stream of recent trades or comments across all markets, with trader quality controls.
# Filtered trade feed
bullpen prediction polymarket feed trades
bullpen prediction polymarket feed trades --min-pnl 10000 --action Buy --min-trade-size 500
# Filtered comment feed
bullpen prediction polymarket feed comments --min-volume 100000 --category politics
bullpen prediction polymarket feed comments --following-only
Common filters for both feed types:
| Filter | Description |
|---|---|
--min-pnl |
Minimum lifetime PnL of the commenter/trader |
--min-volume |
Minimum lifetime volume |
--min-predictions |
Minimum number of predictions made |
--min-position-value |
Minimum current position value |
--category |
Filter by market category |
--exclude-categories |
Comma-separated list of categories to exclude |
Additional filters for the trades feed:
| Filter | Description |
|---|---|
--action |
Trade direction: All, Buy, or Sell |
--min-trade-size |
Minimum trade size in USD |
--min-price / --max-price |
Share price range (0.01–0.99) |
Additional filter for the comments feed:
| Filter | Description |
|---|---|
--following-only |
Limit to users you follow |
Pagination: use --page and --limit (default 20 per page).
Alert Management¶
Configure notifications for trades and comments that match your quality criteria. All alert commands require authentication.
Comment Alerts
Receive notifications when qualifying comments are posted:
# View current comment alert
bullpen prediction polymarket comment-alert
# Set an alert (qualify by PnL and category)
bullpen prediction polymarket comment-alert --set --min-pnl 5000 --category crypto
# Only alert on comments from followed users
bullpen prediction polymarket comment-alert --set --following-only
# Set with multiple quality filters
bullpen prediction polymarket comment-alert --set --min-volume 50000 --min-predictions 20 --exclude-categories sports,culture
# Delete the alert
bullpen prediction polymarket comment-alert --delete
Available filters for --set: --min-pnl, --min-volume, --min-predictions, --min-position-value, --min-position-size, --category, --following-only, --exclude-categories.
Trade Alerts
Receive notifications when qualifying trades are made:
# View current trade alert
bullpen prediction polymarket trade-alert
# Alert on large buys from experienced traders
bullpen prediction polymarket trade-alert --set --min-pnl 10000 --action Buy --min-trade-size 1000
# Alert only from traders you track
bullpen prediction polymarket trade-alert --set --tracked-only
# Set with price range and category exclusions
bullpen prediction polymarket trade-alert --set --min-price 0.10 --max-price 0.90 --exclude-categories culture
# Delete the alert
bullpen prediction polymarket trade-alert --delete
Available filters for --set: --min-pnl, --min-volume, --min-predictions, --min-position-value, --category, --action, --min-trade-size, --min-price, --max-price, --tracked-only, --exclude-categories.
Smart Alerts
Manage broad smart alert preferences for smart money, new wallets, and top traders:
# View current smart alert settings
bullpen prediction polymarket smart-alerts
# Enable smart money and top traders alerts for specific categories
bullpen prediction polymarket smart-alerts --set --categories crypto,politics --smart-money true --top-traders true
# Disable new wallet alerts
bullpen prediction polymarket smart-alerts --set --new-wallet false
Address Tracking¶
Track specific Polymarket addresses and get notified when they trade or comment.
# Track an address
bullpen prediction polymarket track 0xABC...
# Untrack an address
bullpen prediction polymarket track 0xABC... --untrack
# List all tracked addresses
bullpen prediction polymarket track --list
# View recent trades from all tracked addresses
bullpen prediction polymarket track --trades
# Update notification filters for a tracked address
bullpen prediction polymarket track 0xABC... --update-filters --notify-trades true --trade-threshold 500 --action Buy
Notification filters per tracked address:
| Filter | Description |
|---|---|
--notify-comments |
Enable/disable comment notifications |
--notify-trades |
Enable/disable trade notifications |
--trade-threshold |
Minimum trade size in USD for a notification |
--markets |
Comma-separated market slugs to watch |
--category |
Limit to a specific category |
--min-position-size |
Minimum position size |
--action |
Trade direction: All, Buy, or Sell |
Pagination for --list and --trades: use --page and --limit (default 20 per page).