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

> Per-category PnL candles for a trader. Same shape as `/candles`, plus a required `category`.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/trader/pnl/{address}/category-candles
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}/category-candles:
    get:
      tags:
        - Trader
      summary: Get trader category PnL candles
      description: >-
        Per-category PnL candles for a trader. Same shape as `/candles`, plus a
        required `category`.
      operationId: get_trader_category_pnl_candles
      parameters:
        - name: address
          in: path
          description: Trader wallet address
          required: true
          schema:
            type: string
        - name: category
          in: query
          description: Category to scope candles to. Required.
          required: true
          schema:
            $ref: '#/components/schemas/PolymarketCategory'
        - name: resolution
          in: query
          description: >-
            Candle bucket size. `auto` picks the finest resolution that fits the
            whole span within max `count_back` (2500) and overrides any
            caller-supplied `count_back`. Default: 1m for 1d, 1d otherwise.
          required: false
          schema:
            $ref: '#/components/schemas/PnlCandleResolution'
        - name: timeframe
          in: query
          description: 'Default: lifetime'
          required: false
          schema:
            $ref: '#/components/schemas/PnlCandleTimeframe'
        - name: from
          in: query
          description: >-
            Start unix seconds. Overrides the timeframe lower bound. Ignored
            when `count_back` and `to` are both supplied — that combination
            walks `count_back` buckets back from `to`.
          required: false
          schema:
            type: integer
            format: int64
        - name: to
          in: query
          description: >-
            End unix seconds. Defaults to now. Synthetic buckets are never
            emitted past now.
          required: false
          schema:
            type: integer
            format: int64
        - name: count_back
          in: query
          description: >-
            Number of candle buckets to return. Default 500, max 2500. Ignored
            when `resolution=auto` (forced to 2500).
          required: false
          schema:
            type: integer
            format: int32
        - name: pagination_key
          in: query
          description: Cursor from a previous response
          required: false
          schema:
            type: string
        - name: fill_gaps
          in: query
          description: >-
            Forward-fill buckets the trader had no activity in, carrying the
            previous close through to `to` (or now). Default: true. When false,
            only buckets with activity are returned — no synthetic buckets at
            all, so the series ends at the trader's last activity rather than at
            `to`.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Trader category PnL candles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PnlCandlestickBar'
        '400':
          description: Invalid params or endpoint disabled
components:
  schemas:
    PolymarketCategory:
      type: string
      description: Polymarket UI category.
      enum:
        - Politics
        - Sports
        - Crypto
        - Finance
        - Culture
        - Mentions
        - Weather
        - Economics
        - Tech
    PnlCandleResolution:
      type: string
      enum:
        - 1m
        - 1h
        - 4h
        - 1d
        - auto
    PnlCandleTimeframe:
      type: string
      enum:
        - 1d
        - 7d
        - 30d
        - lifetime
    PnlCandlestickBar:
      type: object
      required:
        - t
        - ob
        - cb
        - ub
        - pb
        - nop
      properties:
        t:
          type: integer
          format: int64
          description: Timestamp in epoch seconds at the start of the candle bucket.
          minimum: 0
        ob:
          type: integer
          format: int64
          description: Opening block for this candle.
        cb:
          type: integer
          format: int64
          description: Closing block for this candle.
        ub:
          type: number
          format: double
          description: Latest USDC balance at candle close.
        pb:
          type: number
          format: double
          description: Latest pUSD balance at candle close.
        nop:
          type: integer
          format: int32
          description: Latest open position count at candle close.
        l:
          type:
            - number
            - 'null'
          format: double
          description: Total PnL low value for the candle (= realized + unrealized).
        h:
          type:
            - number
            - 'null'
          format: double
          description: High price.
        o:
          type:
            - number
            - 'null'
          format: double
          description: Open price.
        c:
          type:
            - number
            - 'null'
          format: double
          description: Close price.
        rl:
          type:
            - number
            - 'null'
          format: double
          description: Realized PnL low.
        rh:
          type:
            - number
            - 'null'
          format: double
          description: Realized PnL high.
        ro:
          type:
            - number
            - 'null'
          format: double
          description: Realized PnL open.
        rc:
          type:
            - number
            - 'null'
          format: double
          description: Realized PnL close.
        ul:
          type:
            - number
            - 'null'
          format: double
          description: Unrealized PnL low.
        uh:
          type:
            - number
            - 'null'
          format: double
          description: Unrealized PnL high.
        uo:
          type:
            - number
            - 'null'
          format: double
          description: Unrealized PnL open.
        uc:
          type:
            - number
            - 'null'
          format: double
          description: Unrealized PnL close.
        pl:
          type:
            - number
            - 'null'
          format: double
          description: Portfolio value low.
        ph:
          type:
            - number
            - 'null'
          format: double
          description: Portfolio value high.
        po:
          type:
            - number
            - 'null'
          format: double
          description: Portfolio value open.
        pc:
          type:
            - number
            - 'null'
          format: double
          description: Portfolio value close.

````