# 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](https://fathomcharts.com/en/login) 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](https://fathomcharts.com/en/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](https://fathomcharts.com/en/docs/billing.md) 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](https://fathomcharts.com/en/docs/authentication.md#browser-access).

## 2. Open a connection

For a first try, the [wscat](https://github.com/websockets/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](https://fathomcharts.com/en/docs/indicators/big-trades.md)) 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","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"}}
```

In order:

1. `subscribed`: the subscription is accepted, on the `NQZ6` contract that `NQ.front` designates;
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). Each instrument’s tick size is given by `GET /v1/instruments`, in billionths, in the `tickSizeNanos` field (`"250000000"` for NQ): see [Instruments](https://fathomcharts.com/en/docs.md#instruments). Every field is documented on the [indicator](https://fathomcharts.com/en/docs/indicators/big-trades.md) 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](https://fathomcharts.com/en/docs/websocket.md#cursors-and-resuming) 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](https://fathomcharts.com/en/docs/history.md).

## Next steps

- [Authentication](https://fathomcharts.com/en/docs/authentication.md): restrict a key, rotate it, open the stream from a browser.
- [Real time](https://fathomcharts.com/en/docs/websocket.md): keep your state in sync, resume after a disconnect.
- [Indicator catalog](https://fathomcharts.com/en/docs/indicators.md): parameters and data for every indicator.
- [Use with an LLM](https://fathomcharts.com/en/docs/llm.md): give this documentation to your AI assistant or coding agent.