> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/websocket-api/execution-reports.md).

# Execution Reports

Execution reports are automatically streamed after calling `subscribeTrading`. All execution reports use the same wrapper format:

```json
{
  "type": "executionReport",
  ...
}
```

**Note:** Execution reports echo back the signatures sent in requests. The `signature.payload` field contains the hex-encoded payload with type discriminator that was originally submitted (see [Signatures](/developer-tools/signatures.md) for payload format details).

Execution reports provide:

1. Resting order snapshot
   1. **Initial snapshot** - All resting orders as `OrderStatus` messages. The snapshot contains all active, pending, partially filled, and suspended orders for the account.
2. **Real-time updates** - Ongoing execution reports
   1. Order status changes (new, filled, cancelled, etc.)
   2. Trade execution notifications
   3. Account events (deposits, withdrawals, leverage updates, liquidations, funding)

***

## Message Types

Execution reports contain a `messageType` field indicating the event type:

### Order Events

| Message Type  | Description                                       |
| ------------- | ------------------------------------------------- |
| `Add`         | Order accepted and added to book                  |
| `Executed`    | Order partially or fully filled                   |
| `Cancelled`   | Order cancelled                                   |
| `Modified`    | Order replaced                                    |
| `Suspended`   | Stop order waiting for trigger                    |
| `OrderStatus` | Order snapshot (sent during initial subscription) |
| `TradeReport` | Trade execution details                           |
| `TradeCancel` | Trade cancellation                                |

### Account Events

| Message Type        | Description                        |
| ------------------- | ---------------------------------- |
| `DepositMargin`     | Collateral deposit                 |
| `WithdrawMargin`    | Collateral withdrawal              |
| `TransferMargin`    | Cross ↔ isolated margin transfer   |
| `UpdateLeverage`    | Leverage update                    |
| `FundingRates`      | Funding rate payment               |
| `Liquidation`       | Position liquidation               |
| `ManualLiquidation` | Manual liquidation / ADL execution |

***

## Order Execution Reports

### Add

Order accepted and added to order book.

```json
{
  "type": "executionReport",
  "messageType": "Add",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600000000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "orderType": "Limit",
  "timeInForce": "GTC",
  "orderTimestamp": 1705600000000,
  "filledQuantity": "0",
  "filledPrice": "0",
  "remainingOpenQuantity": "100",
  "signature": {
    "Order": {
      "sig": "0x...",
      "payload": "0x..."
    }
  }
}
```

### Executed

Order partially or fully filled.

```json
{
  "type": "executionReport",
  "messageType": "Executed",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600001000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "orderType": "Limit",
  "timeInForce": "GTC",
  "filledQuantity": "100",
  "filledPrice": "500.00",
  "remainingOpenQuantity": "0",
  "lastFilledQuantity": "100",
  "lastFilledPrice": "500.00",
  "makerTaker": "Maker",
  "matchId": 987654321,
  "signature": {
    "Order": {
      "sig": "0x...",
      "payload": "0x..."
    }
  }
}
```

| Field                | Description                        |
| -------------------- | ---------------------------------- |
| `filledQuantity`     | Total filled quantity (cumulative) |
| `filledPrice`        | Weighted average filled price      |
| `lastFilledQuantity` | Quantity filled in this execution  |
| `lastFilledPrice`    | Price of this execution            |
| `makerTaker`         | `Maker` or `Taker`                 |
| `matchId`            | Unique match identifier            |

### Cancelled

Order cancelled (by user or system).

```json
{
  "type": "executionReport",
  "messageType": "Cancelled",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600002000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "orderType": "Limit",
  "timeInForce": "GTC",
  "filledQuantity": "40",
  "filledPrice": "500.00",
  "remainingOpenQuantity": "0",
  "cancelReason": "User requested",
  "cancelledQuantity": "60",
  "signature": {
    "Order": {
      "sig": "0x...",
      "payload": "0x..."
    }
  }
}
```

| Field               | Description                      |
| ------------------- | -------------------------------- |
| `cancelReason`      | Reason for cancellation          |
| `cancelledQuantity` | Quantity cancelled in this event |

### Modified

Order replaced with new parameters.

```json
{
  "type": "executionReport",
  "messageType": "Modified",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "200",
  "price": "510.00",
  "eventTimestamp": 1705600003000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "orderType": "Limit",
  "timeInForce": "GTC",
  "filledQuantity": "0",
  "filledPrice": "0",
  "remainingOpenQuantity": "200",
  "signature": {
    "Order": {
      "sig": "0x...",
      "payload": "0x..."
    }
  }
}
```

### Suspended

Stop order waiting for trigger price.

```json
{
  "type": "executionReport",
  "messageType": "Suspended",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "0",
  "stopPrice": "490.00",
  "eventTimestamp": 1705600000000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "orderType": "Stop",
  "timeInForce": "IOC",
  "signature": {
    "Order": {
      "sig": "0x...",
      "payload": "0x..."
    }
  }
}
```

### OrderStatus

Order snapshot (sent during initial subscription).

```json
{
  "type": "executionReport",
  "messageType": "OrderStatus",
  "side": "Buy",
  "status": "Pending",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600000000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "orderType": "Limit",
  "timeInForce": "GTC",
  "filledQuantity": "40",
  "filledPrice": "500.00",
  "remainingOpenQuantity": "60"
}
```

**Order Status Values:**

* `Active` - Order resting in order book
* `Suspended` - Stop order awaiting trigger
* `Executed` - Order executed (partially or fully filled)
* `Cancelled` - Order cancelled
* `Pending` - Order accepted, awaiting processing
* `Ended` - Order is no longer active (expired or otherwise terminated)

