把行情、體檢與信號接入你的系統

快速開始

先建立一組只含所需 scope 的 API Key，再在受信任的伺服器端或本地量化程式中設定環境變數。不要把 Key 寫進原始碼、瀏覽器頁面、日誌或 WS URL。

1. 將 API_BASE 設為實際部署的 API 根位址，不含末尾斜線；本頁不替你假定線上位址。
2. 把 FF_API_KEY 放入安全的環境變數或密鑰管理器；把 ACCEPT_LANGUAGE 設為 zh-CN、zh-TW 或 en。
3. 呼叫一個最小唯讀端點，檢查 HTTP 狀態、problem+json 錯誤與 RateLimit 回應標頭，再擴大整合範圍。

curl --fail-with-body "${API_BASE}/v1/public/coins/BTCUSDT" \
  -H "Authorization: Bearer ${FF_API_KEY}" \
  -H "Accept-Language: ${ACCEPT_LANGUAGE}"

範例回應只說明 JSON 結構，不是即時行情、成績或收益聲明。生產可用性請以你自己的部署與健康檢查為準。

認證與 API Key scope

開放介面使用 Authorization: Bearer <API-Key>。Key 格式前綴為 ffk_live_ 或 ffk_test_，建立明文只顯示一次，平台只保存雜湊與前綴。量化版權限 api.enabled 會在每次認證時重新檢查。

可以為 Key 設定 CIDR IP 白名單。請按最小權限分配 scope、分開保存不同環境的 Key，並在洩露或不再使用時撤銷。匿名端點不需要也不應附帶 Key。

偽造、過期、撤銷或 IP 越界回傳 401/403；scope 不足回傳 403 FORBIDDEN；目前方案不再允許 API 時回傳 402 ENT_FEATURE_LOCKED。建立、列表與撤銷 Key 的 /v1/me/api-keys 使用使用者工作階段，不使用另一把 API Key。

Cookie 工作階段、CSRF 與冪等

瀏覽器 Cookie 工作階段的寫請求採用雙提交驗證：X-CSRF-Token 必須與 ff_csrf Cookie 一致。先取得 CSRF，再在建立 API Key 等工作階段寫介面中發送；登入後令牌會輪換，應使用最新值。

curl --cookie-jar cookies.txt "${API_BASE}/v1/auth/csrf"

curl --request POST "${API_BASE}/v1/me/api-keys" \
  --cookie cookies.txt --cookie-jar cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: ${CSRF_TOKEN}" \
  --data '{"name":"local-bot","scopes":["read:market"],"ip_allowlist":[]}'

範例中的 cookies.txt 與 CSRF_TOKEN 都是本地佔位。帶 Authorization 的 API Key 請求一般不驗證 CSRF；Cookie 重新整理令牌流程是文件所述的例外，不能把例外推廣到所有 Bearer 請求。

冪等寫請求

訂單、支付、訂閱變更、提現等指定寫介面要求用戶端產生 UUID 作為 Idempotency-Key。同一 scope 與 Key 保留 24 小時：相同請求重放回傳首次回應，不要把冪等鍵複用到不同請求本文。

Idempotency-Key: ${IDEMPOTENCY_KEY}

同鍵不同請求回傳 422 IDEMPOTENCY_KEY_REUSED；首次請求仍在處理時回傳 409 IDEMPOTENCY_IN_PROGRESS。只有明確要求冪等鍵的端點才需要發送，不要把所有唯讀請求都包裝成寫操作。

REST 錯誤：application/problem+json

成功回應直接回傳資源或列表，不包 {code,data} 外殼。錯誤遵循 RFC 9457，用戶端應同時檢查 HTTP 狀態與穩定 code；title 和 detail 可按 Accept-Language 本地化，不應作為程式分支依據。

{
  "type": "<api-base>/errors/RATE_LIMITED",
  "title": "<localized-title>",
  "status": 429,
  "code": "RATE_LIMITED",
  "detail": "<localized-detail>",
  "instance": "/v1/public/coins/BTCUSDT",
  "request_id": "<request-id>",
  "meta": { "bucket": "api_key" }
}

422 VALIDATION_FAILED 的 meta.errors 是 [{field,code,message}] 陣列。request_id 用於支援排查；錯誤不會故意回顯 SQL、堆疊、第三方原始回應或密鑰。

限流、分頁、時間與金額

限流

API Key REST 請求按 Key 使用 api.rate_per_min 的 60 秒令牌桶，換 IP 不會換桶。匿名公開端點使用各自 IP 桶，具體上限可以不同。已扣額請求無論成功或業務失敗都可能回傳 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset；429 另帶 Retry-After。

RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Retry-After

游標分頁

一般列表 limit 預設 20、最大 100，next_cursor 非空時原樣作為下一次 cursor；游標是不透明字串，不要解碼或自行構造。榜單與預測等端點使用規範中各自的上限，短列表和 CSV 不一定分頁。

{
  "items": [],
  "next_cursor": "<opaque-cursor-or-null>"
}

時間、金額與數值

