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

> Get profit and loss for a wallet in USD. Supports time-windowed P&L with ?period=1d|7d|30d|1y plus tag, category, market, event, and condition filters.

Returns P\&L data for a wallet in USD. Without a `period` parameter, returns all-time P\&L. With `period`, `after`, or `before`, returns realized P\&L for that time window.

The two modes have different counting semantics: all-time `wins` and `losses` are position counts; time-windowed `wins`, `losses`, and `events` are realized P\&L event counts. Do not compare the counts directly.

<Note>
  Wallet P\&L supports focused market filters such as `category`, `tags`/`tag_slug`, `market`/`market_slug`, `event_slug`, and `condition_id`. For leaderboard views, use one primary filter dimension per request.
</Note>

## Request

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

### Query parameters

| Parameter            | Type    | Default | Description                                                                                                                                    |
| -------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `period`             | string  | --      | Time window: `1d`, `7d`, `30d`, `1y`                                                                                                           |
| `after`              | integer | --      | Start timestamp (Unix seconds). Time-windowed queries clamp values below `1` to `1`.                                                           |
| `before`             | integer | --      | End timestamp (Unix seconds)                                                                                                                   |
| `category`           | string  | --      | Filter to one market category, case-insensitive                                                                                                |
| `tags`               | string  | --      | Comma-separated tag slugs to filter by, case-insensitive (e.g. `politics,crypto`, `nfl`, `Iran`)                                               |
| `tag_slug`           | string  | --      | Alias for a single `tags` value                                                                                                                |
| `market`             | string  | --      | Filter by condition ID or market slug                                                                                                          |
| `market_slug`        | string  | --      | Filter by market slug                                                                                                                          |
| `event_slug`         | string  | --      | Filter by parent event slug                                                                                                                    |
| `condition_id`       | string  | --      | Filter by market condition ID                                                                                                                  |
| `include_unrealized` | string  | `false` | Set to `true` to include current unrealized P\&L alongside the realized event-window result. Only applies to time-filtered queries.            |
| `include_combos`     | boolean | `false` | Add combo position P\&L to all-time wallet P\&L. If the wallet has no combo exposure, the response remains 200 with a zero combo contribution. |

## Examples

### All-time P\&L

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

