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

# Wallet P&L Time Series

> Realized P&L bucketed by hour, day, week, or month — chart-ready time series for a wallet.

Returns wallet P\&L buckets for charting. With `period`, `after`, or `before`, each row is a fixed time window (hour, day, week, or month). A running `cumulative_pnl` is included so the response can be plotted directly.

Without an explicit time filter, the endpoint returns a single all-time summary bucket that matches [`GET /v3/wallets/{address}/pnl`](/data/wallets/pnl).

In event-series mode, `wins`, `losses`, and `events` count realized P\&L events in the selected window. In default summary mode, counts are position counts and the response includes `count_type: "positions"` and `summary_bucket: true`.

Rows at timestamp `0` or earlier are ignored in event-series mode, so explicit event windows start at Unix second `1`.

## Request

```
GET /v3/wallets/{address}/pnl/events
```

### Query parameters

| Parameter | Type    | Default | Description                                                                     |
| --------- | ------- | ------- | ------------------------------------------------------------------------------- |
| `group`   | string  | `day`   | Bucket size: `hour`, `day`, `week`, `month`                                     |
| `period`  | string  | --      | Shortcut for `after`: `1d`, `7d`, `30d`, `1y`                                   |
| `after`   | integer | `1`     | Start timestamp (Unix seconds, inclusive). Values below `1` are treated as `1`. |
| `before`  | integer | now     | End timestamp (Unix seconds, inclusive)                                         |
| `limit`   | integer | `5000`  | Max buckets returned, clamped 1-10000                                           |

If `after` and `period` are both set, `after` wins.

## Examples

### All-time summary bucket

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0xbddf61af533ff524d27154e589d2d7a81510c684/pnl/events"
```

```json theme={null}
{
  "address": "0xbddf61af533ff524d27154e589d2d7a81510c684",
  "granularity": "day",
  "bucket_count": 1,
  "buckets": [
    {
      "bucket": 1779908613,
      "realized_pnl": 29035964.931344,
      "cumulative_pnl": 29035964.931344,
      "gross_profit": 29818047.886063,
      "gross_loss": -782082.954719,
      "wins": 482,
      "losses": 33,
      "events": 1016,
      "position_count": 1016,
      "open_positions": 511,
      "unrealized_pnl": -26917534.501466,
      "total_pnl": 2118430.429878,
      "total_volume": 177203290.120101
    }
  ],
  "total_realized_pnl": 29035964.931344,
  "total_events": 1016,
  "total_wins": 482,
  "total_losses": 33,
  "total_positions": 1016,
  "open_positions": 511,
  "unrealized_pnl": -26917534.501466,
  "total_pnl": 2118430.429878,
  "source": "wallet_summary",
  "count_type": "positions",
  "summary_bucket": true,
  "elapsed_ms": 3
}
```

### Daily P\&L for the last 7 days

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x44c1dfe43260c94ed4f1d00de2e1f80fb113ebc1/pnl/events?period=7d&group=day"
```

```json theme={null}
{
  "address": "0x44c1dfe43260c94ed4f1d00de2e1f80fb113ebc1",
  "granularity": "day",
  "after": 1778478745,
  "before": 1779083545,
  "bucket_count": 3,
  "buckets": [
    {
      "bucket": 1778889600,
      "realized_pnl": 0.000525,
      "cumulative_pnl": 0.000525,
      "gross_profit": 0.000525,
      "gross_loss": 0,
      "wins": 1,
      "losses": 0,
      "events": 1
    },
    {
      "bucket": 1778976000,
      "realized_pnl": 611.069702,
      "cumulative_pnl": 611.070227,
      "gross_profit": 618.41811,
      "gross_loss": -7.348408,
      "wins": 23,
      "losses": 3,
      "events": 26
    },
    {
      "bucket": 1779062400,
      "realized_pnl": 11.774724,
      "cumulative_pnl": 622.844951,
      "gross_profit": 11.774724,
      "gross_loss": 0,
      "wins": 2,
      "losses": 0,
      "events": 2
    }
  ],
  "total_realized_pnl": 622.844951,
  "total_events": 29,
  "total_wins": 26,
  "total_losses": 3,
  "source": "realized_pnl_series",
  "elapsed_ms": 4
}
```

### Hourly P\&L for an explicit window

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x44c1dfe43260c94ed4f1d00de2e1f80fb113ebc1/pnl/events?after=1778976000&before=1779062400&group=hour"
```

### Weekly P\&L for the last year

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x44c1dfe43260c94ed4f1d00de2e1f80fb113ebc1/pnl/events?period=1y&group=week"
```

