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

# Get trader category PnL

> Per-category PnL for a trader.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/trader/pnl/{address}/categories
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}/categories:
    get:
      tags:
        - Trader
      summary: Get trader category PnL
      description: Per-category PnL for a trader.
      operationId: get_trader_category_pnl
      parameters:
        - name: address
          in: path
          description: Trader wallet address
          required: true
          schema:
            type: string
        - name: timeframe
          in: query
          description: 'Default: lifetime'
          required: false
          schema:
            $ref: '#/components/schemas/PnlTimeframe'
        - name: sort_by
          in: query
          description: >-
            Default: realized_pnl_usd. Includes the fee-excluded `raw_*` PnL
            metrics.
          required: false
          schema:
            $ref: '#/components/schemas/CategoryPnlSortBy'
        - name: sort_direction
          in: query
          description: 'Default: desc'
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
        - name: limit
          in: query
          description: Default 50, max 500
          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 a previous response
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Per-category PnL rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryPnl'
        '400':
          description: Invalid params
components:
  schemas:
    PnlTimeframe:
      type: string
      enum:
        - 1d
        - 7d
        - 30d
        - lifetime
    CategoryPnlSortBy:
      type: string
      description: |-
        Sort field for category PnL results. Includes fee-excluded (`raw_*`)
        PnL metrics.
      enum:
        - realized_pnl_usd
        - total_pnl_usd
        - unrealized_pnl_usd
        - raw_total_pnl_usd
        - raw_realized_pnl_usd
        - raw_unrealized_pnl_usd
        - raw_total_pnl_pct
        - raw_realized_pnl_pct
        - raw_unrealized_pnl_pct
        - total_volume_usd
        - buy_volume_usd
        - sell_volume_usd
        - redemption_volume_usd
        - merge_volume_usd
        - split_volume_usd
        - total_converts
        - total_fees
        - total_buys
        - total_sells
        - total_splits
        - total_shares_bought
        - markets_traded
        - markets_resolved
        - markets_won
        - markets_lost
        - market_win_rate_pct
        - avg_win_usd
        - avg_loss_usd
        - profit_factor
        - total_wins_usd
        - total_losses_usd
        - best_trade_pnl_usd
        - worst_trade_pnl_usd
        - avg_hold_time_seconds
        - buy_count
        - sell_count
        - redeem_count
        - merge_count
        - split_count
        - outcomes_traded
        - first_trade_at
        - last_trade_at
    SortDirection:
      type: string
      enum:
        - asc
        - desc
    CategoryPnl:
      type: object
      required:
        - realized_pnl_usd
        - markets_traded
        - markets_resolved
        - markets_won
        - markets_lost
        - market_win_rate_pct
        - avg_win_usd
        - avg_loss_usd
        - profit_factor
        - total_buys
        - total_sells
        - total_redemptions
        - total_merges
        - total_volume_usd
        - buy_volume_usd
        - sell_volume_usd
        - redemption_volume_usd
        - merge_volume_usd
        - total_fees
        - total_wins_usd
        - total_losses_usd
        - avg_hold_time_seconds
        - total_shares_bought
        - buy_count
        - sell_count
        - redeem_count
        - merge_count
        - split_count
        - converted_count
        - converted_shares_gained
        - converted_shares_lost
        - outcomes_traded
        - last_block
      properties:
        category:
          type:
            - string
            - 'null'
          description: Category.
        trader:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TraderProfile'
              description: Trader wallet or profile.
        realized_pnl_usd:
          type: number
          format: double
          description: Realized PnL in USD.
        total_pnl_usd:
          type: number
          format: double
          description: Total PnL in USD.
        unrealized_pnl_usd:
          type: number
          format: double
          description: Unrealized PnL in USD.
        realized_pnl_pct:
          type:
            - number
            - 'null'
          format: double
          description: Realized PnL percent.
        total_pnl_pct:
          type:
            - number
            - 'null'
          format: double
          description: Total PnL percent.
        markets_traded:
          type: integer
          format: int64
          description: Markets traded.
          minimum: 0
        markets_resolved:
          type: integer
          format: int64
          description: Markets resolved.
          minimum: 0
        markets_won:
          type: integer
          format: int64
          description: Markets won.
          minimum: 0
        markets_lost:
          type: integer
          format: int64
          description: Markets lost.
          minimum: 0
        market_win_rate_pct:
          type: number
          format: double
          description: Market win rate percent.
        avg_win_usd:
          type: number
          format: double
          description: Average win in USD.
        avg_loss_usd:
          type: number
          format: double
          description: Average loss in USD.
        profit_factor:
          type: number
          format: double
          description: Profit factor.
        total_buys:
          type: integer
          format: int64
          description: Total buys.
          minimum: 0
        total_sells:
          type: integer
          format: int64
          description: Total sells.
          minimum: 0
        total_redemptions:
          type: integer
          format: int64
          description: Total redemptions.
          minimum: 0
        total_merges:
          type: integer
          format: int64
          description: Total merges.
          minimum: 0
        total_splits:
          type: integer
          format: int64
          description: Number of split transactions in the selected timeframe.
          minimum: 0
        total_volume_usd:
          type: number
          format: double
          description: Total volume in USD.
        buy_volume_usd:
          type: number
          format: double
          description: Buy volume in USD.
        sell_volume_usd:
          type: number
          format: double
          description: Sell volume in USD.
        redemption_volume_usd:
          type: number
          format: double
          description: Redemption volume in USD.
        merge_volume_usd:
          type: number
          format: double
          description: Merge volume in USD.
        convert_collateral_usd:
          type: number
          format: double
          description: Convert collateral in USD.
        split_volume_usd:
          type: number
          format: double
          description: USD collateral split into outcome tokens in the selected timeframe.
        total_fees:
          type: number
          format: double
          description: Total fees.
        total_wins_usd:
          type: number
          format: double
          description: Total wins in USD.
        total_losses_usd:
          type: number
          format: double
          description: Total losses in USD.
        best_trade_pnl_usd:
          type:
            - number
            - 'null'
          format: double
          description: Best trade PnL in USD.
        best_trade_condition_id:
          type:
            - string
            - 'null'
          description: Best trade condition ID.
        worst_trade_pnl_usd:
          type:
            - number
            - 'null'
          format: double
          description: Worst trade PnL in USD.
        worst_trade_condition_id:
          type:
            - string
            - 'null'
          description: Worst trade condition ID.
        best_trade_metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TradeMarketRef'
              description: |-
                Market metadata (condition_id, slug, title, question, image_url,
                event_slug) for the market behind the best PnL trade in this
                summary at this timeframe. `null` when no trade qualifies.
        worst_trade_metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TradeMarketRef'
              description: Market metadata for the market behind the worst PnL trade.
        avg_hold_time_seconds:
          type: number
          format: double
          description: Average hold time seconds.
        total_shares_bought:
          type: number
          format: double
          description: Total shares bought.
        total_shares_sold:
          type: number
          format: double
          description: Total shares sold (sells + merges; redemption shares excluded).
        buy_count:
          type: integer
          format: int64
          description: Buy count.
          minimum: 0
        sell_count:
          type: integer
          format: int64
          description: Sell count.
          minimum: 0
        redeem_count:
          type: integer
          format: int64
          description: Redeem count.
          minimum: 0
        merge_count:
          type: integer
          format: int64
          description: Merge count.
          minimum: 0
        split_count:
          type: integer
          format: int64
          description: Split count.
          minimum: 0
        converted_count:
          type: integer
          format: int64
          description: Converted count.
          minimum: 0
        converted_shares_gained:
          type: number
          format: double
          description: Converted shares gained.
        converted_shares_lost:
          type: number
          format: double
          description: Converted shares lost.
        outcomes_traded:
          type: integer
          format: int64
          description: Outcomes traded.
          minimum: 0
        first_trade_at:
          type:
            - integer
            - 'null'
          format: int64
          description: First trade at timestamp.
        last_trade_at:
          type:
            - integer
            - 'null'
          format: int64
          description: Last trade at timestamp.
        last_block:
          type: integer
          format: int64
          description: Last block.
          minimum: 0
    TraderProfile:
      type: object
      required:
        - address
        - verified_badge
      properties:
        address:
          type: string
          description: Wallet address.
        name:
          type:
            - string
            - 'null'
          description: Name.
        pseudonym:
          type:
            - string
            - 'null'
          description: Pseudonym.
        profile_image:
          type:
            - string
            - 'null'
          description: Profile image.
        x_username:
          type:
            - string
            - 'null'
          description: X username.
        verified_badge:
          type: boolean
          description: Verified badge.
    TradeMarketRef:
      type: object
      description: >-
        Market metadata for the market a trader's best / worst trade landed in.

        Accompanies the existing flat `best_trade_pnl_usd` /
        `worst_trade_pnl_usd`

        numerics on trader / event / category PnL summaries.
      properties:
        condition_id:
          type:
            - string
            - 'null'
          description: Condition ID.
        market_slug:
          type:
            - string
            - 'null'
          description: Market slug.
        title:
          type:
            - string
            - 'null'
          description: Title.
        question:
          type:
            - string
            - 'null'
          description: Question.
        image_url:
          type:
            - string
            - 'null'
          description: Image URL.
        event_slug:
          type:
            - string
            - 'null'
          description: Event slug.

````