### All-time P\&L including combos

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x63613e3b96f418332d43cd2af8dc321014d15907/pnl?include_combos=true"
```

```json theme={null}
{
  "address": "0x63613e3b96f418332d43cd2af8dc321014d15907",
  "net_realized_pnl": 113.510513,
  "realized_pnl": 113.510513,
  "gross_profit": 184.901354,
  "gross_loss": -71.390841,
  "unrealized_pnl": 0.0,
  "total_pnl": 113.510513,
  "position_count": 21496,
  "open_positions": 1495,
  "total_volume": 129.837476,
  "include_combos": true,
  "included_position_types": ["market", "combo"],
  "combo_pnl": {
    "position_type": "combo",
    "included": true,
    "realized_pnl": 113.510513,
    "unrealized_pnl": 0.0,
    "total_pnl": 113.510513,
    "position_count": 21492,
    "open_positions": 1495
  }
}
```

For time-windowed or tag-filtered P\&L, the response stays successful. If combo P\&L cannot be safely added to that filtered view, `combo_pnl.included` is `false` and the standard market P\&L fields remain unchanged.

```json theme={null}
{
  "address": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
  "net_realized_pnl": 22053845.825455,
  "gross_profit": 22057977.181649,
  "gross_loss": -4131.356194,
  "unrealized_pnl": 0.000688755,
  "total_pnl": 22053845.826143753,
  "position_count": 22,
  "open_positions": 1,
  "total_volume": 43013258.515682,
  "wins": 18,
  "losses": 4,
  "elapsed_ms": 41
}
```

### 30-day P\&L

```bash theme={null}
curl https://api.polynode.dev/v3/wallets/0xbddf61af533ff524d27154e589d2d7a81510c684/pnl?period=30d
```

```json theme={null}
{
  "address": "0xbddf61af533ff524d27154e589d2d7a81510c684",
  "realized_pnl": 1815261.28,
  "gross_profit": 1918402.27,
  "gross_loss": -103140.98,
  "wins": 33039,
  "losses": 58867,
  "events": 91906,
  "source": "realized_pnl_series",
  "period": "30d",
  "after": 1776134996,
  "before": 1778726996,
  "elapsed_ms": 5902
}
```

### Filtered P\&L

```bash theme={null}
curl "https://api.polynode.dev/v3/wallets/0x952d11ebff81d6bd3185e608ed3515b94618ab8a/pnl?category=crypto"
curl "https://api.polynode.dev/v3/wallets/0x952d11ebff81d6bd3185e608ed3515b94618ab8a/pnl?tag_slug=us-election&period=30d"
curl "https://api.polynode.dev/v3/wallets/0x952d11ebff81d6bd3185e608ed3515b94618ab8a/pnl?market_slug=will-donald-trump-win-the-popular-vote-in-the-2024-presidential-election"
curl "https://api.polynode.dev/v3/wallets/0x952d11ebff81d6bd3185e608ed3515b94618ab8a/pnl?event_slug=presidential-election-popular-vote-winner-2024"
```

### 30-day P\&L with unrealized

Pass `include_unrealized=true` to include current unrealized P\&L alongside the realized event-window result.

```bash theme={null}
curl https://api.polynode.dev/v3/wallets/0xbddf61af533ff524d27154e589d2d7a81510c684/pnl?period=30d&include_unrealized=true
```

```json theme={null}
{
  "address": "0xbddf61af533ff524d27154e589d2d7a81510c684",
  "realized_pnl": 1815261.28,
  "gross_profit": 1918402.27,
  "gross_loss": -103140.98,
  "unrealized_pnl": 14714.71,
  "total_pnl": 1829975.99,
  "open_positions_at_date": 363,
  "wins": 33039,
  "losses": 58867,
  "events": 91906,
  "source": "realized_pnl_series",
  "period": "30d",
  "after": 1776135002,
  "before": 1778727002,
  "elapsed_ms": 3803
}
```

## Response fields (all-time)

| Field                     | Type    | Description                                       |
| ------------------------- | ------- | ------------------------------------------------- |
| `net_realized_pnl`        | number  | Net realized P\&L (USD)                           |
| `gross_profit`            | number  | Sum of winning positions (USD)                    |
| `gross_loss`              | number  | Sum of losing positions (USD, negative)           |
| `unrealized_pnl`          | number  | Paper P\&L from open positions (USD)              |
| `total_pnl`               | number  | `net_realized_pnl + unrealized_pnl` (USD)         |
| `wins`                    | integer | Winning position count                            |
| `losses`                  | integer | Losing position count                             |
| `position_count`          | integer | Total positions                                   |
| `open_positions`          | integer | Currently held positions                          |
| `total_volume`            | number  | Total volume traded (USD)                         |
| `include_combos`          | boolean | Present when `include_combos=true` was requested  |
| `included_position_types` | array   | Position families included in aggregate totals    |
| `combo_pnl`               | object  | Combo-only contribution to the aggregate response |

## Response fields (with period)

| Field          | Type    | Description                                        |
| -------------- | ------- | -------------------------------------------------- |
| `realized_pnl` | number  | Realized P\&L in the time window (USD)             |
| `gross_profit` | number  | Sum of winning events in the window (USD)          |
| `gross_loss`   | number  | Sum of losing events in the window (USD, negative) |
| `wins`         | integer | Winning event count                                |
| `losses`       | integer | Losing event count                                 |
| `events`       | integer | Total P\&L events in the window                    |
| `period`       | string  | The requested period                               |
| `after`        | integer | Start timestamp (Unix seconds)                     |
| `before`       | integer | End timestamp (Unix seconds)                       |
| `source`       | string  | Dataset label for time-windowed queries            |

### Additional fields (with `include_unrealized=true`)

| Field                    | Type    | Description                                                                                            |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------ |
| `unrealized_pnl`         | number  | Current unrealized P\&L for open positions (USD), returned alongside the realized event-window result. |
| `total_pnl`              | number  | `realized_pnl + unrealized_pnl` (USD)                                                                  |
| `open_positions_at_date` | integer | Current open position count returned with the unrealized P\&L estimate                                 |


## OpenAPI

````yaml GET /v3/wallets/{address}/pnl
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:
    get:
      tags:
        - V3 Wallets
      summary: Wallet P&L
      description: >-
        Get wallet profit and loss. Default/all-time mode returns current
        all-time P&L. Time-windowed mode returns realized P&L for the selected
        range.
      operationId: v3_wallet_pnl
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: Wallet address
        - name: period
          in: query
          schema:
            type: string
            enum:
              - 1d
              - 7d
              - 30d
              - 1y
          description: Time window shortcut
        - name: after
          in: query
          schema:
            type: integer
          description: Unix timestamp lower bound
        - name: before
          in: query
          schema:
            type: integer
          description: Unix timestamp upper bound
        - name: include_unrealized
          in: query
          schema:
            type: boolean
            default: false
          description: Include current unrealized P&L alongside time-windowed realized P&L
      responses:
        '200':
          description: Wallet P&L
        '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

````