账户历史

本页是成交 / 委托 / 资金流水 / 持仓历史 相关接口：JSON-RPC 读方法（getUserFills 等）与历史 REST（/api/v1/fills、/api/v1/orders、/api/v1/fund-flows 等）。

getUserFills

用户成交历史（含 gross 扣款 fee；不含 Layer ⑥.2 返佣拆分，返佣见 [getBlockEvents../history/blocks.md#getblockevents 的 Core::RebatePaid）。读 fill archive（权威源）并与 index 内存 merge；client_order_id 由 open 簿 / closed archive 补全。启动时若 archive 落后 journal，由 backfill_fill_history_store 从 journal 回补。

参数	类型	必填	说明
`address`	Address20	是	账户地址
`symbol`	String	否	按市场过滤
`market_id`	u32	否	精确市场过滤（重名/跨代际历史）；携带时优先于 `symbol`，可查已下市市场历史
`start_time_ms`	u64	否	起始时间（毫秒）
`end_time_ms`	u64	否	结束时间（毫秒）
`offset`	usize	否	默认 0
`limit`	usize	否	默认 100，最大 1000

响应 data · UserFillResponse[]： 同 TradeResponse + 以下字段：

字段	类型	说明
`order_id`	u64	用户侧订单 ID（成交↔订单对账键）
`client_order_id`	String?	客户端订单 ID（open 簿 / closed archive 补全）
`fee`	String	该用户在本笔成交中支付的 gross fee（SCALE_6，≥ 0；Layer ⑥.1 扣款，返佣池拆分不在此字段）
`is_taker`	bool	是否吃单方
`aggressor_side`	Side	吃单方向

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "block_height": 12345,
      "event_seq": 3,
      "timestamp_ms": 1717200001000,
      "market_id": 1,
      "symbol": "BTC-USDT",
      "order_id": 1001,
      "client_order_id": "my-cloid-1",
      "price": "97234.50",
      "qty": "0.50000",
      "notional": "48617.250000",
      "fee": "24.308625",
      "is_taker": true,
      "aggressor_side": "Bid"
    }],
    "page": { "offset": 0, "limit": 100, "total": null }
  }
}

getOrderFills

单笔订单成交明细（做市对账点查）。读 fill archive 并与 index 内存 merge；响应字段同 [getUserFills#getuserfills 的 UserFillResponse[]。全量历史永久存储，不截断。

参数	类型	必填	说明
`order_id`	u64	二选一	订单 ID
`client_order_id`	String	二选一	客户端订单 ID（需同时给 `address` + `symbol`，同 [`getOrderStatus`../trading/account.md#getorderstatus）
`address`	Address20	cloid 时必填	账户地址
`symbol`	String	cloid 时必填	市场 symbol
`offset`	usize	否	默认 0
`limit`	usize	否	默认 100，最大 1000

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "block_height": 12345,
      "event_seq": 3,
      "timestamp_ms": 1717200001000,
      "market_id": 1,
      "symbol": "BTC-USDT",
      "order_id": 1001,
      "client_order_id": "my-cloid-1",
      "price": "97234.50",
      "qty": "0.50000",
      "notional": "48617.250000",
      "fee": "24.308625",
      "is_taker": false,
      "aggressor_side": "Bid"
    }],
    "page": { "offset": 0, "limit": 100, "total": null }
  }
}

账户历史（REST）

以下接口均为分页列表 { data, page }，按区块高度新→旧排序。

事件类记录公共字段（fills / fund-flows / bridge-flows / positions / account/events）：

Field	Type	Description
`height`	`number`	区块高度
`seq`	`number`	区块内 event 序号
`timestamp_ms`	`number`	区块时间戳（ms）
`envelope_idx`	`number \| null`	源 event 的 envelope 索引
`tx_hash`	`string \| null`	源 event 的 L2 交易 hash（见 [事件溯源../system/index.md#事件溯源event-provenance）

`GET /api/v1/fills`

账户成交历史。每笔 fill 产生 taker / maker 两行。

Query

Param	Type	Required	Default	Max	Description
`account`	`string`	yes	—	—	账户地址
`market_id`	`number`	no	—	—	市场过滤
`from_block`	`number`	no	—	—	最小区块高度（含）
`to_block`	`number`	no	—	—	最大区块高度（含）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 3,
      "is_taker": true,
      "timestamp_ms": 1717000000000,
      "market_id": 1,
      "order_id": 42,
      "account": "0xabcd…",
      "counterparty": "0x1234…",
      "price": "50000.00",
      "qty": "1.5",
      "notional": "75000.000000",
      "fee": "3.750000",
      "position_action": "close_long",
      "realized_pnl": "100.000000",
      "realized_pnl_pct": "1.64",
      "symbol": "BTC-USDT",
      "envelope_idx": 2,
      "tx_hash": "0x…"
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 150 }
}

