User feed - 4casters API

The user feed streams your account‑scoped updates (orders, fills, cancels).

// user_feed_quickstart.js 
const WebSocket = require('ws'); 
const token = process.env.FOURCASTERS_TOKEN; 
function connectUserFeed() { 
  const ws = new WebSocket('wss://streaming-api.4casters.io/v2/user', { 
    headers: { Authorization: token }, 
  });
  let pingTimer; let lastPong = Date.now(); 
  ws.on('open', () => { 
    console.log('user feed connected'); 
    pingTimer = setInterval(() => { 
      if (ws.readyState === WebSocket.OPEN) { 
        ws.ping(); 
      } 
      if (Date.now() - lastPong > 30000) { 
        console.warn('user feed: missed pong >30s, closing'); 
        ws.terminate(); 
      } 
    }, 10000); 
  }); 
 
  ws.on('pong', () => { lastPong = Date.now(); }); 
 
  ws.on('message', (buf) => { 
    try { 
      const msg = JSON.parse(buf.toString()); 
      console.log('user update:', JSON.stringify(msg, null, 2)); 
    } catch { console.log('user update (raw):', buf.toString()); } 
  }); 
 
  ws.on('error', (e) => console.error('⚠️ user feed error:', e.message));
 
  ws.on('close', (code, reason) => { 
    console.log(`user feed closed: ${code} ${reason}`); 
    clearInterval(pingTimer); 
    // basic backoff reconnect 
    setTimeout(connectUserFeed, 1000); 
  }); 
} 
 
connectUserFeed(); 

Messages

The user feed sends each update as a bare JSON object (no tuple envelope). All updates share one envelope; the action is determined by which of unmatched / matched are populated and by origin.

Common envelope

{
  matched:    null | MatchedBlock,
  unmatched:  null | UnmatchedBlock,
  origin:     "offer" | "wager",

  gameID:             string,
  parentGameID:       string | null,
  eventName:          string,
  league:             string,
  sport:              string,
  live:               boolean,
  start:              string,   // RFC3339
  awayRotationNumber: string,

  platform:           string,   // e.g. "api"
  createdAt:          string,   // RFC3339
  messageID:          string,   // Redis stream entry id, e.g. "1715361234567-0"
}

messageID is the stream entry id added by the streaming-api before send. Persist the latest one you have processed — it is your replay cursor. See Replaying missed messages below.

The `matched` block

Present whenever the update represents a fill (matched != null). Every field below is sent on every fill unless marked conditional. All values are from your perspective — as taker you see the side you took, as maker you see your posted side.

Field	Type	Sent	Meaning
`txID`	string	always	Id of the bet. Dedupe fills on this — it is the same `txID` returned by get matched bets.
`orderID`	string	always	Id of the order this fill came off. As maker, your resting order; as taker, the order you hit.
`wagerRequestID`	string	always	Id of the place request behind the fill. As taker, your own request; as maker, the request that originally posted your order.
`amount`	number	always	Stake excluding commission. Equal to `risk` on a maker fill, but not on a taker fill — see below.
`risk`	number	always	What you stand to lose on this fill. As taker, inclusive of the commission charged on a loss; as maker, no commission applies.
`win`	number	always	What you stand to win on this fill. As taker, net of the commission charged on a win; as maker, no commission applies.
`odds`	integer	always	American odds of your side of the fill.
`type`	string	always	`moneyline`, `spread`, `total`, or `moneyline1x2`.
`side`	string	always	See side and market semantics.
`number`	number	conditional	The spread or total line. Omitted entirely on `moneyline` and `moneyline1x2`.
`market`	string	conditional	`moneyline1x2` only.
`userReference`	string \| null	always	Echoes the `userReference` you sent on the order. `null` if you sent none.
`isPostArb`	boolean	conditional	`true` on fills of `postArb` orders; omitted otherwise.