## Response fields

| Field                      | Type    | Description                                                                    |
| -------------------------- | ------- | ------------------------------------------------------------------------------ |
| `address`                  | string  | The wallet address (lowercased)                                                |
| `granularity`              | string  | Resolved bucket size (`hour`, `day`, `week`, `month`)                          |
| `after`                    | integer | Start of the window (Unix seconds, inclusive)                                  |
| `before`                   | integer | End of the window (Unix seconds, inclusive)                                    |
| `bucket_count`             | integer | Number of buckets returned                                                     |
| `buckets`                  | array   | Time-series rows, ordered oldest → newest                                      |
| `buckets[].bucket`         | integer | Bucket start timestamp (Unix seconds, UTC, truncated to bucket boundary)       |
| `buckets[].realized_pnl`   | number  | Realized P\&L in that bucket (USD)                                             |
| `buckets[].cumulative_pnl` | number  | Running sum of `realized_pnl` over the returned series (USD)                   |
| `buckets[].gross_profit`   | number  | Sum of winning events in that bucket (USD)                                     |
| `buckets[].gross_loss`     | number  | Sum of losing events in that bucket (USD, negative)                            |
| `buckets[].wins`           | integer | Count of winning events in that bucket                                         |
| `buckets[].losses`         | integer | Count of losing events in that bucket                                          |
| `buckets[].events`         | integer | Total P\&L events in event-series mode; position count in default summary mode |
| `buckets[].position_count` | integer | Position count. Present in default summary mode.                               |
| `buckets[].open_positions` | integer | Open position count. Present in default summary mode.                          |
| `buckets[].unrealized_pnl` | number  | Current unrealized P\&L. Present in default summary mode.                      |
| `buckets[].total_pnl`      | number  | `realized_pnl + unrealized_pnl`. Present in default summary mode.              |
| `buckets[].total_volume`   | number  | Wallet volume from the summary source. Present in default summary mode.        |
| `total_realized_pnl`       | number  | Sum of `realized_pnl` across all returned buckets (USD)                        |
| `total_events`             | integer | Sum of `events` across all returned buckets                                    |
| `total_wins`               | integer | Sum of `wins` across all returned buckets                                      |
| `total_losses`             | integer | Sum of `losses` across all returned buckets                                    |
| `source`                   | string  | Dataset label                                                                  |
| `count_type`               | string  | `positions` in default summary mode                                            |
| `summary_bucket`           | boolean | `true` in default summary mode                                                 |
| `elapsed_ms`               | integer | Server-side query time in milliseconds                                         |

## Errors

| HTTP  | When                                                              |
| ----- | ----------------------------------------------------------------- |
| `400` | Invalid wallet address (must be `0x` + 40 hex)                    |
| `400` | Invalid `group` value (must be `hour`, `day`, `week`, or `month`) |
| `400` | `after` greater than `before`                                     |


## OpenAPI

````yaml GET /v3/wallets/{address}/pnl/events
openapi: 3.1.0
info:
  title: PolyNode API
  description: >-
    Real-time Polymarket data API with decoded mempool settlements, OHLCV
    candles, and full Polygon JSON-RPC proxy.
  contact:
    name: PolyNode
    url: https://polynode.dev
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.polynode.dev
    description: Production
security:
  - api_key: []
paths:
  /v3/wallets/{address}/pnl/events:
    get:
      tags:
        - V3 Wallets
      summary: Wallet P&L time series
      description: >-
        Get wallet P&L buckets. Default/all-time mode returns a single all-time
        bucket. Explicit time filters return realized P&L buckets.
      operationId: v3_wallet_pnl_events
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: Wallet address
        - name: group
          in: query
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
            default: day
          description: Bucket size
        - name: period
          in: query
          schema:
            type: string
            enum:
              - 1d
              - 7d
              - 30d
              - 1y
          description: Time window shortcut
        - name: after
          in: query
          schema:
            type: integer
            default: 1
          description: Unix timestamp lower bound. Values below 1 are clamped to 1.
        - name: before
          in: query
          schema:
            type: integer
          description: Unix timestamp upper bound
        - name: limit
          in: query
          schema:
            type: integer
            default: 5000
          description: Maximum bucket count, clamped to 10000
      responses:
        '200':
          description: Wallet P&L buckets
        '400':
          description: Invalid wallet address or query parameter
        '401':
          description: Unauthorized
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````