fathomCHARTSEssayer gratuitement
Démarrer

Démarrage rapide

En cinq minutes : créez une clé, ouvrez une connexion, abonnez-vous aux gros ordres agressifs sur le Nasdaq (NQ), puis demandez la même chose sur une période passée.

1. Créer une clé API

Connectez-vous avec votre adresse e-mail : vous recevez un lien de connexion, sans mot de passe, et votre compte est créé à la première connexion. Créez ensuite une clé dans votre espace compte. Copiez-la tout de suite : elle ne s’affiche qu’une fois.

Deux types de clés :

  • clé de test (fc_test_…) : gratuite, données différées de 10 minutes. Idéale pour développer ;
  • clé live (fc_live_…) : reçoit les droits de vos offres, dont le temps réel avec l’offre Live. Sans offre, elle a les mêmes droits qu’une clé de test.

Gardez la clé dans une variable d’environnement de votre serveur :

BASH
export FATHOM_CHARTS_API_KEY="fc_test_…"

Ne la mettez jamais dans du code exécuté par un navigateur. Pour une page web, voir Accès depuis un navigateur.

2. Ouvrir une connexion

Pour un premier essai, l’outil en ligne de commande wscat suffit :

BASH
npx wscat -c wss://stream.fathomcharts.com/v1 -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY"

3. S’abonner

Une fois connecté, collez ce message dans wscat. Il demande les gros ordres agressifs d’au moins 30 contrats (Fathom Trades) sur le contrat NQ front month :

JSON
{"t":"subscribe","sub":"bt","instrument":"NQ.front","indicator":"big-trades","params":{"minimum":30},"mode":"confirmed","from":"live"}
  • sub est le nom que vous donnez à cette subscription. Chaque message qui la concerne le reprend : vous pouvez donc en ouvrir plusieurs sur la même connexion ;
  • mode: "confirmed" n’envoie que les ordres terminés. Avec mode: "live", vous recevez aussi l’ordre en cours, mis à jour à chaque trade.

4. Lire les messages

Voici ce que cette subscription a reçu à l’ouverture de la séance américaine, le 24 septembre 2026, avec une clé live et l’offre Live :

JSON
{"sub":"bt","t":"subscribed","topic":"b2af53ed8e6cfc8620b4754c0836e0e2","cursor":"20720.111120.0"}
{"sub":"bt","t":"snapshot","cursor":"20720.111120.0","items":[]}
{"sub":"bt","t":"status","state":"live","lagMs":4}
{"sub":"bt","cursor":"20720.111434.0","t":"upsert","id":"1790256600533489285:0","final":true,"ts":"1790256600535054015","data":{"side":"sell","volume":66,"trades":32,"start":"1790256600533489285","end":"1790256600533489285","first":122041,"last":122017,"price":122017,"vwap":122027.71212121213}}
{"sub":"bt","cursor":"20720.112164.0","t":"upsert","id":"1790256605021635921:0","final":true,"ts":"1790256605033449615","data":{"side":"buy","volume":32,"trades":30,"start":"1790256605021635921","end":"1790256605023486337","first":122101,"last":122114,"price":122114,"vwap":122110.125}}
{"t":"hb","cursors":{"bt":"20720.112164.0"}}

Dans l’ordre :

  1. subscribed : la subscription est acceptée ;
  2. snapshot : les objets qui existaient déjà au moment du subscribe (aucun ici) ;
  3. status : le stream est en direct ;
  4. upsert : un nouvel objet, ici un gros ordre terminé ;
  5. hb : le heartbeat, envoyé toutes les 5 secondes pour confirmer que la connexion est vivante.

Le premier upsert décrit un ordre vendeur de 66 contrats, exécuté en 32 trades, qui a fait descendre le prix de 122041 à 122017 ticks, soit de 30 510,25 à 30 504,25 points (un tick vaut 0,25 point sur NQ). Chaque champ est détaillé sur la fiche de l’indicateur.

Avec une clé de test, vous recevez les mêmes messages avec 10 minutes de retard. Marché fermé (week-end, pause quotidienne), le status vaut market_closed et aucun upsert n’arrive avant la réouverture.

Gardez le cursor du dernier message reçu : il vous permettra de reprendre après une coupure.

5. Utiliser le SDK

Le SDK TypeScript @fathom-charts/sdk (Node 22+ et navigateur) gère pour vous l’authentification, le snapshot initial, la reprise après coupure et les doublons. En Node, installez aussi le package ws :

BASH
npm install @fathom-charts/sdk ws

Générez ensuite les types des données de chaque indicateur à partir du catalogue (GET /v1/indicators, sans authentification) :

BASH
curl https://api.fathomcharts.com/v1/indicators -o catalog.json
node node_modules/@fathom-charts/sdk/scripts/generate-types.mjs catalog.json src/fathom-charts-types.ts

Puis, dans src/ :

TS
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!,
});

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

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

Chaque message du serveur devient un event dont le champ type reprend le nom du message (upsert, remove, snapshot, status…).

6. La même requête sur l’historique

Les mêmes instrument, indicator et params fonctionnent sur une période passée. Les dates sont des timestamps en nanosecondes depuis le 1er janvier 1970 (UTC), envoyés sous forme de string. Ici, les 3 dernières journées terminées : l’historique REST s’arrête à minuit UTC (la journée en cours n’y est pas encore), et la période reste dans les 7 jours de la Sandbox, donc elle fonctionne avec une clé de test.

BASH
TODAY=$(( $(date +%s) / 86400 * 86400 ))
FROM="$((TODAY - 3 * 86400))000000000"
TO="${TODAY}000000000"

curl https://api.fathomcharts.com/v1/indicator-queries \
  -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"instrument\":\"NQ.front\",\"indicator\":\"big-trades\",\"params\":{\"minimum\":30},\"from\":\"$FROM\",\"to\":\"$TO\"}"

Vous recevez une page de résultats (items) et un champ next : s’il n’est pas null, renvoyez la même requête avec "cursor": "<valeur de next>" pour obtenir la page suivante. Chaque objet a le même id et le même cursor que lorsque le stream temps réel l’a publié. L’historique contient aussi les versions intermédiaires (final: false) publiées pendant la construction de chaque objet : gardez seulement final: true si seul le résultat terminé vous intéresse. Voir Historique.

Et ensuite