Do not derive win from risk. risk and win are each rounded to 2dp independently from the unrounded stake, so risk x odds can disagree with win by a cent. Book the win value as sent; if it is missing, treat the message as malformed rather than reconstructing it.Do not treat amount as a synonym for risk. On a taker fill amount excludes the commission charged on a loss and risk includes it. Booking amount as your risk will under-count commission on every take.

The same quantities over REST (get matched bets) are string-formatted to 2 decimals rather than numbers, and are computed with a slightly different commission and rounding order. Reconcile with a cent of tolerance rather than exact equality.

The `unmatched` block

Present whenever the update concerns an order resting on (or leaving) the book — placements, cancellations, and the maker side of a fill. Odds and sides are from the maker’s perspective, i.e. what you posted, not what the book offers others.

Field	Type	Sent	Meaning
`orderID`	string	always	Id of the order.
`wagerRequestID`	string	always	Id of the place request that created the order.
`filled`	number	always	On a fill: the risk matched by this event alone, not the running total. `0` on a placement. On a cancellation it is instead the cumulative risk matched before the cancel landed.
`offered`	number	always	Total risk the order offered. `0` identifies a cancellation.
`remaining`	number	always	Risk still resting on the book. `0` means fully matched.
`odds`	integer	always	American odds of your side of the order.
`type`	string	always	`moneyline`, `spread`, `total`, or `moneyline1x2`.
`side`	string	always	See side and market semantics.
`number`	number	conditional	The spread or total line. Omitted entirely on `moneyline` and `moneyline1x2`.
`market`	string	conditional	`moneyline1x2` only.
`userReference`	string	conditional	Echoes the `userReference` you sent; omitted if the order carried none.
`isPostArb`	boolean	conditional	`true` for `postArb` orders; omitted otherwise.

filled and remaining are not the same kind of number. remaining is running state — what is left on the book right now — but on a fill filled describes only that event. Across several partial fills they do not add up: filled + remaining equals offered on the first fill and drifts apart after that.To track how much of a resting order has been matched, use offered - remaining, or accumulate filled yourself. Do not mix the two.

How to identify the action

unmatched.filled === 0 && unmatched.offered > 0 -> order placed
unmatched.offered === 0 -> order cancelled
matched != null && unmatched == null -> matched as taker
matched != null && unmatched != null -> matched as maker (partial fill if unmatched.remaining > 0)

Updates for orders placed with orderType: "postArb" also carry isPostArb: true inside matched / unmatched (on placed, filled, and cancelled updates); the field is omitted otherwise.

Side and market semantics by bet type

The meaning of side (and which extra fields appear) inside matched / unmatched depends on type:

`type`	`side`	`number`	`market`
`moneyline`	participant ObjectID hex	—	—
`spread`	participant ObjectID hex	spread line (e.g. `6.5`)	—
`total`	`"over"` / `"under"`	total line (e.g. `209.5`)	—
`moneyline1x2`	`"yes"` / `"no"`	—	participant ObjectID hex (home or away) or `"draw"`

market is only present on moneyline1x2 updates: it names the 3-way outcome the market is about (home team, away team, or the draw), and side says whether the bet is yes or no on that outcome. All fields are from your perspective — as maker you see your posted side; as taker you see the side you took.

Action: order placed

A new offer was put on the book. unmatched.filled is 0, unmatched.offered > 0, and matched is null.

{
  "unmatched": {
    "filled": 0,
    "offered": 999,
    "remaining": 999,
    "orderID": "62619e6b40e36d0494600f67",
    "wagerRequestID": "62619e6b40e36d0494600f70",
    "type": "moneyline",
    "side": "607349dc22a237cf46b021fb",
    "odds": -105
  },
  "matched": null,
  "origin": "offer",
  "gameID": "603eb5d05eca45001243aedc",
  "parentGameID": null,
  "eventName": "PHILADELPHIA-76ERS-VS-MIAMI-HEAT",
  "league": "NBA",
  "sport": "basketball",
  "live": false,
  "start": "2026-04-22T01:00:00.000Z",
  "awayRotationNumber": "571",
  "platform": "api",
  "createdAt": "2026-04-21T18:11:54.614Z",
  "messageID": "1715361234567-0"
}

