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 a usable Bullpen session. Credentials are resolved automatically from your stored session.
Before login or any money-moving command, run:
State change: auth refresh. Run refresh only when you intend to update the local session from the stored refresh token.
Run bullpen login only when diagnostics say login is required. Login refreshes
local auth only; it does not repair wallet routing. After auth diagnostics are
clean, refresh trading readiness:
State change: readiness refresh. Run this only after auth diagnostics are clean and you need the current trading readiness plan.
If it reports that your account is ready, preview before using the simple trade commands live:
Live: trade submit. Run the preview command above first. The next command places a live order.
Preview the sell before submitting it:
Live: trade submit. Run the preview command above first. The next command places a live order.
bullpen trade sell <MARKET_SLUG> Yes --max --min-price 0.01 --yes
bullpen polymarket orders --output json
bullpen polymarket positions --source polymarket --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 a deposit is missing or funds appear on the wrong wallet, do not try to fix that by logging in again, activating, or switching wallets manually. Start with:
If the preview asks for deeper wallet evidence, run:
Choose price guards from the current preview. After a live close, verify open
orders are gone and check whether any active position or dust remains. If
cleanup remains unresolved, create a passive redacted support bundle with
bullpen support bundle --output json instead of repeatedly submitting orders.
If auth diagnostics or bullpen fix --refresh report a support-required state,
run:
The support bundle command writes a redacted local artifact and prints its path. It may include cached or support-safe remote reads, but it does not refresh auth, refresh wallet or balance evidence, check signing authority, or verify refreshed order credit. Attach the JSON file to 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 bundle --output json or a specific advanced
diagnostic.
When Polymarket rejects a CLOB order or gasless transaction 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 portfolio balances and look at the Polymarket line.
bullpen status reports local login and cached session state; it is not a live
balance check.
| 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 | Run bullpen recover funds --dry-run --output json; 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 transaction (approve + wrap), so no MATIC/POL is required on the normal path.
Preview: wrap plan. This does not sign or submit anything.
Live: wrap submit. Run the preview command above first. Submit only when the wallet, amount, and wrap route match your intent.
The <AMOUNT> argument is in USDC.e (e.g. 100 for $100). Amounts use exact
6-decimal arithmetic, so the pUSD you receive matches the USDC.e you wrap.
When the wallet holds Polygon native USDC, start with
bullpen recover funds --dry-run --output json instead of submitting a wrap
directly. The dry-run identifies whether the CLI has a supported route toward
the pUSD trading path or whether support needs to review diagnostics. Do not
blindly retry an outcome_unknown error; run the diagnostic command printed
by the CLI first.
Live JSON output includes a stable success envelope. success is true only
after the transaction has a confirmed receipt and the post-flight balance check
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 transaction was submitted."
]
}
Example output - wrap live success shape
{
"status": "wrapped",
"kind": "polymarket_wrap_result",
"success": true,
"amount": "100.00",
"tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"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: unwrap plan. This does not sign or submit anything.
Live: unwrap submit. Run the preview command above first. Submit only when the wallet, amount, and unwrap route match your intent.
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 transaction 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 transaction was submitted."
]
}
Example output - unwrap live success shape
{
"status": "unwrapped",
"kind": "polymarket_unwrap_result",
"success": true,
"amount": "100.00",
"tx_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"transaction_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"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
recoverable funds issue, run bullpen recover funds --dry-run --output json.
Execute with bullpen recover funds --yes only after the preview root status is
ready, every executable leg has outcome: "supported" and
legs[].effective_evidence.submit_authorized: true, and the expected source,
destination, and assets are correct. A top-level status of no_op means
nothing needs to move. A
support-only status (backend_only in JSON), blocked, or any executable leg
without submit authorization requires support instead of local retry. Use
wallet-audit only when the support output asks for advanced wallet evidence.
Recovery moves eligible assets; it does not change the selected trading wallet.
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 of executable spend, 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:
Live: trade submit. Run the preview command above first. The next command places a live order.
Live submission uses current market rules and order-book data; see Live Order Checks.
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 filled (ID: <ORDER_ID>)
Spent: $10.00
Received: 15.38 shares
Avg price: 65.0¢
Trade IDs: trade-20260724-a, trade-20260724-b
Tx hashes: pending async resolution
Polymarket's announced CLOB response change applies to successful FAK/FOK
matches from POST /order and POST /orders: those responses may omit
submit-time transaction hashes and return trade IDs instead. WebSocket fills are
unchanged. Bullpen buy and sell commands still submit through the live Bullpen
service; when that service returns trade IDs, the CLI preserves them as
trade_ids.
In JSON output, trade_ids identifies the matched CLOB trades and
transaction_hash_resolution tells you whether hashes are not_needed,
pending, partial, resolved, failed, or backend_unavailable. If a hash
later resolves, Bullpen exposes it as optional confirmation evidence. Do not
depend on transaction hashes being present in the submit response.
Do not replay an accepted or matched order because hash resolution is
pending, partial, failed, or backend_unavailable. Inspect the top-level
order_id, returned order state, and trade_ids instead. trade_ids are not
cancel IDs; cancel commands require the top-level order_id from the order
response or an order ID read from open orders. Bullpen keeps the returned trade
IDs and does not blindly replay the order mutation to obtain transaction hashes.
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:
Live: trade submit. Run the preview command above first. The next command places a live order.
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 rounding down sub-0.01-share dust.
Live submission uses current market rules and order-book data; see Live Order Checks.
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.
Action first:
- Preview the redeem plan with
--dry-run --output json. - Submit once with
--yesafter the plan matches the positions you want to redeem. - If the submit result is uncertain, run
redeem-statusfor that existing operation instead of submitting again.
Preview the auto-discovered redeem plan first:
Live: redeem auto-discovered positions. Run the dry-run command above first. Submit only when the redeem plan matches the positions you intend to redeem.
For large accounts, preview a bounded auto-discovery batch:
Live: redeem bounded auto-discovery batch. Run the dry-run command above first. Submit only after reviewing the matching bounded plan.
For exact targeting, preview the condition IDs first:
bullpen polymarket redeem --condition-ids 0x1111111111111111111111111111111111111111111111111111111111111111,0x2222222222222222222222222222222222222222222222222222222222222222 --dry-run --output json
Live: redeem specific condition IDs. Run the dry-run command above first. Submit only when those condition IDs are the positions you intend to redeem.
bullpen polymarket redeem --condition-ids 0x1111111111111111111111111111111111111111111111111111111111111111,0x2222222222222222222222222222222222222222222222222222222222222222 --yes
| Flag | Description |
|---|---|
--address |
Support override for one proven Polymarket wallet; omit for normal user flow so the CLI enumerates every owner EOA and probes its Safe and Deposit Wallet candidates automatically |
--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 related-outcome markets redeem through the
Polymarket gasless submission path, 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 trace ID,
condition ID, dry-run JSON, and live-submit output instead of treating it as a
generic retry.
After a live redeem submission, successful output includes a durable redeem operation ID. Keep that ID with the tx hash or trace ID. If the CLI prints a post-submit uncertainty warning, the request may already have crossed the external submission boundary. Do not replay the redeem. Inspect the existing operation first:
bullpen polymarket redeem-status <operation-id-or-tx-or-trace>
bullpen polymarket redeem-status <operation-id-or-tx-or-trace> --output json
The lookup can be the full redeem-v1-... operation ID, a raw transaction hash,
or the exact trace ID printed by the previous redeem.
Use --limit <n> only with auto-discovery. It lets you redeem large sets of
possible positions gradually and keeps explicit --condition-ids reserved for
exact targeting.
Dry-run JSON reports possible redeem plans only. A Data API match means the CLI found a potentially redeemable position, but dry-run does not submit to the submission path and does not confirm on-chain value movement. Keep the dry-run JSON so support can separate discovery of possible positions 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, execution_route, and
verification_plan.expected_value_movement before deciding whether to submit
or retry. Important cases include missing discovery data, rate limits,
submission rejection, and mined transactions with no confirmed value movement.
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.
Redeem Status¶
bullpen polymarket redeem-status refreshes evidence for a previous redeem
without resubmitting it. Use it when the original command printed a redeem
operation ID, when a submission response was uncertain after submit, or when
support asks for the current settlement state.
Human output is a status summary. This example is illustrative:
Redeem operation: redeem-v1-tx-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Transaction state: confirmed
Value state: confirmed_positive_payout
Resolution owner: user
Safe to retry: false
Next action: No retry is needed; settlement has durable wallet balance and corroborating evidence.
Payout wallet: 0x2222222222222222222222222222222222222222
Selected wallet: 0x2222222222222222222222222222222222222222
Condition IDs: 0x1111111111111111111111111111111111111111111111111111111111111111
Tx hash: 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
JSON output includes the same top-level decision fields plus the stored evidence record. This example is illustrative:
{
"operation_id": "redeem-v1-tx-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"transaction_state": "confirmed",
"value_state": "confirmed_positive_payout",
"resolution_owner": "user",
"next_action": "No retry is needed; settlement has durable wallet balance and corroborating evidence.",
"safe_to_retry": false,
"record": {
"version": 1,
"operation_id": "redeem-v1-tx-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"ts": "2026-07-22T12:00:00Z",
"operation": "redeem",
"wallet": {
"payout_wallet": "0x2222222222222222222222222222222222222222",
"selected_wallet": "0x2222222222222222222222222222222222222222",
"selected_state": "selected"
},
"condition_ids": [
"0x1111111111111111111111111111111111111111111111111111111111111111"
],
"receipt": {
"tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"block": 12345678,
"verification": {
"state": "confirmed",
"outcome": "confirmed-success",
"details": {
"tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"polygonscan_url": "https://polygonscan.com/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},
"receipt_status": "confirmed"
},
"observed_balances": {},
"warnings": []
}
}
Status meanings:
| State | Meaning | What to do |
|---|---|---|
pending_unknown / pending indexing |
The CLI cannot yet confirm final settlement from receipts, wallet balances, indexer data, or payout events. | Do not replay. Run bullpen polymarket redeem-status <operation-id-or-tx-or-trace> again later, then contact support if balances still look wrong. |
confirmed_positive_payout |
The transaction is confirmed and the payout has durable wallet balance plus corroborating evidence. | No retry is needed. |
confirmed_zero_payout |
The transaction is confirmed and the resolved position paid zero collateral. | No retry is needed. |
reverted_receipt |
The transaction receipt shows the wallet execution reverted. | Do not replay from the old command. Contact support with the operation ID and tx hash. |
temporary_increase_then_stale_index_regression |
A prior balance increase was seen, but an indexed source later looked stale or regressed. | Do not replay. Wait for indexing to converge or contact support with the operation ID. |
| missing evidence | A check failed or is unavailable, so the CLI cannot confirm whether value moved. | Keep the JSON output and contact support if repeated status checks remain unclear. |
wrong_wallet_settlement |
Funds settled to the payout wallet, but that wallet is not the currently selected Polymarket wallet. | Run bullpen polymarket wallet-audit --refresh --output json or bullpen funds balances --output json; include both outputs if filing support. |
contradictory_evidence |
Receipt, wallet balance, indexer, or payout-event evidence disagree. | Do not replay. Contact support with --output json from redeem-status. |
All redeem-status outcomes report safe_to_retry: false. Treat support
escalation as evidence collection, not as a prompt to repeat the original
money-moving command.
Closeout¶
Close out resolved Polymarket inventory from one command. Winning positions 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 winning closeout positions first:
Live: closeout winning positions. Run the dry-run command above first. The next command submits winning-position redeem attempts.
Inspect one lost resolved position without submitting:
bullpen polymarket closeout --scope lost --condition-ids 0x1111111111111111111111111111111111111111111111111111111111111111 --dry-run --output json
| Flag | Description |
|---|---|
--scope all\|won\|lost |
Include all resolved positions, only winning redeemable positions, or only lost zero-payout positions |
--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.
bullpen polymarket limit-buy <MARKET_SLUG> <OUTCOME> \
--price 0.45 --shares 20 --preview --output json
Review the preview output. It does not sign or submit an order.
Live: order submit. Run the preview command above first. The next command places a live limit order.
| Flag | Description |
|---|---|
--price |
Limit price that matches the market tick size (required) |
--shares |
Number of shares (required; must meet the market's current minimum order size) |
--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:
bullpen polymarket limit-buy <MARKET_SLUG> "Yes" \
--price 0.55 --shares 50 --expiration gtc --preview --output json
After review, submit only when the preview matches your intent.
Live: order submit. Run the preview command above first. The next command places a live limit order.
Live submission uses current market rules and order-book data; see Live Order Checks.
Limit Sell¶
Place a limit sell order at a specific price.
bullpen polymarket limit-sell <MARKET_SLUG> <OUTCOME> \
--price 0.65 --shares 15 --preview --output json
Review the preview output. It does not sign or submit an order.
Live: order submit. Run the preview command above first. The next command places a live limit order.
| Flag | Description |
|---|---|
--price |
Limit price that matches the market tick size (required) |
--shares |
Number of shares (required; must meet the market's current minimum order size) |
--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:
bullpen polymarket limit-sell <MARKET_SLUG> "Yes" \
--price 0.70 --shares 15 --expiration fok --preview --output json
After review, submit only when the preview matches your intent.
Live: order submit. Run the preview command above first. The next command places a live limit order.
Live submission uses current market rules and order-book data; see Live Order Checks.
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) |
Live Order Checks¶
Polymarket publishes each market's current price increment and minimum order size. Before a live buy, sell, limit-buy, or limit-sell signs or submits, Bullpen refreshes those rules, the outcome token, and the current order book. The command stops before signing when required market data is unavailable, the refreshed outcome differs from the preview, the executable or rounded size is below the current market minimum, or a price guard fails.
Market buys spend pUSD and must have at least $1 of executable spend before Bullpen converts that spend into shares. Limit-buy shares may round down to the market's allowed precision. Sell and limit-sell shares round down to two decimal places and may leave sub-0.01-share dust. Bullpen also uses related-outcome market type and fee metadata for previews, validation, order preparation, and balance checks. These checks do not add extra fields to the order you sign.
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 (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 data is used for preview, validation, and balance checks; it is not added as extra fields to the order you sign or handled through on-chain fee-collector approval.
Start with the read-only approval check before any live approval mutation. Approval check: Review current approval state before submitting changes.
State change: live approval submit. Run the approval check above first. Submit only when the missing operators match the approvals you intend to grant.
| 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.
There is no separate --preview flag. The no---yes form resolves the wallet,
checks current approvals, prints the operators that would be revoked, and
prompts before submitting.
State change: revoke has no separate preview flag. Run it interactively
only when you are ready to review the printed operators and confirm the
revocation.
Before trading again, check approval state:
Submit approval recovery only when that check reports missing approvals or support directs you to do so.
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 create a passive redacted support bundle
with bullpen support bundle --output json before trying a live order again.
The support bundle may include cached or support-safe remote reads, but it does
not refresh auth, refresh wallet or balance evidence, check signing authority,
or verify refreshed order-credit evidence; use
bullpen polymarket wallet-audit --refresh --include-order-credit --output json
when active order-credit evidence is needed.
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.
Outcome Token Operations¶
Split and merge are gasless operations when the ctf_split_merge experimental feature is enabled; otherwise the CLI refuses before submission. No MATIC is needed for the normal path.
Split¶
Split pUSD into the condition's outcome-token set.
There is no separate preview mode. The command without --yes checks the
request, prints the operation, and asks for confirmation before submission.
State change: split submit. Execute it only after the interactive preflight prints the exact condition, amount, partition, and wallet you intend to mutate.
bullpen polymarket split --condition 0x1111111111111111111111111111111111111111111111111111111111111111 --amount 100.00
| 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.
There is no separate preview mode. The command without --yes checks the
request, prints the operation, and asks for confirmation before submission.
State change: merge submit. Execute it only after the interactive preflight prints the exact condition, amount, partition, and wallet you intend to mutate.
bullpen polymarket merge --condition 0x1111111111111111111111111111111111111111111111111111111111111111 --amount 50.00
| 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.
State change: bounded monitor. This does not move funds, but run it only when you intend to open a temporary live WebSocket subscription and stop it after the timeout.
bullpen polymarket watch <MARKET_SLUG> --output json &
WATCH_PID=$!
sleep 30
kill "$WATCH_PID" 2>/dev/null || true
wait "$WATCH_PID" 2>/dev/null || true
| Arg | Description |
|---|---|
MARKET_SLUG |
Market slug or URL (required) |
The stream is open-ended. Use --output json for line-delimited JSON events.
For finite demos or scripts, stop the background process after a fixed interval
as shown above; the CLI stream itself does not have a --limit or --timeout
flag.
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. Use bullpen deposit; there is no
Polymarket-specific address-printing command.
Withdraw¶
The CLI supports withdrawing USDC.e from a Polygon Deposit Wallet. Use the Bullpen web app for other withdrawal routes.
There is no separate withdraw --preview flag. The form below checks the
route, balance, and recipient safety, prints the withdraw summary, and asks for
confirmation before submitting.
State change: withdraw submit. withdraw has no separate preview flag;
execute it only when the command's own preflight summary shows the exact
Deposit Wallet, Polygon USDC.e amount, and recipient you intend to use, and
only when the destination supports that token.
bullpen polymarket withdraw --to 0x1111111111111111111111111111111111111111 --amount 100.00 --chain polygon --token usdce --i-confirm-destination-supports-token
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 | 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 | Recovery/conversion support depends on account state; preview first. | Polymarket wallet or Bullpen-managed 0x wallet | May need a recovery route before trading. | Run bullpen recover funds --dry-run --output json before live conversion. |
| 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. | Bullpen-managed 0x wallet or contract wallet | Needed only for direct recovery paths; normal 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, Bullpen-managed EOA, bot Safe, or imported external EVM wallet, collect diagnostics instead of retrying a withdrawal:
bullpen recover funds --dry-run --output json
bullpen polymarket wallet-audit --refresh --output json
bullpen funds diagnose-deposit --tx <TX_HASH> --chain <CHAIN> --token <TOKEN> --address <RECIPIENT_ADDRESS> --output json
Run recover funds --dry-run first for missing or wrong-wallet funds. Use
wallet-audit --refresh for deeper selected-wallet evidence, and use
diagnose-deposit when you have a specific transaction hash, chain, token, and
recipient to document. 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-external-wallet, KYC, off-ramp,
exchange, order-credit, or 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 | Usage, 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 submission service 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:
Live: trade submit. Run the preview command above first. The next command places a live order and returns live JSON.
For buy, sell, limit-buy, and limit-sell, live JSON is a safety envelope with
root status: "ok", would_submit: true, signature_requested: true,
exchange_request_submitted: true, preview, and result. The nested
preview object keeps no-submit flags set to false. The nested result
object includes success, order_id, status, trade_ids,
transaction_hash_resolution, fill amounts, error when present, and any
available transaction_hash / transaction_hashes confirmation evidence. Use
result.order_id for cancellation. Do not pass
trade_ids to cancel commands. Trade result status is the CLOB order status,
with values such as MATCHED, LIVE, DELAYED, or UNMATCHED.
transaction_hash_resolution is separate; values such as failed and
backend_unavailable describe transaction-hash lookup, not a new CLOB order
status.