Historique

Calculez un indicateur sur une période passée, avec les mêmes paramètres qu’en temps réel. Vous obtenez exactement ce que le stream temps réel a publié à ce moment-là.

L’historique demande l’offre Historique (ou la Sandbox, limitée aux 7 derniers jours) et une clé avec le scope history.

Faire une requête

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

La requête est refusée avec 403 FORBIDDEN si votre offre ne couvre pas la période demandée : historique non inclus, période plus ancienne que ce que votre offre permet, ou fin de période dans les 10 dernières minutes alors que vos données sont différées.

Lire la réponse

{
  "items": [
    {"t":"upsert","cursor":"20720.111416.0","id":"1790256600533489285:0","final":false,"ts":"1790256600533489285","data":{"side":"sell","volume":31,"trades":15,"start":"1790256600533489285","end":"1790256600533489285","first":122041,"last":122027,"price":122027,"vwap":122034.25806451614}},
    {"t":"upsert","cursor":"20720.111417.0","id":"1790256600533489285:0","final":false,"ts":"1790256600533489285","data":{"side":"sell","volume":34,"trades":16,"start":"1790256600533489285","end":"1790256600533489285","first":122041,"last":122026,"price":122026,"vwap":122033.5294117647}}
  ],
  "next": null,
  "computeUnits": 523875
}

Ci-dessus, les deux premiers des 323 items de cette période (next vaut null : tout tient dans une page).

• items : les mises à jour, dans l’ordre, sous la même forme qu’en temps réel ;
• next : à renvoyer pour obtenir la page suivante, ou null quand tout a été servi ;
• computeUnits : le coût de cette page sur votre compute budget.

L’historique contient toutes les versions publiées en direct, y compris les versions intermédiaires (final: false). Ci-dessus, le groupe de trades vendeurs apparaît dès qu’il franchit le seuil de 30 contrats, puis il est republié à chaque trade qui le prolonge, jusqu’à sa version finale (66 contrats, final: true). Si seul le résultat terminé vous intéresse, ne gardez que final: true.

Les objets commencés avant from sont bien pris en compte : une zone ouverte avant le début de la période et modifiée pendant apparaît exactement comme en direct. Pour cela, le calcul relit aussi les trades antérieurs à from dont il a besoin, ce qui explique qu’une courte période puisse coûter plus de compute units que ses seuls trades.

Une liste vide (items: [] et next: null) signifie que le calcul a bien eu lieu et qu’il n’y a rien sur la période, par exemple aucun big trade au-dessus du seuil. Ce n’est jamais une erreur déguisée : si les données manquent, vous recevez 402 NOT_COVERED ; si le calcul se prépare encore, 409 WARMING.

Pages suivantes

Tant que next n’est pas null, renvoyez la même requête avec "cursor": "<valeur de next>".

• Une page peut contenir moins de limit résultats, voire aucun, sans que la période soit terminée : seul next: null marque la fin.
• Si next est trop ancien, la requête est refusée avec CURSOR_EXPIRED : recommencez depuis le début.

Avec le SDK, FathomChartsRest enchaîne les pages pour vous. history() renvoie les résultats un par un, au fil de votre lecture (et pages(), les pages une par une) :

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

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

const query = {
  instrument: 'NQZ6',
  indicator: 'big-trades',
  params: { minimum: 30 },
  from: '1790256600000000000',
  to: '1790258100000000000',
};

for await (const m of rest.history<BigTradesData>(query)) {
  if (m.t === 'upsert' && m.final && m.data) console.log(m.cursor, m.data.side, m.data.volume);
}

En cas d’erreur, le SDK lève une FathomChartsError qui porte le code de l’erreur. Si vous dépassez le rate limit, il attend puis réessaie automatiquement.

Estimer le coût

Chaque requête est décomptée de votre compute budget mensuel. Avant une requête lourde, demandez une estimation : même corps de requête, rien n’est calculé ni décompté.

curl https://api.fathomcharts.com/v1/indicator-queries/estimate \
  -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instrument":"NQZ6","indicator":"big-trades","params":{"minimum":30},"from":"1790256600000000000","to":"1790258100000000000"}'

{
  "trades": 523875,
  "computeUnits": 523875,
  "coveredFrom": "1790121600000000000",
  "coveredTo": "1790258100000000000",
  "missingDays": [],
  "remainingComputeUnits": 19999476125
}

• computeUnits : le coût de la requête, c’est-à-dire le nombre de trades à lire (trades) multiplié par le coût de l’indicateur (indiqué sur sa fiche du catalogue). Les trades lus incluent ceux qui précèdent from et dont le calcul a besoin ;
• remainingComputeUnits : ce qu’il reste de votre budget ce mois-ci, avant cette requête ;
• coveredFrom, coveredTo : la période réellement lue, qui commence avant from quand le calcul a besoin des trades précédents (ici depuis le 23 septembre 00:00 UTC) ;
• missingDays : les journées sans données, qui feraient échouer la requête avec 402 NOT_COVERED.

Avec le SDK : await rest.estimate(query).

Une requête qui coûterait plus que votre budget restant est refusée avant d’être lancée, avec 429 QUOTA_EXCEEDED. Le header Retry-After indique quand votre budget se renouvelle.

Période disponible

Les requêtes historiques et les exports couvrent les journées terminées (en UTC) publiées par notre fournisseur de données : une période qui touche la journée en cours est refusée avec 402 NOT_COVERED, et le message donne la dernière date servie. Pour inclure la journée en cours, abonnez-vous sur le WebSocket avec from: {"time": …} : le stream enchaîne l’historique et le direct sans trou (voir Démarrer dans le passé).

La profondeur dépend de votre offre : 7 jours en Sandbox, toute la profondeur disponible avec l’offre Historique.

Enchaîner avec le temps réel

Pour charger le passé puis suivre le marché sans trou ni doublon, vous avez deux options :

• la plus simple : abonnez-vous sur le WebSocket avec from: {"time": "<début>"}. Vous recevez le passé, puis le direct, à la suite. Voir Démarrer dans le passé ;
• en deux temps : ouvrez d’abord la subscription temps réel et notez le cursor du snapshot. Lancez ensuite la requête historique avec untilCursor égal à ce cursor : elle s’arrête exactement là où le direct commence.