fathomCHARTSTry it free
Get started

Quickstart

In five minutes: create a key, open a connection, subscribe to large aggressive orders on the Nasdaq (NQ), then ask for the same thing over a past period.

1. Create an API key

Sign in with your email address: you get a sign-in link, no password needed, and your account is created the first time you sign in. Then create a key in your account. Copy it right away: it is shown only once.

There are two kinds of keys:

  • test key (fc_test_…): free, data delayed by 10 minutes. Ideal for development;
  • live key (fc_live_…): gets the rights of your offers, including real-time data with the Live offer. Without an offer, it has the same rights as a test key.

Store the key in an environment variable on your server:

BASH
export FATHOM_CHARTS_API_KEY="fc_test_…"

Never put it in code that runs in a browser. For a web page, see Browser access.

2. Open a connection

For a first try, the wscat command-line tool is all you need:

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

3. Subscribe

Once connected, send this message. It asks for large aggressive orders of at least 30 contracts (Fathom Trades) on the active NQ contract:

JSON
{"t":"subscribe","sub":"bt","instrument":"NQ.front","indicator":"big-trades","params":{"minimum":30},"mode":"confirmed","from":"live"}
  • sub is a name you choose for this subscription. Every message about it carries that name, so you can open several subscriptions on the same connection;
  • mode: "confirmed" sends only completed orders. With mode: "live", you also get the order in progress, updated on every trade.

4. Read the messages

Here is what this subscription received at the US open on September 24, 2026, with a live key and the Live offer:

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"}}

In order:

  1. subscribed: the subscription is accepted;
  2. snapshot: the objects that already existed when you subscribed (none here);
  3. status: the stream is live;
  4. upsert: a new object, here a completed large order;
  5. hb: the heartbeat, sent every 5 seconds to confirm the connection is alive.

The first upsert describes a sell order of 66 contracts, filled in 32 trades, that pushed the price down from 122041 to 122017 ticks, or from 30,510.25 to 30,504.25 points (one tick is 0.25 points on NQ). Every field is documented on the indicator page.

With a test key, you get the same messages 10 minutes late. While the market is closed (weekend, daily break), the status is market_closed and no upsert arrives before it reopens.

Keep the cursor of the last message you received: you will need it to resume after a disconnect.

5. Use the SDK

The @fathom-charts/sdk TypeScript SDK (Node 22+ and browsers) handles authentication, the initial snapshot, resuming after a disconnect and duplicates for you. In Node, also install the ws package:

BASH
npm install @fathom-charts/sdk ws

Then generate the types of each indicator's data from the catalog (GET /v1/indicators, no authentication):

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

Then, in 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);
  }
}

Each server message becomes an event whose type field is the message name (upsert, remove, snapshot, status…).

6. Run the same request over history

The same instrument, indicator and params work over a past period. Times are timestamps in nanoseconds since January 1, 1970 (UTC), sent as strings. Here, the last 3 completed days: REST history stops at midnight UTC (the current day is not in it yet), and the range stays within the Sandbox's 7 days, so it works with a test key.

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\"}"

You get a page of results (items) and a next field: when it is not null, send the same request with "cursor": "<next value>" to get the next page. Each object has the same id and the same cursor as when the real-time stream published it. History also includes the intermediate versions (final: false) published while each object was being built: keep only final: true if you only care about completed results. See History.

Next steps