Connect to WebSocket

United Market offers two real-time interfaces. Most integrations should use the backend Socket.IO endpoint; server-side bots that want the matcher’s native order-book stream can connect to the CLOB WebSocket directly.

Interface	URL	Protocol
Backend (recommended)	`https://api.unitedmarket.ai`	Socket.IO (secure `wss://` after upgrade)
CLOB (direct)	`wss://clob.unitedmarket.ai/ws`	Raw WebSocket

United Market is now live on BNB Smart Chain mainnet. We just launched — start trading on-chain prediction markets today.

The Socket.IO endpoint adds market rooms, automatic reconnection, price snapshots, and normalized payloads. The direct CLOB WebSocket is a lower-level feed intended for advanced, server-side consumers.

Socket.IO (recommended)

Use a Socket.IO client — not a plain WebSocket client — to connect to https://api.unitedmarket.ai. The transport upgrades to a secure WebSocket (wss://) automatically.

Install Client

npm install socket.io-client

Connect

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

const socket = io("https://api.unitedmarket.ai", {
  transports: ["websocket", "polling"],
  reconnection: true,
});

Join a market room with the market conditionId.

const conditionId = "0xd19487c4038d0dce2edeb510a21d6f8534e09d8065d40cb9e10ad2652d86a276";

socket.on("connect", () => {
  socket.emit("join:market", conditionId);
});

socket.emit("leave:market", conditionId);

Client Events

Event	Payload	Description
`join:market`	`conditionId: string`	Subscribe to one market room.
`leave:market`	`conditionId: string`	Unsubscribe from one market room.
`join:activity`	none	Subscribe to global trade activity.
`leave:activity`	none	Unsubscribe from global trade activity.

Server Events

Event	Description
`orderbook:update`	Emitted when market orderbook state changes.
`trade:new`	Emitted when a trade is confirmed on-chain.
`ob:snapshot`	L2 orderbook snapshot for an outcome token.
`price:snapshot`	Latest bid, ask, and midpoint for an outcome.

`orderbook:update`

type OrderbookUpdatePayload = {
  conditionId: string;
  orderbook: {
    type:
      | "order:new"
      | "order:cancelled"
      | "order:matched"
      | "order:filled"
      | "order:settlement";
    orderHash: string;
    tokenId: string;
    timestamp: number;
    data: Record<string, unknown>;
  };
};

After this event, clients can refetch GET /markets/{id}/orderbook or GET /markets/{id}/trading.

`trade:new`

type TradeNewPayload = {
  conditionId: string;
  trade: {
    orderHash: string;
    tokenId: string;
    timestamp: number;
    data: {
      maker: string;
      taker: string;
      makerAmountFilled: string;
      takerAmountFilled: string;
      fee: string;
      txHash: string;
    };
  };
};

`ob:snapshot`

L2 levels are 18-decimal fixed-point strings — divide price and size by 1e18. When synthAsks is true, asks already include complement synthetic asks, so do not re-derive them client-side.

type L2Level = {
  price: string;
  size: string;
  numOrders: number;
};

type ObSnapshotPayload = {
  conditionId: string;
  tokenId: string;
  bids: L2Level[];
  asks: L2Level[];
  timestamp: number;
  // Monotonic matcher sequence number; drop a snapshot whose seq is not
  // greater than the last one you applied. Absent on older builds.
  seq?: number;
  synthAsks?: boolean;
};

`price:snapshot`

type PriceSnapshotPayload = {
  conditionId: string;
  outcomeId: string;
  tokenId: string;
  bid: number | null;
  ask: number | null;
  mid: number | null;
  timestamp: number;
};

Reconnection

Socket.IO reconnects automatically when configured with reconnection: true. Re-emit join:market subscriptions after reconnecting if your client manages rooms outside a persistent component.

Direct WebSocket (CLOB)

Advanced and server-side clients can connect straight to the CLOB matcher’s raw WebSocket. This is a lower-level feed: it streams the matcher’s native events without the backend’s room management, price snapshots, or payload normalization.

WebSocket URL
`wss://clob.unitedmarket.ai/ws`

Send a JSON subscribe message with a market conditionId. The server replies with a subscribed acknowledgement, then streams that market’s events. Subscribe to multiple markets by sending multiple messages; remove one with unsubscribe.

const ws = new WebSocket("wss://clob.unitedmarket.ai/ws");

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      type: "subscribe",
      conditionId:
        "0xd19487c4038d0dce2edeb510a21d6f8534e09d8065d40cb9e10ad2652d86a276",
    }),
  );
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // First an ack: { type: "subscribed", conditionId }
  // Then market events (see Event Format below).
  console.log(msg);
};

// Later: stop receiving events for a market.
// ws.send(JSON.stringify({ type: "unsubscribe", conditionId }));

If you never send a subscribe message, the socket receives events for all markets. Send at least one subscribe to scope the stream to the markets you care about.

Event Format

Every market event shares one envelope. The event name uses the matcher’s native form (ob_snapshot / ob_diff with underscores, and order:*), and the per-event detail lives under data.

type MatcherEvent = {
  type:
    | "order:new"
    | "order:cancelled"
    | "order:matched"
    | "order:filled"
    | "order:settlement"
    | "ob_snapshot"
    | "ob_diff";
  conditionId: string;
  orderHash: string;
  tokenId: string;
  timestamp: number;
  // Monotonic sequence number. Drop any event whose seq is not greater than
  // the last one you applied for that market.
  seq: number;
  data: Record<string, unknown>;
};

For ob_snapshot, data carries the full L2 book. As with the Socket.IO API, price and size are 18-decimal fixed-point strings, and synthAsks: true means asks already include complement synthetic asks.

type ObSnapshotData = {
  bids: Array<{ price: string; size: string; numOrders: number }>;
  asks: Array<{ price: string; size: string; numOrders: number }>;
  synthAsks: true;
};

This is the same data the backend relays, but in the matcher’s raw form: event names use underscores (ob_snapshot, not ob:snapshot) and the payload is wrapped in the MatcherEvent envelope (fields under data) rather than flattened. Use the Socket.IO API if you want the normalized, room-scoped events.

Overview

Guides

API Reference

Socket.IO (recommended)

Install Client

Connect

Client Events

Server Events

`orderbook:update`

`trade:new`

`ob:snapshot`

`price:snapshot`

Reconnection

Direct WebSocket (CLOB)

Event Format

​Socket.IO (recommended)

​Install Client

​Connect

​Subscribe to a Market

​Client Events

​Server Events

​orderbook:update

​trade:new

​ob:snapshot

​price:snapshot

​Reconnection

​Direct WebSocket (CLOB)

​Connect & Subscribe

​Event Format

Socket.IO (recommended)

Install Client

Connect

Subscribe to a Market

Client Events

Server Events

`orderbook:update`

`trade:new`

`ob:snapshot`

`price:snapshot`

Reconnection

Direct WebSocket (CLOB)

Connect & Subscribe

Event Format