認證 - 4casters API

**4casters 目前不發放 API 金鑰。**你使用在 4casters.io 登入時的同一組使用者名稱和密碼，對所有 4casters API 進行認證。無需在帳戶設定中申請、生成或複製任何東西。專用 API 金鑰已在路線圖中。發布時會在更新日誌中公告，本頁也會隨之更新。在此之前，你的登入就是憑證。

工作原理

透過 REST API 的 POST /user/login，使用帳戶的使用者名稱（或電子郵件）和密碼登入。
在回應中收到一個令牌。它是一個 256 個字元的十六進位字串。
在每個 REST 請求和每次 WebSocket 握手中傳送該令牌。三套 API 接受同一個令牌。

API 存取沒有單獨的註冊流程。只要能在網站上登入，就能使用 API。

const res = await fetch('https://api.4casters.io/user/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: process.env.FOURCASTERS_USERNAME,
    password: process.env.FOURCASTERS_PASSWORD,
  }),
});
const { data } = await res.json();
const token = data.user.auth;

import os, requests

res = requests.post(
    "https://api.4casters.io/user/login",
    json={
        "username": os.environ["FOURCASTERS_USERNAME"],
        "password": os.environ["FOURCASTERS_PASSWORD"],
    },
    headers={"User-Agent": "my-bot/1.0"},
)
token = res.json()["data"]["user"]["auth"]

username 欄位既可以填使用者名稱，也可以填帳戶的電子郵件。令牌位於回應主體的 data.user.auth。同一值也會被設為簽名的 auth Cookie；伺服器端整合應讀取 data.user.auth 並忽略該 Cookie。

{
  "data": {
    "user": {
      "id": "5fe37acbb5a23600123662c1",
      "username": "your_username",
      "auth": "5cd551d6...",
      "...": "..."
    }
  }
}

完整的回應結構見 REST 認證頁面。

只登入一次，然後重複使用令牌。登入按 IP 和按帳戶速率限制，且每次成功登入都會簽發一個新令牌。再次登入不會使你已持有的令牌失效。

傳送令牌

REST API
訂單 WebSocket
推送 WebSocket

在 Authorization 請求標頭中傳遞令牌。Bearer 前綴可選。

curl https://api.4casters.io/user/getMe \
  -H "Authorization: Bearer 5cd551d6..."

令牌缺失、未知或已過期時回傳 401，回應主體為 { "error": { "message": "InvalidCredentials", "code": 401 } }。

在握手的 Authorization 請求標頭中傳遞令牌。伺服器從令牌推導你的帳戶。

const ws = new WebSocket('wss://orders-api.4casters.io/orders/ws', {
  headers: { Authorization: token },
});

見訂單 API。

相同的請求標頭、相同的令牌，使用者推送和價格推送都適用。

const ws = new WebSocket('wss://streaming-api.4casters.io/v2/user', {
  headers: { Authorization: token },
});

見推送 API。

令牌有效期


有效期	自登入起 30 天。
30 天之後	下一個已認證的 REST 請求會就地輪換令牌：舊值立即失效，替換值在 `X-Auth-Token` 回應標頭中回傳。
登出	`POST /user/logout` 會使發起該呼叫所用的令牌失效。該帳戶的其他令牌不受影響。

對於長期執行的整合，請選擇以下做法之一：

**遇到任何 401 就重新登入。**最簡單也最穩健。把 401 當作「去獲取新令牌」，而不是致命錯誤。
**監聽 X-Auth-Token。**只要回應中出現該請求標頭，就持久化其值並從此使用它。

一個只登入一次、儲存令牌、從不檢視回應標頭的腳本，會恰好執行 30 天，然後每個請求都以 401 失敗。

雙重認證

4casters 的雙重認證保護的是提款，而不是登入。在帳戶上啟用它不會改變你對 API 的認證方式。POST /user/login 從不要求驗證碼。

狀態碼	含義	處理方式
`400`	請求主體缺少 `username` 或 `password`。	以 JSON 同時傳送兩者。
`401`	使用者名稱或密碼不正確。	檢查憑證。無論帳戶是否存在，訊息都相同。
`403`	帳戶已被封禁、關閉或凍結。	聯絡支援。
`428`	`CHALLENGE_REQUIRED`。僅在平台正在主動抵禦憑證填充攻擊時回傳；此時要求完成人機驗證。	繼續使用已持有的令牌，或稍後重試。腳本用戶端無法完成該驗證。
`429`	超出登入速率限制。	按 `Retry-After` 指定的秒數退避，並重複使用現有令牌而不是重新登入。

保護憑證安全

把使用者名稱和密碼存放在環境變數或金鑰管理器中，絕不要放進原始碼倉庫。
像對待密碼一樣對待令牌。持有它的任何人都能下單並讀取你的帳戶。
考慮為自動化交易使用專用帳戶，這樣洩露的機器人憑證不會危及你的主餘額。開設方式與任何使用者帳戶相同。

​工作原理

​ 登入

​ 傳送令牌

​令牌有效期

​雙重認證

​登入錯誤

​保護憑證安全

工作原理

登入

傳送令牌

令牌有效期

雙重認證

登入錯誤

保護憑證安全