錢包 API 參考

@moosehq/provider-sdk 的 ProviderClient 已經封裝了下面這四個介面——大多數廠商應該直接用它，而不是自己調 HTTP API。所有介面都需要有效的廠商簽名，並按租戶限流。介面自身返回的錯誤都是同樣的結構：{ "error": "<訊息>" }；但因簽名缺失/無效/過期導致的 401，響應體是純文字（invalid signature），不是 JSON——這項校驗在請求到達介面本身之前就發生了。下面每個介面共用的完整狀態碼參考見錯誤碼與重試。

超出你的租戶限流額度時會返回 429，帶 Retry-After 響應頭（需等待的秒數）和響應體 { "error": "rate limit exceeded" }。

POST /v1/wallet/session/verify

請求：

{ "sessionToken": "..." }

響應結構：見 SDK 參考文件裡的 VerifySessionResponse。

錯誤響應：400（sessionToken 缺失或為空）、401（未能解析出廠商身份——簽名缺失或無效；或 session token 無效或已過期）、403（該 session 屬於另一個廠商）、429（超出限流）、500（Central Config 解析失敗）。

POST /v1/wallet/transaction

需要一個 session token——來自運營商啟動呼叫建立的 session，這個介面會在伺服端解析它（線上格式裡沒有單獨的 operatorId 欄位）。提交一筆標準的 BET / WIN / ROLLBACK 交易。ADJUSTMENT 在這個介面上會被拒絕——那是僅限 admin 的操作。

狀態碼含義：

• 400 —— 請求無效（校驗失敗，例如 currency 格式錯誤），或請求與其引用的 session 不符（playerRef/gameId/currency 不一致）
• 401 —— 未能解析出廠商身份（簽名缺失或無效），或 session token 無效或已過期
• 403 —— 該 session 屬於和本次請求簽名者不同的廠商
• 409 —— 同一個 transactionId 已有請求在處理中，先不要重試
• 429 —— 超出限流
• 503 —— 遊戲/運營商未配置
• 500 —— 平台側可重試的失敗（包含判定為 TIMED_OUT 的情況）

200 且 status: "DECLINED" 是正常的業務結果，不是錯誤。

請求/響應結構：見 SDK 參考文件裡的 TransactionRequest / TransactionResponse，即完整的線上資料格式。currency 必須是 3 個字母、大寫的 ISO-4217 代碼（例如 "USD"，不是 "usd"）——格式錯誤會被 400 拒絕。

POST /v1/wallet/balance

按需查詢玩家目前餘額，不會移動任何資金。只需要一個 session token——playerRef 會在伺服端從 session 解析出來，因此廠商永遠無法查詢自己不擁有的 session 底下玩家的餘額。運營商的錢包仍然是唯一的權威來源：這只是一次透傳查詢，不是快取值或平台計算出的值。

請求：

{ "sessionToken": "..." }

響應：

{ "balance": 4200 }

balance 使用最小貨幣單位（例如分），與 TransactionResponse.balance 一致。

對於 DEMO session，這裡返回的是記憶體中的試玩餘額，而不是查詢真實運營商。

狀態碼含義：

• 400 —— sessionToken 缺失或為空
• 401 —— 未能解析出廠商身份（簽名缺失或無效），或 session token 無效或已過期
• 403 —— 該 session 屬於和本次請求簽名者不同的廠商
• 429 —— 超出限流
• 503 —— 運營商未配置
• 500 —— 運營商的餘額介面出錯或逾時

和 POST /v1/wallet/transaction 不同，這個呼叫不做冪等追蹤，平台也不會替你重試（除了 ProviderClient.getBalance 在客戶端做的重試）——因為這是一次讀取操作，失敗了直接重試即可。

機器人偵測遙測不在這套 API 裡

這裡沒有 POST /v1/client/behavior——機器人偵測摘要是由遊戲端瀏覽器直接送到另一個獨立的行為採集端點，用 session token 鑑權，而不是廠商簽名（瀏覽器沒辦法保存你的 HMAC 金鑰）。見 BehaviorReporter 和行為採集端點。