User feed - 4casters API

用户推送投递你账户范围内的更新（订单、成交、取消）。

// 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(); 

消息

用户推送将每条更新作为裸 JSON 对象发送（无元组包装）。所有更新共用同一结构；动作由 unmatched / matched 哪个被填充以及 origin 决定。

通用结构

{
  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 是 streaming-api 在发送前添加的流条目 id。请持久化你已处理的最新一条 — 它就是你的回放游标。参见下方回放错过的消息。

`matched` 块

只要更新表示一笔成交（matched != null），就会出现该块。除非标明为有条件，下列每个字段都会在每笔成交上发送。所有取值都从你的视角出发 — 作为 taker 你看到自己吃到的方向，作为 maker 你看到自己挂出的方向。

字段	类型	是否下发	含义
`txID`	string	始终	该注单的 id。用它做成交去重 — 与获取已撮合投注返回的 `txID` 相同。
`orderID`	string	始终	该成交来自的订单 id。作为 maker，是你的挂单；作为 taker，是你吃到的订单。
`wagerRequestID`	string	始终	该成交背后的下单请求 id。作为 taker，是你自己的请求；作为 maker，是最初挂出你订单的请求。
`amount`	number	始终	不含佣金的本金。在 maker 成交上等于 `risk`，但在 taker 成交上不等于 — 见下文。
`risk`	number	始终	你在该笔成交上可能亏损的金额。作为 taker，包含亏损时收取的佣金；作为 maker，不适用佣金。
`win`	number	始终	你在该笔成交上可能赢得的金额。作为 taker，已扣除获胜时收取的佣金；作为 maker，不适用佣金。
`odds`	integer	始终	该成交中你这一侧的美式赔率。
`type`	string	始终	`moneyline`、`spread`、`total` 或 `moneyline1x2`。
`side`	string	始终	参见按投注类型区分的 side 与 market 语义。
`number`	number	有条件	让分或大小球盘口。在 `moneyline` 和 `moneyline1x2` 上完全省略。
`market`	string	有条件	仅 `moneyline1x2`。
`userReference`	string \| null	始终	回显你在订单上发送的 `userReference`。未发送则为 `null`。
`isPostArb`	boolean	有条件	`postArb` 订单的成交上为 `true`；否则省略。

不要用 risk 推导 win。 risk 和 win 各自从未经四舍五入的本金独立保留到 2 位小数，因此 risk x odds 可能与 win 相差一分钱。请按下发的 win 入账；若该字段缺失，应将消息视为格式错误，而不是自行重建。不要把 amount 当作 risk 的同义词。 在 taker 成交上，amount 不含亏损时收取的佣金，而 risk 包含它。把 amount 当作风险金额入账，会在每次吃单时少计佣金。

REST 上的相同数量（获取已撮合投注）以保留 2 位小数的字符串而非数字给出，且佣金与舍入顺序略有不同。对账时请允许一分钱的容差，不要要求精确相等。

`unmatched` 块

只要更新涉及留在（或离开）订单簿的订单 — 下单、取消，以及成交的 maker 一侧 — 就会出现该块。赔率和方向来自 maker 视角，即你挂出的内容，而不是订单簿向他人展示的报价。

字段	类型	是否下发	含义
`orderID`	string	始终	订单 id。
`wagerRequestID`	string	始终	创建该订单的下单请求 id。
`filled`	number	始终	在成交上：仅本事件匹配到的风险，不是累计值。下单时为 `0`。取消时则为取消到达前已匹配的累计风险。
`offered`	number	始终	该订单挂出的总风险。`0` 标识取消。
`remaining`	number	始终	仍挂在订单簿上的风险。`0` 表示全部成交。
`odds`	integer	始终	该订单中你这一侧的美式赔率。
`type`	string	始终	`moneyline`、`spread`、`total` 或 `moneyline1x2`。
`side`	string	始终	参见按投注类型区分的 side 与 market 语义。
`number`	number	有条件	让分或大小球盘口。在 `moneyline` 和 `moneyline1x2` 上完全省略。
`market`	string	有条件	仅 `moneyline1x2`。
`userReference`	string	有条件	回显你发送的 `userReference`；订单未携带时省略。
`isPostArb`	boolean	有条件	`postArb` 订单为 `true`；否则省略。

filled 和 remaining 不是同一类数字。remaining 是运行时状态 — 此刻订单簿上还剩多少 — 但在成交上 filled 只描述该事件。跨多笔部分成交时它们不会相加：filled + remaining 在第一笔成交时等于 offered，之后会逐渐偏离。要跟踪一笔挂单已成交多少，请使用 offered - remaining，或自行累加 filled。不要把两者混用。

如何识别动作

unmatched.filled === 0 && unmatched.offered > 0 -> 已下单
unmatched.offered === 0 -> 已取消
matched != null && unmatched == null -> 作为 taker 成交
matched != null && unmatched != null -> 作为 maker 成交（若 unmatched.remaining > 0 则为部分成交）

以 orderType: "postArb" 下的订单，其更新还会在 matched / unmatched 内带有 isPostArb: true（下单、成交和取消更新均如此）；否则省略该字段。

按投注类型区分的 side 与 market 语义

matched / unmatched 内 side 的含义（以及会出现哪些额外字段）取决于 type：

`type`	`side`	`number`	`market`
`moneyline`	参赛者 ObjectID 十六进制	—	—
`spread`	参赛者 ObjectID 十六进制	让分盘口（例如 `6.5`）	—
`total`	`"over"` / `"under"`	大小球盘口（例如 `209.5`）	—
`moneyline1x2`	`"yes"` / `"no"`	—	参赛者 ObjectID 十六进制（主队或客队）或 `"draw"`

market 仅出现在 moneyline1x2 更新中：它指明该盘口所针对的三项结果（主队、客队或平局），side 则表示对该结果是 yes 还是 no。所有字段都从你的视角出发 — 作为 maker 你看到自己挂出的方向；作为 taker 你看到自己吃到的方向。

动作：已下单

一笔新挂单进入订单簿。unmatched.filled 为 0，unmatched.offered > 0，且 matched 为 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"
}

