Skip to main content

API for developers

How to issue an API key and pull SpreadFighter data into your own programs: REST with the X-API-KEY header, NATS streams over websocket, subjects by plan, and limits. Keys are available on Pro and Max.

What it is​

The data you see on the dashboard — screeners, indicators, the order book, funding, exchange streams — can be pulled into your own programs: a bot, a spreadsheet, your own server. You need an API key for that. The same key works for both REST and NATS streams.

The full documentation is on the API access page in the app. It opens after you sign in and has the sections Start, REST, NATS, Subjects & plans and Limits. This article is a short overview; look up the lists of endpoints and subjects there: they come from the server and are always current.

Plans​

PlanAPI
FreeNo: you cannot issue a key
ProYes: REST and the NATS subjects of your plan
MaxYes: REST and the NATS subjects of your plan

The plan is checked every time the key is used, not only when it is issued. If your subscription ends or your plan drops to Free, the key stops working by itself; you do not need to revoke it. A plan change reaches key verification within about a minute.

How to get a key​

  1. Open your profile: avatar in the top right corner → Profile.
  2. Find the API keys card.
  3. Enter a key name, for example "bot on my server", and click Issue key.
  4. Copy the key with the Copy button and click I saved it.
warning

The full key is shown once, at issue time. We store only its hash, so the key cannot be recovered. If you lose it, issue a new one and revoke the old one.

A key looks like this: sf_live_<user id>_<key id>_<secret>.

The key list shows the name, key id, creation date, last use and status: active, revoked or expired. Revoke a key you no longer need with the Revoke button. The How to connect link in the card leads to the documentation page.

REST​

REST is for on-demand requests: history, snapshots, reference data. The key goes only in the X-API-KEY header. It is not accepted as a URL parameter or in the request body — that keeps it out of proxy logs and browser history.

curl -H "X-API-KEY: sf_live_..." \
  "https://core-api.hel1.prod.hz.spreadfighter.cloud/api/hftActivities?symbol=BTCUSDT&timeFrame=1m&limit=10"
HostData
https://core-api.hel1.prod.hz.spreadfighter.cloudSignals, indicators, screeners
https://depth-api.hel1.prod.hz.spreadfighter.cloudOrder book
https://funding-api.hel1.prod.hz.spreadfighter.cloudFunding

The full list of endpoints with parameters is in the signals service Swagger. The other two services have no Swagger.

NATS​

NATS carries real-time streaming data. You connect over websocket to wss://nats-ws.hel1.prod.hz.spreadfighter.cloud and pass the same key as a token. Your client library must support token auth: in @nats-io/nats-core that is the token field, in nats.go the nats.Token option.

import { wsconnect } from "@nats-io/nats-core";

const nc = await wsconnect({
  servers: ["wss://nats-ws.hel1.prod.hz.spreadfighter.cloud"],
  token: "sf_live_...",
});

const sub = nc.subscribe("sf.core.scripts.screener.marketPower.1m.all.dict");
for await (const m of sub) {
  console.log(m.json());
}

A Go example is on the documentation page.

Subjects​

Subject names follow this shape:

PatternWhat it is
sf.core.scripts.screener.<name>.>Screener calculations
binance.futures.<stream>.>Exchange streams
private.<your-uid>.>Your own events
  • The > sign covers the whole remainder of a subject, * covers exactly one segment.
  • Subscribing to a subject outside your plan is not an error: no data simply arrives.
  • You can publish only into your own namespace private.<your-uid>. Writing to shared streams is not permitted.

The Subjects & plans section of the documentation page shows which subjects each plan opens. The list comes from the server — from the same place that grants connection rights. Subjects your plan does not include are dimmed there.

Limits​

WhatLimit
KeysUp to 10 active keys per account. Revoked ones do not count
Key revocationTakes effect in about a minute: key verification is cached. If a key is compromised, assume it still works for up to a minute
Plan changeReaches key verification within about a minute
Slow NATS consumptionIf a subscriber falls behind, the server buffers up to 64 MB of data and drops the connection
NATS reconnectsFrequent connections by one user are limited: 12 per minute on average, up to 30 in a row

To stay within the consumption limit, subscribe narrowly rather than to everything, and avoid heavy work inside the message handler: queue messages and process them separately.