Positions

This page covers subscribing to position updates with subscribe_positions, and the positions payload that subscription delivers.

Subscribing to position updates

Subscribe to real-time position changes by emitting subscribe_positions. This requires an HMAC-signed handshake. See Authentication. subscribe_positions accepts the same payload as subscribe_market_prices:

Field	Type	Description
`marketAddresses`	`string[]`	Contract addresses for AMM markets
`marketSlugs`	`string[]`	Slugs for CLOB markets

import { io } from 'socket.io-client';

const socket = io('wss://ws.limitless.exchange/markets', {
  transports: ['websocket'],
  extraHeaders: wsAuthHeaders(TOKEN_ID, SECRET),
});

socket.on('connect', () => {
  // Subscribe to position updates for specific markets
  socket.emit('subscribe_positions', {
    marketAddresses: ['0x1234...'],   // AMM markets
    marketSlugs: ['btc-100k-weekly'], // CLOB markets
  });
});

// Confirmation
socket.on('system', (data) => {
  console.log(data);
  // { message: 'Successfully subscribed to position updates', markets: { addresses: [...], slugs: [...] } }
});

// Position updates
socket.on('positions', (data) => {
  console.log('Position update:', data);
});

Like subscribe_market_prices, calling subscribe_positions again replaces the previous subscription. Include all markets in a single call. A repeat subscribe_positions is accepted only within 30 seconds of the handshake timestamp; after that, reconnect with freshly signed headers (see Overview).

If neither marketSlugs nor marketAddresses is given the server ignores the message: no system acknowledgement, no snapshot, no frames.

Position updates are pushed automatically when your balances change (e.g. after a trade is mined). You do not need to poll.

The initial snapshot is rate-limited per account (10 subscribes per 10 seconds by default). Beyond that the subscription is still active and live updates arrive, but the snapshot is skipped; fetch positions over REST if you need it.

Event payload

`positions`

Position updates have different shapes depending on market type. AMM markets:

{
  "account": "0xabcd...",
  "marketAddress": "0x1234...",
  "positions": [
    {
      "tokenId": "123456",
      "balance": "1000000",
      "outcomeIndex": 0,
      "collateralOutOnSell": "950000"
    }
  ],
  "type": "AMM"
}

CLOB markets:

{
  "account": "0xabcd...",
  "marketSlug": "btc-100k-weekly",
  "positions": [
    {
      "tokenId": "19633204485790...",
      "ctfBalance": "10000000",
      "averageFillPrice": "0.65",
      "costBasis": "6500000",
      "marketValue": "7000000",
      "marketId": 7348
    }
  ],
  "tokenIds": ["19633204485790..."],
  "timestamp": 1783728000000,
  "type": "CLOB"
}

Field	Type	Description
`timestamp`	`number`	Optional. Epoch milliseconds of the on-chain balance change that triggered this update. Only present on balance-change updates; the initial snapshot after `subscribe_positions` omits it. Use it to order snapshots against trade confirmations.

WebSocket overview: connection details, handshake authentication, and the full event reference

Getting Started

Quick Start

TypeScript SDK

Python SDK

Go SDK

Rust SDK

WebSocket

Subscribing to position updates

Event payload

`positions`

​Subscribing to position updates

​Event payload

​positions

​Related

Subscribing to position updates

Event payload

`positions`

Related