時間輸入輸出使用 ISO 8601 UTC，輸出帶 Z；CSV 時間窗為 [from,to)，最長 31 天。JSON 欄位使用 snake_case，空值保持 null，不把缺資料補成 0。

單幣體檢

匿名快檢回傳六個欄位，不登入、不扣全檢次數、不寫檔案。它可能有獨立 IP 限流；sentence 按請求語言產生。

curl --fail-with-body "${API_BASE}/v1/public/checkup/symbols/BTCUSDT" \
  -H "Accept-Language: ${ACCEPT_LANGUAGE}"

{
  "symbol": "BTCUSDT",
  "grade": "B",
  "stage": "accumulation",
  "sentence": "<localized-summary>",
  "stale": false,
  "as_of": "2026-10-28T00:00:00Z"
}

以上 JSON 是結構範例，不代表 BTC 目前等級或階段。用戶端應使用實際回應的 as_of 與 stale 展示資料新鮮度。

體檢檔案與全檢

帶 read:checkup 的 Key 只能存取所屬使用者的報告：按 report_id 讀取檔案；GET /v1/public/checkups/{symbol}/latest 讀取該幣最新檔案；GET /v1/public/checkups/{symbol}?depth=full 執行全檢。pro=true 請求專業欄位；可見性仍由後端權益與內容決定，locked、sections 和 pro 不會被前端解鎖。

curl --fail-with-body "${API_BASE}/v1/public/checkup/reports/${REPORT_ID}?pro=false" \
  -H "Authorization: Bearer ${FF_API_KEY}" \
  -H "Accept-Language: ${ACCEPT_LANGUAGE}"

curl --fail-with-body "${API_BASE}/v1/public/checkups/BTCUSDT?depth=full&pro=false" \
  -H "Authorization: Bearer ${FF_API_KEY}" \
  -H "Accept-Language: ${ACCEPT_LANGUAGE}"

單幣預測鏡像

匿名與工作階段預測鏡像位於 /v1/coins/{symbol}/predictions；API Key 開放預測位於 /v1/public/coins/{symbol}/predictions，要求 read:market。兩者 limit 預設 50、最大 200，並按各自訪問者權益套用延遲；next_cursor 非空時原樣傳回 cursor。

curl --fail-with-body "${API_BASE}/v1/coins/BTCUSDT/predictions?limit=50"

curl --fail-with-body "${API_BASE}/v1/public/coins/BTCUSDT/predictions?limit=50" \
  -H "Authorization: Bearer ${FF_API_KEY}"

{
  "items": [
    {
      "prediction_id": "<prediction-id>",
      "symbol": "BTCUSDT",
      "type": "near_edge",
      "direction": "long",
      "status": "open",
      "target_lo": 100.0,
      "target_hi": 120.0,
      "invalid_price": 90.0,
      "resolve_price": null,
      "opened_at": "2026-10-28T00:00:00Z",
      "deadline": "2026-10-29T00:00:00Z",
      "resolved_at": null,
      "era": "5"
    }
  ],
  "next_cursor": null,
  "as_of": null,
  "delayed_minutes": 15
}

預測 items[] 欄位

items 的元素類型以回應卡片中的 OpenAPI 為準；上表欄位按平台 market service 的實際序列化核對。預測狀態包括 open、hit、failed、expired、corrupt；空目標或結果保持 null。這裡是預測鏡像，不是收益承諾。

行情、信號、存證與 CSV

以下卡片直接展開真實 OpenAPI 契約。公開路徑中的 public 不等於匿名：請逐端點檢查認證行。狀態物件 state、venues、meta 等自由物件的內部鍵未由規範固定時，頁面不會另造欄位表。

歷史狀態與信號 CSV 匯出

兩個 CSV 端點都要求 export:data 和 data.export=full，窗口最長 31 天、單檔最多 100,000 筆資料列；超出時回傳 422，而不是靜默截斷。回應為 text/csv、private, no-store，適合串流保存。

curl --fail-with-body --get "${API_BASE}/v1/public/market/export/states.csv" \
  -H "Authorization: Bearer ${FF_API_KEY}" \
  --data-urlencode "symbol=BTCUSDT" \
  --data-urlencode "from=2026-10-01T00:00:00Z" \
  --data-urlencode "to=2026-10-28T00:00:00Z" \
  --output market-states.csv

symbol, recorded_at, source, hour_at, stage, raw_stage, cluster, dump_score, ev_score, p_rally_ratio, chg24_pct, last_price, vol24_quote, vol_z, dist_ath_pct, funding_bps, oi_chg_24h_pct, impact_pct, level, delisted, primary_venue, summary_plain, low_revisit

以上是從後端 STATE_COLUMNS 核對的市場 CSV 表頭順序。嵌套物件以緊湊 JSON 放在儲存格中；文字公式前綴會被轉義。空儲存格表示缺資料，不應補零。信號 CSV 使用後端 SIGNAL_COLUMNS，並透過 /v1/public/signals/export.csv 匯出。

