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

# List combo positions with legs, metadata, and PnL

> Lists a trader's combos (parlays), one entry per combo, each expanded into its legs with market metadata, live prices, won/lost/pending status, the trader's PnL row, and derived figures (implied probability, potential payout, dead flag). Supports title search and combo-level sorting.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/trader/pnl/{address}/combos
openapi: 3.1.0
info:
  title: Polymarket API
  description: >-
    RESTful API for querying Polymarket prediction markets data including
    events, markets, traders, holders, and real-time metrics
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.struct.to/v1
security: []
paths:
  /polymarket/trader/pnl/{address}/combos:
    get:
      tags:
        - Trader
      summary: List combo positions with legs, metadata, and PnL
      description: >-
        Lists a trader's combos (parlays), one entry per combo, each expanded
        into its legs with market metadata, live prices, won/lost/pending
        status, the trader's PnL row, and derived figures (implied probability,
        potential payout, dead flag). Supports title search and combo-level
        sorting.
      operationId: get_trader_combos_pnl
      parameters:
        - name: address
          in: path
          description: Trader wallet address
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: >-
            Lifecycle filter; omit for all combos. `resolved` matches wins and
            losses; `resolved_win` also matches redeemable/redeemed
          required: false
          schema:
            $ref: '#/components/schemas/ComboStatusFilter'
        - name: search
          in: query
          description: Case-insensitive substring match on the combo market title.
          required: false
          schema:
            type: string
        - name: sort_by
          in: query
          description: >-
            Default: total_pnl_usd. Aggregated across the combo's held sides.
            `title` sorts alphabetically by market title; `end_date` sorts by
            the market resolution date; `redeemable` surfaces combos with
            redeemable winning shares.
          required: false
          schema:
            $ref: '#/components/schemas/ComboPnlSortBy'
        - name: sort_direction
          in: query
          description: 'Default: desc'
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
        - name: limit
          in: query
          description: Page size (default 10, max 100)
          required: false
          schema:
            type: integer
            format: int32
        - name: offset
          in: query
          description: >-
            Row skip; clamped to a max of 3500. Takes precedence over
            pagination_key.
          required: false
          schema:
            type: integer
            format: int32
        - name: pagination_key
          in: query
          description: Cursor from the previous page
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Combo entries with per-leg detail and position PnL
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ComboPnlResponse'
        '400':
          description: Invalid parameter
components:
  schemas:
    ComboStatusFilter:
      type: string
      description: |-
        Status filter for the combo listing. Looser than the entry's `status`
        field: `resolved` matches wins and losses, and `resolved_win` also
        matches redeemable/redeemed combos.
      enum:
        - open
        - closed
        - resolved
        - resolved_win
        - resolved_loss
        - redeemable
        - redeemed
    ComboPnlSortBy:
      type: string
      description: |-
        Sort keys for the combo listing — aggregates summed (or, for the
        timestamps, min/max) across a combo's held sides. `title` sorts by
        combo market title, `end_date` by market resolution date, and
        `redeemable` by whether a winning held side still has shares.
      enum:
        - total_pnl_usd
        - realized_pnl_usd
        - unrealized_pnl_usd
        - raw_total_pnl_usd
        - raw_realized_pnl_usd
        - raw_unrealized_pnl_usd
        - total_buy_usd
        - first_trade_at
        - last_trade_at
        - title
        - end_date
        - redeemable
    SortDirection:
      type: string
      enum:
        - asc
        - desc
    ComboPnlResponse:
      type: object
      required:
        - condition_id
        - is_dead
        - legs_won
        - legs_lost
        - legs_pending
        - leg_count
        - legs
      properties:
        condition_id:
          type: string
          description: Normalized combo condition id.
        position:
          type: object
          description: |-
            The trader's position row for this combo (same shape as the
            positions endpoint). Omitted when the trader holds no position on
            this combo.
        implied_probability:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Probability of this position paying out, implied by current leg
            prices (resolved legs count as 0 or 1).
        potential_payout:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Gross USD payout if this held side can still win/redeem, or the
            already-realized redemption amount when it has won and redeemed.
            Omitted for dead losing positions and zero-balance closed positions.
        is_dead:
          type: boolean
          description: True once the position can no longer pay out.
        status:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ComboStatus'
              description: |-
                Lifecycle state of the combo. Omitted when the trader holds no
                position on it.
        legs_won:
          type: integer
          minimum: 0
        legs_lost:
          type: integer
          minimum: 0
        legs_pending:
          type: integer
          minimum: 0
        leg_count:
          type: integer
          minimum: 0
        legs:
          type: array
          items:
            $ref: '#/components/schemas/ComboLegDetail'
    ComboStatus:
      type: string
      description: Lifecycle state of a combo entry — the most specific state that applies.
      enum:
        - open
        - closed
        - resolved_win
        - resolved_loss
        - redeemable
        - redeemed
    ComboLegDetail:
      type: object
      required:
        - position_id
        - v2_condition_id
        - condition_id
        - leg_market_type
        - outcome_index
      properties:
        position_id:
          type: string
          description: Position id of this leg (decimal).
        v2_condition_id:
          type: string
          description: |-
            Alternate condition id form of this leg; use `condition_id` for
            market lookups.
        condition_id:
          type: string
          description: |-
            Condition id of the leg's market — use this with the market
            endpoints.
        leg_market_type:
          $ref: '#/components/schemas/ComboLegMarketType'
          description: Type of the leg's market.
        outcome_index:
          type: integer
          format: int32
          description: Index of the outcome this leg is on within its market.
          minimum: 0
        outcome:
          type:
            - string
            - 'null'
          description: Outcome name (e.g. "Yes", "No", or a team/player name).
        last_price:
          type:
            - number
            - 'null'
          format: double
          description: Latest traded price of this leg's outcome (0-1).
        status:
          type:
            - string
            - 'null'
          description: |-
            Leg result: "won", "lost", or "pending" while the market is
            unresolved.
        market_slug:
          type:
            - string
            - 'null'
        event_slug:
          type:
            - string
            - 'null'
        question:
          type:
            - string
            - 'null'
        title:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'
    ComboLegMarketType:
      type: string
      description: Kind of market a combo leg is on.
      enum:
        - binary
        - multi_outcome

````