polymarket-combo-builder

name	polymarket-combo-builder
description	Build an atomic Polymarket combo (parlay) - pick 2+ binary market legs, get live combined odds quoted over RFQ, and place the whole thing as ONE signed order. Every leg must hit to win; any single leg losing is a total loss of the stake. Live placement works with EOA / self-custody wallets, and with deposit wallets after a one-time activate_combo_dw() setup. Dry-run by default (a local plan, not a paper fill). Sports-general (World Cup ready).
category	world-cup
tags	["world-cup","parlay","combo"]
metadata	{"author":"Simmer (@simmer_markets)","version":"0.1.1","displayName":"Combo Builder","difficulty":"beginner"}

Combo Builder

Place a real Polymarket combo (parlay): bundle 2+ binary legs into one YES/NO position, settled by a single signed RFQ order on Polymarket's combo exchange. Polymarket quotes the combined odds live; you sign once; if every leg hits you win the combined payout, and if any single leg loses you lose the whole stake.

This is the atomic combo — distinct from the leg-by-leg polymarket-worldcup-parlay-roller. Live placement works with EOA / self-custody wallets, and with deposit wallets after a one-time activate_combo_dw() setup (details below).

Read DISCLAIMER.md before going live. This is a framework, not an edge, and it runs in dry-run by default. Dry-run is a local plan — it resolves legs and shows the combined-odds estimate but signs and sends nothing. There is no paper / simulated-fill mode for combos (they're Polymarket-only). Note: dry-run still reads your wallet key to resolve trading identity, but it never signs or sends.

Polymarket venue only. Combos are a BETA Polymarket product (sports markets today); label them as such to users.

How payout works

A combo's combined price is the makers' quoted probability that all legs hit. Example: three legs near 0.50 each quote around a 0.12–0.15 combined price, i.e. a ~7–8x payout multiple on the stake. The quote you sign already bakes in maker spread — it is not a naive product of the leg prices (the skill shows that product only as a pre-quote preview).

Setup

Agent: do this once with the user.

1. Get the thesis in natural language, e.g. "Brazil to win AND over 2.5 goals AND Argentina to win."
2. Resolve each pick to a combo leg. Combo-eligible legs come from the combo-markets feed — simmer_sdk.combo.fetch_combo_legs(). Each leg exposes position_ids = [YES_token, NO_token]; store the chosen side's token id. Moneyline, spread (-spread-), and total/over-under (-total-) legs are all eligible.
3. Confirm with the user, restating each leg's exact resolution condition and the total-loss-if-any-leg-loses risk.
4. Write combo_config.json from combo_config.example.json (>= 2 legs).
5. Dry-run first, review the plan, then go live.

Run

python combo_builder.py            # dry-run: resolve legs, show estimate + plan, place nothing
python combo_builder.py --live     # place the combo for real (money path)
python combo_builder.py --legs     # browse combo-eligible legs (no config needed)

Dry-run opens no socket, signs nothing, and moves no money. --live requires a configured wallet (WALLET_PRIVATE_KEY or OWS_WALLET) and a live Simmer client.

Wallet support

• EOA (signature_type 0): standard self-custody key. Works today, no extra setup.
• Deposit wallet (signature_type 3 / POLY_1271): works after a one-time activate_combo_dw() — see below.

OWS-signed deposit wallets can run the activate_combo_dw() setup headlessly with the same local OWS vault used for standard DW activation. Live combo order placement still requires the SDK's combo signing path to support that wallet type; if placement rejects your OWS setup, use a raw WALLET_PRIVATE_KEY for the wallet that owns the deposit wallet until OWS combo order signing is available.

Deposit wallets: one-time combo activation

Combos settle on a separate exchange that your wallet must approve first. The standard DW activation (activate_polymarket_dw()) does not set this — combo approval is opt-in. Run it once per deposit wallet:

client.activate_combo_dw()              # user-primary DW
client.activate_combo_dw(agent_id="…")  # per-agent (Elite) DW

This signs the combo-exchange approval batch locally with your raw key or OWS vault, and Simmer's server relays it gaslessly under our builder credentials (it approves the combo exchange to spend the DW's pUSD + combo position tokens). It is idempotent — safe to re-run. After it completes, place_combo(..., dry_run=False) settles normally for supported deposit-wallet signers.

Before a live DW placement the SDK runs a quick on-chain pre-check and, if the combo approval is missing, raises a clear "run client.activate_combo_dw() first" error instead of letting the order fail at settlement. (Dry-run works for all wallet types with no activation.)

Notes

• Min stake $1 (Polymarket order minimum). The stake is the most you can lose.
• The combined quote is valid ~5 seconds; the skill signs and accepts inside that window automatically, re-quoting if it lapses.
• No "risk-free" or "guaranteed" anything — a combo is strictly higher-variance than its legs.