> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kuru.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Market trades stream

> Replay and follow finalized taker-side fills for one market.

```text theme={null}
trades@f
```

This is a market-scoped, replayable stream. Its cursor is
`(feedEpoch, marketSeq)`. Without `seq`, it begins with live trades. With
`seq`, it replays retained fills after that cursor and then joins live delivery.

## Subscribe

```json theme={null}
{
  "op": "sub",
  "id": 2,
  "t": "trades@f",
  "m": "0x8121EE960066e4344A213F9aC7502395502aEe7a",
  "feedEpoch": 0,
  "seq": 1022
}
```

## Decoded event

The shape below is the inner `message` returned by `decodeExchangeWsEnvelope`
or `decodeExchangeWsMessage`. Every binary socket message also carries an outer
`id: bigint`, matching your subscription ID. Use it to route snapshots, replay,
and live updates. See [binary subscription envelopes](/api/exchange/websocket#binary-subscription-envelope).

```ts theme={null}
interface ExchangeWsMarketTradesFrame {
  wireVersion: 1;
  feedEpoch: bigint;
  view: "finalized";
  kind: "trades";
  marketAddress: string;
  marketSeq: bigint;
  previousMarketSeq: bigint | null;
  globalSeq: bigint;
  sourceBlock: { blockNumber: bigint; blockId: string };
  trades: Array<{
    tradeId: bigint;
    recordIndex: number;
    takerSide: "buy" | "sell";
    price: bigint;
    baseFilled: bigint;
    blockTimestamp: bigint;
  }>;
}
```

`takerSide` is the taker's side. `price` is in native market price precision (pp); `baseFilled` remains in the
market's native size precision. The stable identity of a fill
is `(marketAddress, tradeId, recordIndex)`.

`previousMarketSeq` links to the previous publication in this exact market,
view, and topic stream; it is `null` when the wire value is zero. For a replay
requested after `R`, accept the first frame when `marketSeq > R` and its
predecessor is `null` or at most `R`. Subsequent frames require exact equality
between `previousMarketSeq` and the last accepted `marketSeq`.

## PnL versus market trade prices

This market stream supplies execution prices and sizes for market data; it
does not include user IDs, historical fee rates, or match boundaries. It cannot
by itself reconstruct a user's fee-adjusted PnL. Use the
[user trades accounting guide](/api/exchange/websocket-reference/user-trades#calculating-client-side-pnl)
for position initialization, match-level fee rounding, and buy/sell accounting.
That guide also explains when the user-scoped stream lacks enough information
for exact maker accounting and when to use indexed PnL instead.

## Canonical event timestamp

Each decoded trade row or order delta event includes `blockTimestamp: bigint`
in Unix seconds. It is the source block's canonical header timestamp and is
identical in live delivery and retained replay. It is not the publication time.
Order snapshot rows are unchanged. See the [event timestamp changelog](/api/exchange/user-trades-changelog#kur-1719-canonical-event-timestamps).


## AsyncAPI

````yaml api/exchange/asyncapi.yaml trades
id: trades
title: Subscribe to market trades
description: Replay and follow finalized fills for one market.
servers:
  - id: mainnet
    protocol: wss
    host: gateway.mainnet.kuru.io
    bindings: []
    variables: []
  - id: testnet
    protocol: wss
    host: gateway.testnet.kuru.io
    bindings: []
    variables: []
address: /ws
parameters: []
bindings: []
operations:
  - &ref_1
    id: subscribeTrades
    title: Subscribe trades
    type: receive
    messages:
      - &ref_2
        id: request
        contentType: application/json
        payload:
          - name: trades@f subscription
            type: object
            properties:
              - name: op
                type: string
                enumValues:
                  - sub
                required: true
              - name: id
                type: integer
                description: >-
                  JSON integer restricted to JavaScript's exact safe-integer
                  range.
                required: true
              - name: t
                type: string
                enumValues:
                  - trades@f
                required: true
              - name: m
                type: string
                description: Lowercase 20-byte market contract address.
                required: true
              - name: feedEpoch
                type: integer
                description: Feed namespace. Required when seq is supplied.
                required: false
              - name: seq
                type: integer
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          additionalProperties: false
          required:
            - op
            - id
            - t
            - m
          allOf:
            - if:
                required:
                  - seq
                x-parser-schema-id: <anonymous-schema-9>
              then:
                required:
                  - feedEpoch
                x-parser-schema-id: <anonymous-schema-10>
              x-parser-schema-id: <anonymous-schema-8>
          properties:
            op:
              type: string
              enum:
                - sub
              x-parser-schema-id: <anonymous-schema-6>
            id: &ref_0
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: >-
                JSON integer restricted to JavaScript's exact safe-integer
                range.
              x-parser-schema-id: ControlInteger
            t:
              type: string
              enum:
                - trades@f
              x-parser-schema-id: <anonymous-schema-7>
            m:
              type: string
              pattern: ^0x[0-9a-f]{40}$
              description: Lowercase 20-byte market contract address.
              x-parser-schema-id: MarketAddress
            feedEpoch:
              allOf:
                - *ref_0
              description: Feed namespace. Required when seq is supplied.
              x-parser-schema-id: FeedEpoch
            seq:
              allOf:
                - *ref_0
              minimum: 1
              x-parser-schema-id: ReplaySequence
          x-parser-schema-id: TradesSubscription
        title: trades@f subscription
        example: |-
          {
            "op": "sub",
            "id": 2,
            "t": "trades@f",
            "m": "0x8121EE960066e4344A213F9aC7502395502aEe7a",
            "feedEpoch": 0,
            "seq": 1022
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: request
    bindings: []
    extensions:
      - id: x-parser-unique-object-id
        value: trades
sendOperations:
  - *ref_1
receiveOperations: []
sendMessages:
  - *ref_2
receiveMessages: []
extensions:
  - id: x-parser-unique-object-id
    value: trades
securitySchemes: []

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.