概念與架構總覽

本站面向廠商——也就是在 Moose 遊戲平台運營商頁面裡運行遊戲的遊戲工作室。除了必要的背景知識之外，本站不涵蓋運營商那一側的內容（啟動 session、嵌入 iframe、shell 端的橋接邏輯）。

三個訊息方向

你的接入會涉及三條互相獨立的通道。它們很容易被混為一談，因為都是在「你這一側」和「平台」之間搬動資料，但呼叫方、傳輸方式和信任模型各不相同：

方向	傳輸方式	由誰簽名	範例
廠商 → 平台	簽名 HTTP，由你發起呼叫	你	`verifySession`、`submitTransaction`、`getBalance`
平台 → 廠商	簽名 HTTP，由平台發起呼叫	你（負責驗證）	Session 撤銷、免費旋轉發放/查詢/取消
遊戲 → shell	瀏覽器 `postMessage`，單向	無（透過信封標記與 origin 檢查建立同源信任）	`GameBridge` 的生命週期事件

前兩者用的是同一套 HMAC 機制，只是方向相反——見簽名與鑑權。第三者則完全與簽名無關：這是同一個瀏覽器裡，你的 iframe 和運營商嵌入頁面之間的訊息傳遞，靠 origin 比對和信封標記驗證，而不是密碼學簽名。

@moosehq/provider-sdk 執行在你的後端（RGS，遠端遊戲伺服器）。它負責簽名並發出廠商 → 平台的呼叫，也負責驗證平台 → 廠商的呼叫。你的 HMAC 金鑰只存在這裡，也只應該存在這裡。
@moosehq/game-client-sdk 執行在瀏覽器裡，也就是運營商嵌入的 iframe 內部。它負責把你遊戲的生命週期上報給 shell，並收集用於機器人偵測的數據。它永遠看不到你的金鑰——依設計，它根本沒有簽名任何東西的能力。

如果本頁只記住一條規則：金鑰永遠不會離開你的後端。 接下來的每一頁都建立在這個前提上。

以下規則貫穿本站每一個端點、每一頁內容——在深入各篇指南之前值得先內化：

金額永遠是該貨幣最小單位的整數（例如 USD 的分）——絕不用浮點數。100 代表 $1.00。currency 永遠是大寫的 3 字母 ISO-4217 代碼。
身份永遠不會從請求主體裡被信任。 你的廠商身份來自你的簽名；玩家身份來自他們的 session token。沒有任何一個你自己設定的 providerId 或 playerRef 欄位是平台單純相信的。
冪等性永遠以你自己生成的 ID 為鍵：錢包呼叫用 transactionId，免費旋轉用 requestRef/externalRef。同一次邏輯嘗試的重試要複用相同的 ID——SDK 自身的重試已經會自動這樣做。
WIN 是獨立於 BET 的另一筆交易，不是同一個請求裡的一個欄位。兩者之中結束該局的那一筆要帶上 roundComplete: true。

完整的欄位層級參考見資料模型與列舉。