.NET SDK reference

This page describes version 1.1.2 of HFTFeed.Client. For a step-by-step introduction, start with Connect with the .NET SDK.

Package

The assembly also contains public types in the HFTfeed.Fix2.Codec namespace. They are internal building blocks of the SDK, not part of its supported API, and can change in any release.

HFTFeedClient

public sealed class HFTFeedClient : IDisposable

Constructors

email and password are your hftfeed.com login. The constructors throw ArgumentNullException when email or password is null, or host is null or blank. Nothing connects until you call Start.

The default endpoint is also available as constants: HFTFeedClient.DefaultHost ("fix-server.hftfeed.com", a name since 1.1.2 — 1.1.0 and 1.1.1 held an address), HFTFeedClient.DefaultPort (9030) and HFTFeedClient.AlternatePort (9031). The host is resolved on every connect, so the machine needs DNS, and a move of the feed to another address needs no new SDK.

Methods

Don't call Start on a client that is already connected, and don't call Start, Stop or Dispose from inside a callback.

Properties

Events

The events are properties of delegate type. Assign a handler with =, or combine handlers with += and -=.

Connection lifecycle

What Start does

Start() also checks for a free connection attempt before step 1, so a refused call doesn't sign in either. Then the status becomes CONNECTED and OnConnectionStatus fires. A Logout received during these steps is also passed to OnError. A Start that throws has already closed its connection and never starts automatic reconnects; you can call Start again. Stop() from another thread ends a Start in progress, which then throws OperationCanceledException.

Stop and Dispose

Stop() sends a Logout if the connection is open, closes the socket without waiting for the server's reply, sets DISCONNECTED, cancels automatic reconnects (including an attempt or a wait in progress) and clears the list of subscribed symbols. Dispose() calls Stop(); it never throws and is safe to call more than once.

Connecting again after Stop

A stopped client can be started again with Start; a disposed one can't. SubscribedSymbolsCount is 0 after Stop(), and the next Start subscribes to nothing, so call Subscribe or SubscribeAll again once Start has returned. The symbol list is loaded again at every logon.

Automatic reconnect

With AutoReconnect = true, the client reconnects when the connection closes unexpectedly: a network failure, a server restart, a heartbeat timeout or any other disconnect that came without a Logout. It waits a random time before each attempt:

After that wait, an attempt also waits until the connection limit allows another connection.

Each attempt repeats steps 2 to 4 of Start with the SenderCompID from your first Start; it does not repeat the HTTPS sign-in, but the server checks your login and plan on every logon. After a successful attempt the client raises OnConnectionStatus(CONNECTED), then subscribes again to every symbol it had subscribed, in one request, and raises OnSubscribe with Resubscribed: <n> symbols. Failed attempts are reported on OnError.

The client stops retrying when an attempt succeeds, when you call Stop() or Dispose() (which also end an attempt or a wait in progress), when you set AutoReconnect to false, or when the server answers an attempt with a Logout. It never reconnects after the server ended a session with a Logout, and it only reconnects sessions that were established: a Start that fails throws instead.

Connection attempts

The server accepts at most 6 new connections per minute from one IP address. A connection over that limit is closed at once without an answer and gives the address a strike. One strike expires every 10 minutes; 3 strikes block the address for 5 minutes, 6 for an hour and 9 for a day, and the server closes every connection from a blocked address the same way.

The SDK therefore opens at most 5 connections per host in any 60 seconds. The count is shared by every HFTFeedClient in the process and covers Start and automatic reconnects alike:

• A connection counts from the moment the client starts to open it, so clients connecting at the same time can't overshoot.
• If the TCP connection is not established (connection refused, host unreachable, connect timeout, or cancelled), the attempt never reached the server and no longer counts.
• An established connection counts for 60 seconds whatever happens next: logon refused, closed by the server, or ended by Stop(). A connection that completes after the client stopped waiting for it (after the 10-second connect timeout) is counted when it completes.

