Tracking a trader's combo (parlay) PnL

What you’ll build: a parlay portfolio view for a Polymarket wallet — every combo the trader holds, each expanded into its legs with live prices, won/lost/pending status, and the combo-level PnL row.

A combo (combinatorial market / parlay) is one tradeable instrument whose payout depends on multiple underlying legs. Struct treats the combo as a single position with a single entry price, so there is no separate per-leg PnL. What you get instead is the useful decomposition: the trader’s combo position row, plus each leg’s market metadata, live price, and result status, together with derived figures a parlay UI needs (implied_probability, potential_payout, is_dead, leg counts).

When to use this

Wallet pages that separate parlays from standard binary and neg-risk positions.
Drilldowns from a combo row into “which legs are still live?”
Leaderboard or scout tools that rank wallets by combo_trade_count and then open their combo book.

Combo vs combos

Endpoint	Use when
`GET /v1/polymarket/trader/pnl/{address}/combos`	List the trader’s combos (one entry per parlay), with filters, sort, and pagination.
`GET /v1/polymarket/trader/pnl/{address}/combo`	Expand one combo by `condition_id` or `position_id`.

Both return the same entry shape (ComboPnlResponse). Listing is for the portfolio; the singular endpoint is for a detail view after the user clicks a row.

Step 1: list the trader’s combos

Page through open parlays first, then widen the status filter as needed.

curl "https://api.struct.to/v1/polymarket/trader/pnl/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/combos?status=open&sort_by=total_pnl_usd&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
resp = requests.get(
    f"https://api.struct.to/v1/polymarket/trader/pnl/{address}/combos",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "status": "open",
        "sort_by": "total_pnl_usd",
        "sort_direction": "desc",
        "limit": 10,
    },
).json()

combos = resp["data"]
pagination = resp.get("pagination") or {}

Filters and sort

Param	Notes
`status`	Lifecycle filter. Omit for all. Values: `open`, `closed`, `resolved`, `resolved_win`, `resolved_loss`, `redeemable`, `redeemed`. `resolved` matches wins and losses; `resolved_win` also matches redeemable and redeemed.
`search`	Case-insensitive substring on the combo market title.
`sort_by`	Default `total_pnl_usd`. Also: `realized_pnl_usd`, `unrealized_pnl_usd`, fee-excluded `raw_*` PnL fields, `total_buy_usd`, `first_trade_at`, `last_trade_at`, `title`, `end_date`, `redeemable`. Aggregates are across the combo’s held sides.
`sort_direction`	Default `desc`.
`limit` / `offset` / `pagination_key`	Page size default 10, max 100. `offset` is clamped to 3500 and takes precedence over `pagination_key`.

Each call costs 1 credit.

Step 2: read one combo entry

Each list item (and the singular endpoint response) looks like this:

Field	Meaning
`condition_id`	Normalized combo condition id.
`position`	The trader’s position row for this combo (same shape as positions). Omitted when the wallet has no position on this combo.
`status`	Combo lifecycle: `open`, `closed`, `resolved_win`, `resolved_loss`, `redeemable`, `redeemed`.
`implied_probability`	Probability the held side pays out, from current leg prices (won = 1, lost = 0, pending = last price).
`potential_payout`	Gross USD payout if the held side can still win or redeem, or the realized redemption amount when already redeemed. Omitted for dead losing positions and zero-balance closed positions.
`is_dead`	`true` once the position can no longer pay out.
`legs_won` / `legs_lost` / `legs_pending` / `leg_count`	Leg tallies.
`legs`	Per-leg detail: market metadata, `last_price`, and `status` (`won` / `lost` / `pending`).

A Yes combo dies when any leg loses. A No combo dies when every leg has resolved and none lost (the all-win case). Use is_dead and the leg tallies to drive “still alive” badges without re-deriving the rules client-side.

Step 3: expand a single combo

Pass exactly one of condition_id or position_id. Use position_id when you already have a row from positions or from /combos (it selects that outcome side). Use condition_id when you only know the market; the API prefers the Yes side and falls back to whichever side the trader holds.

curl "https://api.struct.to/v1/polymarket/trader/pnl/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/combo?condition_id=0x03..." \
  -H "X-API-Key: YOUR_API_KEY"

detail = requests.get(
    f"https://api.struct.to/v1/polymarket/trader/pnl/{address}/combo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"position_id": combos[0]["position"]["position_id"]},
).json()["data"]

for leg in detail["legs"]:
    print(leg.get("title"), leg.get("outcome"), leg.get("status"), leg.get("last_price"))

Unknown combos return 200 with data: null and an unknown combo message (not a 404). Passing both ids, neither id, a non-combo id, or a malformed id returns 400. Each call costs 1 credit.

Finding combos from the rest of the PnL suite

You do not have to start on /combos. Related fields on existing trader PnL surfaces:

Positions / markets: rows carry combo_type: "combinatorial" when the market is a combo (parlay). Filter with combo=combinatorial (or true / false) on positions and markets.
Trader summary / global leaderboard: combo_trade_count is the number of combo-exchange fills. Sort the global PnL leaderboard with sort_by=combo_trade_count to find active parlay traders, then open /combos for that wallet.

curl "https://api.struct.to/v1/polymarket/trader/pnl/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/positions?status=open&combo=combinatorial" \
  -H "X-API-Key: YOUR_API_KEY"

From a position row, pass its position_id into /combo for the leg breakdown.

API reference: List combo PnL, Single combo PnL
Trader open and closed positions
Live trader PnL dashboard
Market-level Combos APIs (list, metrics, analytics, candlesticks, holders): List combo markets, Global combo analytics snapshot, GET /v1/polymarket/combos/legs

Essentials

Data access

Markets

Traders & positions

PnL

Charts & feeds

Builders

Holders

Alerts

Tracking a trader's combo (parlay) PnL

When to use this

Combo vs combos

Step 1: list the trader’s combos

Filters and sort

Step 2: read one combo entry

Step 3: expand a single combo

Finding combos from the rest of the PnL suite

​When to use this

​Combo vs combos

​Step 1: list the trader’s combos

​Filters and sort

​Step 2: read one combo entry

​Step 3: expand a single combo

​Finding combos from the rest of the PnL suite

​Related

When to use this

Combo vs combos

Step 1: list the trader’s combos

Filters and sort

Step 2: read one combo entry

Step 3: expand a single combo

Finding combos from the rest of the PnL suite

Related