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

# Lifetime Performance

> View lifetime trading performance for a specific wallet address. Wallet Stats All Time on Our data (~9mo)

**Platform:** Polymarket\
**Endpoint:** `POST /v2/semantic/retrieve/parameterized`\
**Authentication:** Bearer token

## Query parameters

All requests use `agent_id` `586` (Lifetime Performance). Set filters inside `params` in the playground — all values must be strings.

| Parameter | Type | Description |
| - | - | - |
| `wallet_address` | String | Wallet address (required). For example, `"0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"`. |

## Example Request

```bash cURL theme={null}
curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 586,
  "params": {
    "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 586,
    "params": {
        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "agent_id": 586,
  "params": {
    "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();
```

## Example Response

```json theme={null}
{
  "timestamp": "",
  "params": {
    "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "avg_pnl_per_trade": "2.26",
        "avg_trade_size": "122.24",
        "last_updated": "2026-03-14T00:00:00Z",
        "proxy_wallet": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e",
        "roi_pct": "1.85",
        "total_invested": "22785473.35",
        "total_pnl": "420395.44",
        "total_trades": 186403
      }
    ]
  }
}
```

## Response fields

| Field | Type | Description |
| - | - | - |
| `proxy_wallet` | String | Proxy wallet address associated with the trading activity |
| `total_trades` | Integer | Total number of trades executed |
| `avg_trade_size` | String (Decimal) | Average size of each trade |
| `avg_pnl_per_trade` | String (Decimal) | Average profit or loss generated per trade |
| `total_invested` | String (Decimal) | Total capital invested across all trades |
| `total_pnl` | String (Decimal) | Total profit and loss across all trades (negative values indicate a loss) |
| `roi_pct` | String (Decimal) | Return on investment expressed as a percentage |
| `last_updated` | String (ISO 8601) | Timestamp indicating when the metrics were last updated |


## OpenAPI

````yaml /api-reference/polymarket-lifetime-performance.openapi.json POST /api/v2/semantic/retrieve/parameterized
openapi: 3.1.0
info:
  title: Falcon API — Lifetime Performance
  version: 1.0.0
servers:
  - url: https://narrative.agent.heisenberg.so
    description: Production
security:
  - bearerAuth: []
paths:
  /api/v2/semantic/retrieve/parameterized:
    post:
      tags:
        - Polymarket
      summary: Lifetime Performance
      description: View lifetime trading performance for a specific wallet address.
      operationId: polymarketLifetimePerformance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolymarketLifetimePerformanceRequest'
            examples:
              default:
                summary: Lifetime stats for a wallet
                value:
                  agent_id: 586
                  params:
                    wallet_address: '0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e'
                  pagination:
                    limit: 10
                    offset: 0
                  formatter_config:
                    format_type: raw
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolymarketLifetimePerformanceResponse'
        '400':
          description: Bad request — check params
        '401':
          description: Unauthorized — check your Bearer token
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
              --header 'Authorization: Bearer YOUR_TOKEN' \
              --header 'Content-Type: application/json' \
              --data '{
              "agent_id": 586,
              "params": {
                "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
              },
              "pagination": { "limit": 10, "offset": 0 },
              "formatter_config": { "format_type": "raw" }
            }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
                headers={"Authorization": "Bearer YOUR_TOKEN"},
                json={
                    "agent_id": 586,
                    "params": {
                        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e",
                    },
                    "pagination": {"limit": 10, "offset": 0},
                    "formatter_config": {"format_type": "raw"},
                },
            )

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: |-
            const response = await fetch(
              "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
              {
                method: "POST",
                headers: {
                  Authorization: "Bearer YOUR_TOKEN",
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  agent_id: 586,
                  params: {
                    wallet_address: "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e",
                  },
                  pagination: { limit: 10, offset: 0 },
                  formatter_config: { format_type: "raw" },
                }),
              }
            );

            const data = await response.json();
components:
  schemas:
    PolymarketLifetimePerformanceRequest:
      type: object
      required:
        - params
      properties:
        agent_id:
          type: integer
          enum:
            - 586
          default: 586
          x-default: 586
          description: Lifetime Performance agent ID.
        params:
          $ref: '#/components/schemas/PolymarketLifetimePerformanceParams'
        pagination:
          $ref: '#/components/schemas/PolymarketLifetimePerformancePagination'
        formatter_config:
          $ref: '#/components/schemas/PolymarketLifetimePerformanceFormatterConfig'
    PolymarketLifetimePerformanceResponse:
      type: object
      readOnly: true
      properties:
        timestamp:
          type: string
          readOnly: true
        params:
          $ref: '#/components/schemas/PolymarketLifetimePerformanceResponseParams'
        pagination:
          type: object
          readOnly: true
          properties:
            limit:
              type: integer
              readOnly: true
            offset:
              type: integer
              readOnly: true
            has_more:
              type: boolean
              readOnly: true
        data:
          type: object
          readOnly: true
          properties:
            results:
              type: array
              readOnly: true
              items:
                type: object
                readOnly: true
                additionalProperties: true
        request_id:
          type: string
          readOnly: true
    PolymarketLifetimePerformanceParams:
      type: object
      description: Filter parameters. All values must be strings.
      additionalProperties: false
      required:
        - wallet_address
      properties:
        wallet_address:
          type: string
          default: '0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e'
          description: Wallet address to retrieve lifetime performance for.
    PolymarketLifetimePerformancePagination:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 10
          description: Maximum number of records returned per request.
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of records to skip before returning results.
    PolymarketLifetimePerformanceFormatterConfig:
      type: object
      properties:
        format_type:
          type: string
          enum:
            - raw
          default: raw
          description: Output format. Use "raw" for structured JSON.
    PolymarketLifetimePerformanceResponseParams:
      type: object
      readOnly: true
      properties:
        wallet_address:
          type: string
          readOnly: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Falcon API key from the dashboard

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.