Field	Type	Description
`is_taker`	`boolean`	是否为 taker 侧
`notional`	`string`	`price × qty`（SCALE_6）
`fee`	`string`	该参与者手续费（SCALE_6）
`position_action`	`string \| null`	开/平仓效果：`open_long` / `open_short` / `close_long` / `close_short`；无法判定时省略
`realized_pnl`	`string \| null`	本笔成交 attributed 已实现盈亏（SCALE_6）；derive 自同 envelope 内匹配的 `PositionUpdated` 或强平 `Liquidated`
`realized_pnl_pct`	`string \| null`	盈利率（百分比，两位小数）；开仓/加仓为 `"0.00"`
`envelope_idx`	`number \| null`	源 event 的 envelope 索引
`tx_hash`	`string \| null`	源 event 的 L2 交易 hash

开/平仓判定与 PnL 关联规则见 FillRecord。

`GET /api/v1/orders`

账户历史委托（按 order_id 聚合，一行一单，仅已关闭订单）。

与当前委托的分工

场景	数据来源
当前委托（挂单中，实时）	Chain `getAccountOrders` 或 WS `orderUpdates`；亦可本服务 `GET /api/v1/chain/open-orders`（链 proxy）
历史委托（已成交/已撤/已过期）	本接口

默认不传 status 时，服务端附加 status != open，不返回挂单。索引层 derive worker 仍会物化 open 行（供内部聚合），但对外历史列表不包含。

derive worker 从链事件物化：OrderAccepted → 建单；OrderResting → 更新挂簿快照（改价/改量，price / qty / filled_qty）；Filled → 累计成交量/均价；OrderDone / 特殊撤单 event → 终态。

Query

Param	Type	Required	Default	Max	Description
`owner`	`string`	yes	—	—	订单 owner 地址
`market_id`	`number`	no	—	—	市场过滤
`status`	`string`	no	排除 `open`	—	终态过滤：`filled` \| `partial_cancelled` \| `cancelled` \| `expired`；显式 `open` 可单独查挂单（读侧索引，非历史主路径）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "order_id": 100,
      "owner": "0xabcd…",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Bid",
      "price": "50000.00",
      "qty": "1.5",
      "filled_qty": "1.2",
      "avg_fill_price": "49980.50",
      "status": "partial_cancelled",
      "close_reason": "Cancelled",
      "placed_height": 12345,
      "placed_at_ms": 1717000000000,
      "closed_height": 12350,
      "closed_at_ms": 1717000005000,
      "placed_tx_hash": "0x…",
      "closed_tx_hash": "0x…"
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 42 }
}

Field	Type	Description
`status`	`string`	聚合终态。默认列表仅含 `filled` / `partial_cancelled` / `cancelled` / `expired`；`open` 仅当显式 `status=open` 时出现
`filled_qty`	`string`	已成交量（size 精度）
`avg_fill_price`	`string \| null`	成交均价（price 精度）
`close_reason`	`string \| null`	链上 `DoneReason` 或特殊撤单原因（如 `CancelledByPositionFlat`）
`qty`	`string`	原始委托数量
`placed_tx_hash`	`string \| null`	下单（`OrderAccepted`）所在 L2 交易 hash
`closed_tx_hash`	`string \| null`	终态 event 所在 L2 交易 hash（撤单/过期/完全成交）

排序：closed_at_ms 新→旧；相同时 order_id 大→小。列表时间轴与 closed_at_ms 一致（非 placed_at_ms）。

分页：total 为匹配过滤后的已关闭订单总数（默认不含 open）。

`GET /api/v1/fund-flows`

账户资金流水（Core::BalanceChanged 余额变更）。

Query

Param	Type	Required	Default	Max	Description
`account`	`string`	yes	—	—	账户地址
`reason`	`string`	no	—	—	变更原因过滤，如 `TakerFee`、`BridgeDeposit`、`RealizedPnl`、`RebateToInviter`、`RebateToInvitee`
`market_id`	`number`	no	—	—	市场过滤（部分原因带 `market_id`）
`from_block`	`number`	no	—	—	最小区块高度（含）
`to_block`	`number`	no	—	—	最大区块高度（含）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 8,
      "timestamp_ms": 1717000000000,
      "account": "0xabcd…",
      "delta": "-3.750000",
      "new_balance": "996.250000",
      "reason": "TakerFee",
      "market_id": 1,
      "envelope_idx": 2,
      "tx_hash": "0x…"
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 200 }
}

Field	Type	Description
`delta`	`string`	余额变动量（可为负）
`new_balance`	`string`	变动后余额
`reason`	`string`	变更原因，见链层 `BalanceReason`
`envelope_idx`	`number \| null`	源 event 的 envelope 索引
`tx_hash`	`string \| null`	源 event 的 L2 交易 hash

常见 reason 值：TakerFee、MakerFee、RealizedPnl、BridgeDeposit、BridgeWithdrawDebit、BridgeWithdrawRefund、Liquidation、ImRelease、ImAutoAllocate、ImManualAllocate、MakerFeeRefund、FeeRecipientCredit、OracleTrade、Withdrawal、BankruptcyFloor、RebateToInviter、RebateToInvitee。

