Bullpen CLI Skill¶

This is a live example of the AI agent skill format. For the full format specification, see AI Agent Skill Format Specification.

Wallet model¶

Each Polymarket user has two layers of wallet selection:

Bullpen wallet (owner EOA) — set via bullpen wallet select. Determines which Turnkey-managed signing key is active. A user may have multiple Bullpen wallets in one account.
Polymarket wallet kind (Deposit Wallet vs Safe vs Proxy) — determined automatically by the Bullpen server per owner EOA. Users typically do NOT pick this manually; the server's selection is authoritative. For a given owner, exactly one wallet kind is "active" and all routing uses it. When the user has assets on a non-active wallet kind, the audit + consolidate workflow surfaces and fixes the state.

The server-selected wallet is what every CLI command routes through by default. The --wallet-kind safe|dw override is available only for asset-moving commands (consolidate, sweep-stranded) and is not a trading-wallet switch. Trading commands always follow the server selection.

--wallet <OWNER_EOA> pins the Bullpen owner/signer for automation. It does not override Safe vs Deposit Wallet server selection and does not bypass 1151 / L2_WALLET_DISAGREEMENT wallet-routing guards.

Common user scenarios¶

"My trade was rejected with 'maker address not allowed'" — This usually means the server selected a Deposit Wallet for this user but it has not been activated yet (never traded). The CLI auto-bundles CLOB setup on first trade. If errors persist, run bullpen polymarket activate to set up credentials explicitly.

"I have funds on my Safe AND my Deposit Wallet" — Split-brain state from an older CLI version. Run bullpen polymarket wallet-audit first (dry-run), then bullpen polymarket consolidate --yes to move assets to the server-selected wallet.

"My trade failed with 1151 / server-vs-on-chain wallet disagreement" — Run bullpen polymarket wallet-audit --refresh --output json first. Do not use --wallet as a bypass: --wallet only pins the Bullpen owner EOA and does not override Safe vs Deposit Wallet server selection. If the audit/support path confirms the account should trade from the Deposit Wallet, run bullpen polymarket wallet select --kind dw --yes, then bullpen polymarket activate --yes if the selected wallet has never traded.

"I want my funds on the other wallet, not the one the server picked" — Default to bullpen polymarket consolidate with no --wallet-kind override. Do not add --wallet-kind safe or --wallet-kind dw unless wallet-audit --refresh or Bullpen support explicitly identifies that deployed, owned wallet as the intended asset-movement destination. This override changes only the asset-movement target; it does not change the server-selected trading wallet.

"My first trade fails with credential errors" — Never-traded wallet case. Run bullpen polymarket activate to create CLOB credentials and bundle missing approvals explicitly.

Copy-trade lifecycle¶

Prefer pause over delete. Deleting a subscription is destructive in one specific way that affects open positions.

Delete affects the subscription record only. It does NOT touch open Polymarket positions — those live on the user's Polymarket wallet, not the subscription. Open positions remain after delete.
Delete DOES stop mirror-sells. If the subscription has exit_behavior = mirror_sells, future mirror-sell events from the followed trader stop firing once the subscription is deleted. Open positions become manual-exit-only. Warn users about this before deleting.
pause is the non-destructive alternative. bullpen tracker copy pause <ADDRESS> moves the subscription to Paused. resume restores it to Active. Subscription config (including exit_behavior) is preserved.
Execution history retention on delete is server-side. The CLI cannot guarantee history rows persist after delete; do not promise retention unless Bullpen support confirms it for the account.

Pre-delete snapshot recipe. Before any destructive action on a copy-trade subscription, capture state so the user can rebuild if needed:

bullpen tracker copy list --output json > copy-list-snapshot.json
bullpen tracker copy executions --output json > copy-executions-snapshot.json
bullpen polymarket positions --output json > positions-snapshot.json

Decision tree: - Want to stop copying temporarily? → pause (reversible) - Subscription is misconfigured and you want a clean restart? → pause first, then either update or delete-and-recreate - Open positions need to exit on the followed trader's signals? → DO NOT delete; pause only

Instructions¶

Quick Start (if user is new)¶

