Polymarket Wallet Routing And Recovery¶
Not sure where to start? If you have a symptom (balance shows $0, deposit missing, can't trade, funds on the wrong wallet), begin with the symptom → command decision tree. This page is the deeper reference on the routing model and recovery.
Bullpen now uses a three-category Polymarket routing model:
- Legacy Safe — your older Safe can still trade. Do not deploy a Deposit Wallet.
- Deposit Wallet flow — your Deposit Wallet is the trading wallet.
- New user — no Polymarket wallet exists yet. Trading creates the Deposit Wallet flow.
Bullpen selects the active Polymarket wallet for each Bullpen-managed 0x wallet. For legacy Safe users, server selection is authoritative: a Safe / Proxy must be both deployed and allowed before it can remain the selected trading wallet. If funds or positions are on a non-selected wallet, the active trading flow cannot use them until they are moved.
For a missing deposit or wrong-wallet symptom, start with the recovery preview:
If the preview asks for deeper routing evidence, refresh the read-only audit:
The audit enumerates every Bullpen-managed 0x wallet, asks for the selected and allowed Polymarket wallet, checks Safe / Proxy / current Deposit Wallet / deployed legacy Deposit Wallet / CLI-proven locally signable owned EOA balances and positions, and reports assets outside the selected trading wallet.
If wallet-audit reports stranded assets¶
Preview the guided recovery plan first:
Execute only after the dry-run root status is ready, every executable leg
has outcome: "supported" and effective_evidence.submit_authorized: true,
and the source, destination, route, and assets match your intent:
Live: Run the matching recovery dry-run first. Submit only when the plan is ready and every executable leg is supported and authorized.
This submits the reviewed recovery plan and can move funds or positions. Retry only from the submit fields in the returned plan.
recover funds --dry-run is read-only. It handles pUSD / USDC.e / USDC
balances, position transfer, open-order cancellation, and order credit
warnings. Order credit cannot be moved on-chain; follow the web-app
withdrawal guidance shown by the command. After a live submit, retry only the
submitted failed or unknown leg when that leg reports
submit.safe_to_retry: true. If a submitted leg reports an unknown outcome or
submit.safe_to_retry=false, check status or send the JSON output to support
before submitting again.
For support cases involving stranded funds, manual recovery, or wallet selection errors, do not treat a recovery preview or command output as customer resolution by itself. Record the intended destination wallet, the final selected trading wallet, before/after balances or positions, activation state, and the result of the original blocked trading or redeem flow.
If You Need One Owner Or Wallet Kind¶
Audit or recover one Bullpen-managed 0x wallet:
bullpen polymarket wallet-audit --owner <BULLPEN_0X_WALLET> --output json
bullpen polymarket consolidate --owner <BULLPEN_0X_WALLET> --dry-run --output json
The default recovery target is the account-selected trading wallet, which is almost always what you want.
Support-only
--wallet-kindoption. It forces assets onto a wallet kind that the server may not select for trading. Use it only when Bullpen support explicitly tells you which side to force after reviewing yourwallet-auditoutput; forcing the wrong side can strand funds again. Without it, recovery routes to the selected trading wallet on its own.
bullpen polymarket consolidate --wallet-kind safe --dry-run --output json
bullpen polymarket consolidate --wallet-kind dw --dry-run --output json
Execute a forced target only after Bullpen support confirms the reviewed preview:
Live: Run the matching consolidate dry-run first. Submit only when Bullpen support confirms the reviewed forced-target plan.
bullpen polymarket consolidate --wallet-kind safe --yes
bullpen polymarket consolidate --wallet-kind dw --yes
These commands can move assets to a forced wallet kind. Use them only after Bullpen support confirms the dry-run output.
If wallet-audit Finds No Stranded Assets¶
No recovery is needed. If you still cannot trade, refresh the CLI readiness
decision and follow the printed next_action or recovery_plan.next_action:
Safety: This is a non-runnable readiness-refresh example. Run it only when
wallet-audit finds no stranded assets and you need the CLI's current
recommended next action.
Run bullpen polymarket preflight --output json or
bullpen polymarket activate --yes only when fix, preflight, or support
prints that exact next action. Activation repairs missing trading approvals; it
does not change wallet selection or move funds.
Legacy pUSD Migration¶
bullpen polymarket migrate moves pUSD between a legacy Safe/Proxy wallet and a
Deposit Wallet. It auto-detects direction from wallet category and balances;
use --target safe or --target dw when both sides hold pUSD or Bullpen
support tells you which side to consolidate to. bullpen polymarket
migrate-collateral remains a deprecated compatibility alias for the older
pUSD migration flow, including its documented --dry-run, --amount, and
--reverse options.
Use these commands only when you specifically need to move pUSD between an old
Safe/Proxy wallet and Deposit Wallet. For balances, positions, open orders,
mixed assets, or missing deposits, use wallet-audit, recover funds, or the
support handoff printed by the CLI.
Preview legacy migration before submitting:
If both wallets hold pUSD, preview both target choices before executing one:
bullpen polymarket migrate --target dw --preview --output json
bullpen polymarket migrate --target safe --preview --output json
Execute only the reviewed target:
Live: Run the matching migration preview first. Submit only when the target, source, destination, and pUSD movement match your intent.
This moves pUSD between wallet routes. Submit only after the matching preview output names the intended source and target.