# 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](https://fathomcharts.com/login) 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](https://fathomcharts.com/account). **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](https://fathomcharts.com/docs/facturation.md). 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](https://fathomcharts.com/docs/authentification.md#accès-depuis-un-navigateur).

## 2. Ouvrir une connexion

Pour un premier essai, l’outil en ligne de commande [wscat](https://github.com/websockets/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](https://fathomcharts.com/docs/indicateurs/big-trades.md)) 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","instrument":"NQZ6","tickSizeNanos":"250000000"}
{"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, sur le contrat `NQZ6` que désigne `NQ.front` ;
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). Le tick size de chaque instrument est donné par `GET /v1/instruments`, en milliardièmes, dans le champ `tickSizeNanos` (`"250000000"` pour NQ) : voir [Instruments](https://fathomcharts.com/docs.md#instruments). Chaque champ est détaillé sur la fiche de l’[indicateur](https://fathomcharts.com/docs/indicateurs/big-trades.md).

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](https://fathomcharts.com/docs/websocket.md#cursors-et-reprise) 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](https://fathomcharts.com/docs/historique.md).

## Et ensuite

- [Authentification](https://fathomcharts.com/docs/authentification.md) : restreindre une clé, la remplacer, ouvrir le stream depuis un navigateur.
- [Temps réel](https://fathomcharts.com/docs/websocket.md) : tenir son état à jour, reprendre après une coupure.
- [Catalogue des indicateurs](https://fathomcharts.com/docs/indicateurs.md) : paramètres et données de chaque indicateur.
- [Utiliser avec un LLM](https://fathomcharts.com/docs/llm.md) : donner cette documentation à votre assistant IA ou à votre coding agent.