Connect market data, checkups, and signals to your systems

Quickstart

Create an API Key with only the scopes you need, then configure environment variables on a trusted server or in a local quantitative program. Never put the Key in source code, browser pages, logs, or a WS URL.

1. Set API_BASE to the API root of your actual deployment, without a trailing slash. This guide does not assume an online address for you.
2. Store FF_API_KEY in a secure environment variable or secret manager, and set ACCEPT_LANGUAGE to zh-CN, zh-TW, or en.
3. Call a minimal read-only endpoint and inspect the HTTP status, problem+json errors, and RateLimit response headers before expanding the integration.

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

Example responses illustrate JSON shapes, not live market data, performance, or returns. Assess production availability through your own deployment and health checks.

Authentication and API Key scopes

Open endpoints use Authorization: Bearer <API-Key>. Keys start with ffk_live_ or ffk_test_. The plaintext is shown once at creation; the platform stores only its hash and prefix. The Quant entitlement api.enabled is checked again on every authentication.

A Key can have a CIDR IP allowlist. Grant minimum scopes, keep environment-specific Keys separate, and revoke a Key when it is exposed or no longer used. Anonymous endpoints neither need nor should receive a Key.

Forged, expired, revoked, or IP-rejected credentials return 401/403. Insufficient scope returns 403 FORBIDDEN; losing the API entitlement returns 402 ENT_FEATURE_LOCKED. /v1/me/api-keys creation, listing, and revocation use the user session, not another API Key.

Cookie sessions, CSRF, and idempotency

Browser Cookie session writes use double-submit validation: X-CSRF-Token must match the ff_csrf Cookie. Obtain a CSRF token first, then send it to session write endpoints such as API Key creation. Login rotates the token, so always use the latest value.

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 and CSRF_TOKEN are local placeholders. Requests authorized with an API Key generally skip CSRF. The Cookie refresh-token flow is the documented exception; do not generalize that exception to every Bearer request.

Idempotent writes

Designated writes such as orders, payments, subscription changes, and withdrawals require a client-generated UUID in Idempotency-Key. A scope and Key pair is retained for 24 hours: replaying the same request returns the first response. Never reuse a Key with a different body.

Idempotency-Key: ${IDEMPOTENCY_KEY}

The same Key with a different request returns 422 IDEMPOTENCY_KEY_REUSED. If the first request is still running, the response is 409 IDEMPOTENCY_IN_PROGRESS. Send the header only to endpoints that explicitly require it; do not turn read-only calls into writes.

REST errors: application/problem+json

Success responses return a resource or list directly, without a {code,data} wrapper. Errors follow RFC 9457. Clients should inspect both HTTP status and the stable code. title and detail may be localized through Accept-Language and must not drive program logic.

{
  "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" }
}

For 422 VALIDATION_FAILED, meta.errors is an array of {field,code,message}. Use request_id when contacting support. Errors deliberately omit SQL, stack traces, raw third-party responses, and secrets.

Rate limits, pagination, time, and amounts

Rate limits

API Key REST calls use a 60-second api.rate_per_min token bucket keyed by the Key, so changing IP does not change the bucket. Anonymous public endpoints have separate IP buckets with potentially different limits. Charged requests may return RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset after either success or a business error; 429 also includes Retry-After.

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

Cursor pagination

For regular lists, limit defaults to 20 and has a maximum of 100. When next_cursor is non-null, pass it back unchanged as cursor. Cursors are opaque: do not decode or construct them. Radar and predictions have their own schema limits, and short lists or CSV responses are not necessarily paginated.

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

Time, amounts, and numbers

Time input and output use ISO 8601 UTC, with Z on output. CSV windows are [from,to) and can span at most 31 days. JSON fields use snake_case. Missing values remain null and are never replaced with zero.

Per-coin checkups

The anonymous quick check returns six fields. It requires no login, consumes no full-checkup quota, and writes no archive. A separate IP limit may apply. sentence is generated in the requested language.

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"
}

The JSON above is a shape example, not BTC's current grade or stage. Use the actual response's as_of and stale values to communicate freshness.

Checkup archives and full checks

A Key with read:checkup can access only its user's reports: read an archive by report_id; get the coin's latest archive through GET /v1/public/checkups/{symbol}/latest; or run a full check through GET /v1/public/checkups/{symbol}?depth=full. pro=true requests professional fields; backend entitlements and content still determine visibility. locked, sections, and pro cannot be unlocked by the client.

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}"