动作：已取消

用户（或系统代其）取消了一笔挂单。区分字段是 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"
}

动作：订单成交（taker）

用户吃掉了他人的挂单。unmatched 为 null，matched 携带成交，origin 为 "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"
}

动作：订单成交（maker，部分成交）

有人吃到了用户挂出的报价。matched 和 unmatched 均被填充；unmatched.remaining 显示订单簿上仍剩余的数量。因为设置了 unmatched，origin 为 "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"
}

动作：订单成交（moneyline1x2）

足球三项盘上的成交携带上文所述的 market + side 组合，而不是参赛者十六进制 side。此处用户以 +120 吃了主队的 “yes”（投注阿森纳获胜）：

{
  "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"
}

注意同一笔成交的两个视角：taker 看到同一 market 上 side: "yes"、赔率 +120，maker 看到 side: "no"、赔率 -120。

回放错过的消息

v2 用户推送支持连接中断后的缺口恢复。每条消息都带有 messageID（单调递增的流条目 id，例如 "1751552702114-0"）。若连接断开，你可以精确拉取错过的消息。

接口

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

鉴权方式与 WebSocket 相同：在 Authorization 请求头、Auth 请求头或 token 查询参数中携带 token。仅返回属于已鉴权用户的消息。

参数	是否必填	含义
`afterID`	是	断开前你处理的最后一条消息的 `messageID`。结果从严格晚于它的位置开始。
`beforeID`	否	不包含的上界。省略则读到保留历史的末尾。

响应：`success`

你的 afterID 仍在保留历史中，因此返回的列表是完整的缺口填充 — afterID 与 beforeID 之间没有任何丢失：

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

按顺序应用这些消息，然后继续处理实时消息。

响应：`cache_expired`

你的 afterID 已超出保留历史，因此服务器无法证明回放是完整的：

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

availableMessages 是仍被保留的内容，最旧的在前。超出保留窗口的更早消息无法通过回放恢复 — 请及时重连，而不要依赖过长的回看。

示例：带回放的重连客户端

完整的 Node.js 客户端（为简洁起见省略 keepalive ping/pong — 参见本页顶部的快速入门）。正确性依赖两点：每条消息 — 实时、缓冲或回放 — 都经过同一套只向前推进的游标检查；回放失败时重连，而不是带着缺口进入实时。

// 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();

​消息

​通用结构

​matched 块

​unmatched 块

​如何识别动作

​按投注类型区分的 side 与 market 语义

​动作：已下单

​动作：已取消

​动作：订单成交（taker）

​动作：订单成交（maker，部分成交）

​动作：订单成交（moneyline1x2）

​回放错过的消息

​接口

​响应：success

​响应：cache_expired

​示例：带回放的重连客户端

消息

通用结构

`matched` 块

`unmatched` 块

如何识别动作

按投注类型区分的 side 与 market 语义

动作：已下单

动作：已取消

动作：订单成交（taker）

动作：订单成交（maker，部分成交）

动作：订单成交（moneyline1x2）

回放错过的消息

接口

响应：`success`

响应：`cache_expired`

示例：带回放的重连客户端