> 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/profit-and-loss.md).

# Profit & Loss

### Request Body (JSON)

```json
{
    "agent_id": 569,
    "params": {
        "granularity": "1d",
        "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "start_time": "2026-02-10",
        "end_time": "2026-02-28"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

***

### Available Filters

| Parameter      | Type          | Description                                  | Example         |
| -------------- | ------------- | -------------------------------------------- | --------------- |
| `wallet`       | String        | Wallet address to calculate realized PnL for | `"0xabc123..."` |
| `granularity`  | String        | Aggregation interval for performance metrics | `"1d"`          |
| `start_time`   | String (date) | Start date for the query range               | `"2026-02-10"`  |
| `end_time`     | String (date) | End date for the query range                 | `"2026-02-28"`  |
| `condition_id` | String        | Optional market condition ID filter          | `"0x..."`       |

### Supported Granularity

| Value | Description             |
| ----- | ----------------------- |
| `1d`  | Daily aggregation       |
| `3d`  | 3-day aggregation       |
| `1w`  | Weekly aggregation      |
| `1m`  | Monthly aggregation     |
| `all` | Full-period aggregation |

<details>

<summary>Response 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": 569,
    "params": {
        "granularity": "1d",
        "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "start_time": "2026-02-10",
        "end_time": "2026-02-28"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

| Field          | Type              | Description                                        |
| -------------- | ----------------- | -------------------------------------------------- |
| `date`         | String (ISO 8601) | Date for which the metrics are aggregated          |
| `proxy_wallet` | String            | Wallet address for which performance is calculated |
| `invested`     | String (Decimal)  | Total amount invested during the period            |
| `pnl`          | String (Decimal)  | Net realized profit and loss for the period        |
| `trades`       | Integer           | Total number of trades executed during the period  |
| `wins`         | Integer           | Number of profitable trades                        |
| `losses`       | Integer           | Number of losing trades                            |
| `win_rate`     | String (Decimal)  | Win rate for the period                            |

<details>

<summary>Example Response</summary>

```bash
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "2026-02-28",
    "granularity": "1d",
    "start_time": "2026-02-10",
    "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "date": "2026-02-19T00:00:00Z",
        "invested": "830494.18",
        "losses": 0,
        "pnl": "0.00",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 3342,
        "win_rate": "0.00",
        "wins": 0
      },
      {
        "date": "2026-02-20T00:00:00Z",
        "invested": "241245.70",
        "losses": 18,
        "pnl": "-302209.22",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 406,
        "win_rate": "0.49",
        "wins": 2
      },
      {
        "date": "2026-02-21T00:00:00Z",
        "invested": "891551.87",
        "losses": 2,
        "pnl": "-178123.20",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 1771,
        "win_rate": "0.11",
        "wins": 2
      },
      {
        "date": "2026-02-22T00:00:00Z",
        "invested": "1595819.97",
        "losses": 4,
        "pnl": "319548.75",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 2756,
        "win_rate": "0.33",
        "wins": 9
      },
      {
        "date": "2026-02-23T00:00:00Z",
        "invested": "673510.38",
        "losses": 12,
        "pnl": "204833.78",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 740,
        "win_rate": "1.08",
        "wins": 8
      },
      {
        "date": "2026-02-24T00:00:00Z",
        "invested": "649676.60",
        "losses": 1,
        "pnl": "48837.55",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 984,
        "win_rate": "0.10",
        "wins": 1
      },
      {
        "date": "2026-02-25T00:00:00Z",
        "invested": "711943.39",
        "losses": 8,
        "pnl": "186648.16",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 921,
        "win_rate": "1.85",
        "wins": 17
      }
    ]
  }
}
```

</details>

***

### Notes

* Use a **larger time range** with smaller `granularity` values (e.g. `1d`) to analyze detailed trading performance over time.
* Increase `granularity` (e.g. `1w` or `1m`) when analyzing **long-term performance trends** to reduce the number of returned data points.
* Use `condition_id` to **isolate performance for a specific market**, which is useful when evaluating strategy effectiveness in individual events.
* If `condition_id` is omitted or set to `"ALL"`, the endpoint returns **aggregated PnL across all markets** for the wallet.
* Ensure `start_time` and `end_time` are **valid ISO date strings** to correctly filter the time window.
* Compare `wins`, `losses`, and `win_rate` together with `pnl` to better understand **trading efficiency versus profitability**.