> ## Documentation Index
> Fetch the complete documentation index at: https://docs.struct.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking a trader's combo (parlay) PnL

> List a wallet's multi-leg combo positions and expand one parlay into its legs, implied probability, and potential payout using the trader combo PnL endpoints.

<Info>
  **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.
</Info>

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`](/api-reference/trader/list-combo-positions-with-legs-metadata-and-pnl) | List the trader's combos (one entry per parlay), with filters, sort, and pagination. |
| [`GET /v1/polymarket/trader/pnl/{address}/combo`](/api-reference/trader/combo-position-with-legs-metadata-and-pnl)        | 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.

```bash theme={null}
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"
```

```python theme={null}
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](/api-reference/trader/get-trader-position-pnl)). 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.

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

```python theme={null}
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](/api-reference/trader/get-trader-position-pnl) and [markets](/api-reference/trader/get-trader-market-pnl).
* **Trader summary / global leaderboard:** `combo_trade_count` is the number of combo-exchange fills. Sort the [global PnL leaderboard](/api-reference/trader/get-global-pnl-leaderboard) with `sort_by=combo_trade_count` to find active parlay traders, then open `/combos` for that wallet.

```bash theme={null}
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.

## Related

* API reference: [List combo PnL](/api-reference/trader/list-combo-positions-with-legs-metadata-and-pnl), [Single combo PnL](/api-reference/trader/combo-position-with-legs-metadata-and-pnl)
* [Trader open and closed positions](/guides/trader-open-and-closed-positions)
* [Live trader PnL dashboard](/guides/live-trader-pnl-dashboard)
* Market-level Combos APIs (list, metrics, analytics, candlesticks, holders): [List combo markets](/api-reference/combos/list-combo-markets), [Global combo analytics snapshot](/api-reference/combos/global-combo-analytics-snapshot), [`GET /v1/polymarket/combos/legs`](/api-reference/combos/expand-a-combo-into-its-legs-with-market-metadata)