Prediction (Polymarket)¶
Discover and browse Prediction markets on Polymarket, check real-time prices, and view positions with P&L tracking.
Ready to trade? Polymarket orders settle in pUSD (USDC-backed collateral), so you wrap USDC into pUSD before your first buy. See Trading → Collateral: Wrap And Unwrap and Trading → Buy.
Discover Markets¶
The discover command supports 7 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 |
traders |
Leaderboard by volume and P&L | --limit, --show-wallet-address |
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:
View top traders:
Show full trader wallet addresses in table output:
See what a wallet holds:
View a wallet's recent trades:
Filters and Sorting¶
Apply filters across lenses:
bullpen polymarket discover --min-liquidity 10000 --min-volume 50000
bullpen polymarket discover --sort ending-soon --limit 5
bullpen 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
--------------------------------------------------------------------------------------------
Example BTC daily price market Yes 65¢ / No 35¢ $1.2M $500.0K Today
Example ETH market cap market Yes 42¢ / No 58¢ $800.5K $320.0K This week
JSON output for scripts:
Positions¶
View active, closed, or redeemable prediction market positions for a wallet.
Active Positions¶
# View your own positions (address from stored credentials)
bullpen polymarket positions
# View another wallet's positions
bullpen polymarket positions --address 0xABC...
# Compare source views for your wallet
bullpen polymarket positions --source bullpen
bullpen polymarket positions --source polymarket
Output:
Positions (2 open, Total P&L: +$123.45)
Source: polymarket
Redeemable: 2 positions ($45.00)
Market Outcome Shares Entry Now Value P&L ROE
-----------------------------------------------------------------------------------------------------------
Example BTC daily price market Yes 50.0 $0.60 $0.65 $32.50 +$2.50 +8.3%
Example ETH market cap market No 100.0 $0.30 $0.35 $35.00 +$5.00 +16.7%
Closed Positions¶
bullpen polymarket positions --closed
# Or for another wallet
bullpen polymarket positions --address 0xABC... --closed
Output:
Portfolio Value: $1234.56 | Cash: $500.00 | Unrealized P&L: +$123.45
Market Outcome Result Shares Invested Payout P&L P&L %
------------------------------------------------------------------------------------------------------
Example resolved BTC market Yes Profit 80.0 $48.00 $80.00 +$32.00 +66.7%
Will SOL reach $500? No Loss 20.0 $14.00 $0.00 -$14.00 -100.0%
Redeemable Positions¶
Show only positions ready to redeem (resolved markets with winning outcomes):
Redeemable rows are candidates, not proof that a relayer submission will
succeed. Use bullpen polymarket redeem --dry-run --output json for the plan
and keep live-submit output for support if a condition still fails.
Source Selection¶
bullpen polymarket positions defaults to the public Polymarket Data API; use --source polymarket for current exchange-facing exposure. Use --source bullpen to opt into Bullpen's experimental authenticated, server-aggregated view with realized P&L in summary.realized_pnl. The Bullpen source may lag active-position reconciliation after recent trades; when it detects stale active rows, JSON may include summary.data_warning. Large accounts should treat the current reconciliation as one-page bounded and compare against --source polymarket before making liquidation or redeem decisions.
Active Polymarket JSON omits summary.realized_pnl because closed rows are not fetched for that snapshot; use --closed when you need closed-row realized P&L from Polymarket.
JSON output includes both the backwards-compatible top-level source and _meta.source. Branch scripts on _meta.source when comparing Bullpen and Polymarket views.
JSON Output¶
bullpen polymarket positions --output json
bullpen polymarket positions --source polymarket --output json
Non-streaming commands that support --output json emit a single JSON
document. Commands that are inherently interactive, raw/script-oriented, or
streaming reject JSON mode instead of mixing prompt text into JSON output.
Polymarket API Contract¶
Bullpen documents Polymarket command output as one of three contracts:
| Contract | Meaning |
|---|---|
exact |
The command or internal adapter matches the official Polymarket endpoint's method, parameters, and response shape. |
normalized |
Bullpen uses a Polymarket API or SDK path, then returns stable Bullpen field names or an envelope for CLI and agent use. |
proxied |
Bullpen routes through Bullpen services for auth, safety, or trade execution instead of calling the upstream endpoint directly. |
Prediction trade commands such as buy, sell, limit-buy, and limit-sell
are proxied. CLOB read commands such as prices, books, balances, orders, and
rewards may be exact or normalized depending on the command page. Treat the
command page and JSON examples as the contract for automation.
Search¶
Search across prediction markets and trader profiles.
bullpen polymarket search "bitcoin"
bullpen polymarket search "trump" --type market --status active
bullpen 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.
bullpen polymarket search "bitcoin" --type market --limit 5
bullpen polymarket event <EVENT_OR_MARKET_SLUG>
List Events¶
List and filter prediction market events. The default returns active/open events only.
bullpen polymarket events
bullpen polymarket events --include-closed --limit 25
bullpen polymarket events --closed --tag politics
bullpen polymarket events --output json
Use --include-closed when you want resolved events mixed into the list. discover --output json includes event-level active and closed fields when available, so scripts can filter without drilling into nested markets.
Real-Time Prices¶
Quick price check for a prediction market, showing midpoint, last trade price, bid/ask, and spread for each outcome.
For read-only market data commands, the market argument can be a market slug, numeric Gamma ID, decimal or 0x CLOB token ID, or 0x condition ID.
Output:
<MARKET_SLUG>
Outcome Midpoint Last Trade Bid Ask Spread
------------------------------------------------------
Yes 65¢ 64¢ 64¢ 66¢ 2.0¢
No 35¢ 36¢ 34¢ 36¢ 2.0¢
Filter to a specific outcome:
Market Details¶
Show detailed information about a specific market by slug, numeric Gamma ID, CLOB token ID, or condition ID.
Browse Markets¶
List and filter markets from the Polymarket CLOB.
# List active markets sorted by volume
bullpen polymarket markets --active --sort volume
# Filter by minimum liquidity
bullpen polymarket markets --min-liquidity 50000 --limit 10
# Browse closed markets
bullpen polymarket markets --closed --sort volume_24hr
# Filter by tag
bullpen polymarket markets --tag-id 42 --active
| Flag | Description |
|---|---|
--limit |
Maximum results (default 20) |
--offset |
Pagination offset |
--sort |
Sort by: volume, liquidity, volume_24hr, created_at |
--active |
Only active markets |
--closed |
Only closed markets |
--tag-id |
Filter by tag ID |
--min-volume |
Minimum volume |
--min-liquidity |
Minimum liquidity |
Price History¶
View price history charts for specific market outcomes.
bullpen polymarket price-history <MARKET_SLUG> --outcome Yes
bullpen polymarket price-history <MARKET_SLUG> --outcome No --interval 1w
Intervals: 1m, 1h, 6h, 1d (default), 1w, max
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 polymarket data leaderboard
bullpen polymarket data leaderboard --time-period 7d --limit 10
bullpen polymarket profit --address 0x1111111111111111111111111111111111111111 --window 7d --limit 10 --output json
bullpen polymarket volume --address 0x1111111111111111111111111111111111111111 --window 30d --limit 10 --output json
bullpen polymarket user-pnl --address 0x1111111111111111111111111111111111111111 --interval all --fidelity 1h --output json
Leaderboard --time-period values: 1d, 7d, 30d, 90d, all (default)
profit --window values: all, 30d, 7d, 1d.
volume --window values: all, 30d, 7d.
These commands do not accept 90d; use bullpen polymarket data leaderboard --time-period 90d for 90-day ranking.
user-pnl / pnl-series values: --interval all|1m|1w|1d|12h|6h|max; --fidelity 1d|18h|12h|3h|1h.
Analytics commands such as leaderboards, trader profiles, smart money,
open interest, and event-level volume live under bullpen polymarket data.
Address-level public leaderboard rows use first-class commands:
bullpen polymarket profit, bullpen polymarket volume, and
bullpen polymarket user-pnl. These commands read the same public Polymarket
leaderboard and user-PnL APIs used by the web app. They are distinct from
event top-holder analytics, Bullpen account PnL, and closed-position
accounting.
Trader Profiles¶
Look up detailed statistics for any trader by wallet address.
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
and the prediction_analytics experimental feature:
bullpen experimental enable prediction_analytics
bullpen polymarket data smart-money
bullpen polymarket data smart-money --type top_traders --category crypto
bullpen polymarket data 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 polymarket limit-buy <MARKET_SLUG> Yes --price 0.45 --shares 100
bullpen polymarket limit-sell <MARKET_SLUG> Yes --price 0.65 --shares 50
Limit orders currently require at least 5 shares.
Price range: market tick-size dependent (in dollars). Supported expiration values are gtc (good til canceled, default), fok, and fak. gtd is reserved and currently rejected because the CLI does not yet accept an explicit expiration timestamp.
Social & Community¶
Comments¶
View comments on markets, events, series, or by a specific user.
# Comments on a market
bullpen polymarket comments <MARKET_SLUG>
# Comments on an event or series
bullpen polymarket comments my-event-slug --event
bullpen polymarket comments my-series-slug --series
# Comments from a specific user
bullpen polymarket comments --user 0xABC...
# Replies to a specific comment
bullpen polymarket comments <MARKET_SLUG> --replies <comment-id>
Filter to high-quality comments using --filtered with trader quality thresholds:
bullpen polymarket comments --filtered --min-pnl 5000 --min-volume 50000
bullpen polymarket comments --filtered --category crypto --following-only
bullpen 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 polymarket feed trades
bullpen polymarket feed trades --min-pnl 10000 --action Buy --min-trade-size 500
# Filtered comment feed
bullpen polymarket feed comments --min-volume 100000 --category politics
bullpen 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.0001–0.9999) |
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 tracker alerts comment
# Set an alert (qualify by PnL and category)
bullpen tracker alerts comment set --min-pnl 5000 --tracked-only
# Only alert on comments from followed users
bullpen tracker alerts comment set --tracked-only
# Set with multiple quality filters
bullpen tracker alerts comment set --min-position-size 10000 --exclude-category sports,culture
# Delete the alert
bullpen tracker alerts comment delete
Available filters for comment set: --min-pnl, --min-volume, --min-predictions, --min-position-value, --min-position-size, --tracked-only, and --exclude-category.
Trade Alerts
Receive notifications when qualifying trades are made:
# View current trade alert
bullpen tracker alerts trade
# Alert on large buys from experienced traders
bullpen tracker alerts trade set --min-pnl 10000 --action Buy --min-trade-size 1000
# Alert only from traders you track
bullpen tracker alerts trade set --tracked-only
# Set with price range and category exclusions
bullpen tracker alerts trade set --min-share-price 0.10 --max-share-price 0.90 --exclude-category culture
# Delete the alert
bullpen tracker alerts trade delete
Available filters for trade set: --min-pnl, --min-volume, --min-predictions, --min-position-value, --min-trade-size, --min-share-price, --max-share-price, --action, --tracked-only, and --exclude-category.
Smart Alerts
Manage broad smart alert preferences for smart money, new wallets, and top traders:
# View current smart alert settings
bullpen tracker alerts smart --dry-run
# Enable smart money and top traders alerts for specific categories
bullpen tracker alerts smart --smart-money true --top-traders true --categories crypto,politics --yes
# Disable new wallet alerts
bullpen tracker alerts smart --new-wallets false --yes
Address Tracking¶
Polymarket address tracking is available under the tracker subcommand. See tracker command docs for full details.
# Track a Polymarket address
bullpen tracker add 0xABC... --nickname "Whale" --notify-trades true
# Stop tracking
bullpen tracker remove 0xABC...
# List tracked addresses
bullpen tracker list
# View trade feed from tracked addresses
bullpen tracker feed
# Update tracking settings
bullpen tracker update 0x1111111111111111111111111111111111111111 --trade-threshold 500
The tracker command also supports wallet groups (tracker groups), watchlist
management (tracker watchlist), alerts (tracker alerts), and Polymarket copy
trading (tracker copy). tracker copy does not create Hyperliquid
subscriptions; Hyperliquid copy trading uses the separate hl copy namespace.
See Prediction Copy Trading for the prediction
market workflow and Copy Trading Boundaries
for the product split.
Activity Feed¶
View your account activity history — trades, redemptions, merges, splits, rewards, conversions, and maker rebates.
# View recent activity (defaults to your own address)
bullpen polymarket activity
# Specify a different address
bullpen polymarket activity --address 0xABC...
# Filter by activity type
bullpen polymarket activity --type trade
bullpen polymarket activity --type trade,redeem,reward
# Filter by side and date range
bullpen polymarket activity --side buy --start 2026-02-01 --end 2026-02-24
# Sort by USDC size
bullpen polymarket activity --sort cash --limit 20
| Flag | Type | Default | Description |
|---|---|---|---|
--address |
string | own | Wallet address |
--limit |
number | 50 |
Maximum results |
--type |
string | Comma-separated types: trade, split, merge, redeem, reward, conversion, maker_rebate | |
--market |
string | Filter by market condition ID (repeatable) | |
--side |
string | Filter by side: buy, sell | |
--start |
string | Start date (ISO 8601 date or unix timestamp) | |
--end |
string | End date (ISO 8601 date or unix timestamp) | |
--sort |
string | Sort by: timestamp, tokens, cash |
Tags & Series¶
Browse Tags¶
List market tags (categories) or discover related tags.
# List all tags
bullpen polymarket tags
# Find tags related to a specific tag
bullpen polymarket tags --related crypto
| Flag | Type | Description |
|---|---|---|
--related |
string | Show tags related to this slug |
Browse Series¶
List event series or view details for a specific series.
# List all series
bullpen polymarket series
# View a specific series by ID
bullpen polymarket series 42
| Arg | Type | Description |
|---|---|---|
ID |
positional | Series ID (optional; omit to list all) |