WebSocket Events

Receive real-time position updates via WebSocket. All position state changes are delivered as events over a persistent Socket.IO connection.

SDK support: The @dimes-dot-fi/sdk/ws entry point ships PositionSocket and MarketSocket clients for the user gateways (JWT auth). They wrap Socket.IO, manage reconnection, and camelize every payload to match the rest of the SDK. Prefer them over wiring up Socket.IO by hand — see Using the SDK below. For the partner gateways (API key auth) the SDK has no client yet; use Socket.IO directly as shown in the raw examples. Runnable: 05-websocket.ts (Node) and react/streams.tsx (React reconciliation).

Two WebSocket gateways are available. Both deliver the same event types and payload shapes — they differ only in authentication and scope.

Gateway	Namespace	Auth	Scope
Partner	/v1/ws/prediction-markets/positions	API key	All positions for the partner
User	/v1/ws/prediction-markets/user-positions	User JWT	Only positions for the authenticated user

---

Using the SDK

For the user gateways, the SDK's @dimes-dot-fi/sdk/ws entry point gives you typed clients so you don't touch Socket.IO directly. Both clients take a getToken callback (so they always reconnect with a fresh JWT) and an optional baseUrl (defaults to https://api.dimes.fi — set it to https://api-sandbox.dimes.fi for sandbox). Payloads arrive camelCased (event.createdAt, event.data) to match the REST types returned elsewhere by the SDK.

Position events

PositionSocket connects to the user-positions gateway. Subscribe to a specific event type, to "*" for all of them, or to onNotification for the user-gateway notification stream. Every on* call returns an unsubscribe function.

import { PositionSocket } from "@dimes-dot-fi/sdk/ws";

const socket = new PositionSocket({
  getToken: () => currentJwt, // called on every (re)connect
  // baseUrl: "https://api-sandbox.dimes.fi", // for sandbox
});

socket.onConnect(() => console.log("connected"));

const off = socket.on("position.opened", (event) => {
  // event.data is a full Position (camelCased), same shape as the REST API
  addOpenPosition(event.data);
});

socket.on("position.opening", (event) => showFinalizing(event.data.id));

// Transient, informational messages (user gateway only)
socket.onNotification((event) => showToast(event.data.message));

socket.onError((err) => console.error("ws error", err));

socket.connect();

// later: off(); socket.disconnect();

When the JWT rotates, call socket.reconnectWithToken() to drop and re-establish the connection with the new token.

Market events

MarketSocket connects to the user-markets gateway with the same API. Remember that market event data is always an array (see Market events below):

import { MarketSocket } from "@dimes-dot-fi/sdk/ws";

const markets = new MarketSocket({ getToken: () => currentJwt });

markets.on("market.discovered", (event) => {
  for (const market of event.data) upsertMarket(market); // full Market objects
});

markets.on("market.eligibility_changed", (event) => {
  for (const delta of event.data) mergeMarketFields(delta.id, delta); // deltas
});

markets.connect();

The raw Socket.IO examples below remain accurate for the partner gateways and non-JS clients; the SDK clients simply wrap that same protocol for the user gateways.

---

Partner gateway

Namespace:

Environment	WebSocket URL
Production	wss://api.dimes.fi/v1/ws/prediction-markets/positions
Sandbox	wss://api-sandbox.dimes.fi/v1/ws/prediction-markets/positions

Sandbox emits the same event types and payload shapes as production — only the host and the key prefix differ. See Environments.

Transport: Socket.IO

Auth: Partner API key, passed as either:

• Socket.IO auth payload (recommended): auth: { apiKey: "dm_live_skey_..." } (or dm_sbx_skey_... in sandbox). Transmitted in the handshake body — never appears in URLs, server logs, or browser history.

• HTTP header: Authorization: Api-Key dm_live_skey_... (or dm_sbx_skey_... in sandbox). For Socket.IO clients, set this via the extraHeaders option.

On successful auth, the connection is scoped to the partner. All events for positions created through that partner's API keys are delivered.

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

const socket = io("wss://api.dimes.fi/v1/ws/prediction-markets/positions", {
  auth: {apiKey: process.env.DIMES_API_KEY},
});

socket.on("connect", () => {
  console.log("Connected to position events");
});

socket.on("position.opened", (event) => {
  console.log("Position opened:", event.data.id);
});

socket.on("error", (error) => {
  console.error("WebSocket error:", error);
});

---

User gateway

Environment	WebSocket URL
Production	wss://api.dimes.fi/v1/ws/prediction-markets/user-positions
Sandbox	wss://api-sandbox.dimes.fi/v1/ws/prediction-markets/user-positions

Transport: Socket.IO

Auth: User JWT (the same token from POST /tokens), passed as either:

• Socket.IO auth payload (recommended): auth: { token: "<jwt>" }.

• HTTP header: Authorization: Bearer <jwt>. For Socket.IO clients, set this via the extraHeaders option.

On successful auth, the connection is scoped to the authenticated user. Only events for positions belonging to that specific wallet address and partner are delivered — other users' positions are never visible.

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

const socket = io("wss://api.dimes.fi/v1/ws/prediction-markets/user-positions", {
  auth: {token: userJwt},
});

socket.on("position.opening", (event) => {
  // Early signal — position is being finalized on-chain
  showFinalizing(event.data.id);
});

socket.on("position.opened", (event) => {
  // Position fully open — display position card
  addOpenPosition(event.data);
});

---

Authentication errors

If authentication fails on either gateway, the server emits an error event and disconnects:

{
  "error": {
    "type": "AUTHENTICATION_ERROR",
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

---

Event envelope

All events follow the resource.action naming pattern with a consistent envelope:

{
  "id": "evt_abc123",
  "type": "position.opened",
  "created_at": "2025-06-01T10:00:05.000Z",
  "data": {
    ...
  }
}

Field	Type	Description
id	string	Unique event identifier (prefixed evt_)
type	string	Event type in resource.action format
created_at	string (ISO 8601)	When the event was emitted
data	object	Event payload — always contains the full position object matching the REST API shape

The data object contains the same representation you would get from GET /positions/{id}. This means event consumers can reuse the same types/parsers as their REST integration.

---

Event types

Event Type	Trigger
position.created	On-chain position account created (user submitted tx)
position.opening	Finalize-open tx confirmed on-chain (early signal, before indexer picks up)
position.opened	Position finalized on-chain, tokens acquired (indexer confirmed)
position.close_requested	User submitted close request
position.closed	Close finalized, proceeds distributed
position.settled	Market resolved, position settled
position.liquidated	Position liquidated due to insufficient margin
position.force_unwound	Position partially unwound to reduce leverage (position remains open)
position.partial_close_requested	Owner requested a partial close; slice queued (position remains open)
position.partial_close_initiated	Partial-close slice withdrawn, sell order in flight (position remains open)
position.partial_closed	Partial close finalized; position remains open at reduced size
position.partial_close_aborted	Partial-close slice never filled; position restored to original size
position.reverted	Position open failed, collateral refunded
position.cancelled	Position cancelled before opening (EVM only)

---

Event payloads

The data field in every event is a full position object — the same shape returned by the REST API. See the Positions section of the API Reference for complete field definitions.

Event	status	Position shape
position.created	pending	Open shape (entry, current, risk, fees, timing)
position.opening	pending	Open shape (early signal — position not yet indexed)
position.opened	open	Open shape
position.close_requested	closing	Open shape
position.closed	closed	Closed shape — close_reason: "closed", entry, result, fees
position.settled	settled	Closed shape — close_reason: "settled", entry, result, fees
position.liquidated	liquidated	Closed shape — close_reason: "liquidated", entry, result, fees
position.force_unwound	open	Open shape (reduced size — current values reflect new position)
position.partial_close_requested	open	Open shape (slice queued — size unchanged until initiated)
position.partial_close_initiated	open	Open shape (current reflects the survivor while the slice sells)
position.partial_closed	open	Open shape (reduced size — current values reflect new position)
position.partial_close_aborted	open	Open shape (slice never filled — size restored to original)
position.reverted	cancelled	Closed shape — close_reason: "reverted", revert_reason, entry, result, fees
position.cancelled	cancelled	Closed shape — close_reason: "reverted", entry, result, fees

Open positions include current, risk, fees, and timing sections. Closed, settled, and liquidated positions replace those with close_reason and result (including collected_liquidation_fee_* for liquidations).

The position.reverted payload additionally carries revert_reason, classifying why the open failed before it landed: exchange_unavailable (the prediction-market venue was temporarily unavailable — safe to retry), slippage_exceeded (price moved beyond your slippage tolerance before the order filled), or unknown. It is non-null only when close_reason is reverted; collateral is always returned regardless of reason. Surface exchange_unavailable as a transient, retryable issue and slippage_exceeded as a price-moved message.

The four position.partial_close_* events track an owner-requested partial close — the position stays open throughout and ends at a reduced size. Treat position.partial_closed like position.force_unwound: re-render the still-open position from the smaller current.* values.

position.opening vs position.opened

position.opening fires as soon as the finalize-open transaction is confirmed on-chain — before the event indexer picks it up. This gives the UI an early signal (~5-15 seconds faster) that the position is about to open.

position.opened fires later when the indexer delivers the confirmed PositionOpened event.

Recommended UI behavior: On position.opening, show a "finalizing" state. On position.opened, transition to the full open position view with live data. If position.reverted arrives instead, the open failed — show the error state.

---

Listening to events

Subscribe to specific event types using Socket.IO's standard event listeners:

socket.on("position.created", (event) => {
  updatePositionStatus(event.data.id, "pending");
});

socket.on("position.opening", (event) => {
  // Early signal — show "finalizing" state
  updatePositionStatus(event.data.id, "finalizing");
});

socket.on("position.opened", (event) => {
  addOpenPosition(event.data);
});

socket.on("position.close_requested", (event) => {
  updatePositionStatus(event.data.id, "closing");
});

socket.on("position.closed", (event) => {
  showSettlement(event.data);
});

socket.on("position.settled", (event) => {
  showSettlement(event.data);
});

socket.on("position.liquidated", (event) => {
  alertLiquidation(event.data);
});

socket.on("position.force_unwound", (event) => {
  // Position still open but reduced in size
  updateOpenPosition(event.data);
});

socket.on("position.partial_closed", (event) => {
  // Owner-requested partial close finalized — position still open, now smaller
  updateOpenPosition(event.data);
});

socket.on("position.reverted", (event) => {
  // Open failed — show error
  showOpenFailed(event.data);
});

socket.on("position.cancelled", (event) => {
  showCancelled(event.data);
});

---

Notification events (user gateway only)

In addition to position state-transition events, the user gateway emits notification events. These are informational messages that provide feedback during asynchronous operations — they are not errors and do not indicate a state change.

Envelope:

{
  "id": "evt_abc123",
  "type": "notification",
  "created_at": "2025-06-01T10:00:05.000Z",
  "data": {
    "code": "ORDER_FULFILLMENT_RETRYING",
    "message": "Order fulfillment not possible at current slippage tolerance. Retrying.",
    "params": {
      "position_id": "dm_pos_abc123",
      "slippage_bps": 150
    }
  }
}

Field	Type	Description
data.code	string	Machine-readable notification code
data.message	string	Human-readable description
data.params	object	Additional context (varies by notification code)

Notification codes:

Code	When	Params
ORDER_FULFILLMENT_RETRYING	Order could not be filled at current slippage; retrying	position_id, slippage_bps
PARTIAL_OPEN_PROGRESS	Floor or retry leg of a FAK partial-open fulfilled; reports cumulative progress	position_id, cumulative_filled_making_amount, target_making_amount, attempt_number
PARTIAL_OPEN_FLOOR_MISSED	Floor FOK of a FAK partial-open failed to fill after retries; position reverted	position_id

Listening:

socket.on("notification", (event) => {
  showToast(event.data.message);
});

Notifications are transient — display them as a toast or inline status message. They do not require user action.

---

Market events

In addition to position events, two WebSocket gateways stream market updates: new markets coming online, eligibility changes, and max-leverage changes. They mirror the position gateways exactly — same Socket.IO transport, same auth, same envelope — and differ only in scope.

Gateway	Namespace	Auth	Scope
Partner	/v1/ws/prediction-markets/markets	API key	All markets visible to the partner
User	/v1/ws/prediction-markets/user-markets	User JWT	Markets visible to the authenticated user

Auth is identical to the position gateways: the partner gateway takes an API key (auth: { apiKey: "dm_live_skey_..." } or Authorization: Api-Key ...), and the user gateway takes a user JWT (auth: { token: "<jwt>" } or Authorization: Bearer <jwt>). See Partner gateway and User gateway above for the full handshake details — they apply unchanged.

Environment	Partner URL	User URL
Production	wss://api.dimes.fi/v1/ws/prediction-markets/markets	wss://api.dimes.fi/v1/ws/prediction-markets/user-markets
Sandbox	wss://api-sandbox.dimes.fi/v1/ws/prediction-markets/markets	wss://api-sandbox.dimes.fi/v1/ws/prediction-markets/user-markets

data is always an array

Important: Unlike position events — where data is a single object — market events always deliver data as an array. A single market change arrives as an array of one; when many markets change at once (e.g. a batch eligibility sweep), they are batched into a single event. Always iterate data as an array.

The envelope is otherwise identical to position events:

{
  "id": "evt_mkt_abc123",
  "type": "market.discovered",
  "created_at": "2025-06-01T10:00:05.000Z",
  "data": [
    { ... },
    { ... }
  ]
}

Market event types

Event Type	Trigger	data items
market.discovered	A new market comes online	Full market objects (same shape as GET /v1/markets)
market.eligibility_changed	A market's tradeability / capacity / notional limits change	Delta objects — only the changed fields
market.max_leverage_changed	An eligible market's max leverage changes	Delta objects — id, polymarket, leverage (no min_bps/step_bps)

market.discovered carries the complete market payload — identical to an item from GET /v1/markets, including the optional prices block when available. The two *_changed events carry deltas: each item contains the market id, the always-present polymarket identifiers (so you can map the delta onto your cached market), and only the fields that actually changed. Merge those fields into your cached copy of the market by id.

market.discovered

data is an array of full market objects, each identical to an item from GET /v1/markets. See the Markets section of the API Reference for complete field definitions.

{
  "id": "evt_mkt_abc123",
  "type": "market.discovered",
  "created_at": "2025-06-01T10:00:05.000Z",
  "data": [
    {
      "id": "dm_mkt_abc123",
      "category": "politics",
      "provider": "polymarket",
      "status": "active",
      "ticker": "will-trump-win-the-2024-election",
      "title": "Will Trump win the 2024 election?",
      "accepting_new_positions": true,
      "min_notional_usd": "5.00",
      "min_notional_usd_pips": "50000",
      "max_notional_yes_usd": "50.00",
      "max_notional_no_usd": "50.00",
      "sided_eligibility": { "yes": { "...": "..." }, "no": { "...": "..." } },
      "leverage": { "...": "..." },
      "fees": { "...": "..." },
      "polymarket": {
        "condition_id": "0xabc123...",
        "no_token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
        "slug": "will-trump-win-the-2024-election",
        "yes_token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455"
      },
      "prices": {
        "yes_bid_price_usd": "0.49",
        "yes_ask_price_usd": "0.51",
        "no_bid_price_usd": "0.49",
        "no_ask_price_usd": "0.51"
      }
    }
  ]
}

market.eligibility_changed

data is an array of deltas. Each delta is { id, polymarket, ...only the changed fields }. Changed fields may include any of: accepting_new_positions, rejection_reason_code, sided_eligibility, max_notional_yes_usd(_pips), max_notional_no_usd(_pips), capacity_max_notional_yes_usd(_pips), capacity_max_notional_no_usd(_pips), slippage_max_notional_yes_usd(_pips), slippage_max_notional_no_usd(_pips). It never includes leverage.

{
  "id": "evt_mkt_def456",
  "type": "market.eligibility_changed",
  "created_at": "2025-06-01T10:01:00.000Z",
  "data": [
    {
      "id": "dm_mkt_abc123",
      "polymarket": {
        "condition_id": "0xabc123...",
        "no_token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
        "slug": "will-trump-win-the-2024-election",
        "yes_token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455"
      },
      "accepting_new_positions": false,
      "rejection_reason_code": "QUOTE_MARKET_NOT_ELIGIBLE"
    }
  ]
}

market.max_leverage_changed

data is an array of deltas. Each delta is { id, polymarket, leverage }, where leverage carries the same fields as the leverage block in a full market object except the constants min_bps and step_bps — those never change, so read them from the market discovery payload. Only emitted for markets that are currently allowed/eligible.

{
  "id": "evt_mkt_ghi789",
  "type": "market.max_leverage_changed",
  "created_at": "2025-06-01T10:02:00.000Z",
  "data": [
    {
      "id": "dm_mkt_abc123",
      "polymarket": {
        "condition_id": "0xabc123...",
        "no_token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
        "slug": "will-trump-win-the-2024-election",
        "yes_token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455"
      },
      "leverage": {
        "max_bps": 50000,
        "max_yes_bps": 50000,
        "max_no_bps": 30000,
        "max_market_leverage_per_notional": {
          "yes": { "at100_usd_bps": 50000, "at500_usd_bps": 40000, "at1000_usd_bps": 30000, "at10000_usd_bps": 20000 },
          "no": { "at100_usd_bps": 30000, "at500_usd_bps": 25000, "at1000_usd_bps": 20000, "at10000_usd_bps": 15000 }
        }
      }
    }
  ]
}

Connecting to market events

The connection flow is identical to the position gateways — only the namespace changes. Remember to iterate data:

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

const socket = io("wss://api.dimes.fi/v1/ws/prediction-markets/user-markets", {
  auth: {token: userJwt},
});

socket.on("connect", () => {
  console.log("Connected to market events");
});

socket.on("market.discovered", (event) => {
  // Full market objects — add/refresh them in your local store
  for (const market of event.data) {
    upsertMarket(market);
  }
});

socket.on("market.eligibility_changed", (event) => {
  // Deltas — merge only the changed fields into the cached market by id
  for (const delta of event.data) {
    mergeMarketFields(delta.id, delta);
  }
});

socket.on("market.max_leverage_changed", (event) => {
  for (const delta of event.data) {
    mergeMarketFields(delta.id, {leverage: delta.leverage});
  }
});

socket.on("error", (error) => {
  console.error("WebSocket error:", error);
});

For the partner gateway, swap the namespace to /v1/ws/prediction-markets/markets and authenticate with your API key (auth: {apiKey: process.env.DIMES_API_KEY}) exactly as shown for the partner position gateway.

---

Best practices

Deduplicate on event id. Store processed event IDs and skip duplicates. The same event may be delivered more than once.

Handle events out of order. A position.closed event could arrive before position.close_requested due to network timing. Use the created_at timestamp and the position status from the REST API as the source of truth if ordering matters.

Reconnect on disconnect. Configure your client's reconnection settings for production reliability.

Use REST API as fallback. If your WebSocket connection drops, use GET /positions to catch up on any missed state changes.