> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/traders/lifetime-performance.md).

# Lifetime Performance

### Request Body (JSON)

```json
{
    "agent_id": 586,
    "params": {
        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

### Available Filters

| Parameter        | Type   | Description                                      | Example         |
| ---------------- | ------ | ------------------------------------------------ | --------------- |
| `wallet_address` | String | Wallet address to query. This field is required. | `"0xabc123..."` |

<details>

<summary>Example Request <strong>(cURL)</strong></summary>

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 586,
    "params": {
        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

### Response Fields

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

<details>

<summary>Example Response</summary>

```bash
{
  "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
      }
    ]
  }
}
```

</details>

***

### Notes

* Use this endpoint to analyze a wallet’s **long-term trading behavior**, as the data reflects the entire available historical dataset (\~9 months).
* Compare `total_pnl` with `total_invested` to better understand **overall profitability relative to capital deployed**.
* Use `roi_pct` together with `total_trades` to evaluate **performance efficiency versus trading frequency**.
* Analyze `avg_trade_size` and `avg_pnl_per_trade` to understand **risk profile and average trade profitability**.
* Combine this endpoint with **PnL or Leaderboard endpoints** to compare long-term performance with recent trading activity.
* Monitor `last_updated` to ensure your application is using the **most recent wallet statistics available**.