Output And Errors¶

Bullpen is meant to be usable by people, shell scripts, and AI agents. Use --output json when you need stable machine-readable output, support evidence, or retry decisions.

Output Modes¶

Most commands default to table or text output for terminal use.

bullpen portfolio balances

Use JSON for automation:

bullpen portfolio balances --output json
bullpen polymarket wallet-audit --refresh --output json
bullpen doctor auth --output json

Non-streaming JSON commands emit one JSON document to stdout. Streaming commands emit one JSON document per line. Commands that cannot safely mix prompts or raw interactive output with JSON reject JSON mode instead of returning partial JSON.

See the JSON Output Contract for schema-version, numeric-field, and compatibility rules.

Error JSON¶

When JSON mode can render an error, the CLI emits an object with stable top-level fields and optional command-specific fields.

{
  "error": "Polymarket relayer returned STATE_FAILED",
  "chain": ["relayer batch failed after validation"],
  "hint": "Capture the relayer trace ID and contact support before retrying.",
  "relayer_trace_id": "trace_..."
}

Consumers should accept optional fields as nullable and tolerate extra fields. Do not scrape human text when a typed field such as code, error_code, relayer_trace_id, wallet_kind, schema_version, or polymarket_status is available.

Newer error surfaces include a typed envelope in addition to legacy command-specific fields:

Field	Meaning
`ok`	`false` for JSON error envelopes.
`code`	Stable dotted error family, for example `auth.login_required`, `auth.device_login_stalled`, `wallet.selection_disagreement`, or `redeem.relayer_rejected`. Prefer this field over prose or legacy `error_code` when it is present.
`recoverability`	Machine-readable recovery class such as `login_required`, `state_inspection_required`, `retryable_without_action`, `user_action_required`, or `support_required`.
`requires_login`	Whether login is required before retrying. Do not infer this from human text.
`safe_to_retry`	Whether the same action can be retried without additional state inspection.
`next_command`	A single `bullpen ...` command that is safe to run next, when one exists.
`support_safe_evidence`	Redacted support context. It may include `code`, legacy `error_code`, `auth_state`, service, operation, or bounded device-login stall counters, but never secrets.
`recovery`	Canonical recovery projection for Polymarket money-path failures. Prefer `recovery.recovery_status` or `recovery.status`, `recovery.next_action`, `recovery.terminal`, and `recovery.safe_to_retry` over scraping human text.
`recovery_plan`	Shared account-level recovery plan from `fix`, `recover polymarket`, `support`, and Polymarket wallet diagnostics.
`market_state`	Polymarket preview/rejection state such as `market_resolved`, `orderbook_unavailable`, or `closed_or_resolved`. When present with `would_submit:false`, no order was submitted.
`would_submit` / `signature_requested` / `exchange_request_submitted`	Preview-safety fields. `false` means the command stopped before signing or exchange submission. Do not describe that as a CLOB rejection.
`signing_capability`	Auth diagnostic object that proves whether the active signer can sign a non-money test digest. Inspect `signing_capability.signing_capability`, `resolution_owner`, `next_action`, and `safe_to_retry`.

error_code remains for backward compatibility and command-specific support codes. Agents should prefer code when both fields are present.

Relayer and recovery-oriented errors may also include support_safe_cause, retryable_without_action, recovery_action, and next_action. support_safe_cause is a string label for support routing. recovery_action names ownership of the next step; for example, support_backend_if_repeated means retry once after a short delay, then stop and send the JSON to support if the same backend/provider failure repeats.

When bullpen support --output json emits both next_action and support_next_action, treat next_action as the account recovery step and support_next_action as the instruction for attaching the generated support artifact.

Wallet-routing diagnostics may include deposit_wallet_derivation: beacon_proxy, legacy_uups, or legacy_uups_fallback_rpc_unavailable. Use that field to compare diagnostics across bullpen doctor wallet, legacy bullpen polymarket wallet check, and bullpen funds diagnose-deposit. wallet-audit uses the same beacon-aware resolver internally, but does not currently emit the provenance field. Do not assume a legacy-derived address is current when the field says fallback was used because RPC was unavailable.

Auth Retry Safety¶

Some auth-looking errors happen after a live request has reached a service. Agents must distinguish retryable auth refresh from no-replay auth rejection.

If JSON includes requires_state_inspection: true, do not automatically retry the live command. Run the next_action diagnostics, inspect the relevant account or order state, and retry manually only when the state is known.

Examples of no-replay auth classes include:

USERGATE_AUTH_REJECTED_NO_REPLAY
PEAR_MUTATION_AUTH_REJECTED_NO_REPLAY
TRADE_SERVER_REDEEM_AUTH_REJECTED_NO_REPLAY

USERGATE_AUTH_REJECTED_NO_REPLAY covers Bullpen account-service mutations such as email OTP send, wallet private-key import, deposit-wallet deploy/reregister, wallet selection/nickname/visibility, notification mark/preference, portfolio or PnL refresh with refresh=true, pre-swap transfer submit, Solana SubmitV4/RecordSwap/sponsored SPL transfer, Polymarket contract-wallet selection, wallet-tracker add/remove, Turnkey API-key revoke, and copy-trading mutations. It means Bullpen sent the write once and did not refresh/replay after service-side auth rejection.

HYPERLIQUID_COPY_RAW_TOKEN_AUTH_REJECTED means the caller used a raw-token Hyperliquid copy context. Raw-token contexts cannot refresh Bullpen auth in place, so the error is not retryable with the same token. Route through normal CLI auth or inspect bullpen doctor auth --output json before deciding whether human login is required.

For these errors, retryable and retryable_without_action are false. This is different from safe read retries or idempotent Polymarket CLOB order submits that reuse the same body and idempotency key.

Hyperliquid copy service errors use HYPERLIQUID_COPY_SERVICE_REJECTED or HYPERLIQUID_COPY_SERVICE_UNAVAILABLE when the CLI can identify the copy service context. Before escalating, run bullpen hl copy list --include-stopped --output json, verify whether the failed command expects a subscription id or leader address, and capture the failed command again with --output json.

HYPERLIQUID_MARGIN_INSUFFICIENT means Hyperliquid accepted the selected market route but rejected the order because the account did not have enough usable margin for that market context. This can happen on HIP-3 DEXes even when price reads and previews work. Run bullpen hl balances --output json and bullpen hl status --all-dexes --output json, reduce size, or add usable margin before retrying.

SOLANA_MARKET_DATA_UNAVAILABLE means a Solana market-data endpoint such as token whales reached Bullpen services but the upstream read failed. Treat it as a read-side provider issue. It is not a Polymarket routing failure and does not require wallet repair or re-login unless diagnostics separately say auth is invalid.

TURNKEY_POLICY_DENIAL means Turnkey rejected the requested activity by account policy, for example ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2. This is a server-side account repair. Do not loop on bullpen login, CLOB API-key reset, or CLI upgrades. Capture bullpen doctor auth --output json and open or continue a Bullpen support ticket so support can grant the missing Turnkey activity permission.

doctor auth --output json and support evidence include signing_capability separately from token validity and credential decryptability. A healthy session can still report turnkey_resource_missing, login_required, or provider_unavailable for the signing probe. Follow that object's next_action; do not repeatedly re-login unless it says login is required.

Resolved or closed Polymarket previews may return market_state with would_submit:false, signature_requested:false, and exchange_request_submitted:false. For market_resolved, use bullpen recover redeem --dry-run --output json if you hold outcome tokens. For orderbook_unavailable, search/discover an active market or wait for a live orderbook instead of retrying the same preview as if an order failed.

Exit Codes¶

Scripts and agents should check the process exit code before deciding whether to retry.

Exit code	Meaning	Typical response
0	Success	Continue.
1	General or unknown error	Read the JSON/prose error and avoid blind retry loops.
2	Authentication failure	Run `bullpen doctor auth --output json` and inspect typed `code`, `requires_login`, `safe_to_retry`, and `next_command`. Log in only for `auth.login_required`, `auth.refresh_rejected`, or login-required diagnostics. Fix writable storage for `AUTH_REFRESH_PERSISTENCE_FAILED`. Retry only explicitly retryable/idempotent service auth errors; raw-token, no-replay, `requires_state_inspection=true`, and non-idempotent mutation paths require inspection or re-auth first.
3	Validation or confirmation failed before execution	Fix the command, flags, amount, prompt behavior, or input data.
4	Execution failed after validation	Inspect the typed error; support may be needed for upstream/account-state failures.
5	Network, timeout, or connection failure	Retry only when idempotent or after checking service health.
6	Polymarket relayer degraded	Capture trace IDs and support output; do not repeat live submits indefinitely.
7	CLI version below supported minimum	Run `bullpen upgrade`.
13	Polymarket wallet selection disagrees with on-chain evidence	Run `bullpen polymarket wallet-audit --refresh --output json` and contact support.
14	Turnkey wallet resource is missing	Run `bullpen doctor auth --output json` and contact support if it persists.

Support-Grade Capture¶

When reporting a CLI issue, capture the smallest set of JSON outputs that proves the failure class:

bullpen --version
bullpen status --output json
bullpen doctor auth --output json
bullpen doctor wallet --output json

For Polymarket wallet, trade, redeem, or withdraw failures, add:

bullpen polymarket wallet-audit --refresh --output json

For redeem failures, also include the dry-run and live-submit output:

bullpen polymarket redeem --dry-run --output json
bullpen polymarket redeem --yes --output json

Do not share private keys, seed phrases, JWTs, API tokens, full config files, or unredacted logs.

Agent Guidance¶

Agents should prefer this sequence:

Run a read-only command with --output json.
Check exit code and typed error fields.
For money-moving commands, run --preview or --dry-run first when the command supports it.
Use --yes only when the user explicitly asked for the live action and the preview/dry-run is acceptable.
Stop and ask for human review on wallet-routing disagreement, relayer STATE_FAILED, unsupported withdraw, unknown error, or repeated network failure.