C# SDK

FathomCharts handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination, exports and rate-limit retries for you. This page describes every option and method; the behaviour the four SDKs share is in SDKs.

Install

dotnet add package FathomCharts

• .NET 8 or later, and .NET Standard 2.0: the package also runs in .NET Framework 4.8 hosts, such as the add-ons of trading platforms.
• Its dependencies are System.Text.Json and a managed zstd decompressor (ZstdSharp.Port); on .NET Standard 2.0, Microsoft.Bcl.AsyncInterfaces too. Nothing native to install.

Indicator types

dnx FathomCharts.Types https://api.fathomcharts.com/v1/indicators FathomChartsTypes.cs

dnx comes with the .NET 10 SDK. Otherwise, install the tool once (dotnet tool install -g FathomCharts.Types) and run FathomCharts.Types https://api.fathomcharts.com/v1/indicators FathomChartsTypes.cs. It takes the catalog’s URL or a file saved from GET /v1/indicators.

The file holds, in the namespace FathomCharts.Indicators, one record per indicator for its parameters (BigTradesParams) and one for its data (BigTradesData), with the catalog’s descriptions as XML doc comments; strings with a fixed set of values become enums, and IndicatorIds lists the indicator ids (IndicatorIds.BigTrades). A tuple, such as a footprint level [price, bid, ask, unknown?], is a double[] whose positions its doc comment gives. Generate the file again when the catalog changes.

Real time: FathomChartsStream

using FathomCharts;
using FathomCharts.Indicators;

await using var stream = new FathomChartsStream(new StreamOptions
{
    Url = "wss://stream.fathomcharts.com/v1",
    ApiKey = Environment.GetEnvironmentVariable("FATHOM_CHARTS_API_KEY"),
    OnStateChange = state => Console.WriteLine($"connection {state}"),
});

var bigTrades = stream.Subscribe<BigTradesData>(new SubscribeOptions
{
    Instrument = "NQ.front",
    Indicator = IndicatorIds.BigTrades,
    Params = new BigTradesParams { Minimum = 30 },
    Mode = Mode.Confirmed,
});

await foreach (var e in bigTrades)
{
    if (e is Upsert<BigTradesData> upsert) Console.WriteLine($"{upsert.Cursor} {upsert.Data.Side} {upsert.Data.Volume}");
}

Options

StreamOptions, durations as TimeSpan:

OnStateChange and OnNotice run on the stream’s threads: keep them short. await using (or DisposeAsync(), Close()) closes the stream. stream.ConnectionState is Idle, Connecting, Open, Reconnecting or Closed; stream.Maintenance lists the maintenance windows announced on the connection and not over, by start.

Subscribe()

stream.Subscribe<T>(options) opens a subscription and returns a Subscription<T>, to read with await foreach. SubscribeOptions holds the fields of the subscribe message: Instrument, Indicator, Params (a generated <Name>Params, or any object serialized to JSON), Mode (Mode.Live by default) and From (From.Live by default, From.Cursor(cursor, engine) or From.Time(time)). The SDK picks the sub name itself. T is the indicator’s data type (BigTradesData…); without it, Subscribe(options) gives the data as JsonElement.

The events are records deriving from StreamEvent: Subscribed, Snapshot<T>, Upsert<T>, Remove, Status, Reset and Notice, to test with is or switch. Their fields are those of Events, in Pascal case (TickSizeNanos, LagMs). An error on the subscription ends the loop: await foreach throws a FathomChartsException carrying the received Code.

Subscription

Leaving the loop (break, return or an exception in its body) closes the subscription. Reconnection, resuming and close codes: see Connection lifecycle; to resume after your process restarts, see Resume after a restart.

History: FathomChartsRest

using var rest = new FathomChartsRest(new RestOptions
{
    BaseUrl = "https://api.fathomcharts.com",
    ApiKey = Environment.GetEnvironmentVariable("FATHOM_CHARTS_API_KEY"),
});

Methods

Queries are records with the fields of the API, as on the History page: PageQuery (Instrument, Indicator, Params, From, To, Mode, Limit, Cursor, UntilCursor, Snapshot) and RangeQuery for exports. Every method takes a CancellationToken: cancelling a call, or the wait for a retry, throws ABORTED.

Errors

Every error the SDK throws, or ends a loop with, is a FathomChartsException. Its codes are listed in Errors (ErrorCodes; the WebSocket close codes, CloseCode). CONFIGURATION also covers an invalid Url or BaseUrl, and data that does not fit the type T.

Cursors

Cursors.Compare("20720.111416.0", "20720.111417.0"); // < 0