> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Positions

> Subscribe to position updates and read the positions payload

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](/developers/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             |

```typescript theme={null}
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);
});
```

<Warning>
  Like `subscribe_market_prices`, calling `subscribe_positions` again **replaces** the previous subscription. Include all markets in a single call.
</Warning>

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

## Event payload

### `positions`

Position updates have different shapes depending on market type.

**AMM markets:**

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

**CLOB markets:**

```json theme={null}
{
  "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. |

## Related

* [WebSocket overview](/developers/websocket/overview): connection details, handshake authentication, and the full event reference