The count is kept per host name exactly as passed to the constructor (ignoring case), not per port: ports 9030 and 9031 share it. It is not shared between processes, and the server counts everything from your IP address, so several programs on one machine or behind one NAT can still go over the server's limit together.

Heartbeats

• The client sends a Heartbeat when it has sent nothing for HeartbeatSeconds, and answers every TestRequest from the server at once.
• The server sends a Heartbeat when it has sent nothing for the heartbeat interval. When it has heard nothing from you for 1.2 intervals it sends a TestRequest, and after 2 intervals it closes the connection without a Logout.
• The server clamps the interval to 5 to 60 seconds, but the client times its own heartbeats from the value you set. Keep HeartbeatSeconds in that range.
• The client does not time out a silent connection by itself. It notices a drop when the socket closes or a send fails.

Symbols

public class HFTFeedSymbol

ToString() returns "<SymbolKey> <SymbolName> (<Digits>)". The list contains the symbols the server currently publishes. It is loaded at every logon, including automatic reconnects.

Subscriptions

Notices

The subscription methods report their local outcome as text on OnSubscribe or OnUnsubscribe. Only the notices that say Subscribed or Unsubscribed mean a request was sent.

When the client is not connected, the methods send nothing and OnError receives Not connected: call Start() before subscribing.

Server responses

The server does not confirm a subscription: ticks for the symbol start to arrive. Subscribing to a symbol twice, or unsubscribing from one you don't have, is ignored. A few ticks that were already on their way can still arrive shortly after Unsubscribe. When the server refuses a request, OnError receives an HFTFeedException with the message MarketDataRequest rejected: <reason>:

The client still lists a refused symbol as subscribed. To try again, call Unsubscribe(key) and then Subscribe(key).

Request rate

The server accepts at most 50 messages per second from a session, counting everything the client sends. Messages over the limit are refused, and OnError receives Session-level reject: Rate limited; a refused subscribe request still counts as subscribed in the client. If a session goes over the limit in three different seconds within one minute, the server ends it with message rate limit. Use SubscribeAll(), or pace individual Subscribe calls.

Ticks

public class Md

ToString() returns "<Symbol> <Bid>/<Ask>". Every tick carries both sides of the book for one symbol. Ticks arrive in the order the server sent them. When your application reads slowly, the server merges queued updates for a symbol and sends only the latest price.

Threading model

• The client reads the network on one background thread per connection and calls OnNewTick on it, one tick at a time. Nothing else is read while a callback runs.
• A slow OnNewTick backs up the connection. The server then merges queued updates, and if your session's queue stays full for 10 seconds it ends the session with slow consumer.
• Other callbacks run on the threads listed under Events, so two callbacks can run at the same time. Make your handlers thread-safe.
• An exception thrown by a callback is caught and passed to OnError; the client keeps running. Exceptions thrown by OnError itself are ignored.
• The client's public methods can be called from any thread.

Process ticks off the receive thread shows how to hand ticks to a worker.

Receiving without allocations

With ReuseTickObject = true the client's receive path allocates nothing per tick, including while it waits for data; the SDK's own tests check this over 100,000 ticks and on a live connection. The symbol key string comes from the symbol list, so it is not allocated either. With the default false, the only allocation per tick is the new Md. Setting OnFixMsg adds one string per message.

client.ReuseTickObject = true;
client.OnNewTick = tick =>
{
    // The same Md instance is passed for every tick: copy the values you need,
    // and never keep a reference to it or read it from another thread.
    var key = tick.Symbol;
    var bid = tick.Bid;
    var ask = tick.Ask;
    OnQuote(key, bid, ask); // your own method
};

Tick rates

TPS and TPM count the ticks the client received in the last second and the last minute, whether or not OnNewTick is set. Reading them is cheap and safe from any thread:

using var monitor = new Timer(
    _ => Console.WriteLine($"{client.TPS} ticks/s, {client.TPM} ticks/min, {client.SubscribedSymbolsCount} symbols"),
    null, TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(5));