If the user hasn't set up Bullpen yet, guide them through this canonical order:

Install CLI: brew install BullpenFi/tap/bullpen
Log in: bullpen login
Verify session: bullpen status
Install AI skills: bullpen skill install
Restart Claude/Codex so it picks up the new skills, then ask it anything

To update an existing install: bullpen upgrade (updates the binary and skills automatically).

Current Wallet-Selection Guidance¶

The DW-vs-Safe split-brain workflow is the current wallet-recovery path:

Server-driven wallet selection. The server authoritatively selects each user's active Polymarket wallet kind (Deposit Wallet or Safe). The CLI consults the server first and falls back to on-chain bytecode detection only when the server has no selection. bullpen status shows the server-selected status; a split-brain warning is emitted if assets are detected on a non-selected wallet.
bullpen polymarket wallet-audit --refresh --output json. Read-only audit command: enumerates all owner EOAs and all wallet kinds (Deposit Wallet / Safe / Proxy / signer EOA), reads on-chain balances + CTF positions + CLOB credit per wallet, and reports assets stranded on a non-server-selected wallet. Use this first when a user reports 1151 / L2_WALLET_DISAGREEMENT, balance discrepancies, missing positions, or "I migrated but my funds are gone." --refresh forces a fresh server wallet-selection read instead of trusting cached routing state.
bullpen polymarket wallet select --kind dw --yes. Explicit server wallet-selection repair. Use only when wallet-audit --refresh or Bullpen support confirms the account should trade from the Deposit Wallet. Then run bullpen polymarket activate --yes if the selected wallet has never traded.
bullpen polymarket consolidate. Asset consolidation orchestrator. Default target is the server-selected wallet for each owner. Idempotent; dry-run by default (--yes required to execute). Handles pUSD / USDC.e / USDC sweep, CTF position on-chain transfer, and CLOB open-order pre-flight cancel. Surfaces CLOB credit as a warning with a web-app deep link (CLOB credit cannot be moved on-chain). Default to no --wallet-kind override. --wallet-kind safe|dw is an asset-movement override only; it does not override the server-selected trading wallet and should be used only when wallet-audit --refresh or Bullpen support explicitly identifies a deployed, owned destination.
bullpen polymarket activate. First-trade activation for a never-used wallet — creates CLOB API credentials and bundles missing setApprovalForAll calls. Usually invoked transparently on first trade; standalone command exists for explicit setup.
Split-brain warning on status and login banner. bullpen status emits a split-brain warning when assets are detected on a non-server-selected wallet. Use --no-split-brain-warning to suppress in scripts.
Strengthened deploy-deposit-wallet gate. The command refuses when the server's selection is already a Deposit Wallet (re-deployment is a no-op and can confuse the registry). Use bullpen polymarket reregister-deposit-wallet if the server-side registry is out of sync.
sweep-stranded --to defaults to server-selected wallet. The default destination is the server-selected Polymarket wallet.
bullpen polymarket wallet check superseded. wallet-audit is the recommended diagnostic. wallet check is a legacy/backcompat command; use it only when Bullpen support asks for old-format output.

1151 repair workflow: For 1151: server-vs-on-chain wallet disagreement or L2_WALLET_DISAGREEMENT: (1) bullpen polymarket wallet-audit --refresh --output json; (2) do not retry with --wallet as a bypass, because it does not override Safe vs Deposit Wallet server selection; (3) if the audit/support path confirms Deposit Wallet should be selected, run bullpen polymarket wallet select --kind dw --yes; (4) run bullpen polymarket activate --yes if the selected wallet has never traded; (5) retry the blocked operation.

Wallet diagnostic workflow: For users with balance discrepancies or split-brain state without 1151: (1) bullpen polymarket wallet-audit to identify the trading wallet and any stranded assets; (2) bullpen polymarket consolidate (dry-run first, then --yes) to move assets to the server-selected wallet; (3) bullpen polymarket preflight to confirm approvals and pUSD balance; (4) bullpen polymarket activate if the wallet has never traded.

