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

# Market data (/perps)

> Subscribe to live perpetual market ticks per symbol.

The `/perps` namespace streams live market snapshots for perpetual markets. You subscribe per symbol
and receive `market_tick` pushes, throttled to at most \~4 per second per symbol.

## Subscribe / unsubscribe

| Event                | Direction       | Payload              | Returns        |
| -------------------- | --------------- | -------------------- | -------------- |
| `subscribe_market`   | client → server | `{ symbol: "BTC" }`  | `{ ok: true }` |
| `unsubscribe_market` | client → server | `{ symbol: "BTC" }`  | `{ ok: true }` |
| `market_tick`        | server → client | `PerpMarketSnapshot` | —              |
| `connected`          | server → client | `{ userId }`         | —              |
| `error`              | server → client | `{ message }`        | —              |

## Example

```javascript theme={null}
import { io } from "socket.io-client";

const socket = io("wss://api.alpha-labs.trade/perps", {
  transports: ["websocket"],
  auth: { token: process.env.MURMO_API_KEY },
});

socket.on("connected", () => {
  socket.emit("subscribe_market", { symbol: "BTC" });
  socket.emit("subscribe_market", { symbol: "SOL" });
});

socket.on("market_tick", (snap) => {
  console.log(snap.symbol, snap.markPriceUsd, snap.fundingRatePercentage);
});

// later
socket.emit("unsubscribe_market", { symbol: "SOL" });
```

## `market_tick` payload

```json theme={null}
{
  "symbol": "BTC",
  "markPriceUsd": 68250.5,
  "midPriceUsd": 68249.0,
  "oraclePriceUsd": 68251.2,
  "fundingRatePercentage": 0.0042,
  "openInterestBaseLots": 1820345,
  "volume24hUsd": 91234567.8,
  "prevDayPriceUsd": 67010.0,
  "receivedAt": "2026-06-02T19:00:00.000Z"
}
```

| Field                   | Type               | Notes                              |
| ----------------------- | ------------------ | ---------------------------------- |
| `symbol`                | string             | Market symbol.                     |
| `markPriceUsd`          | number             | Mark price (USD).                  |
| `midPriceUsd`           | number \| null     | Mid price (USD).                   |
| `oraclePriceUsd`        | number             | Oracle price (USD).                |
| `fundingRatePercentage` | number             | Funding rate per funding interval. |
| `openInterestBaseLots`  | number             | Open interest in base lots.        |
| `volume24hUsd`          | number             | 24h notional volume (USD).         |
| `prevDayPriceUsd`       | number             | Price 24h ago (for % change).      |
| `receivedAt`            | string (date-time) | When the snapshot was captured.    |

<Warning>
  Unlike the REST API, the `market_tick` stream sends **numeric** price/funding/volume fields, not
  decimal strings — it's optimized for low-latency streaming. For values you'll do exact money math
  on (entry sizing, accounting), read prices from `GET /api/v1/perps/markets`, which returns the
  full-precision decimal-string contract.
</Warning>

<Tip>
  Subscriptions are per symbol. Subscribe only to the markets you're tracking to minimize traffic;
  ticks are already throttled to \~4/sec/symbol.
</Tip>