`bullpen polymarket limit-buy`¶

Last updated: August 26, 2026

Place a limit buy order on a prediction market outcome

Usage¶

bullpen polymarket limit-buy [OPTIONS] --price <PRICE> --shares <SHARES> <MARKET_SLUG> <OUTCOME>

Live Help¶

Place a limit buy order on a prediction market outcome

Usage: bullpen polymarket limit-buy [OPTIONS] --price <PRICE> --shares <SHARES> <MARKET_SLUG> <OUTCOME>

Arguments:
  <MARKET_SLUG>
          Market slug

  <OUTCOME>
          Outcome name

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

          [possible values: table, json]

      --price <PRICE>
          Limit price (e.g., "0.45" for 45 cents — valid range depends on market tick size)

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

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

      --shares <SHARES>
          Number of shares to buy (provider minimum comes from live CLOB /book.min_order_size metadata; e.g., "100")

      --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.

      --expiration <EXPIRATION>
          Order time-in-force: gtc (Good-Til-Cancelled, default), fok (Fill-Or-Kill), or fak (Fill-And-Kill). gtd is reserved and rejected until explicit expiration timestamps are supported

          Possible values:
          - gtc: Good-Til-Cancelled: rests on the book until explicitly cancelled
          - fok: Fill-Or-Kill: must fill entirely immediately, otherwise cancelled
          - gtd: Reserved Good-Til-Date value. Currently rejected until an explicit expiration timestamp is supported
          - fak: Fill-And-Kill: fills as much as possible immediately, rest cancelled

          [default: gtc]

      --post-only
          Post-only mode: reject the order if it would fill immediately

      --yes
          Skip confirmation

      --preview
          Show order preview without executing

      --auto-wrap
          Automatically wrap USDC.e → pUSD when pUSD balance is insufficient before placing the limit 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

      --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=]

      --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

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

EXAMPLES:
  # Preview a resting limit buy without signing or submitting
  bullpen polymarket limit-buy $ACTIVE_MARKET_SLUG No --price 0.001 --shares 10 --preview --output json

  # Place a Good-Til-Cancelled limit buy
  bullpen polymarket limit-buy $ACTIVE_MARKET_SLUG No --price 0.001 --shares 10 --yes

  # Preview a post-only limit buy from a pinned Bullpen wallet
  bullpen polymarket limit-buy $ACTIVE_MARKET_SLUG No --price 0.001 --shares 10 --post-only --wallet 0x1111111111111111111111111111111111111111 --preview

Example Commands¶

bullpen polymarket limit-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.