Reference

PerpDB WebSockets

Premium

Live position lifecycle fills streamed per protocol, optionally narrowed to one market or owner address. Delivery is best-effort; the REST endpoints remain the durable source of truth.

Lifecycle fills

WSS

Stream GMTrade fills as they land, each tagged with the position_id the REST surface exposes. The scope is the URL, so watching several scopes means opening several connections.

Headers

x-api-keystringrequired

API key sent in the WebSocket upgrade header; never accepted as a query parameter.

Query parameters

marketstring

Optionally filter the stream to a market symbol or protocol-native market variant, when available.

addressstring

Optionally filter the stream to an owner address; combining filters returns their intersection.

Connection limits

Concurrent connections per account: 50

Response

101

{ data: PositionEvent }

PositionEvent

data

protocolProtocol identifier.

marketMarket symbol (e.g. SOL-PERP).

market_variantProtocol-native market variant identifier; null when unavailable.

position_idIdentifier of the position lifecycle; null when unavailable.

eventLifecycle-aware fill action: open is the first fill, while close and liquidation are terminal.open | increase | decrease | close | liquidation

sidePosition side.long | short

size_delta_usdSigned notional change: positive for an increase and negative for a decrease.

position_size_usdPosition notional after the fill.

priceExecution price.

entry_priceRunning size-weighted average entry price after the fill.

collateral_delta_usdSigned collateral change.

realized_pnl_usdRealized PnL on the fill, if any.

fee_usdTrading fee charged on the fill; excludes borrowing, funding, and liquidation charges.

borrowing_fee_usdBorrowing charge settled on the fill; null when none was settled.

funding_fee_usdFunding charge settled on the fill; null when none was settled.

liquidation_fee_usdLiquidation charge settled on the fill; null when none was settled and not included in the trading fee.

fee_total_usdTotal of all applicable fee components on the fill.

trade_idProtocol-native fill identifier; null when unavailable.

addressOwner wallet address (base58).

txTransaction signature.

timeTimestamp when the fill executed.

Request

websocat

websocat -H 'x-api-key: ak_...' \
  'wss://api.perpdb.xyz/v1/stream/gmtrade/fills?market=SOL-PERP'

Example

{
  "data": {
    "protocol": "gmtrade",
    "market": "SOL-PERP",
    "market_variant": "SOL/USD[WSOL-USDC]",
    "position_id": 4821937,
    "event": "increase",
    "side": "long",
    "size_delta_usd": 2500,
    "position_size_usd": 7500,
    "price": 168.42,
    "entry_price": 165.87,
    "collateral_delta_usd": 500,
    "realized_pnl_usd": 0,
    "fee_usd": 1.5,
    "borrowing_fee_usd": 0.22,
    "funding_fee_usd": 0.08,
    "liquidation_fee_usd": null,
    "fee_total_usd": 1.8,
    "trade_id": 918273,
    "address": "7NfgSkEcRr3FBixjD5cJTmb4kAV8Y6DAxNvbLnk3S9pE",
    "tx": "3QzUyfWvYcJ8gV1kM5xTn9rBq2eL6hPdS4mKjNwEbAtCgRfXhZs7DqoJp8uWvYcLkM5xTn9rBq2eL6hPdS4mKjNw",
    "time": "2026-08-09T14:32:07.184Z"
  }
}