Prediction Trading¶
Buy, sell, and redeem Prediction market shares on Polymarket.
What is pUSD? pUSD is Polymarket's USDC-backed trading collateral. You trade with pUSD, not raw USDC. Before your first trade you wrap USDC into pUSD; to cash out you unwrap pUSD back into USDC. See Collateral: Wrap And Unwrap below.
Prerequisites¶
Trading requires authentication via bullpen login. Credentials are resolved automatically from your stored session.
Before moving money, run:
If it reports that your account is ready, use the simple trade commands:
bullpen trade buy <MARKET_SLUG> Yes 5 --preview --output json
bullpen trade buy <MARKET_SLUG> Yes 5 --max-price 0.20 --yes
bullpen trade sell <MARKET_SLUG> Yes --max --preview --output json
The bullpen trade commands use the same Polymarket trade engine as
bullpen polymarket buy and bullpen polymarket sell. Use the advanced
command names only when you need flags that are not exposed by the simple
journey yet.
If bullpen fix --refresh reports a support-required state, run:
The support command writes a redacted artifact and prints a short summary you can paste into a support ticket. Do not repeatedly retry live orders or switch wallets unless the CLI or support gives that exact next action.
Advanced wallet details¶
Bullpen supports older Safe / Proxy accounts and newer Deposit Wallet accounts.
Normal users should not choose a wallet route manually. When Bullpen and
Polymarket routing are healthy, the CLI uses the account route reported by
Bullpen. If account evidence is inconsistent, money-moving commands fail closed
and ask for bullpen support or a specific advanced diagnostic.
When Polymarket rejects a CLOB order or gasless relayer batch while its status page reports degraded relevant components (CLOB API, Markets API, Polygon (RPC), or User auth), the CLI appends a Polymarket status advisory to the error. JSON error envelopes include a nested polymarket_status object only in that outage-shaped case; local auth, balance, market, and validation errors do not include it.
Collateral: Wrap And Unwrap¶
Polymarket V2 markets are denominated in pUSD, a trading collateral backed 1:1 by USDC. You cannot place orders with raw USDC — you first convert (wrap) USDC into pUSD, and to cash out you convert (unwrap) pUSD back into USDC.
Which balance do I have?¶
Run bullpen status or bullpen portfolio balances and look at the Polymarket
line:
| What you see | What it means | What to do |
|---|---|---|
pUSD |
Trading collateral, ready to use | You can trade. |
USDC.e |
Bridged USDC on Polygon (the older Polymarket collateral token) | Wrap it into pUSD before trading. |
Native USDC |
Polygon-native USDC | Preview a wrap first; conversion depends on account state. |
USDC.e (bridge-wrapped USDC) and native Polygon USDC are two different
Polygon tokens; both are distinct from pUSD. Always confirm the exact token and
network before moving funds — see the withdraw routing table.
Wrap USDC into pUSD¶
Preview first; the preview does not sign or submit anything. Wrapping is a gasless two-step relayer batch (approve + wrap), so no MATIC/POL is required on the normal path.
# 1. Preview the conversion (read-only)
bullpen polymarket wrap 100 --preview --output json
# 2. Submit once the plan looks right
bullpen polymarket wrap 100 --yes
The <AMOUNT> argument is in USDC (e.g. 100 for $100). Amounts use exact
6-decimal arithmetic, so the pUSD you receive matches the USDC you wrap.
Live JSON output includes a stable success envelope. success is true only
after the relayer transaction has a confirmed receipt and the post-flight
balance proof confirms the expected pUSD movement.
Example output - wrap preview shape
{
"status": "dry-run",
"operation": "wrap",
"amount": "100.000000",
"source_wallet_kind": "deposit_wallet",
"source_wallet": "0x2222222222222222222222222222222222222222",
"would_submit": false,
"batch": [
{ "label": "USDC.e.approve(Collateral Onramp)" },
{ "label": "Collateral Onramp.wrap" }
],
"warnings": [
"Preview only; no USDC.e approval, wrap, unwrap, or relayer transaction was submitted."
]
}
Example output - wrap live success shape
{
"status": "wrapped",
"kind": "polymarket_wrap_result",
"success": true,
"amount": "100.00",
"tx_hash": "0xabc123...",
"transaction_hash": "0xabc123...",
"receipt_status": "confirmed",
"source_wallet_kind": "deposit_wallet",
"verification": {
"state": "confirmed",
"outcome": "confirmed-success"
},
"warnings": []
}
Unwrap pUSD back into USDC¶
Unwrap when you want to stop trading and move value back toward a withdrawal route.
# Preview, then submit
bullpen polymarket unwrap 100 --preview --output json
bullpen polymarket unwrap 100 --yes
Unwrapping produces USDC.e on Polygon. To take funds off Polymarket entirely,
unwrap first, then follow the withdraw routing table for the exact
asset and network. pUSD itself is not a direct exchange/bank withdrawal asset.
The preview validates balances, wallet routing, and the relayer batch shape, but
it cannot guarantee that the live on-chain call will execute. If live unwrap
returns POLYMARKET_RECEIPT_REVERTED, run bullpen polymarket approve --check
--output json and bullpen doctor wallet --output json, then include the JSON
error and transaction hash in support if both diagnostics are green.
Example output - unwrap preview shape
{
"status": "dry-run",
"operation": "unwrap",
"amount": "100.000000",
"source_wallet_kind": "safe",
"source_wallet": "0x2222222222222222222222222222222222222222",
"would_submit": false,
"batch": [
{ "label": "pUSD.approve(Collateral Offramp)" },
{ "label": "Collateral Offramp.unwrap" }
],
"warnings": [
"Preview only; no pUSD approval, wrap, unwrap, or relayer transaction was submitted."
]
}
Example output - unwrap live success shape
{
"status": "unwrapped",
"kind": "polymarket_unwrap_result",
"success": true,
"amount": "100.00",
"tx_hash": "0xdef456...",
"transaction_hash": "0xdef456...",
"receipt_status": "confirmed",
"source_wallet_kind": "safe",
"verification": {
"state": "confirmed",
"outcome": "confirmed-success"
},
"warnings": []
}
Multi-wallet note¶
wrap and unwrap operate on your active Polymarket wallet. If you hold
multiple wallets, the CLI warns you and (for wrap/unwrap) probes your other
owner wallets when the active one is empty. If a wrap or unwrap reports a
support-required issue, run bullpen support. Use wallet-audit only when the
support output asks for advanced wallet evidence. See
Wallet Routing And Funds Recovery for
the detailed recovery guide.
Buy¶
Buy shares on a prediction market outcome.
Example:
bullpen polymarket search "bitcoin" --type market --limit 5
bullpen polymarket buy <MARKET_SLUG> "Yes" 10.00 --max-price 0.55 --preview
Market buys spend USD fill-cost notional, not shares. The amount must be at
least 1 USDC, and both --preview and live submit reject smaller amounts before
auth, signing, or order construction.
--preview estimates the order without signing, approving, or submitting.
Rerun with --yes only after the preview is acceptable:
The command first shows a trade preview, then executes if --yes is set:
Buy Yes on "Example BTC daily price market"
Price: 65¢ | Amount: $10.00
Est. shares: 15.38 | Potential: $15.38
Spread: 1.2¢
Order submitted successfully (ID: abc123)
Filled: 15.38 @ 65¢
Without --yes, the preview is shown and you are prompted to confirm interactively (Confirm trade? [y/N]:). Entering anything other than y cancels the trade.
Key flags: --preview estimates without submitting; --yes skips the
interactive confirmation; --max-price caps the acceptable market price.
Sell¶
Sell shares on a prediction market outcome.
Example:
Preview output:
Rerun with --yes only after the preview is acceptable:
Key flags: --preview estimates without submitting; --yes skips the
interactive confirmation; --min-price sets a minimum acceptable price; --max
sells the full detected position after flooring exchange dust.
If a preview reports market_state: "market_resolved" or
market_state: "closed_or_resolved", the command did not submit an order and
the CLOB cannot sell that outcome. Run
bullpen recover redeem --dry-run --output json for winning or uncertain
resolved positions, or use bullpen polymarket closeout --scope lost --dry-run
--output json to account for zero-payout resolved positions.
Redeem¶
Redeem resolved prediction market positions. Collect winnings for markets that have settled.
# Preview the auto-discovered redeem plan first
bullpen polymarket redeem --dry-run --output json
# Preview a bounded auto-discovery batch for large accounts
bullpen polymarket redeem --limit 20 --dry-run --output json
# Submit the bounded auto-discovered redeem plan after review
bullpen polymarket redeem --yes
# Submit a specific condition ID after review
bullpen polymarket redeem --condition-ids id1,id2,id3 --yes
| Flag | Description |
|---|---|
--address |
Support override for a specific Polymarket wallet route; omit for normal user flow so the CLI can auto-discover the selected wallet route |
--condition-ids |
Optional comma-separated condition IDs to redeem; omit to auto-discover redeemable positions |
--limit |
Process only the first N auto-discovered condition IDs; useful for large accounts or provider rate limits |
--dry-run |
Print the redeem plan without submitting; use this first for support diagnostics |
--yes |
Skip confirmation prompt |
Standard binary markets and supported neg-risk markets redeem through the
Polymarket relayer, so normal customer redemptions should not require MATIC.
Start with --dry-run --output json when support is involved. If the same
condition repeatedly fails with STATE_FAILED, capture the relayer trace ID,
condition ID, dry-run JSON, and live-submit output instead of treating it as a
generic retry.
Use --limit <n> only with auto-discovery. It lets you redeem large candidate
sets gradually and keeps explicit --condition-ids reserved for exact
targeting.
Dry-run JSON reports candidate plans only. A Data API candidate means the CLI
found a potentially redeemable position, but dry-run does not submit to the
relayer and does not prove on-chain value movement. The JSON includes
redeemability_proof_scope, relayer_readiness_proven:false, and
value_movement_proven:false so support can separate candidate discovery from
live redeem success.
Redeem JSON can also include redeem_plan and, when available,
execution_context. For support or agent workflows, inspect
redeem_plan.case_type, payout_proof_source, execution_route, and
verification_plan.expected_value_movement before deciding whether to submit
or retry. Important cases include gamma_missing_onchain_recovered,
discovery_rate_limited, relayer_rejected, and mined_no_value_moved.
Without --yes, the CLI lists the condition IDs and prompts for confirmation (Confirm redeem? [y/N]:).
To find redeemable condition IDs, check your positions:
In positions JSON, redeemable means Bullpen expects the row to pay non-zero
value. upstream_redeemable preserves Polymarket's raw flag when it is
available. A lost resolved row can be upstream-redeemable on-chain while still
not being a useful recovery action.
Closeout¶
Close out resolved Polymarket inventory from one command. Winning candidates use
the same redeem submission flow as bullpen polymarket redeem; lost zero-payout
positions are reported so you can identify what is resolved against you.
# Preview all resolved closeout candidates first
bullpen polymarket closeout --dry-run --output json
# Redeem all winning positions after review
bullpen polymarket closeout --scope won --yes
# Inspect one lost resolved position
bullpen polymarket closeout --scope lost --condition-ids 0xYourConditionId --dry-run --output json
| Flag | Description |
|---|---|
--scope all\|won\|lost |
Include all resolved candidates, only winning redeem candidates, or only lost zero-payout candidates |
--condition-ids |
Optional comma-separated condition IDs to target a single resolved position or a small batch |
--dry-run |
Print the closeout plan without submitting winning-position redeem transactions |
--yes |
Skip confirmation for winning-position redeem submission |
In current releases, --scope lost is report-only. It does not submit zero-payout burn
transactions. Use it to clear up what is lost/resolved and keep support output
honest; use --scope won --yes to submit winning-position redeem attempts.
Limit Buy¶
Place a limit buy order at a specific price.
| Flag | Description |
|---|---|
--price |
Limit price that matches the market tick size (required) |
--shares |
Number of shares (required; Polymarket currently rejects orders below 5 shares) |
--expiration |
Order expiration: gtc (default), fok, or fak. gtd is reserved and currently rejected because the CLI does not yet accept an explicit expiration timestamp. |
--post-only |
Reject if the order would fill immediately (maker-only) |
--yes |
Skip confirmation prompt |
--preview |
Show order preview without executing |
Example:
Limit Sell¶
Place a limit sell order at a specific price.
| Flag | Description |
|---|---|
--price |
Limit price that matches the market tick size (required) |
--shares |
Number of shares (required; Polymarket currently rejects orders below 5 shares) |
--expiration |
Order expiration: gtc (default), fok, or fak. gtd is reserved and currently rejected because the CLI does not yet accept an explicit expiration timestamp. |
--post-only |
Reject if the order would fill immediately (maker-only) |
--yes |
Skip confirmation prompt |
--preview |
Show order preview without executing |
Example:
Trade Preview¶
Every buy, sell, limit-buy, and limit-sell command shows a preview before executing. The preview includes:
| Field | Description |
|---|---|
| Side | Buy or Sell |
| Outcome | The outcome being traded (e.g., "Yes") |
| Market | The market question |
| Price | Current price in cents |
| Amount | USD value of the trade |
| Est. shares | Estimated shares to receive (buy only) |
| Potential | Potential payout if outcome wins (buy only) |
| Spread | Bid-ask spread in cents (buy only) |
Pre-Trade Setup¶
Approve¶
Check and set ERC-1155 and pUSD token approvals required for trading. Approvals are one-time per operator on Polygon and are submitted gaslessly via relayer (no MATIC needed). The CLI selects the correct approval set based on your wallet kind:
- Safe / Proxy accounts: ERC-1155 operators + pUSD spenders required by Polymarket V2.
- Deposit Wallet accounts: ERC-1155 operators + pUSD spenders required by Polymarket V2.
The Bullpen fee-collector spender is excluded for every wallet kind because Polymarket's gasless transaction allowlist rejects that spender. Fee attribution is handled by the signed order and Bullpen's order-submission path, not by on-chain fee-collector approval.
# Check approval status
bullpen polymarket approve --check
# Set all required approvals
bullpen polymarket approve --yes
| Flag | Description |
|---|---|
--check |
Only check approval status, don't submit transactions |
--yes |
Skip confirmation prompt |
Revoke¶
Revoke all Polymarket trading approvals (ERC-1155 + pUSD) in a single gasless batch. Useful before account close or wallet-key rotation.
After revoke, run bullpen polymarket approve --yes to re-establish approvals before trading again.
Preflight¶
Run pre-trade safety checks before placing orders. Checks server time sync, account status (close-only mode), pUSD trading balance/allowance, and ERC-1155 approval status.
For automation, use JSON output:
The JSON includes wallet_address, wallet_kind, wallet_kind_label, and
clob_readiness. Treat clob_readiness.trade_ready: false as a stop sign:
follow clob_readiness.next_action or generate a support bundle before trying a
live order again.
Balance fields keep backward compatibility. usdc_e_balance is raw
micro-USDC.e, usdc_e_balance_base_units is the explicit raw field, and
usdc_e_balance_usd is the human-readable formatted value.
CTF Operations¶
Split and merge are gasless relayer operations when the ctf_split_merge experimental feature is enabled; otherwise the CLI refuses before submission. No MATIC is needed for the relayer path.
Split¶
Split pUSD into the condition's outcome-token set via the Conditional Token Framework (CTF).
| Flag | Description |
|---|---|
--condition |
Condition ID (required) |
--amount |
Amount in pUSD to split (required) |
--partition |
Optional custom partition index set list |
--parent-collection |
Optional parent collection ID |
--yes |
Skip confirmation prompt |
Merge¶
Merge a complete outcome-token set back into pUSD.
| Flag | Description |
|---|---|
--condition |
Condition ID (required) |
--amount |
Number of pUSD complete sets to merge (required) |
--partition |
Optional custom partition index set list |
--parent-collection |
Optional parent collection ID |
--yes |
Skip confirmation prompt |
Real-Time Data¶
Watch¶
Subscribe to real-time market data updates.
| Arg | Description |
|---|---|
MARKET_SLUG |
Market slug or URL (required) |
The stream runs until Ctrl+C. Use --output json for line-delimited JSON events.
Bridge & Funds¶
Deposit¶
Use the bullpen deposit command to deposit funds. It opens the Bullpen web app, which guides you to the correct deposit address for your wallet kind and the asset/chain you choose:
The CLI does not display raw deposit addresses to prevent accidental wrong-chain or wrong-token deposits. The previous bullpen polymarket deposit --address … form is deprecated.
Withdraw¶
The CLI supports withdrawing USDC.e from a Polygon Deposit Wallet. Use the Bullpen web app for other withdrawal routes.
The command refuses unsupported token or chain combinations instead of falling back to the retired Polymarket V1 bridge endpoint.
Before withdrawing, verify the exact asset and network. pUSD, Polygon USDC.e, native Polygon USDC, exchange USDC on Base/Ethereum, and bank cash-out are different paths.
| Asset / route | Network | CLI support | Owner | Cost / gas expectation | Next action |
|---|---|---|---|---|---|
| pUSD trading collateral | Polygon | Not a direct exchange/bank withdrawal asset. Unwrap or use the web app route shown for your account. | Polymarket trading wallet | May require unwrap or web-app flow. | Do not send pUSD directly to exchange/bank routes. |
| USDC.e from a Polymarket Deposit Wallet | Polygon | Supported by bullpen polymarket withdraw --chain polygon --token usdce after confirmation. |
Polymarket Deposit Wallet | Relayer/gasless path when supported by your account. | Withdraw only to a self-custody ERC-20 wallet or destination that explicitly accepts Polygon USDC.e. |
| Native USDC | Polygon | Wrap/pre-swap support depends on account state; preview first. | Polymarket wallet or owner EOA | May need a pre-swap/wrap route before trading. | Run bullpen polymarket wrap <AMOUNT> --preview --output json before live wrapping. |
| USDT or unsupported ERC-20s | Polygon | Not a Polymarket withdraw/trading asset in the CLI. | Depends on where funds landed | Recovery may require support/manual handling. | Run diagnostics and contact support instead of retrying a CLI trade. |
| POL / native gas token | Polygon | Not used as Polymarket trading collateral. | Owner EOA or contract wallet | Needed only for direct on-chain recovery paths; normal relayer paths should be gasless. | Keep diagnostics; support can advise whether manual recovery is needed. |
| Exchange USDC deposit address | Base/Ethereum/Arbitrum/other | Not supported by Polymarket withdraw commands unless that exchange explicitly supports the exact token and network. | External exchange | Sending the wrong token/network may strand funds. | Use the Bullpen web app or exchange-specific instructions. |
| Bank cash-out / off-ramp | N/A | Not a CLI command. | Bullpen/web-app support flow | Fees/timing are not controlled by the CLI. | Use the Bullpen web app and support flow. |
Do not send pUSD-on-Polygon or Polygon USDC.e to a Coinbase/Base USDC address unless the destination explicitly supports that exact token and network. If funds were already sent to a wrong chain, wrong token, signer EOA, bot Safe, or imported wallet, collect diagnostics instead of retrying a withdrawal:
bullpen funds diagnose-deposit --tx <TX_HASH> --chain <CHAIN> --token <TOKEN> --address <RECIPIENT_ADDRESS> --output json
bullpen polymarket wallet-audit --refresh --output json
These diagnostics are evidence bundles, not recovery attempts. funds
diagnose-deposit stays read-only and reports no_recovery_attempted:true.
Support can investigate recoverable transfers when custody, chain, token,
recipient, and routing validation are available, but the CLI does not promise
wrong-chain, imported-wallet, KYC, off-ramp, exchange, order-credit, or
backend-ledger recovery.
Bridge Status Utility¶
Use this only to check the status of an existing support-provided bridge
deposit address. For new deposits, use bullpen deposit and complete the web
app flow.
| Flag | Description |
|---|---|
--status |
Check status for an existing support-provided bridge address |
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General or unknown error |
| 2 | Authentication failure |
| 3 | Validation or confirmation failed before execution |
| 4 | Execution failed after validation (e.g. order rejected by exchange) |
| 5 | Network, timeout, or connection failure |
| 6 | Polymarket relayer degraded |
| 7 | CLI version below the supported minimum |
| 13 | Polymarket wallet selection disagrees with on-chain evidence |
| 14 | Turnkey wallet resource is missing |
JSON Output¶
Most trading commands accept --output json: