`bullpen polymarket buy`¶

Last updated: August 26, 2026

Buy shares on a prediction market outcome.

Usage¶

bullpen polymarket buy [OPTIONS] <MARKET_SLUG> <OUTCOME> <AMOUNT_USD>

Live Help¶

Buy shares on a prediction market outcome.

Market buys use USD notional, not share count. They must meet the Bullpen local $1 executable-spend floor. The provider share minimum is market-specific and read live from CLOB /book.min_order_size after price/tick normalization.

Usage: bullpen polymarket buy [OPTIONS] <MARKET_SLUG> <OUTCOME> <AMOUNT_USD>

Arguments:
  <MARKET_SLUG>
          Active market slug from `bullpen polymarket search`

  <OUTCOME>
          Outcome name. Binary markets accept aliases such as Y/N, True/False, and 1/0

  <AMOUNT_USD>
          Amount in USD (e.g., "10.50" = $10.50 of fill cost, NOT shares). Bullpen local executable-spend floor: $1. The provider share minimum is market-specific and read live from CLOB /book.min_order_size after price/tick normalization

Options:
      --output <OUTPUT>
          Output format for command results

          [possible values: table, json]

      --yes
          Skip confirmation

      --env <ENV>
          Target environment to connect to (overrides config.toml)

          [env: BULLPEN_ENV=]
          [possible values: staging, production]

      --preview
          Show order preview without executing

      --config <CONFIG>
          Path to a custom config.toml file (overrides $BULLPEN_CONFIG and the default location).

          Explicit --config and BULLPEN_CONFIG paths fail closed: if the file is missing, the CLI exits validation instead of silently loading defaults. Credentials still resolve via BULLPEN_HOME, so set BULLPEN_HOME too when isolating a session.

      --max-price <MAX_PRICE>
          Maximum acceptable fill price — reject if fill would exceed this price

      --auto-wrap
          Automatically wrap USDC.e → pUSD when pUSD balance is insufficient before placing the buy order. This is a money-moving consent flag: typing it authorises a USDC.e → pUSD wrap for exactly the shortfall amount. For manual control use `bullpen polymarket wrap <amount>` instead

      --wallet <WALLET>
          Pin this command to a specific Bullpen-managed 0x wallet. Does not override the server-selected Safe/Proxy/Deposit Wallet or bypass 1151 safety checks. Use in bot automation to avoid wallet-select races

      --read-only
          Enable read-only mode: blocks all mutating commands

      --non-interactive
          Suppress interactive prompts; does NOT imply --yes for money-moving commands

          [env: BULLPEN_NON_INTERACTIVE=]

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # Preview a USD-notional market buy on No without signing or submitting
  bullpen polymarket buy $ACTIVE_MARKET_SLUG No 10 --preview --output json

  # Buy USD-notional No with a maximum fill price
  bullpen polymarket buy $ACTIVE_MARKET_SLUG No 10 --max-price 0.01 --yes

  # Pin a specific Bullpen wallet for automation and preview the order
  bullpen polymarket buy $ACTIVE_MARKET_SLUG No 10 --wallet 0x1111111111111111111111111111111111111111 --preview

Example Commands¶

bullpen polymarket buy --help

JSON Output¶

Contract: JSON Output Contract.

Live order 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 order identity, fill amounts, and hash-resolution metadata when the trading service returns them.

key	type	nullable	notes
`success`	boolean	no	Whether the order request completed successfully
`order_id`	string	yes	CLOB order ID; use this value for order cancellation, not `trade_ids`
`status`	string	yes	Order status such as `MATCHED`, `LIVE`, `DELAYED`, or `UNMATCHED`
`transaction_hash`	string	yes	First resolved transaction hash when available; null while hash resolution is pending or unavailable
`transaction_hashes`	array	yes	Resolved transaction hashes, an empty array for a proven no-fill live order, or null when not supplied/resolved yet
`trade_ids`	array	yes	CLOB trade IDs returned for matched trades; these identify trades but are not order IDs and are not transaction hashes
`transaction_hash_resolution`	string	no	Hash-resolution state: `not_needed`, `pending`, `partial`, `resolved`, `failed`, or `backend_unavailable`
`making_amount`	number/string	yes	Amount offered by the order when returned
`taking_amount`	number/string	yes	Amount received by the order when returned
`filled_size`	number/string	yes	Filled share size when returned
`shares`	number/string	yes	Filled shares alias used by automation consumers
`spend`	number/string	yes	USD/pUSD spent for buy-side fills when returned
`proceeds`	number/string	yes	USD/pUSD proceeds for sell-side fills when returned
`avg_price`	number/string	yes	Average fill price when returned
`error`	string	yes	Error detail when the order did not complete successfully

Use result.order_id for cancellation. trade_ids identify matched CLOB trades and are not cancel IDs. Pending, partial, failed, or unavailable hash resolution is not a reason to submit the order again; inspect order state first.

Error output follows the shared JSON output contract linked above.

Stability¶

Patch releases may add nullable or optional fields. Minor releases may add required fields or increment schema_version. Major releases may remove or rename fields.