Collateral management workflow: For users adding pUSD: (1) bullpen polymarket preflight to check current balance and approvals; (2) bullpen polymarket wrap <AMOUNT> --preview --output json to inspect the no-submit approve + wrap batch; (3) bullpen polymarket wrap <AMOUNT> --yes to convert USDC to pUSD; (4) if wallet-audit recommends migration, run bullpen polymarket migrate --preview --output json before any bullpen polymarket migrate --yes.

Step 1: Identify What the User Wants to Do¶

Route to the right reference based on the user's intent:

Getting started (install, authenticate, configure, install skills): - references/getting-started.md

Find and research markets (discover, search, events, prices, tags, series): - references/discovery-and-research.md

Trade (buy, sell, limit orders, redeem, CTF split/merge, bridge funds): - references/trading.md

Manage portfolio and orders (positions, open orders, cancel, watchlist, activity): - references/portfolio-and-orders.md

Social and signals (comments, feeds, alerts, tracker, leaderboard): - references/social-and-signals.md

Account and platform (auth, config, portfolio balances, points, status): - references/platform-and-account.md

Wallet management (list wallets, select primary, switch chains): - references/platform-and-account.md

Step-by-step tutorials (complete workflows with exact commands): - references/trading-tutorial.md — discover → trade → manage → redeem - references/copy-trading-tutorial.md — find traders → copy → monitor → manage - references/tracker-tutorial.md — track wallets → groups → watchlist → alerts

Scripting and automation (JSON output, jq piping, batch workflows): - references/scripting-and-automation.md - references/cross-protocol-sizing.md — unit semantics for Polymarket, Hyperliquid, and Solana trade sizing

Hyperliquid / perpetuals (perps trading, positions, funding, balances, orders, live watch, funds movement): - references/hyperliquid.md

Solana (experimental Solana balance/portfolio, token price/metadata by mint, Jupiter Ultra swaps, activity history, withdraw, deposit): - references/solana.md

Bracket contests (March Madness, tournament picks, fill bracket, leaderboard): - references/bracket-contest.md

Community and support (Discord, X/Twitter, file a ticket, report a bug): - references/community.md

Diagnostics and troubleshooting (collect system info, debug errors, file support tickets): - references/diagnostics.md

Troubleshooting (deposit not showing, wrong asset, account access, CLI errors): - references/troubleshooting.md

Many tasks span multiple categories. Read all relevant references before acting.

Step 2: Key Rules¶

Before running any command, keep these rules in mind:

Most data and automation commands support --output json for machine-readable output. Default is table; raw/script, interactive, and explicitly unsupported streaming commands reject JSON mode.
Trading commands require --yes to skip interactive confirmation (essential for automation).
Authentication is required for any write operation (trading, orders, alerts, comments).
Read-only operations (discover, search, price, event, default and server-filtered leaderboards) work without local auth when the server accepts anonymous reads. Filtered social feeds/comments still require login.
Market slugs remain the primary identifier (e.g., will-bitcoin-hit-100k). Read-only market data commands such as market, price, orderbook, holders, trades, price-history, and candles also accept numeric Gamma IDs, decimal or 0x CLOB token IDs, and 0x condition IDs. Trading and money-moving commands still use market slugs/outcomes unless their help says otherwise.
Outcomes are specified by name: Yes, No, or the outcome text for multi-outcome markets. Aliases work too: Y/N, True/False, 1/0.
Limit prices must match each market's tick size (representing cents per share / probability).
Global flags: --env staging|production, --config <path> work on all commands. If --config is omitted, BULLPEN_CONFIG is used before the default ~/.bullpen/config.toml. Explicit --config and BULLPEN_CONFIG paths fail closed when missing instead of silently loading defaults. Credentials still resolve via BULLPEN_HOME, so set BULLPEN_HOME too when isolating a session.

Step 3: Execute¶

Run commands via bullpen CLI. If the CLI is not installed, start with references/getting-started.md.

Quick Command Map¶

Use this for simple queries without reading full references:

bullpen prediction ... is a visible alias for bullpen polymarket ...; help output may show the canonical polymarket form.