Action: order cancelled

The user (or the system on their behalf) cancelled an offer. The distinguishing field is unmatched.offered === 0.

{
  "unmatched": {
    "filled": 0,
    "offered": 0,
    "remaining": 0,
    "orderID": "62619e6b40e36d0494600f67",
    "wagerRequestID": "62619e6b40e36d0494600f70",
    "type": "spread",
    "side": "607349dc22a237cf46b021fb",
    "number": 6.5,
    "odds": -110
  },
  "matched": null,
  "origin": "offer",
  "gameID": "603eb5d05eca45001243aedc",
  "parentGameID": null,
  "eventName": "PHILADELPHIA-76ERS-VS-MIAMI-HEAT",
  "league": "NBA",
  "sport": "basketball",
  "live": false,
  "start": "2026-04-22T01:00:00.000Z",
  "awayRotationNumber": "571",
  "platform": "api",
  "createdAt": "2026-04-21T18:12:30.000Z",
  "messageID": "1715361234890-0"
}

Action: order matched (taker)

The user took someone else’s offer. unmatched is null, matched carries the fill, and origin is "wager".

{
  "unmatched": null,
  "matched": {
    "txID": "62619e6b40e36d0494600f99",
    "amount": 100.0,
    "risk": 100.0,
    "win": 95.24,
    "odds": -105,
    "orderID": "62619e6b40e36d0494600f67",
    "wagerRequestID": "62619e6b40e36d0494600f70",
    "type": "moneyline",
    "side": "607349dc22a237cf46b021fb"
  },
  "origin": "wager",
  "gameID": "603eb5d05eca45001243aedc",
  "parentGameID": null,
  "eventName": "PHILADELPHIA-76ERS-VS-MIAMI-HEAT",
  "league": "NBA",
  "sport": "basketball",
  "live": false,
  "start": "2026-04-22T01:00:00.000Z",
  "awayRotationNumber": "571",
  "platform": "api",
  "createdAt": "2026-04-21T18:13:00.000Z",
  "messageID": "1715361240000-0"
}

Action: order matched (maker, partial fill)

Someone hit the user’s posted offer. Both matched and unmatched are populated; unmatched.remaining shows what is still on the book. Because unmatched is set, origin is "offer".

{
  "unmatched": {
    "filled": 100,
    "offered": 500,
    "remaining": 400,
    "orderID": "62619e6b40e36d0494600f67",
    "wagerRequestID": "62619e6b40e36d0494600f70",
    "type": "spread",
    "side": "607349dc22a237cf46b021fb",
    "number": 6.5,
    "odds": 110
  },
  "matched": {
    "txID": "62619e6b40e36d0494600fa0",
    "amount": 100,
    "risk": 100,
    "win": 110,
    "odds": 110,
    "orderID": "62619e6b40e36d0494600f67",
    "wagerRequestID": "62619e6b40e36d0494600f70",
    "type": "spread",
    "side": "607349dc22a237cf46b021fb",
    "number": 6.5
  },
  "origin": "offer",
  "gameID": "603eb5d05eca45001243aedc",
  "parentGameID": null,
  "eventName": "PHILADELPHIA-76ERS-VS-MIAMI-HEAT",
  "league": "NBA",
  "sport": "basketball",
  "live": false,
  "start": "2026-04-22T01:00:00.000Z",
  "awayRotationNumber": "571",
  "platform": "api",
  "createdAt": "2026-04-21T18:14:00.000Z",
  "messageID": "1715361250000-0"
}

Action: order matched (moneyline1x2)

Fills on 3-way soccer markets carry the market + side pair described above instead of a participant-hex side. Here the user took “yes” on the home team at +120 (a bet that Arsenal wins):

