SDK TypeScript

@fathom-charts/sdk gère pour vous l’authentification, le snapshot initial, la reprise après coupure, les doublons, la pagination de l’historique, les exports et les retries du rate limit. Cette page décrit toutes ses options et méthodes.

Installer

npm install @fathom-charts/sdk ws

• ESM uniquement : le package ne fournit pas de build CommonJS. Votre projet doit déclarer "type": "module" dans son package.json (ou utiliser des fichiers .mjs / .mts).
• Node 22 ou plus récent, et les navigateurs. exportNdjson() demande Node 22.15 ou plus récent (décompression zstd de node:zlib).
• ws n’est utile qu’en Node : il ouvre la connexion avec le header Authorization. Dans un navigateur, le SDK utilise le WebSocket natif avec un stream token, et n’importe jamais ws.

Le SDK importe ws dynamiquement, avec un nom de module dans une variable, pour que les bundlers navigateur ne l’embarquent pas. Webpack signale alors Critical dependency: the request of a dependency is an expression : cet avertissement est sans conséquence.

Types des indicateurs

Le SDK est générique : les données d’un indicateur sont typées par les types que vous générez depuis le catalogue (GET /v1/indicators, sans authentification).

curl https://api.fathomcharts.com/v1/indicators -o catalog.json
npx fathom-charts-types catalog.json src/fathom-charts-types.ts

Le fichier généré exporte, pour chaque indicateur, <Nom>Params et <Nom>Data (BigTradesData, FootprintData…), ainsi que IndicatorParams, IndicatorData et IndicatorId. Les descriptions du catalogue deviennent des commentaires JSDoc ; un niveau de footprint est typé [number, number, number, number?] (le 4e élément est facultatif). Le dossier de sortie est créé s’il n’existe pas. Régénérez le fichier quand le catalogue change (son engineFingerprint change avec le calcul).

Temps réel : FathomChartsStream

import { FathomChartsStream } from '@fathom-charts/sdk';
import type { BigTradesData } from './fathom-charts-types.js';

const stream = new FathomChartsStream({
  url: 'wss://stream.fathomcharts.com/v1',
  apiKey: process.env.FATHOM_CHARTS_API_KEY!,
  onStateChange: (state) => console.log('connexion', state),
});

const sub = stream.subscribe<BigTradesData>({
  instrument: 'NQ.front',
  indicator: 'big-trades',
  params: { minimum: 30 },
  mode: 'confirmed',
});

for await (const event of sub) {
  if (event.type === 'upsert') console.log(event.cursor, event.data.side, event.data.volume);
}

Options

subscribe()

stream.subscribe<D>(options) ouvre une subscription et renvoie un objet Subscription, à lire avec for await. Ses options sont celles du message subscribe : instrument, indicator, params ({} par défaut), mode (live par défaut) et from ("live" par défaut, { cursor } ou { time }). Le SDK choisit lui-même le nom sub. Le type D est celui des données de l’indicateur (BigTradesData…).

La boucle reçoit des events dont le champ type reprend le nom du message du serveur, sans le champ sub :

Les autres messages du serveur ne deviennent pas des events : le SDK traite lui-même les hb (détection d’une connexion muette, cursor de reprise), les pong et les notice (transmis à onNotice). Un error sur la subscription arrête la boucle : for await lève une FathomChartsError qui porte le code reçu (INVALID_PARAMETERS, UNKNOWN_INSTRUMENT, FORBIDDEN, QUOTA_EXCEEDED, NOT_COVERED…).

Le SDK ignore les doublons : après une reprise, aucun upsert ou remove dont le cursor n’est pas strictement supérieur au dernier reçu ne vous est remis.

Subscription

Sortir de la boucle (break, return ou une exception dans son corps) appelle close().

Cycle de vie de la connexion

Toutes les subscriptions d’un FathomChartsStream partagent une seule connexion, qui compte dans le nombre de connexions de votre offre :

• la connexion s’ouvre au premier subscribe() ;
• quand la dernière subscription se ferme (break, close(), ou un error du serveur sur la dernière subscription), le SDK ferme la connexion (close code 1000, raison idle) et connectionState passe à idle. Un nouveau subscribe() la rouvre ;
• stream.close() ferme toutes les subscriptions et la connexion. L’appeler juste après subscribe(), avant que la connexion soit ouverte, est sans risque. Un subscribe() après close() lève CLOSED ;
• connectionState vaut idle, connecting, open, reconnecting ou closed.

