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

# PnL Leaderboard

> Falcon Leaderboard API

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

## Query parameters

All requests use `agent_id` `579` (PnL Leaderboard). Set filters inside `params` in the playground — all values must be strings.

| Parameter | Type | Description |
| - | - | - |
| `wallet_address` | String | Use `"ALL"` for all wallets, or a specific wallet address. |
| `leaderboard_period` | String | Time window: `1d`, `3d`, `7d`, or `30d`. |

## 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": 579,
  "params": {
    "wallet_address": "ALL",
    "leaderboard_period": "1d"
  },
  "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": 579,
    "params": {
        "wallet_address": "ALL",
        "leaderboard_period": "1d"
    },
    "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": 579,
  "params": {
    "wallet_address": "ALL",
    "leaderboard_period": "1d"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

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

## Example Response

```json theme={null}
{
  "timestamp": "2025-01-15T12:00:00Z",
  "params": {
    "min_win_rate_15d": "0.45",
    "max_win_rate_15d": "0.95",
    "min_roi_15d": "0",
    "min_total_trades_15d": "50",
    "max_total_trades_15d": "100000",
    "min_pnl_15d": "5000",
    "sort_by": "roi"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "leaderboard_rank": 1,
        "wallet": "0x0720803c7cb0d0c5a928787b3b7ea148c6831cdb",
        "tier": "A",
        "f_score": 87.4,
        "roi_pct_15d": 41.5,
        "win_rate_pct_15d": 0.72,
        "sharpe_ratio_15d": 1.25,
        "total_trades_15d": 120,
        "markets_traded_15d": 18,
        "total_pnl_15d": 12500.5,
        "total_volume_15d": 3600711.99,
        "trajectory": "Improving"
      }
    ]
  },
  "request_id": "req_abc123"
}
```

## Response fields

| Field | Type | Description |
| - | - | - |
| `rank` | Integer | Leaderboard rank within the selected period |
| `address` | String | Wallet address |
| `total_pnl` | String (decimal) | Total profit and loss for the period (negative values indicate a loss) |
| `roi` | String (decimal) | Return on investment |
| `win_rate` | String (decimal) | Win percentage (0–1) |
| `sharpe_ratio` | String (decimal) | Risk-adjusted performance metric |
| `total_volume` | String (decimal) | Total trading volume |
| `markets_traded` | Integer | Number of unique markets traded |
| `total_trades` | Integer | Total number of trades executed |


## OpenAPI

````yaml /api-reference/polymarket-pnl-leaderboard.openapi.json POST /api/v2/semantic/retrieve/parameterized
openapi: 3.1.0
info:
  title: Falcon API — PnL Leaderboard
  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: PnL Leaderboard
      description: >-
        Returns ranked wallet performance for a selected leaderboard time
        window.
      operationId: polymarketPnlLeaderboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolymarketPnlLeaderboardRequest'
            examples:
              default:
                summary: Top wallets for the 1-day leaderboard
                value:
                  agent_id: 579
                  params:
                    wallet_address: ALL
                    leaderboard_period: 1d
                  pagination:
                    limit: 10
                    offset: 0
                  formatter_config:
                    format_type: raw
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolymarketPnlLeaderboardResponse'
        '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": 579,
              "params": {
                "wallet_address": "ALL",
                "leaderboard_period": "1d"
              },
              "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": 579,
                    "params": {
                        "wallet_address": "ALL",
                        "leaderboard_period": "1d",
                    },
                    "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: 579,
                  params: {
                    wallet_address: "ALL",
                    leaderboard_period: "1d",
                  },
                  pagination: { limit: 10, offset: 0 },
                  formatter_config: { format_type: "raw" },
                }),
              }
            );

            const data = await response.json();
components:
  schemas:
    PolymarketPnlLeaderboardRequest:
      type: object
      required:
        - params
      properties:
        agent_id:
          type: integer
          enum:
            - 579
          default: 579
          x-default: 579
          description: PnL Leaderboard agent ID.
        params:
          $ref: '#/components/schemas/PolymarketPnlLeaderboardParams'
        pagination:
          $ref: '#/components/schemas/PolymarketPnlLeaderboardPagination'
        formatter_config:
          $ref: '#/components/schemas/PolymarketPnlLeaderboardFormatterConfig'
    PolymarketPnlLeaderboardResponse:
      type: object
      readOnly: true
      properties:
        timestamp:
          type: string
          readOnly: true
        params:
          $ref: '#/components/schemas/PolymarketPnlLeaderboardResponseParams'
        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
    PolymarketPnlLeaderboardParams:
      type: object
      description: Filter parameters. All values must be strings.
      additionalProperties: false
      required:
        - wallet_address
        - leaderboard_period
      properties:
        wallet_address:
          type: string
          default: ALL
          description: >-
            Wallet address filter. Use "ALL" for all wallets, or a specific
            address.
        leaderboard_period:
          type: string
          enum:
            - 1d
            - 3d
            - 7d
            - 30d
          default: 1d
          description: Leaderboard time window.
    PolymarketPnlLeaderboardPagination:
      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.
    PolymarketPnlLeaderboardFormatterConfig:
      type: object
      properties:
        format_type:
          type: string
          enum:
            - raw
          default: raw
          description: Output format. Use "raw" for structured JSON.
    PolymarketPnlLeaderboardResponseParams:
      type: object
      readOnly: true
      properties:
        wallet_address:
          type: string
          readOnly: true
        leaderboard_period:
          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.