{
  "unmatched": null,
  "matched": {
    "txID": "685e321440e36d0494601b07",
    "amount": 100.0,
    "risk": 100.0,
    "win": 120.0,
    "odds": 120,
    "orderID": "685e2f1c40e36d0494601a22",
    "wagerRequestID": "685e321440e36d0494601b00",
    "type": "moneyline1x2",
    "side": "yes",
    "market": "607349dc22a237cf46b021fb"
  },
  "origin": "wager",
  "gameID": "685e21aa0be1b7d5a3f9c4d2",
  "parentGameID": null,
  "eventName": "ARSENAL-VS-CHELSEA",
  "league": "EPL",
  "sport": "soccer",
  "live": false,
  "start": "2026-07-04T19:00:00.000Z",
  "awayRotationNumber": "3012",
  "platform": "api",
  "createdAt": "2026-07-03T14:25:02.114Z",
  "messageID": "1751552702114-0"
}

{
  "unmatched": {
    "filled": 100,
    "offered": 500,
    "remaining": 400,
    "orderID": "685e2f1c40e36d0494601a22",
    "wagerRequestID": "685e2f1c40e36d0494601a19",
    "type": "moneyline1x2",
    "side": "no",
    "market": "607349dc22a237cf46b021fb",
    "odds": -120
  },
  "matched": {
    "txID": "685e321440e36d0494601b07",
    "amount": 120.0,
    "risk": 120.0,
    "win": 100.0,
    "odds": -120,
    "orderID": "685e2f1c40e36d0494601a22",
    "wagerRequestID": "685e2f1c40e36d0494601a19",
    "type": "moneyline1x2",
    "side": "no",
    "market": "607349dc22a237cf46b021fb"
  },
  "origin": "offer",
  "gameID": "685e21aa0be1b7d5a3f9c4d2",
  "parentGameID": null,
  "eventName": "ARSENAL-VS-CHELSEA",
  "league": "EPL",
  "sport": "soccer",
  "live": false,
  "start": "2026-07-04T19:00:00.000Z",
  "awayRotationNumber": "3012",
  "platform": "api",
  "createdAt": "2026-07-03T14:25:02.114Z",
  "messageID": "1751552702114-1"
}

Note the two perspectives of the same fill: the taker sees side: "yes" at +120, the maker sees side: "no" at -120 on the same market.

Replaying missed messages

The v2 user feed supports gap recovery after a dropped connection. Every message carries a messageID (a monotonically increasing stream entry id, e.g. "1751552702114-0"). If your connection drops, you can fetch exactly the messages you missed.

Endpoint

GET https://streaming-api.4casters.io/v2/user/messages?afterID=<messageID>&beforeID=<messageID>

Authentication is the same as the WebSocket: token in the Authorization header, Auth header, or token query parameter. Only messages belonging to the authenticated user are returned.

Parameter	Required	Meaning
`afterID`	yes	The `messageID` of the last message you processed before the drop. Results start strictly after it.
`beforeID`	no	Exclusive upper bound. Omit to read to the end of the retained history.

Response: `success`

Your afterID was still present in the retained history, so the returned list is a complete gap-fill — nothing between afterID and beforeID was lost:

{
  "status": "success",
  "messages": [
    { "...": "feed messages in order, each with its messageID" }
  ]
}

Apply the messages in order and resume processing live messages.

Response: `cache_expired`

Your afterID has aged out of the retained history, so the server cannot prove the replay is complete:

{
  "status": "cache_expired",
  "availableMessages": [
    { "...": "whatever is still retained, oldest first" }
  ]
}

availableMessages is whatever is still retained, oldest first. Messages older than the retention window are not recoverable through replay — reconnect promptly rather than relying on long look-back.

Example: reconnecting client with replay

A complete Node.js client (keepalive ping/pong omitted for brevity — see the quickstart at the top of this page). Two things keep it correct: every message — live, buffered, or replayed — passes through one forward-only cursor check, and a failed replay reconnects rather than going live over the gap.

