Execution Reports

Real-time order and account event notifications via WebSocket

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

{
  "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 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.

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

Executed

Order partially or fully filled.

{
  "type": "executionReport",
  "messageType": "Executed",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600001000000000,
  "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).

{
  "type": "executionReport",
  "messageType": "Cancelled",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600002000000000,
  "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.

{
  "type": "executionReport",
  "messageType": "Modified",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "200",
  "price": "510.00",
  "eventTimestamp": 1705600003000000000,
  "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.

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

OrderStatus

Order snapshot (sent during initial subscription).

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

For a resting SL/TP leg, the snapshot also carries closePosition:

{
  "type": "executionReport",
  "messageType": "OrderStatus",
  "side": "Sell",
  "status": "Suspended",
  "instrument": "BTC",
  "quantity": "0.05",
  "price": "0",
  "stopPrice": "58000.00",
  "closePosition": true,
  "eventTimestamp": 1705600000000000000,
  "traderOrderId": 1705600000003,
  "orderId": 123456791,
  "orderType": "StopLoss",
  "timeInForce": "GTC",
  "filledQuantity": "0",
  "filledPrice": "0",
  "remainingOpenQuantity": "0.05"
}

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)

TradeReport

Report sent for every trade.

{
  "type": "executionReport",
  "messageType": "TradeReport",
  "side": "Sell",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600001000000000,
  "matchId": 987654321,
  "tradeType": "Matched"
}

TradeCancel

Trade busted because its on-chain settlement failed (dropped or reverted). The fill is reversed.

{
  "type": "executionReport",
  "messageType": "TradeCancel",
  "side": "Buy",
  "instrument": "NVDA",
  "quantity": "100",
  "price": "500.00",
  "eventTimestamp": 1705600002000000000,
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "matchId": 987654321,
  "tradeType": "Matched"
}

---

Account Event Reports

DepositMargin

Collateral deposit event.

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

WithdrawMargin

Collateral withdrawal event.

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

TransferMargin

Cross ↔ isolated margin transfer event.

{
  "type": "executionReport",
  "messageType": "TransferMargin",
  "id": 100004,
  "eventTimestamp": 1705600003000000000,
  "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.

{
  "type": "executionReport",
  "messageType": "UpdateLeverage",
  "id": 100003,
  "eventTimestamp": 1705600002000000000,
  "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.

{
  "type": "executionReport",
  "messageType": "FundingRates",
  "id": 100004,
  "eventTimestamp": 1705600003000000000,
  "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.

{
  "type": "executionReport",
  "messageType": "Liquidation",
  "id": 100005,
  "eventTimestamp": 1705600004000000000,
  "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.

{
  "type": "executionReport",
  "messageType": "ManualLiquidation",
  "id": 100006,
  "eventTimestamp": 1705600005000000000,
  "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 (Unix nanoseconds)

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
reduceOnly	boolean	(Optional) Whether the order was signed reduce-only. Omitted when the report carries no order payload, so absent means unknown, not false
closePosition	boolean	(Optional) SL/TP only: true = managed (auto-syncs to position size), false = unmanaged (fixed qty)
signature	Object	(Optional) Original signed payload echoed back. See Signatures for format

Note: reduceOnly tells you why a resting order changed size or was cancelled on its own — a reduce-only order is kept in step with your position. See Reduce-Only Orders.

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.

---