> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4casters.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 簡介

> 4casters 點對點博彩交易所的公開 REST API

4casters REST API 讓你可以登入、查詢賽事和訂單簿、下單 / 改單 / 取消訂單，並以程式化方式讀取投注歷史。它與驅動 4casters Web 應用的是同一套 API。

<h2 id="base-url">
  基礎 URL
</h2>

本節中的所有端點均以以下地址為根：

```
https://api.4casters.io
```

<h2 id="conventions">
  約定
</h2>

* **傳輸**：僅 HTTPS。
* **編碼**：JSON。凡帶請求主體的請求均傳送 `Content-Type: application/json`。
* **回應結構**：除少數明確標註的例外（`/affiliate/getAffiliateCommission`、`/exchange/getOddsForAveragePrice`）外，每個成功回應都包裝為：`{ "data": <payload> }`。
* **識別符號**：賽事 ID、參賽方 ID 和訂單 ID 均為 MongoDB `ObjectID` 字串（24 位十六進位）。
* **賠率**：所有賠率均為美式格式（熱門為負，冷門為正），除非另有說明。
* **時間**：所有時間戳記均為帶 `Z` 的 ISO 8601（UTC）。

<h2 id="authentication">
  認證
</h2>

幾乎每個端點都需要認證。先透過 [POST `/user/login`](/zh-Hant/pages/rest/authentication) 登入一次，然後在每個請求中傳送回傳的認證令牌 — 詳情見 [認證](/zh-Hant/pages/rest/authentication)。

<h2 id="per-order-errors-vs-http-errors">
  單筆訂單錯誤與 HTTP 錯誤
</h2>

「下單」和「改單」端點接受批次並回傳按單結果。HTTP `200` 成功回應仍可能在 `data.createdSessions[i]` 中包含單筆訂單失敗。各端點頁面上有單筆訂單的錯誤形態。

HTTP 級別的錯誤（`4xx`、`5xx`）以 `{ "error": "<message>" }` 回傳。

<h2 id="rate-limiting">
  速率限制
</h2>

適用三層速率限制：

* **全域，按 IP** — 發往 API 的每個請求都計入每 IP 預算：**滾動 60 秒視窗內 3,000 次請求**（持續約每秒 50 次）。超出時回傳 `429`，帶 `Retry-After` 回應標頭（秒）以及回應主體 `{ "error": "Too many requests. Please try again later." }`。
* **認證路由**（`/user/login`、密碼重置、註冊）還有額外的按 IP 和按帳戶速率限制。
* **下單 / 改單 / 取消路由**還會按帳戶額外速率限制。

讀取端點沒有按帳戶限制 — 僅適用全域每 IP 上限。

<h2 id="timeouts">
  超時
</h2>

伺服器端耗時超過 **15 秒** 的請求會被中止，並回傳 `503`，回應主體為 `{ "error": { "message": "Network Error", "code": 503 } }`。

<h2 id="real-time-updates">
  即時更新
</h2>

REST API 可與 [WebSocket 推送 API](/zh-Hant/pages/streaming/introduction) 搭配，獲取即時訂單簿行情以及按帳戶的成交 / 結算事件。`/user/login` 回傳的認證令牌對兩者都有效。

<h2 id="endpoint-index">
  端點索引
</h2>

<CardGroup cols={2}>
  <Card title="認證" href="/zh-Hant/pages/rest/authentication">登入並獲取認證令牌。</Card>
  <Card title="使用者" href="/zh-Hant/pages/rest/user/get-me">帳戶資訊、餘額、投注和訂單。</Card>
  <Card title="訂單" href="/zh-Hant/pages/rest/orders/place-order">下單、改單、查詢和取消訂單。</Card>
  <Card title="市場" href="/zh-Hant/pages/rest/markets/get-orderbook">瀏覽聯賽、賽事、參賽方和訂單簿。</Card>
  <Card title="聯盟" href="/zh-Hant/pages/rest/affiliate/get-affiliate-commission">聯盟佣金。</Card>
</CardGroup>

<h2 id="legacy-postman-collection">
  舊版 Postman 集合
</h2>

先前的文件以 Postman 集合形式存在。它仍保留作參考，但這些 Mintlify 文件現為權威來源 — Postman 集合在新端點、參數或回應形態上可能滯後。

<Card title="4Casters API — Postman 集合" icon="link" href="https://documenter.getpostman.com/view/6710109/U16gNmHG">
  檢視舊版 Postman 文件
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.