Raw FIX messages

OnFixMsg receives the text of every FIX message the client receives or sends, with the SOH (
) separators left in place, and a note when an incoming sequence number is not the expected one. It builds a string for every message, so use it only while debugging. The outgoing Logon contains your password in tag 554; mask it before you log anything:

client.OnFixMsg = raw =>
{
    var start = raw.IndexOf("
554=", StringComparison.Ordinal);
    if (start >= 0)
    {
        start += 5;
        var end = raw.IndexOf('
', start);
        raw = raw[..start] + "***" + (end >= 0 ? raw[end..] : "");
    }
    Console.WriteLine(raw.Replace('
', '|'));
};

The FIX protocol reference explains every message you will see.

Exceptions

HFTFeedException derives from Exception. HFTFeedAuthException, HFTFeedLogoutException, HFTFeedThrottledException and HFTFeedTimeoutException derive from HFTFeedException. HFTFeedLogoutException adds:

• Text: the server's reason (FIX tag 58). The exception's Message is Server logout: followed by Text.
• IsTooManySessions: true when Text contains too many sessions.

HFTFeedThrottledException (new in 1.1.1) adds RetryAfter, a TimeSpan: how long until the next connection attempt is allowed.

Thrown by Start

Reported on OnError

Server logout reasons

The server ends or refuses a session with a FIX Logout that carries a reason. The SDK passes it to OnError as an HFTFeedLogoutException (and throws it from Start during logon). It never reconnects automatically after a Logout.

Disconnects without a logout

In these cases the connection simply closes and the status changes to DISCONNECTED:

• a network failure or a server restart;
• the server heard nothing from the client for two heartbeat intervals;
• the connection broke the protocol rules on the FIX protocol page;
• your IP address opened more than 6 connections in a minute, or is temporarily blocked. The server closes such connections at once without an answer, so Start throws HFTFeedException with … closed the connection before the Logon completed …, and a reconnect attempt reports the same on OnError.

AutoReconnect applies only to a session that was established. The first case is the one it is for; the SDK's connection attempts limit keeps its own retries below the server's limit.

Limits

HFTFeed may adjust these limits. When you reach one, the reason in the error or Logout tells you which.

Performance and latency

• Run close to the server. The feed server is in the LD4 data center near London, and network distance adds more delay than anything in your process.
• Keep OnNewTick fast. The client reads the next message only after your callback returns. Copy the values and hand them to a worker.
• Avoid garbage. Set ReuseTickObject = true and copy values into structs, so the receive path creates no objects per tick and the garbage collector has less to do.
• Leave OnFixMsg unset in production; it creates a string for every message.
• Resolve symbols once. Build your key-to-symbol lookup after Start() instead of searching GetSymbols() per tick.
• Subscribe only to what you use. Every extra symbol is extra data to read and handle.
• TCP is set up for you. The client disables Nagle's algorithm, so requests leave immediately. On Linux and macOS the receive thread waits for data in a plain blocking receive, without allocating.
• Busy polling, if you have a core to spare. With BusyPollMicroseconds greater than 0, the receive thread keeps checking the socket for that many microseconds after it runs dry before it waits in the kernel, so a tick that arrives in that window is read without a thread wake-up. While the feed is active this keeps one CPU core busy. Typical values are 1,000 to 50,000; set it before Start.
• A larger receive buffer for bursts. ReceiveBufferSize sets the kernel receive buffer before connecting. It absorbs longer bursts while your OnNewTick handler is occasionally slow; it does not lower latency.
• Warm up before you measure. .NET compiles code the first time it runs, so the first ticks after start take longer to handle. Measure after a warm-up period, with a Release build.
• Synchronize your clock (NTP or PTP) before you compare EntryTimeUtc with local time.

Troubleshooting

Still stuck? Contact support with your SDK version, the time of the problem in UTC, your SenderCompID (client.ClientId) and the messages OnError reported. Never send your password.