***

## Account Event Reports

### DepositMargin

Collateral deposit event.

```json
{
  "type": "executionReport",
  "messageType": "DepositMargin",
  "id": 100001,
  "eventTimestamp": 1705600000000,
  "message": {
    "messageType": "depositMargin",
    "amount": "1000.00",
    "status": "submitted",
    "permitSignature": "0x05...",
    "depositSignature": {
      "sig": "0x...",
      "payload": "0x07..."
    },
    "transactionHash": "0xabcd..."
  }
}
```

### WithdrawMargin

Collateral withdrawal event.

```json
{
  "type": "executionReport",
  "messageType": "WithdrawMargin",
  "id": 100002,
  "eventTimestamp": 1705600001000,
  "message": {
    "messageType": "withdrawMargin",
    "amount": "500.00",
    "status": "settled",
    "signature": {
      "sig": "0x...",
      "payload": "0x..."
    },
    "transactionHash": "0xef01..."
  }
}
```

### TransferMargin

Cross ↔ isolated margin transfer event.

```json
{
  "type": "executionReport",
  "messageType": "TransferMargin",
  "id": 100004,
  "eventTimestamp": 1705600003000,
  "message": {
    "messageType": "transferMargin",
    "amount": "250.00",
    "instrument": "BTC",
    "direction": "crossToIsolated",
    "status": "settled",
    "signature": {
      "sig": "0x...",
      "payload": "0x08..."
    },
    "transactionHash": "0x2345..."
  }
}
```

`direction` is `crossToIsolated` or `isolatedToCross`. A failed transfer carries `status: "failed"` and a `reason` field instead of `transactionHash`.

### UpdateLeverage

Leverage update event.

```json
{
  "type": "executionReport",
  "messageType": "UpdateLeverage",
  "id": 100003,
  "eventTimestamp": 1705600002000,
  "message": {
    "messageType": "updateLeverage",
    "leverage": 1000,
    "instrument": "NVDA",
    "status": "settled",
    "signature": {
      "sig": "0x...",
      "payload": "0x..."
    }
  }
}
```

**Note:** `leverage` value is leverage × 100 (e.g., 1000 = 10x leverage)

### FundingRates

Funding rate payment event.

```json
{
  "type": "executionReport",
  "messageType": "FundingRates",
  "id": 100004,
  "eventTimestamp": 1705600003000,
  "message": {
    "messageType": "fundingRates",
    "instant": "2024-01-18T12:00:00Z",
    "fundingVec": [
      {
        "symbol": "AAPL",
        "markPrice": "180.50",
        "fundingRate": "0.0001"
      },
      {
        "symbol": "NVDA",
        "markPrice": "500.25",
        "fundingRate": "0.00015"
      }
    ],
    "status": "settled"
  }
}
```

### Liquidation

Position liquidation event.

```json
{
  "type": "executionReport",
  "messageType": "Liquidation",
  "id": 100005,
  "eventTimestamp": 1705600004000,
  "message": {
    "messageType": "liquidation",
    "instrument": "NVDA",
    "filledQuantity": "100",
    "remainingQuantity": "0",
    "status": "settled",
    "reason": "Insufficient margin"
  }
}
```

| Field        | Type   | Description                 |
| ------------ | ------ | --------------------------- |
| `instrument` | string | Instrument being liquidated |

### ManualLiquidation

Manual liquidation or ADL (auto-deleveraging) execution event.

```json
{
  "type": "executionReport",
  "messageType": "ManualLiquidation",
  "id": 100006,
  "eventTimestamp": 1705600005000,
  "message": {
    "messageType": "manualLiquidation",
    "matchId": 987654321,
    "status": "settled",
    "reason": "ADL",
    "transactionHash": "0xabcd..."
  }
}
```

| Field             | Type   | Description                               |
| ----------------- | ------ | ----------------------------------------- |
| `matchId`         | u64    | Match identifier for the liquidation fill |
| `status`          | string | Transaction status (see below)            |
| `reason`          | string | *(Optional)* Reason for the liquidation   |
| `transactionHash` | string | *(Optional)* On-chain transaction hash    |

***

## Transaction Status

Account events include a `status` field:

| Status      | Description                             |
| ----------- | --------------------------------------- |
| `submitted` | Operation submitted, pending processing |
| `settled`   | Operation completed successfully        |
| `failed`    | Operation failed                        |

***

## Common Fields

All execution reports include:

| Field            | Type   | Description                    |
| ---------------- | ------ | ------------------------------ |
| `type`           | string | Always `"executionReport"`     |
| `messageType`    | string | Event type (see tables above)  |
| `eventTimestamp` | i64    | Event timestamp (milliseconds) |

Order events include:

| Field           | Type   | Description                                                                                                         |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `side`          | string | `Buy` or `Sell`                                                                                                     |
| `instrument`    | string | Instrument symbol                                                                                                   |
| `orderId`       | u64    | Exchange order ID                                                                                                   |
| `traderOrderId` | u64    | *(Optional)* Your client order ID. Omitted for system-generated orders (e.g. liquidations), which have no client ID |
| `quantity`      | string | Order quantity                                                                                                      |
| `price`         | string | Order price                                                                                                         |
| `signature`     | Object | *(Optional)* Original signed payload echoed back. See [Signatures](/developer-tools/signatures.md) for format       |

**Note:** The `signature` field is included in `Add`, `Executed`, `Cancelled`, `Modified`, and `Suspended` messages to provide cryptographic proof of the original order. It is also included in `OrderStatus` snapshots, and omitted from `TradeReport` and `TradeCancel` messages.

***