Intent	Command
Install CLI	`brew install bullpenfi/tap/bullpen`
Log in	`bullpen login`
Check auth status	`bullpen status` (shows wallet kind, server-selected status, split-brain warning if applicable, Deposit Wallet address, and Solana enablement)
Check Polymarket platform status	`bullpen polymarket status` (public read-only status page with per-component health)
Discover markets	`bullpen polymarket discover` (default hides untradeable markets; use `--include-untradeable` to include them, prefixed with `[NOT TRADEABLE]`)
Discover sports markets	`bullpen polymarket discover sports` (Sports markets have a 1-second matching delay by design. If a sports order doesn't fill immediately, the CLI prints a hint to retry with a more aggressive price.)
Discover crypto markets	`bullpen polymarket discover crypto`
Search markets	`bullpen polymarket search "bitcoin"`
Get event details	`bullpen polymarket event <SLUG>`
Check price	`bullpen polymarket price <MARKET>`
Check price history	`bullpen polymarket price-history --outcome <OUTCOME> <MARKET>`
View market details	`bullpen polymarket market <MARKET>`
List markets with filters	`bullpen polymarket markets --active --sort volume`
Browse tags	`bullpen polymarket tags`
Browse series	`bullpen polymarket series`
Buy shares	`bullpen polymarket buy <SLUG> <OUTCOME> <USD_AMOUNT> [--max-price <PRICE>]`
Sell shares	`bullpen polymarket sell <SLUG> <OUTCOME> <SHARES> [--min-price <PRICE>]` or `--max`
Limit buy	`bullpen polymarket limit-buy --price 0.45 --shares 100 <SLUG> <OUTCOME>`
Limit sell	`bullpen polymarket limit-sell --price 0.65 --shares 50 <SLUG> <OUTCOME>`
View positions	`bullpen polymarket positions`
View open orders	`bullpen polymarket orders`
Cancel an order	`bullpen polymarket orders --cancel <ORDER_ID>`
Cancel all orders	`bullpen polymarket orders --cancel-all --yes`
Redeem resolved	`bullpen polymarket redeem` (auto-probes all of your wallets for outcome tokens and reports which wallet received the payout)
View watchlist	`bullpen tracker watchlist`
Add to watchlist	`bullpen tracker watchlist add <SLUG>`
View activity	`bullpen polymarket activity` (also: `history`)
View typed trade history	`bullpen polymarket data my-trades [--type trade\\|redeem\\|split\\|merge\\|convert]`
View recent trades	`bullpen polymarket trades <MARKET>`
View top holders	`bullpen polymarket holders <MARKET>`
View event top holders	`bullpen prediction event-top-holders <EVENT_ID_OR_SLUG>`
View comments	`bullpen polymarket comments <SLUG>`
View trade feed	`bullpen polymarket feed trades`
View comment feed	`bullpen polymarket feed comments`
Leaderboard	`bullpen polymarket data leaderboard`
Trader profile	`bullpen polymarket data profile <ADDRESS>`
Wallet stats	`bullpen prediction wallet-stats <ADDRESS>`
Smart money signals	`bullpen polymarket data smart-money`
Portfolio balances	`bullpen portfolio balances`
Portfolio P&L	`bullpen portfolio pnl`
Current quests	`bullpen quests`
Quest history	`bullpen quests history`
List wallets	`bullpen wallet list`
View wallet addresses	`bullpen wallet addresses`
Import wallet	`bullpen wallet import --chain evm`
Rename wallet	`bullpen wallet nickname <ADDRESS> "Name"`
Hide wallet	`bullpen wallet hide <ADDRESS>`
Set primary EVM wallet	`bullpen wallet select <ADDRESS> --chain evm`
Set primary Solana wallet	`bullpen wallet select <ADDRESS> --chain solana`
View primary wallets	`bullpen wallet info`
Show all 4 wallet addresses + balances	`bullpen wallet show-addresses`
Audit Polymarket wallet state	`bullpen polymarket wallet-audit` (read-only; shows all wallet kinds, on-chain balances, and stranded assets across all owner EOAs; use `--refresh --output json` for 1151)
Repair confirmed DW server selection	`bullpen polymarket wallet select --kind dw --yes` (only after `wallet-audit --refresh` or support confirms DW should be selected; then `bullpen polymarket activate --yes` if needed)
Consolidate assets to server-selected wallet	`bullpen polymarket consolidate` (dry-run; add `--yes` to execute; default to no `--wallet-kind`; `--wallet-kind safe\\|dw` is an asset-movement override, not a trading-wallet switch)
First-trade wallet activation	`bullpen polymarket activate` (creates CLOB credentials and bundles approvals; usually auto-invoked on first trade)
Funds balances	`bullpen funds balances`
Deposit funds	`bullpen deposit` (opens web app with correct per-chain routing; the old `funds deposit-address` flow is not available)
Track a trader	`bullpen tracker add <ADDRESS>`
Track with group	`bullpen tracker add <ADDRESS> --group <ID> --nickname "Name"`
List tracked addresses	`bullpen tracker list`
View tracked trades	`bullpen tracker feed`
Manage groups	`bullpen tracker groups`
Create a group	`bullpen tracker groups create "Name" --emoji "🐋"`
Share a group	`bullpen tracker groups share <GROUP_ID>`
Import a group	`bullpen tracker groups import <CODE>`
Browse curated groups	`bullpen tracker groups curated`
View alerts config	`bullpen tracker alerts`
Set trade alert	`bullpen tracker alerts trade set --min-trade-size 5000 --tracked-only`
Set smart alerts	`bullpen tracker alerts smart --smart-money true`
Upgrade CLI	`bullpen upgrade`
List bracket contests	`bullpen polymarket bracket contests --status open`
Auto-fill chalk bracket	`bullpen polymarket bracket fill-chalk <CONTEST_ID> --tiebreaker 145`
Fill bracket from file	`bullpen polymarket bracket fill <CONTEST_ID> --file picks.json`
Bracket summary	`bullpen polymarket bracket summary <CONTEST_ID>`
Submit bracket pick	`bullpen polymarket bracket pick <CONTEST_ID> --slot <SLOT> --winner "Duke"`
Bracket leaderboard	`bullpen polymarket bracket leaderboard <CONTEST_ID>`
Deposit funds	`bullpen deposit` (opens web app)
Join Discord	`open "https://discord.com/invite/bullpen"`
Follow on X	`open "https://x.com/BullpenFi"`
File support ticket	`open "https://bullpen-help.freshdesk.com/support/tickets/new"`
Collect diagnostics	`bullpen status --output json` + `bullpen config show --output json`
Copy a trader	`bullpen tracker copy start <ADDRESS> --preset recommended`
List copy trades	`bullpen tracker copy list` (shows stopped time/reason when available)
View copy trade status	`bullpen tracker copy status <ADDRESS>`
Pending confirmations	`bullpen tracker copy pending`
Confirm copy trade	`bullpen tracker copy confirm <ID>`
Watch copy trades live	`bullpen tracker copy watch`
Copy trade stats	`bullpen tracker copy stats`
Copy trade risk config	`bullpen tracker copy risk`
Pause a copy trade (non-destructive)	`bullpen tracker copy pause <ADDRESS>` (preserves the subscription and any future mirror-sells; safer than delete)
Resume a paused copy trade	`bullpen tracker copy resume <ADDRESS>`
Snapshot before destructive action	`bullpen tracker copy list --output json` + `bullpen tracker copy executions --output json` + `bullpen polymarket positions --output json`
Delete a copy trade (last resort)	`bullpen tracker copy delete <ADDRESS>` (see "Copy-trade lifecycle" note below)
View orderbook	`bullpen polymarket orderbook <MARKET>`
Preview trade fees	`bullpen polymarket preview <SLUG> <OUTCOME> <AMOUNT>`
Browse categories	`bullpen polymarket categories`
List events	`bullpen polymarket events`
View candles	`bullpen polymarket candles --outcome Yes <MARKET>`
List sports	`bullpen polymarket sports-list`
List teams	`bullpen polymarket teams --league nba`
Preview wrap USDC to pUSD	`bullpen polymarket wrap <AMOUNT> --preview --output json`
Wrap USDC to pUSD	`bullpen polymarket wrap <AMOUNT> --yes`
Preview unwrap pUSD to USDC	`bullpen polymarket unwrap <AMOUNT> --preview --output json`
Unwrap pUSD to USDC	`bullpen polymarket unwrap <AMOUNT> --yes`
Sweep stranded ERC-20 from Safe	`bullpen polymarket sweep-stranded --token <SYMBOL_OR_ADDR> --amount <TOKEN_AMOUNT> --yes` (amount is in token units; default destination is server-selected wallet; use `--to <ADDR>` to override)
Check trade readiness	`bullpen polymarket preflight`
Check V2 approvals	`bullpen polymarket approve --check`
Verify email	`bullpen verify-email`
Install AI skills	`bullpen skill install`
List AI skills	`bullpen skill list`
Manage group addresses	`bullpen tracker groups add-address <GROUP_ID> <ADDR>`
Auth diagnostics	`bullpen doctor auth`
Force logout	`bullpen logout --force`
Hyperliquid balances	`bullpen hl balances`
Hyperliquid positions / status	`bullpen hl status`
Hyperliquid price	`bullpen hl price <COIN>`
Hyperliquid funding rates	`bullpen hl funding`
Preview a long perp	`bullpen hl long <COIN> --size <USD_NOTIONAL> --preview`
Open a long perp	`bullpen hl long <COIN> --size <USD_NOTIONAL> --yes`
Open a post-only long limit	`bullpen hl long <COIN> --size <USD_NOTIONAL> --limit <PRICE> --tif alo --yes`
Preview a long bracket	`bullpen hl long <COIN> --size <USD_NOTIONAL> --tp <PRICE> --sl <PRICE> --preview`
Preview a scale ladder	`bullpen hl scale <COIN> --side long --notional <USD> --start <PRICE> --end <PRICE> --levels <N> --preview`
Place a scale ladder	`bullpen hl scale <COIN> --side long --notional <USD> --start <PRICE> --end <PRICE> --levels <N> --yes`
Open a short perp	`bullpen hl short <COIN> --size <USD> --yes`
Preview a short bracket	`bullpen hl short <COIN> --size <USD_NOTIONAL> --tp <PRICE> --sl <PRICE> --preview`
Close a perp position	`bullpen hl close <COIN> --yes`
Close with post-only limit	`bullpen hl close <COIN> --limit <PRICE> --tif alo --yes`
Flatten all HL positions	`bullpen hl close-all --yes`
Cancel all HL orders	`bullpen hl cancel-all --yes`
Watch HL fills live	`bullpen hl watch fills`
Watch HL orderbook live	`bullpen hl watch orderbook <COIN>`
Watch HL trades live	`bullpen hl watch trades <COIN>`
Watch HL candles live	`bullpen hl watch candles <COIN>`
Transfer spot <-> perp	`bullpen hl transfer --amount <USD> --to perp --yes`
Withdraw from Hyperliquid	`bullpen hl withdraw --amount <USD> --yes`
Deposit to Hyperliquid via bridge	`bullpen hl deposit --amount <USD> --yes`

Hyperliquid default account reads and writes use the active EVM wallet as the signing address. hl status, hl balances, hl stats, and hl topology JSON can include optional signer_address for authenticated default-account reads; explicit --address public reads omit it. Table mode can show Signing as: / Reading as: context and warns on multiple EVM wallets unless --no-multi-wallet-warning or JSON output is used.

Solana commands are opt-in. Run bullpen experimental enable solana once; the setting writes [experimental] solana = true to the Bullpen config and persists across upgrades.

Hyperliquid transfer verification waits 1.5 seconds before polling and defaults to 5 attempts at 1500 ms. Advanced tuning uses BULLPEN_HYPERLIQUID_TRANSFER_VERIFY_ATTEMPTS (clamped 1-20) and BULLPEN_HYPERLIQUID_TRANSFER_VERIFY_POLL_MS (clamped 250-10000); raising attempts or lowering the interval increases Hyperliquid /info request load.

Examples¶

Example 1: First-Time Setup and First Trade¶

User says: "Set up Bullpen and buy Yes on the Bitcoin market"

Actions: 1. Install: brew install bullpenfi/tap/bullpen 2. Log in: bullpen login 3. Verify: bullpen status 4. Check readiness with bullpen polymarket preflight (checks pUSD balance and V2 approvals) 5. If pUSD balance is $0, preview the wrap first: bullpen polymarket wrap 10 --preview --output json, then execute with bullpen polymarket wrap 10 --yes 6. Find the market: bullpen polymarket search "bitcoin" 7. Check the price: bullpen polymarket price will-bitcoin-hit-100k 8. Buy shares: bullpen polymarket buy will-bitcoin-hit-100k Yes 10 --yes 9. Verify position: bullpen polymarket positions

Example 2: Market Research Workflow¶

User says: "Research the most active prediction markets"

Actions: 1. Discover trending: bullpen polymarket discover --sort volume --limit 10 --output json 2. Pick an event and drill down: bullpen polymarket event <SLUG> --output json 3. Check pricing: bullpen polymarket price <MARKET> --output json 4. View recent trades: bullpen polymarket trades <MARKET> --output json 5. Check top holders: bullpen polymarket holders <MARKET> --output json 6. Check smart money: bullpen polymarket data smart-money --output json

Example 3: Execute a Buy and Verify¶

User says: "Buy $50 of Yes shares on will-trump-win and show me the position"

Actions: 1. Preview the order: bullpen polymarket buy will-trump-win Yes 50 --preview 2. Execute: bullpen polymarket buy will-trump-win Yes 50 --yes 3. Check position: bullpen polymarket positions --output json

Example 4: Set Up Smart Money Alerts¶

User says: "Alert me when whales trade on crypto markets"

Current commands: bullpen polymarket smart-alerts is live. Use bullpen tracker alerts smart for tracker-based smart alert settings.

Actions: 1. Enable smart alerts: bullpen tracker alerts smart --smart-money true --top-traders true 2. Track specific traders: bullpen tracker add <ADDRESS> 3. Check current alerts: bullpen tracker alerts --output json

Example 5: Automated Portfolio Monitoring¶

User says: "Script that checks my positions and finds markets to trade"

# Check positions
bullpen polymarket positions --output json | jq '.positions[] | {market: .title, shares: .size, value: .current_value}'

# Find high-volume active markets
bullpen polymarket discover --sort volume --min-liquidity 100000 --output json | jq '.events[].markets[]? | {title, volume, liquidity}'

# Check prices on watchlist
bullpen tracker watchlist --output json | jq -r '.items[].Prediction.slug' | while read slug; do
  bullpen polymarket price "$slug" --output json
done

# Get filtered leaderboard ideas
bullpen polymarket data leaderboard --time-period 7d --sort copyability --hide-farmers --limit 5 --output json

Example 6: Diagnose and Resolve Split-Brain Wallet State¶

User says: "I migrated to Deposit Wallet but my funds seem to be missing"

Actions: 1. Audit all wallet kinds and balances: bullpen polymarket wallet-audit --refresh --output json 2. Review the report — look for assets on a non-server-selected wallet 3. Dry-run consolidation to confirm the plan: bullpen polymarket consolidate 4. Execute: bullpen polymarket consolidate --yes 5. Confirm trade readiness: bullpen polymarket preflight

If the failure is 1151 / L2_WALLET_DISAGREEMENT, do not treat consolidate --wallet-kind safe as the default repair. Follow the 1151 repair workflow above and use bullpen polymarket wallet select --kind dw --yes only when the refreshed audit or Bullpen support confirms Deposit Wallet selection is intended.

Legacy/backcompat commands¶

bullpen polymarket wallet check — legacy/backcompat; use bullpen polymarket wallet-audit instead unless Bullpen support asks for old-format output
bullpen polymarket migrate-collateral — use bullpen polymarket migrate for collateral migration or bullpen polymarket consolidate for server-selected wallet consolidation

Note: bullpen polymarket reregister-deposit-wallet is NOT deprecated — it remains the explicit fix for users whose server-side Deposit Wallet registry is out of sync.

Troubleshooting¶

Hint Sentinels¶

Bullpen's source may wrap command hints as <<RUN: bullpen ...>> or <<TRY: bullpen ...>> so validation tests can prove the command path exists. Normal CLI output strips those wrappers. If a raw sentinel leaks into stderr/stdout, treat the inner bullpen ... text as the command guidance, do not include the <<RUN: / <<TRY: wrapper when running it, and report the leak as a CLI bug.

Error	Fix
"Not authenticated"	Run `bullpen login`
"Market not found"	The CLI will suggest similar markets ("Did you mean?"). Use slugs from `bullpen polymarket search` or `discover`, not numeric IDs. You can also paste a full Polymarket URL.
"Insufficient balance"	Check `bullpen portfolio balances` and fund via `bullpen deposit` (opens web app)
"Positions API shows 0 shares"	This is an indexing delay warning after a recent trade, not a real error. The order may still succeed. Wait a few seconds and retry, or run `bullpen polymarket positions` to verify holdings.
"Rate limited"	Wait 30 seconds and retry; reduce request frequency in scripts
"Order failed"	Run `bullpen polymarket preflight` to check approvals and balance
"Approval needed"	Run `bullpen polymarket approve` before first sell on a market
"Polymarket CLOB API-key creation failed (HTTP 403)"	Visit `polymarket.com` with the connected wallet, open Settings -> API Keys, create an API key, then rerun the CLI command
"Polymarket relayer reports degraded service" or "Polymarket relayer returned HTTP 5xx"	Retry in a few minutes; this maps relayer `STATE_FAILED`, rate limiting, or upstream 5xx to a retryable outage
"polymarket_status" in an error	Polymarket's status page is degraded for a trading-relevant component; retry shortly and check https://status.polymarket.com
"Closed-only / geo-restricted"	Run `bullpen doctor auth` and contact Polymarket support; Bullpen support can help collect diagnostics
Turnkey 404 / "case sensitive"	Upgrade and retry the failing command; current builds normalize wallet-address casing before signing.
"spender not in allowed list" on Safe wallets	Run `bullpen upgrade` then `bullpen polymarket approve --yes`.
"I logged out and now my balance shows $0"	Run `bullpen upgrade`; current builds refresh stale wallet-routing automatically on the next command.
"Copy-trade 100x portfolio inflation"	Run `bullpen upgrade`; current builds prefer native Hyperliquid portfolio values.
"Bullpen is not authorized to perform: ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2"	Contact `support@bullpen.fi`; this points to a server-side Turnkey policy issue that support can repair.
"Where are my funds?" / `funds balances` shows wrong amount after a server-side migration	Run `bullpen polymarket wallet-audit`. Lists all wallet addresses (signer EOA + Safe + Deposit Wallet + Solana) with on-chain pUSD/USDC.e balances and flags stranded assets. Also try `bullpen wallet show-addresses`.
"1151: server-vs-on-chain wallet disagreement" or `L2_WALLET_DISAGREEMENT`	Run `bullpen polymarket wallet-audit --refresh --output json`. Do not retry with `--wallet` as a bypass; it does not override Safe vs Deposit Wallet server selection and does not bypass 1151. If audit/support confirms DW should be selected, run `bullpen polymarket wallet select --kind dw --yes`, then `bullpen polymarket activate --yes` if needed.
Split-brain warning on `bullpen status`	Run `bullpen polymarket wallet-audit` to confirm the stranded wallet, then `bullpen polymarket consolidate --yes` to move assets to the server-selected wallet.
"maker address not allowed" on first trade	Run `bullpen polymarket activate` to create CLOB credentials and bundle approvals for a never-traded wallet.
Command not found	Run `bullpen upgrade` to get the latest version
Config issues	Run `bullpen config init` to reset, or `bullpen config show` to inspect
Other bugs	Report at github.com/BullpenFi/bullpen-cli-releases/issues or Bullpen Support

Resources¶

Docs: cli.bullpen.fi
Bug reports: github.com/BullpenFi/bullpen-cli-releases/issues
Support: bullpen-help.freshdesk.com
Releases: github.com/BullpenFi/bullpen-cli-releases
Full LLM docs bundle: cli.bullpen.fi/llm.txt