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 a guarantee that a redeem 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.
Live redeem output includes a durable redeem operation ID when a submission is
recorded. If the CLI reports uncertainty after submit, do not replay the redeem.
Inspect the existing attempt with
bullpen polymarket redeem-status <operation-id-or-tx-or-trace> or
bullpen polymarket redeem-status <operation-id-or-tx-or-trace> --output json,
then share the JSON with support if the status remains pending, missing
evidence, reverted, wrong-wallet, or contradictory.
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.
Command Output¶
Treat each command page and its JSON examples as the automation contract. Read
commands such as prices, books, balances, orders, and rewards may return
Polymarket data with Bullpen field names and envelopes that stay stable for
scripts. Trade commands such as buy, sell, limit-buy, and limit-sell
handle account checks, order preparation, and submission through Bullpen before
returning the documented result fields.
Do not branch scripts on backend implementation names. Branch on documented fields, typed errors, and the next action printed by the CLI.
Rewards and reconciliation reads can report uncertainty instead of a shortfall
verdict. When JSON says cross_chain_reward_totals_compared: false or marks
actual rewards as non-comparable, do not subtract claimable/claimed totals from
Polymarket volume evidence; capture the JSON for support or rerun the specific
rewards command after the upstream data source is comparable.
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, public 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 public Polymarket wallet trader analytics by wallet address. This is not Bullpen account identity, a Bullpen account profile, or a local CLI profile.
bullpen polymarket data trader-profile 0xABC...
bullpen polymarket data trader-profile 0xABC... --trades
Shows volume, trade count, win rate, biggest win, and account age. Add
--trades for recent trade history. bullpen polymarket data profile remains
accepted as a compatibility alias; use trader-profile in new examples and
scripts.
Smart Money Signals¶
View smart money trading signals and discover top traders. Requires
authentication and the prediction_analytics experimental feature.
State change: Enable authenticated smart-money analytics reads.
Then inspect smart-money data:
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.
Live: Submit only after the matching limit-buy preview shows the intended market, outcome, price, shares, and expiration.
Preview the matching limit sell:
Live: Submit only after the matching limit-sell preview shows the intended market, outcome, price, shares, and expiration.
Preview first, then submit with --yes only after the JSON matches your
intended market, outcome, price, size, and expiration. Limit orders must meet
the market's current minimum order size.
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:
Review the current setting before changing comment alerts.
State change: Set the comment alert configuration you intend to keep:
Alternative filters can target followed users or exclude categories. Run one
comment set command with the combination you want.
State change: Delete the current comment alert only when you intend to remove it:
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:
Review the current setting before changing trade alerts.
State change: Set the trade alert configuration you intend to keep:
Alternative filters can target tracked traders, price ranges, or category
exclusions. Run one trade set command with the combination you want.
State change: Delete the current trade alert only when you intend to remove it:
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:
Use the same setting flags for preview and live submission. Setting flags
include --smart-money true|false, --new-wallets true|false,
--top-traders true|false, and --categories <LIST>.
Preview a category-filtered smart alert update:
bullpen tracker alerts smart --smart-money true --top-traders true --categories crypto,politics --dry-run
Live: Submit the same category-filtered update only after reviewing the preview.
bullpen tracker alerts smart --smart-money true --top-traders true --categories crypto,politics --yes
Preview disabling new-wallet alerts:
Live: Disable new-wallet alerts only after reviewing the matching preview.
Address Tracking¶
Polymarket address tracking is available under the tracker subcommand. See tracker command docs for full details.
Check the current tracker list before changing tracked addresses.
State change: Add, remove, or update only the tracked address entry you intend to change.
# Track a Polymarket address
bullpen tracker add 0xABC... --nickname "Whale" --notify-trades true
# Stop tracking
bullpen tracker remove 0xABC...
# Update tracking settings
bullpen tracker update 0x1111111111111111111111111111111111111111 --trade-threshold 500
Read the feed after changes when you need to verify tracked-address activity:
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) |