// user_feed_replay_client.js
const WebSocket = require('ws');
const token = process.env.FOURCASTERS_TOKEN;
const HOST = 'streaming-api.4casters.io';

// Your replay cursor: the messageID of the last message you processed.
// Persist it durably (disk/db) so replay also works across process restarts.
let cursor = null;

// messageIDs are "<unix-ms>-<seq>"; compare numerically part by part.
function isAfterCursor(messageID) {
  if (!cursor) return true;
  const [ms, seq] = messageID.split('-').map(Number);
  const [cMs, cSeq] = cursor.split('-').map(Number);
  return ms > cMs || (ms === cMs && seq > cSeq);
}

function processMessage(msg) {
  // Replay can overlap live delivery, so every message — live, buffered,
  // or replayed — passes through this check. The cursor only moves forward.
  if (!isAfterCursor(msg.messageID)) return;
  cursor = msg.messageID;
  // Business logic goes here. `msg` is the same envelope everywhere.
  console.log('user update:', msg.origin, msg.messageID);
}

async function replayGap() {
  const params = new URLSearchParams({ afterID: cursor });
  const res = await fetch(`https://${HOST}/v2/user/messages?${params}`, {
    headers: { Authorization: token },
  });
  if (!res.ok) throw new Error(`replay request failed: ${res.status}`);
  const body = await res.json();

  if (body.status === 'success') {
    // Complete gap-fill: nothing between the cursor and now was lost.
    body.messages.forEach(processMessage);
  } else if (body.status === 'cache_expired') {
    // Apply what is still retained; anything older is not recoverable.
    console.warn('replay window expired - messages may have been lost');
    body.availableMessages.forEach(processMessage);
  } else {
    throw new Error(`unexpected replay status: ${body.status}`);
  }
}

function connect() {
  const ws = new WebSocket(`wss://${HOST}/v2/user`, {
    headers: { Authorization: token },
  });

  let live = false; // false while replay is in flight
  const buffer = [];
  // Settles when the open handler is done, so a reconnect never starts a
  // second replay while this one is in flight.
  let openTask = Promise.resolve();

  ws.on('open', () => {
    openTask = (async () => {
      console.log('user feed connected');
      if (cursor !== null) {
        try {
          await replayGap();
        } catch (e) {
          // Going live now would advance the cursor over the unfilled gap
          // and lose it — reconnect and retry from the same cursor.
          console.error('replay failed, reconnecting:', e.message);
          ws.terminate();
          return;
        }
      }
      // Drain messages buffered during replay; processMessage skips
      // anything the replay already covered.
      buffer.splice(0).forEach(processMessage);
      live = true;
    })();
  });

  ws.on('message', (buf) => {
    const msg = JSON.parse(buf.toString());
    if (live) processMessage(msg);
    else buffer.push(msg);
  });

  ws.on('close', async (code, reason) => {
    console.log(`user feed closed: ${code} ${reason} - reconnecting`);
    await openTask.catch(() => {});
    setTimeout(connect, 1000);
  });

  ws.on('error', (e) => console.error('user feed error:', e.message));
}

connect();

​Messages

​Common envelope

​The matched block

​The unmatched block

​How to identify the action

​Side and market semantics by bet type

​Action: order placed

​Action: order cancelled

​Action: order matched (taker)

​Action: order matched (maker, partial fill)

​Action: order matched (moneyline1x2)

​Replaying missed messages

​Endpoint

​Response: success

​Response: cache_expired

​Example: reconnecting client with replay

Messages

Common envelope

The `matched` block

The `unmatched` block

How to identify the action

Side and market semantics by bet type

Action: order placed

Action: order cancelled

Action: order matched (taker)

Action: order matched (maker, partial fill)

Action: order matched (moneyline1x2)

Replaying missed messages

Endpoint

Response: `success`

Response: `cache_expired`

Example: reconnecting client with replay