Webhook 端點、簽名與重試

Webhook 管理使用 webhooks:manage，不是 Cookie 工作階段。建立回應中的 secret 只出現一次，請立即存入密鑰管理器；端點必須是允許的公網 HTTPS 位址，不能帶帳號口令。

curl --request POST "${API_BASE}/v1/me/webhooks" \
  -H "Authorization: Bearer ${FF_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"url":"<public-https-webhook-url>"}'

{
  "id": "<endpoint-uuid>",
  "url": "<public-https-webhook-url>",
  "status": "active",
  "created_at": "2026-10-28T00:00:00Z",
  "secret": "<shown-once-store-securely>"
}

驗證簽名

對原始請求本文不做換行、重排或 JSON 再序列化。主簽名材料為 id.timestamp.body，使用 endpoint secret 做 HMAC-SHA256，並與 FF-Webhook-Signature 的 v1=<hex> 常數時間比較；時間戳允許 5 分鐘窗口。X-FF-Signature 是只簽原始 body 的相容標頭，新整合優先驗證主簽名。

FF-Webhook-Id · FF-Webhook-Timestamp · FF-Webhook-Signature: v1=<hex> · X-FF-Signature: sha256=<hex>

import hashlib
import hmac
import os
import time

def verify_webhook(headers, raw_body: bytes) -> bool:
    delivery_id = headers["FF-Webhook-Id"]
    timestamp = headers["FF-Webhook-Timestamp"]
    signature = headers["FF-Webhook-Signature"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    material = delivery_id.encode() + b"." + timestamp.encode() + b"." + raw_body
    expected = hmac.new(
        os.environ["FF_WEBHOOK_SECRET"].encode(), material, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, "v1=" + expected)

範例從 FF_WEBHOOK_SECRET 讀取密鑰，不含真實 secret。生產程式碼還應拒絕缺失或畸形標頭、限制原始請求本文大小，並在驗證通過後再解析 JSON。

投遞與重試

接收方回傳 2xx 才算成功。首次失敗後按 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時、24 小時重試，共 7 次嘗試；之後該投遞標記 failed。端點連續 3 天沒有一次成功會自動停用並通知主人。

按 FF-Webhook-Id 與事件 id 去重，接收處理必須冪等；同一事件對同一端點只成功一次。只投遞端點建立之後發生的事件。可透過 GET /v1/me/webhooks/{endpoint_id}/deliveries 讀取投遞狀態，DELETE /v1/me/webhooks/{endpoint_id} 撤銷端點。

WebSocket 連線與訂閱

即時流使用 Centrifugo。先用 API Key 透過 HTTP 換 600 秒連線 JWT，再為私有頻道逐個換 600 秒訂閱 JWT；最後連線部署提供的 Centrifugo WebSocket 位址。長期 API Key 只出現在 HTTP Authorization 標頭。

curl --request POST "${API_BASE}/v1/public/realtime/token" \
  -H "Authorization: Bearer ${FF_API_KEY}"

curl --get "${API_BASE}/v1/public/realtime/subscribe-token" \
  -H "Authorization: Bearer ${FF_API_KEY}" \
  --data-urlencode "channel=live:coin.BTCUSDT"

{
  "token": "<short-lived-jwt>",
  "expires_in": 600,
  "allowed_channels": ["live:*"],
  "channel": "live:coin.BTCUSDT"
}

import { createApiKeyTokenSource, RealtimeClient } from "@ff/realtime";

const tokens = createApiKeyTokenSource({
  apiBaseUrl: process.env.API_BASE!,
  apiKey: process.env.FF_API_KEY!,
});
// API Key 自动使用 connect.data.token / subscribe.data.token；
// 普通用户 JWT 才使用原生 getToken / getSubscribeToken。
const client = new RealtimeClient({
  url: process.env.FF_REALTIME_URL!,
  ...tokens,
});
const stop = client.listen("live:coin.BTCUSDT", (ctx) => {
  console.log(ctx.data);
});

每個 Key 最多持有 10 個未過期連線令牌租約，訂閱令牌不佔此租約。舊連線到期後再取新連線令牌，不要提前反覆換票；這是簽發側租約限制，不等於真實線上連線數。

範例複用儲存庫現有 @ff/realtime，在受信任的伺服器端或本地程式執行。Key 撤銷後不能換發新令牌；已簽 JWT 是無狀態憑證，最長可存活到原 exp（600 秒），不保證即時離線。user:* 與 admin:* 不對 API Key 開放。

目前開放端點目錄

下表在建置時列舉 /v1/public 的真實 OpenAPI operations；operationId、方法和路徑以規範為準。新增公開端點隨共享規範產生後進入目錄，認證中繼資料仍需與後端路由一起核對。

相關管理與工作階段端點

API Key 管理、預測與 Webhook 不完全位於 /v1/public，單獨列出以免遺漏或誤改路徑。

未在此列出的後台、內部 ingest、節點控制面和管理端介面不是開放 API。目錄存在不代表外部生產網域已驗收或對你的網路可達。