账户 PnL

返回用户在日期范围内的每日与累计盈亏（PnL）统计。供账户仪表盘的每日与累计 PnL 卡片及概览指标使用。

GET /account/pnl
Authorization: Bearer <token>

请求参数

名称	类型	必需	说明
`symbol`	`string`	否	过滤到单个市场（如 `BTC-USDT`）。缺省时聚合全部市场。
`start_date`	`string`	否	下界（含），格式 `YYYY-MM-DD`（UTC）。
`end_date`	`string`	否	上界（含），格式 `YYYY-MM-DD`（UTC）。
`days`	`int64`	否	回看窗口天数，在 `start_date` 与 `end_date` 未同时提供时生效。只提供两者之一时该日期会被忽略，回退到 `days`。默认 `30`。

解析顺序：

若 start_date 与 end_date 都已设置，使用该显式范围。
否则（包括只设置了其中一个的情况 —— 那个单独的日期会被忽略），服务端使用 UTC 下的 [today − days, today]。today 始终取 Utc::now().date_naive()。

响应

{
  "daily": [
    {
      "date": "2026-05-10",
      "realized_pnl": "125.30",
      "volume": "10000.00",
      "trade_count": 12,
      "fees": "5.00"
    }
  ],
  "cumulative": {
    "total_realized_pnl": "320.50",
    "total_unrealized_pnl": "-12.40",
    "total_pnl": "308.10",
    "total_volume": "85000.00",
    "total_trades": 87,
    "total_fees": "42.50",
    "win_rate": "62.50",
    "avg_profit_per_trade": "3.68"
  },
  "symbol": null
}

窗口内某天没有任何活动时，该天仍会出现在 daily 中，所有数值字段为 0、trade_count 为 0。序列在 UTC 下从 start_date 到 end_date 连续无缺口。

用户在窗口内完全没有成交时，daily 是一串连续的全零行，cumulative 各项均为零。

响应字段

顶层

字段	类型	说明
`daily`	`DailyPnl[]`	每个 UTC 日一行，在 `start_date` 与 `end_date` 之间连续。
`cumulative`	`CumulativePnl`	同一窗口上的聚合统计。
`symbol`	`string \| null`	回显 `symbol` 请求参数。

`DailyPnl`

字段	类型	说明
`date`	`string`	UTC 日期，格式 `YYYY-MM-DD`。
`realized_pnl`	`Decimal`	当日 `realized_pnl_events.realized_pnl` 之和（USDT）。
`volume`	`Decimal`	当日成交名义价值，按用户为 maker 或 taker 的 `trades` 计算 `SUM(price × amount)`（USD）。
`trade_count`	`int64`	用户为 maker 或 taker 的 `trades` 行数。
`fees`	`Decimal`	用户在 `trades` 上承担的手续费部分（用户为 maker 时取 maker 费，否则取 taker 费），按日求和（USDT）。

`CumulativePnl`

所有字段覆盖同一窗口 [start_date, end_date]（闭区间，UTC）。

字段	类型	说明
`total_realized_pnl`	`Decimal`	窗口内 `realized_pnl_events.realized_pnl` 之和。
`total_unrealized_pnl`	`Decimal`	当前所有未平仓位的浮动盈亏，在请求时刻按各 symbol 最新标记价格计算。与日期窗口无关。
`total_pnl`	`Decimal`	`total_realized_pnl + total_unrealized_pnl`。
`total_volume`	`Decimal`	窗口内 `trades` 上的 `SUM(price × amount)`。
`total_trades`	`int64`	窗口内用户为 maker 或 taker 的 `trades` 行数。
`total_fees`	`Decimal`	窗口内用户在 `trades` 上承担的手续费之和。
`win_rate`	`Decimal`	窗口内 `count(realized_pnl_events with realized_pnl > 0) / count(realized_pnl_events) × 100`。以百分数返回（如 `62.50` 表示 62.5%）。窗口内没有平仓时为 `0`。
`avg_profit_per_trade`	`Decimal`	`total_realized_pnl / total_trades`。`total_trades` 为 `0` 时为 `0`。

错误

HTTP	`code`	场景
400	`INVALID_START_DATE`	`start_date` 无法按 `YYYY-MM-DD` 解析。
400	`INVALID_END_DATE`	`end_date` 无法按 `YYYY-MM-DD` 解析。
500	`DAILY_TRADE_STATS_FAILED`	聚合每日成交行时数据库出错。
500	`DAILY_PNL_FETCH_FAILED`	聚合每日已实现 PnL 时数据库出错。
500	`STATS_FETCH_FAILED`	计算累计成交统计时数据库出错。
500	`WIN_RATE_FETCH_FAILED`	计算胜率时数据库出错。

错误响应体：

{ "error": "...", "code": "..." }

注意事项

所有金额均以十进制字符串返回。调用方应使用任意精度算术解析，不要用浮点数。
日边界为 UTC。没有 tz 参数；需要本地时区视图的调用方应在客户端对 daily 行自行聚合。
total_unrealized_pnl 不依赖 start_date / end_date —— 它始终反映用户当前的未平仓位与最新标记价格。

请求参数​

响应​

响应字段​

顶层​

DailyPnl​

CumulativePnl​

错误​

注意事项​

请求参数

响应

响应字段

顶层

`DailyPnl`

`CumulativePnl`

错误

注意事项