Per-coin prediction mirror

Anonymous and session predictions live at /v1/coins/{symbol}/predictions; API Key predictions live at /v1/public/coins/{symbol}/predictions and require read:market. For both, limit defaults to 50 with a maximum of 200, and viewer entitlements determine delay. Pass a non-null next_cursor back unchanged as 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
}

Prediction items[] fields

The response card's OpenAPI is authoritative for the items element type. The table above reflects the platform market service's actual serialization. Prediction statuses are open, hit, failed, expired, and corrupt. Missing targets and results remain null. This is a prediction mirror, not a promise of returns.

Market data, signals, proofs, and CSV

These cards expand the real OpenAPI contracts directly. public in a path does not mean anonymous: check each endpoint's authentication row. When internal keys of free-form objects such as state, venues, and meta are not fixed by the schema, this page does not invent a field table for them.

Historical state and signal CSV exports

Both CSV endpoints require export:data and data.export=full. A window can span at most 31 days and a file at most 100,000 data rows. Larger exports return 422 rather than silently truncating. Responses are text/csv with private, no-store and are suitable for streaming to storage.

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

The market CSV header order above was checked against backend STATE_COLUMNS. Nested objects are compact JSON in cells, and spreadsheet formula prefixes in text are escaped. Empty cells mean missing data and must not be filled with zero. Signal CSV uses backend SIGNAL_COLUMNS and is exported through /v1/public/signals/export.csv.

Webhook endpoints, signatures, and retries

Webhook management uses webhooks:manage, not a Cookie session. The secret in the creation response appears only once; store it immediately in a secret manager. Endpoints must be allowed public HTTPS URLs and cannot contain usernames or passwords.

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>"
}

Verify signatures

Do not add newlines, reorder, or reserialize the raw request body. The primary signed material is id.timestamp.body. Compute HMAC-SHA256 with the endpoint secret and use constant-time comparison with v1=<hex> in FF-Webhook-Signature. The timestamp window is five minutes. X-FF-Signature signs only the raw body for compatibility; new integrations should prioritize the primary signature.

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)

The example reads its secret from FF_WEBHOOK_SECRET and contains no real secret. Production code should also reject missing or malformed headers, cap raw body size, and parse JSON only after verification succeeds.

Delivery and retries

Only a 2xx receiver response counts as success. After the initial failure, retries occur after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 24 hours: seven attempts in total. The delivery is then marked failed. An endpoint with no success for three consecutive days is disabled and its owner is notified.

Deduplicate on FF-Webhook-Id and event id, and make receivers idempotent. The same event succeeds at most once per endpoint. Only events that occur after endpoint creation are delivered. Read delivery states through GET /v1/me/webhooks/{endpoint_id}/deliveries and revoke an endpoint with DELETE /v1/me/webhooks/{endpoint_id}.

WebSocket connections and subscriptions

Realtime streams use Centrifugo. First exchange the API Key over HTTP for a 600-second connection JWT, then obtain a 600-second subscription JWT for each private channel. Finally connect to the Centrifugo WebSocket address supplied by your deployment. The long-lived API Key appears only in the HTTP Authorization header.

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);
});

Each Key can hold at most 10 unexpired connection-token leases; subscription tokens do not consume these leases. Obtain a new connection token after the old connection expires rather than rotating early. This is an issuance-side lease limit, not a count of real online connections.

The example reuses the repository's @ff/realtime package and runs on a trusted server or local program. A revoked Key cannot obtain new tokens. Already-issued JWTs are stateless and can live until their original exp (600 seconds), so immediate disconnection is not guaranteed. user:* and admin:* channels are not available to API Keys.

Current open endpoint directory

This table enumerates real OpenAPI operations under /v1/public at build time. The specification is authoritative for operationIds, methods, and paths. New public endpoints enter the directory when the shared specification is regenerated; authentication metadata still needs review against backend routes.

Related management and session endpoints

API Key management, predictions, and Webhooks are not all under /v1/public, so they are listed separately to preserve their actual paths.

Admin, internal ingest, node control-plane, and management endpoints omitted here are not open APIs. Inclusion in this directory does not mean an external production hostname has passed acceptance or is reachable from your network.