Positions Channel

Channel: positions
Authentication: Required

{
  "method": "subscribe",
  "params": {
    "channel": "positions",
    "market_ids": [1, 2]
  }
}

Parameter	Type	Required	Description
`market_ids`	number[]	No	Filter by market IDs. Empty = all markets
`makers`	string[]	No	Account filter. Omit it — an authenticated client is scoped to its own account

Authenticate before subscribing: for an authenticated client the subscription is scoped to its own account.

Message Format

Snapshot

Sent immediately after subscribing. Contains your positions in the subscribed markets.

{
  "method": "snapshot",
  "channel": "positions",
  "type": "snapshot",
  "data": [
    {
      "account": "0x1234567890123456789012345678901234567890",
      "market_id": "1",
      "size": "0.020463",
      "quote_amount": "-1456.615970721655103383",
      "side": "BUY",
      "margin_mode": 0,
      "leverage": "25",
      "avg_entry_price": "66819.6",
      "isolated_usdc_balance": "0",
      "last_funding_payment": "-1343.280402365544640442",
      "unsettled_funding": "3.82702329635071426",
      "block_number": "0",
      "log_index": "0",
      "worker_timestamp": "0"
    }
  ],
  "position_count": 1,
  "worker_timestamp": "1786934110123456789"
}

Snapshot rows are rebuilt from current state, so their per-row block_number, log_index and worker_timestamp are all "0". Only rows on update messages carry real block metadata.

Update

Sent when one of your positions is opened, modified, or closed.

{
  "channel": "positions",
  "type": "update",
  "market_id": "1",
  "data": [
    {
      "account": "0xE11651462598edA667b2ca42f523b3a87f559aE0",
      "market_id": "1",
      "size": "0",
      "quote_amount": "0",
      "side": "SELL",
      "margin_mode": 0,
      "leverage": "11",
      "avg_entry_price": "0",
      "isolated_usdc_balance": "0",
      "last_funding_payment": "-1317.375850280955754602",
      "unsettled_funding": "0",
      "block_number": "19328351",
      "log_index": "527",
      "worker_timestamp": "1786934110000000000"
    }
  ],
  "block_number": 19328351,
  "log_index": 527,
  "worker_timestamp": "1786934110234567891"
}

data is always an array. A closed position is reported as size: "0" rather than being omitted.

Snapshot Message Fields

Field	Type	Description
`method`	string	Always `"snapshot"`
`channel`	string	Always `"positions"`
`type`	string	Always `"snapshot"`
`data`	array	Array of position objects
`position_count`	number	Number of positions in the array
`worker_timestamp`	string	Server time in nanoseconds

The snapshot carries no market_id and no block metadata.

Update Message Fields

Field	Type	Description
`channel`	string	Always `"positions"`
`type`	string	Always `"update"`
`market_id`	string	Market ID
`data`	array	Array of position objects
`block_number`	number	Blockchain block number
`log_index`	number	Log index within the block
`worker_timestamp`	string	Server time in nanoseconds

Position updates carry no tx_hash, and there is no timestamp or block_timestamp field on this channel.

Position Object Fields

Field	Type	Description
`account`	string	Account address
`market_id`	string	Market ID
`size`	string	Signed position size, decimal — negative on a short, `"0"` when flat
`quote_amount`	string	Signed cumulative quote, decimal. Normally the opposite sign to `size`; a partial reduce folds realised PnL into it and can leave both the same sign
`side`	string	`"BUY"` (long) or `"SELL"` (short)
`margin_mode`	number	`0` = cross, `1` = isolated — a number, not a string
`leverage`	string	Leverage multiplier, decimal (`"11"` = 11×)
`avg_entry_price`	string	Weighted average entry price, decimal
`isolated_usdc_balance`	string	Margin assigned to this position in isolated mode, decimal
`last_funding_payment`	string	Funding checkpoint stored on the position, decimal
`unsettled_funding`	string	`(accumulated_funding − last_funding_payment) × size`, decimal
`block_number`	string	Block of the last update (string, unlike the envelope's number)
`log_index`	string	Log index of the last update (string, unlike the envelope's number)
`worker_timestamp`	string	Per-object server time in nanoseconds; `"0"` on snapshot rows

🚧
side is not a flat indicator
side mirrors the sign of size on an open position, but a closed position keeps whichever direction it last held while size goes to "0". Read size — its sign is authoritative for both direction and flatness.

Examples

Subscribe to all markets

{
  "method": "subscribe",
  "params": {
    "channel": "positions"
  }
}

Subscribe to specific markets

{
  "method": "subscribe",
  "params": {
    "channel": "positions",
    "market_ids": [1, 2]
  }
}

Unsubscribe

{
  "method": "unsubscribe",
  "params": {
    "channel": "positions"
  }
}

Notes

Price Format

All size, price and USDC fields are decimal strings, not wei.

Private Channel

Authenticate before subscribing. The channel is meant to carry your own positions only.

Subscribe

Message Format

Snapshot

Update

Snapshot Message Fields

Update Message Fields

Position Object Fields

side is not a flat indicator

Examples

Subscribe to all markets

Subscribe to specific markets

Unsubscribe

Notes

Price Format

Private Channel

`side` is not a flat indicator