Après une coupure, le SDK se reconnecte avec un backoff exponentiel et du jitter, et renvoie chaque subscribe avec from: { cursor }, le dernier cursor reçu : vous recevez de nouveau subscribed et status, puis les messages manqués, sans snapshot si la reprise réussit, ou un reset suivi d’un snapshot sinon. Une subscription from: { time } qui a déjà reçu un cursor reprend à ce cursor : la période passée n’est jamais rejouée une seconde fois. Seule une coupure pendant warming, avant le premier cursor, la relance depuis le time d’origine, et la partie rejouée depuis l’historique est alors décomptée de nouveau.

Après une de ces erreurs définitives, un nouveau subscribe() sur le même FathomChartsStream lève la même erreur : corrigez la cause, puis créez un nouveau FathomChartsStream.

Reprendre après un redémarrage

Le SDK reprend seul après une coupure, tant que votre process tourne. Pour reprendre après un redémarrage de votre process, enregistrez sub.cursor au fil de l’eau (avec l’état que vous en avez tiré), puis rouvrez la subscription avec from: { cursor } :

import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { FathomChartsStream } from '@fathom-charts/sdk';
import type { BigTradesData } from './fathom-charts-types.js';

// Ici un fichier ; en production, le stockage de votre état (base de données…).
const CURSOR_FILE = 'big-trades.cursor';
const saved = existsSync(CURSOR_FILE) ? readFileSync(CURSOR_FILE, 'utf8') : undefined;

const stream = new FathomChartsStream({
  url: 'wss://stream.fathomcharts.com/v1',
  apiKey: process.env.FATHOM_CHARTS_API_KEY!,
});

const sub = stream.subscribe<BigTradesData>({
  instrument: 'NQ.front',
  indicator: 'big-trades',
  params: { minimum: 30 },
  mode: 'confirmed',
  from: saved ? { cursor: saved } : 'live',
});

for await (const event of sub) {
  if (event.type === 'upsert') console.log(event.data.side, event.data.volume);
  // Le cursor est enregistré une fois l’event traité.
  if (sub.cursor) writeFileSync(CURSOR_FILE, sub.cursor);
}

Si le cursor est trop ancien, vous recevez un reset puis un nouveau snapshot : repartez de celui-ci.

Historique : FathomChartsRest

import { FathomChartsRest } from '@fathom-charts/sdk';

const rest = new FathomChartsRest({ baseUrl: 'https://api.fathomcharts.com', apiKey: process.env.FATHOM_CHARTS_API_KEY! });

Méthodes

Chaque méthode qui interroge l’historique prend la requête décrite sur la page Historique (instrument, indicator, params, from, to, mode, et selon la méthode limit, cursor, untilCursor, snapshot), et un AbortSignal facultatif.

Les options de exportNdjson() : signal, maxResumes (nombre de reprises consécutives sans nouvelle ligne avant d’abandonner, 5 par défaut) et resumeDelayMs (délai avant la première reprise, 1 s par défaut, doublé à chaque reprise consécutive jusqu’à 30 s). Si la toute première requête échoue (erreur réseau ou 5xx avant le header X-Export-Token), exportNdjson() ne la renvoie jamais : un nouvel export serait facturé de nouveau. Il lève l’erreur, et vous décidez.

Rate limit et retries

Un 429 RATE_LIMITED est réessayé jusqu’à rateLimitRetries fois : après le délai du header Retry-After (60 secondes au plus), ou, sans ce header, après 1, 2, puis 4 secondes. Un AbortSignal interrompt l’attente immédiatement. 429 QUOTA_EXCEEDED (budget du mois épuisé) n’est jamais réessayé : il est levé tout de suite.

Erreurs

Toutes les erreurs du SDK sont des FathomChartsError :

Codes propres au SDK, en plus de ceux de l’API (la liste complète est exportée dans ERROR_CODES) :

Une fermeture 4001 donne UNAUTHORIZED, avec un message qui rappelle les causes possibles (clé absente, mal formée, inconnue, révoquée ou expirée, stream token invalide, expiré ou déjà utilisé).

Cursors

compareCursors(a, b) compare deux cursors <utcDay>.<rank>.<k> nombre par nombre et renvoie un nombre négatif, zéro ou positif. Un cursor mal formé (nombres avec des zéros en tête, champ manquant…) lève INVALID_PARAMETERS.

import { compareCursors } from '@fathom-charts/sdk';

compareCursors('20720.111416.0', '20720.111417.0'); // < 0