把行情、体检与信号接入你的系统

快速开始

先创建一个只含所需 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 与 Idempotency

浏览器 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。目录存在不代表外部生产域名已验收或对你的网络可达。