Portfolio Subscription

Subscribe to portfolio update notifications for a specific user address.

Subscribe Request

{
  "id": 4,
  "method": "SUBSCRIBE",
  "params": {
    "chainId": 143,
    "userAddress": "0xafdf17420b93db5b5badfd74cb503da099d18071",
    "type": "portfolio"
  }
}

Unsubscribe Request

{
  "id": 4,
  "method": "UNSUBSCRIBE",
  "params": {
    "chainId": 143,
    "userAddress": "0xafdf17420b93db5b5badfd74cb503da099d18071",
    "type": "portfolio"
  }
}

Parameter Description

• chainId (required): Chain ID

• userAddress (required): User address (lowercase)

• type (required): Must be "portfolio"

Data Stream Message

{
  "stream": "portfolio",
  "data": {
    "type": "order",
    "userAddress": "0xafdf17420b93db5b5badfd74cb503da099d18071",
    "instrument": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
    "expiry": "4294967295"
  }
}

Note: data.type may be one of: order, range, position, or gate.

Portfolio Update Description

• This message is pushed when a user's orders, range orders, positions, or gates change

• The type field indicates the change type:

  • order: Order change

  • range: Range order change

  • position: Position change

  • gate: Gate change

• After receiving this message, clients should call the corresponding REST API to fetch the latest portfolio details

Order event details

When "stream": "portfolio" and data.type is order, the data object may include an orderInfo field for convenience. The server includes orderInfo only when the event contains an OrderId (i.e., event.OrderId != 0).

Example snippet pushed on order events:

{
  "stream": "portfolio",
  "data": {
    "type": "order",
    "userAddress": "0x...",
    "instrument": "0x...",
    "expiry": "4294967295",
    "orderInfo": {
      "oid": "192712318191",
      "orderId": "1030049889949000026",
      "type": "placed"
    }
  }
}

• orderInfo.oid (string): oid = shiftLeft(asUint24(tick), 24) + nonce

• orderInfo.orderId (string): The client-visible order ID (sent as string to preserve precision).

• orderInfo.type (string): The event type for the order. Allowed values:

  • placed — Order was placed (corresponds to SnapshotEventOrderTypePlacing)

  • filled — Order was fully filled (corresponds to SnapshotEventOrderTypeFilled)

  • partialFilled — Order was partially filled (corresponds to SnapshotEventOrderTypePartialFilled)

  • canceled — Order was canceled (corresponds to SnapshotEventOrderTypeCanceled)

Clients receiving a portfolio message with data.type == "order" should:

1. Inspect data.orderInfo (if present) to quickly determine which order and what kind of change occurred.

2. Call the appropriate REST API (for example, /v4/public/mm/orderById or /v4/public/mm/order/realtime) if they need the full order details.

Important Notes

• This subscription only sends notifications when changes occur

• You must call the REST API endpoints to retrieve the actual updated data

• The notification includes the instrument and expiry to help identify which instrument was affected

• When present, the orderInfo object helps identify which order changed and the kind of event (placed, filled, partialFilled, canceled).