返佣入账（RebateToInviter / RebateToInvitee）与 [GET /api/v1/rebate/events../history/referral.md#get-apiv1rebateevents 的 Core::RebatePaid 成对出现；汇总明细见返佣接口，流水侧按 reason 过滤即可。

`GET /api/v1/bridge-flows`

充提生命周期事件（Bridge::*）。

Query

Param	Type	Required	Default	Max	Description
`account`	`string`	yes	—	—	账户地址
`event_type`	`string`	no	—	—	事件类型：`DepositRecorded`、`DepositCredited`、`WithdrawRequested`、`WithdrawSettled`、`WithdrawRefunded`
`from_block`	`number`	no	—	—	最小区块高度（含）
`to_block`	`number`	no	—	—	最大区块高度（含）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 2,
      "timestamp_ms": 1717000000000,
      "event_type": "DepositCredited",
      "account": "0xabcd…",
      "amount": "1000.000000",
      "new_balance": "1000.000000",
      "deposit_seq": 5,
      "request_id": null,
      "chain_id": null,
      "reason_code": null,
      "envelope_idx": 0,
      "tx_hash": "0x…",
      "external_tx_hash": null
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 12 }
}

Field	Type	Description
`envelope_idx`	`number \| null`	源 event 的 envelope 索引
`tx_hash`	`string \| null`	L2 envelope 交易 hash
`external_tx_hash`	`string \| null`	L1 链上交易 hash（如 `DepositRecorded` / `WithdrawSettled` body 内）
`event_type`	`string`	`DepositRecorded` \| `DepositCredited` \| `WithdrawRequested` \| `WithdrawSettled` \| `WithdrawRefunded`
`amount`	`string`	金额（SCALE_6）
`new_balance`	`string \| null`	变更后余额（部分事件有）
`deposit_seq`	`number \| null`	充值序号
`request_id`	`number \| null`	提现 request ID
`chain_id`	`number \| null`	外链 chain ID
`reason_code`	`number \| null`	退款原因码（`WithdrawRefunded`）

`GET /api/v1/positions`

账户持仓变动历史（Exec::Position*）。

Query

Param	Type	Required	Default	Max	Description
`owner`	`string`	yes	—	—	账户地址
`market_id`	`number`	no	—	—	市场过滤
`event_type`	`string`	no	—	—	`Updated`、`Flattened`、`ForceClosedAtMark`
`from_block`	`number`	no	—	—	最小区块高度（含）
`to_block`	`number`	no	—	—	最大区块高度（含）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 4,
      "timestamp_ms": 1717000000000,
      "owner": "0xabcd…",
      "market_id": 1,
      "event_type": "Updated",
      "old_size": "0",
      "new_size": "1.5",
      "new_entry_vwap": "50000.00",
      "realized_pnl": "0",
      "mark_price": null,
      "symbol": "BTC-USDT",
      "envelope_idx": 2,
      "tx_hash": "0x…"
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 30 }
}

Field	Type	Description
`envelope_idx`	`number \| null`	源 event 的 envelope 索引
`tx_hash`	`string \| null`	源 event 的 L2 交易 hash

`GET /api/v1/account/events`

按账户过滤的链上事件（通用分类查询，数据来自 event 表）。

Query

Param	Type	Required	Default	Max	Description
`account`	`string`	yes	—	—	账户地址
`kind`	`string`	no	—	—	事件大类：`Exec`、`Core`、`Bridge`、`Trigger`、`Liquidation`、`Ops`
`sub_kind`	`string`	no	—	—	子类型，如 `Filled`、`BalanceChanged`
`market_id`	`number`	no	—	—	市场过滤
`from_block`	`number`	no	—	—	最小区块高度（含）
`to_block`	`number`	no	—	—	最大区块高度（含）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 3,
      "envelope_idx": 0,
      "kind": "Exec",
      "sub_kind": "Filled",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "tx_hash": "0x…",
      "account": "0xabcd…",
      "timestamp_ms": 1717000000000,
      "body": { "price": "50000.00", "qty": "1.5" }
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 500 }
}

Field	Type	Description
`envelope_idx`	`number`	事件所在 envelope 索引
`tx_hash`	`string \| null`	产生该 event 的 L2 交易 hash
`timestamp_ms`	`number`	区块时间戳（ms）
`kind` / `sub_kind`	`string`	事件大类 / 子类型
`body`	`object`	原始事件 JSON

getUserFills​

getOrderFills​

账户历史（REST）​

GET /api/v1/fills​

GET /api/v1/orders​

GET /api/v1/fund-flows​

GET /api/v1/bridge-flows​

GET /api/v1/positions​

GET /api/v1/account/events​

getUserFills

getOrderFills

账户历史（REST）

`GET /api/v1/fills`

`GET /api/v1/orders`

`GET /api/v1/fund-flows`

`GET /api/v1/bridge-flows`

`GET /api/v1/positions`

`GET /api/v1/account/events`