diff --git a/src/Anubis/Brokers/Alpaca.cs b/src/Anubis/Brokers/Alpaca.cs
new file mode 100644
index 0000000..51089f0
--- /dev/null
+++ b/src/Anubis/Brokers/Alpaca.cs
@@ -0,0 +1,408 @@
+using System.Globalization;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Anubis.Core;
+using Anubis.Data;
+
+namespace Anubis.Brokers;
+
+/// Addresses and limits of Alpaca on the free "Basic" plan (SPEC 4.1, docs re-read on 10/11/2026: API-NOTES).
+public sealed record AlpacaOptions
+{
+ public Uri DataUrl { get; init; } = new("https://data.alpaca.markets");
+
+ /// Trading API: paper by default. Assets, calendar and clock come from here.
+ public Uri TradingUrl { get; init; } = new("https://paper-api.alpaca.markets");
+
+ /// Real-time feed of the free plan: IEX only.
+ public Uri StreamUrl { get; init; } = new("wss://stream.data.alpaca.markets/v2/iex");
+
+ /// Symbols the free plan allows on the stream.
+ public int MaxStreamSymbols { get; init; } = 30;
+
+ /// Consolidated (SIP) data only when the request ends at least 15 minutes ago; one more minute of margin.
+ public TimeSpan SipDelay { get; init; } = TimeSpan.FromMinutes(16);
+
+ /// The plan allows 200 calls a minute; Anubis stays a little below.
+ public int CallsPerMinute { get; init; } = 190;
+}
+
+/// Key id and secret of an Alpaca API key. Never logged (trap 17).
+public sealed record AlpacaCredentials(string KeyId, string Secret)
+{
+ public override string ToString() => "AlpacaCredentials(***)";
+}
+
+/// The broker's clock: whether the market is open and when it opens and closes next.
+public sealed record MarketClock(DateTimeOffset At, bool IsOpen, DateTimeOffset NextOpen, DateTimeOffset NextClose);
+
+///
+/// The data part of the Alpaca adapter on the free plan (issue #19): assets, daily bars from the consolidated
+/// tape (real and adjusted, volumes never from IEX: trap 8), minute bars, quotes, the IEX stream within 30
+/// symbols, calendar, clock and corporate actions. Without keys every call says so and nothing is sent.
+///
+public sealed class AlpacaClient : IMarketDataSource
+{
+ public static readonly TimeZoneInfo NewYork = TimeZoneInfo.FindSystemTimeZoneById("America/New_York");
+
+ private const int SymbolsPerRequest = 100;
+ // Unit splits (SPAC units turning into shares and warrants) are not price splits and are not read.
+ private const string ActionTypes = "forward_split,reverse_split,cash_dividend,stock_dividend,name_change";
+
+ private readonly ApiHttp _http;
+ private readonly IClock _clock;
+ private readonly AlpacaOptions _options;
+ private readonly AlpacaCredentials? _credentials;
+ private readonly Func _sockets;
+ private readonly RateLimiter _limiter;
+
+ public AlpacaClient(HttpClient http, IClock clock, AlpacaCredentials? credentials, AlpacaOptions? options = null, Func? sockets = null)
+ {
+ _clock = clock;
+ _options = options ?? new AlpacaOptions();
+ _credentials = credentials;
+ _http = new ApiHttp(http, clock, "Alpaca");
+ _sockets = sockets ?? (() => new ClientWebSocketTransport());
+ _limiter = new RateLimiter(clock, _options.CallsPerMinute, TimeSpan.FromMinutes(1));
+ if (credentials is not null)
+ {
+ Redactor.Register(credentials.KeyId);
+ Redactor.Register(credentials.Secret);
+ }
+ }
+
+ public string Venue => Venues.Alpaca;
+
+ /// False until the user saves the Alpaca keys: the stock part waits for them (SPEC 2.3).
+ public bool IsConfigured => _credentials is not null;
+
+ public async Task> ListInstrumentsAsync(CancellationToken cancellationToken)
+ {
+ // Every status: inactive assets stay in the catalogue for the universe "as of" a past date (SPEC 6.7).
+ using var json = await GetAsync(_options.TradingUrl, "/v2/assets?asset_class=us_equity", cancellationToken).ConfigureAwait(false);
+ return json.RootElement.EnumerateArray().Select(ReadAsset).ToList();
+ }
+
+ public static InstrumentSpec ReadAsset(JsonElement item) =>
+ new(Venues.Alpaca, Text(item, "symbol"), Text(item, "name"), AssetClasses.Equity, "USD")
+ {
+ Exchange = Text(item, "exchange"),
+ Status = Text(item, "status"),
+ Fractionable = item.TryGetProperty("fractionable", out var f) && f.ValueKind == JsonValueKind.True,
+ };
+
+ public async Task> FetchDailyBarsAsync(string symbol, DateOnly first, DateOnly last, CancellationToken cancellationToken)
+ {
+ var all = await FetchDailyBarsAsync([symbol], first, last, cancellationToken).ConfigureAwait(false);
+ return all.TryGetValue(symbol, out var bars) ? bars : [];
+ }
+
+ ///
+ /// Consolidated daily bars of many symbols, real and adjusted for splits and dividends, for the days from
+ /// to . A day whose close is not 15 minutes old is left out.
+ ///
+ public async Task>> FetchDailyBarsAsync(
+ IReadOnlyCollection symbols, DateOnly first, DateOnly last, CancellationToken cancellationToken)
+ {
+ ArgumentNullException.ThrowIfNull(symbols);
+ var end = DayStart(last.AddDays(1));
+ var latest = _clock.UtcNow - _options.SipDelay;
+ if (end > latest)
+ {
+ end = latest;
+ }
+
+ var result = new Dictionary>(StringComparer.Ordinal);
+ foreach (var chunk in symbols.Distinct().Chunk(SymbolsPerRequest))
+ {
+ var raw = await BarsAsync(chunk, "1Day", "sip", "raw", DayStart(first), end, cancellationToken).ConfigureAwait(false);
+ var adjusted = await BarsAsync(chunk, "1Day", "sip", "all", DayStart(first), end, cancellationToken).ConfigureAwait(false);
+ foreach (var (symbol, bars) in raw)
+ {
+ var adjustedByDay = adjusted.TryGetValue(symbol, out var a) ? a.ToDictionary(b => NewYorkDay(b.OpensAt)) : [];
+ result[symbol] = bars
+ .Select(b =>
+ {
+ var day = NewYorkDay(b.OpensAt);
+ return new DailyBar(day, b.Open, b.High, b.Low, b.Close, b.Volume)
+ {
+ Adjusted = adjustedByDay.TryGetValue(day, out var adj) ? new Ohlc(adj.Open, adj.High, adj.Low, adj.Close) : null,
+ };
+ })
+ .Where(b => b.Day >= first && b.Day <= last)
+ .ToList();
+ }
+ }
+
+ return result;
+ }
+
+ public async Task> FetchMinuteBarsAsync(string symbol, DateTimeOffset start, DateTimeOffset until, CancellationToken cancellationToken)
+ {
+ // Older than 15 minutes: the consolidated tape. Otherwise IEX, the only real-time feed of the free plan.
+ var feed = until <= _clock.UtcNow - _options.SipDelay ? "sip" : "iex";
+ var bars = await BarsAsync([symbol], "1Min", feed, "raw", start, until.AddTicks(-1), cancellationToken).ConfigureAwait(false);
+ return bars.TryGetValue(symbol, out var list) ? list.Where(b => b.OpensAt >= start && b.OpensAt < until).ToList() : [];
+ }
+
+ public async Task FetchQuoteAsync(string symbol, CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync(_options.DataUrl, "/v2/stocks/quotes/latest?feed=iex&symbols=" + Uri.EscapeDataString(symbol), cancellationToken)
+ .ConfigureAwait(false);
+ if (!json.RootElement.GetProperty("quotes").TryGetProperty(symbol, out var item))
+ {
+ throw new MarketDataException("Alpaca: nessuna quotazione per " + symbol, retryable: false);
+ }
+
+ return ReadQuote(symbol, item);
+ }
+
+ /// Exchange sessions from to , in UTC (times are New York's).
+ public async Task> FetchCalendarAsync(DateOnly first, DateOnly last, CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync(_options.TradingUrl,
+ $"/v2/calendar?start={first:yyyy-MM-dd}&end={last:yyyy-MM-dd}", cancellationToken).ConfigureAwait(false);
+ return json.RootElement.EnumerateArray().Select(ReadSession).ToList();
+ }
+
+ public static MarketSession ReadSession(JsonElement item)
+ {
+ var date = DateOnly.ParseExact(Text(item, "date"), "yyyy-MM-dd", CultureInfo.InvariantCulture);
+ return new MarketSession(date, NewYorkMoment(date, Text(item, "open")), NewYorkMoment(date, Text(item, "close")));
+ }
+
+ public async Task FetchClockAsync(CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync(_options.TradingUrl, "/v2/clock", cancellationToken).ConfigureAwait(false);
+ return ReadClock(json.RootElement);
+ }
+
+ public static MarketClock ReadClock(JsonElement item) => new(
+ Moment(Text(item, "timestamp")), item.GetProperty("is_open").GetBoolean(), Moment(Text(item, "next_open")), Moment(Text(item, "next_close")));
+
+ /// Splits, dividends and symbol changes with ex-date (process date for name changes) in the range (SPEC 6.10).
+ public async Task> FetchCorporateActionsAsync(IReadOnlyCollection symbols, DateOnly first, DateOnly last,
+ CancellationToken cancellationToken)
+ {
+ ArgumentNullException.ThrowIfNull(symbols);
+ var actions = new List();
+ foreach (var chunk in symbols.Distinct().Chunk(SymbolsPerRequest))
+ {
+ string? page = null;
+ do
+ {
+ var path = $"/v1/corporate-actions?symbols={Uri.EscapeDataString(string.Join(',', chunk))}&types={ActionTypes}" +
+ $"&start={first:yyyy-MM-dd}&end={last:yyyy-MM-dd}&limit=1000" + (page is null ? "" : "&page_token=" + Uri.EscapeDataString(page));
+ using var json = await GetAsync(_options.DataUrl, path, cancellationToken).ConfigureAwait(false);
+ actions.AddRange(ReadCorporateActions(json.RootElement.GetProperty("corporate_actions")));
+ page = NextPage(json.RootElement);
+ }
+ while (page is not null);
+ }
+
+ return actions;
+ }
+
+ /// The corporate_actions object of the response, grouped by type.
+ public static IReadOnlyList ReadCorporateActions(JsonElement groups)
+ {
+ var list = new List();
+ foreach (var group in groups.EnumerateObject())
+ {
+ foreach (var item in group.Value.EnumerateArray())
+ {
+ var key = "alpaca:" + Text(item, "id");
+ switch (group.Name)
+ {
+ case "forward_splits" or "reverse_splits" or "forward_split" or "reverse_split":
+ var oldRate = Decimal(item, "old_rate");
+ var newRate = Decimal(item, "new_rate");
+ if (oldRate > 0 && newRate > 0)
+ {
+ list.Add(new CorporateAction(Text(item, "symbol"), CorporateActionKinds.Split, Day(item, "ex_date"), Venues.Alpaca, key)
+ {
+ Ratio = newRate / oldRate,
+ NewSymbol = Text(item, "new_symbol") is { Length: > 0 } s ? s : null,
+ });
+ }
+
+ break;
+ case "cash_dividends" or "cash_dividend":
+ list.Add(new CorporateAction(Text(item, "symbol"), CorporateActionKinds.CashDividend, Day(item, "ex_date"), Venues.Alpaca, key)
+ {
+ CashAmount = Decimal(item, "rate"),
+ Currency = Text(item, "currency") is { Length: > 0 } c ? c : "USD",
+ });
+ break;
+ case "stock_dividends" or "stock_dividend":
+ list.Add(new CorporateAction(Text(item, "symbol"), CorporateActionKinds.StockDividend, Day(item, "ex_date"), Venues.Alpaca, key)
+ {
+ Ratio = 1m + Decimal(item, "rate"),
+ });
+ break;
+ case "name_changes" or "name_change":
+ list.Add(new CorporateAction(Text(item, "old_symbol"), CorporateActionKinds.SymbolChange, Day(item, "process_date"), Venues.Alpaca, key)
+ {
+ NewSymbol = Text(item, "new_symbol"),
+ });
+ break;
+ default:
+ break;
+ }
+ }
+ }
+
+ return list;
+ }
+
+ public async IAsyncEnumerable StreamAsync(IReadOnlyCollection symbols, [EnumeratorCancellation] CancellationToken cancellationToken)
+ {
+ ArgumentNullException.ThrowIfNull(symbols);
+ var credentials = RequireCredentials();
+ if (symbols.Count > _options.MaxStreamSymbols)
+ {
+ throw new MarketDataException(
+ $"Alpaca: il piano gratuito segue al massimo {_options.MaxStreamSymbols} titoli dal vivo, ne sono stati chiesti {symbols.Count}.", retryable: false);
+ }
+
+ if (symbols.Count == 0)
+ {
+ yield break;
+ }
+
+ await using var socket = _sockets();
+ await socket.ConnectAsync(_options.StreamUrl, null, cancellationToken).ConfigureAwait(false);
+ await socket.SendAsync(JsonSerializer.Serialize(new { action = "auth", key = credentials.KeyId, secret = credentials.Secret }), cancellationToken)
+ .ConfigureAwait(false);
+ await socket.SendAsync(JsonSerializer.Serialize(new { action = "subscribe", bars = symbols, quotes = symbols }), cancellationToken).ConfigureAwait(false);
+ while (await socket.ReceiveAsync(cancellationToken).ConfigureAwait(false) is { } message)
+ {
+ foreach (var item in ParseStreamMessage(message))
+ {
+ yield return item;
+ }
+ }
+ }
+
+ /// Events in one stream message (always an array). Control messages give none; errors stop the feed.
+ public static IReadOnlyList ParseStreamMessage(string message)
+ {
+ using var json = JsonDocument.Parse(message);
+ var events = new List();
+ foreach (var item in json.RootElement.EnumerateArray())
+ {
+ var symbol = Text(item, "S");
+ switch (Text(item, "T"))
+ {
+ case "b":
+ events.Add(new BarEvent(symbol, ReadBar(item), Closed: true));
+ break;
+ case "q":
+ events.Add(new QuoteEvent(ReadQuote(symbol, item)));
+ break;
+ case "t":
+ events.Add(new TradeEvent(symbol, Moment(Text(item, "t")), Decimal(item, "p"), Decimal(item, "s")));
+ break;
+ case "error":
+ var code = item.TryGetProperty("code", out var c) ? c.GetRawText() : "?";
+ throw new MarketDataException($"Alpaca: errore del flusso {code}: {Text(item, "msg")}",
+ retryable: code is "406" or "407" or "500");
+ default:
+ break;
+ }
+ }
+
+ return events;
+ }
+
+ private async Task>> BarsAsync(IReadOnlyCollection symbols, string timeframe, string feed, string adjustment,
+ DateTimeOffset start, DateTimeOffset end, CancellationToken cancellationToken)
+ {
+ var result = new Dictionary>(StringComparer.Ordinal);
+ if (end < start)
+ {
+ return result;
+ }
+
+ string? page = null;
+ do
+ {
+ // The feed is always explicit: its default changes with the endpoint and the subscription (API-NOTES).
+ var path = $"/v2/stocks/bars?symbols={Uri.EscapeDataString(string.Join(',', symbols))}&timeframe={timeframe}" +
+ $"&start={Rfc3339(start)}&end={Rfc3339(end)}&feed={feed}&adjustment={adjustment}&limit=10000&sort=asc" +
+ (page is null ? "" : "&page_token=" + Uri.EscapeDataString(page));
+ using var json = await GetAsync(_options.DataUrl, path, cancellationToken).ConfigureAwait(false);
+ if (json.RootElement.TryGetProperty("bars", out var bars) && bars.ValueKind == JsonValueKind.Object)
+ {
+ foreach (var symbol in bars.EnumerateObject())
+ {
+ if (!result.TryGetValue(symbol.Name, out var list))
+ {
+ result[symbol.Name] = list = [];
+ }
+
+ list.AddRange(symbol.Value.EnumerateArray().Select(ReadBar));
+ }
+ }
+
+ page = NextPage(json.RootElement);
+ }
+ while (page is not null);
+
+ return result;
+ }
+
+ private async Task GetAsync(Uri host, string pathAndQuery, CancellationToken cancellationToken)
+ {
+ var credentials = RequireCredentials();
+ var headers = new Dictionary { ["APCA-API-KEY-ID"] = credentials.KeyId, ["APCA-API-SECRET-KEY"] = credentials.Secret };
+ var text = await _http.GetStringAsync(new Uri(host, pathAndQuery), _limiter, headers, cancellationToken).ConfigureAwait(false);
+ return JsonDocument.Parse(text);
+ }
+
+ private AlpacaCredentials RequireCredentials() =>
+ _credentials ?? throw new MarketDataException("Alpaca: mancano le chiavi. La parte azionaria resta in attesa finché non le inserisci.", retryable: false);
+
+ internal static Bar ReadBar(JsonElement item) =>
+ new(Moment(Text(item, "t")), item.GetProperty("o").GetDouble(), item.GetProperty("h").GetDouble(), item.GetProperty("l").GetDouble(),
+ item.GetProperty("c").GetDouble(), item.GetProperty("v").GetDouble());
+
+ private static Quote ReadQuote(string symbol, JsonElement item) =>
+ new(symbol, Decimal(item, "bp"), Decimal(item, "ap"), Moment(Text(item, "t")))
+ {
+ BidSize = Decimal(item, "bs"),
+ AskSize = Decimal(item, "as"),
+ };
+
+ /// A daily bar's time is midnight in New York expressed in UTC: its day is the New York date.
+ public static DateOnly NewYorkDay(DateTimeOffset moment) => DateOnly.FromDateTime(TimeZoneInfo.ConvertTime(moment, NewYork).DateTime);
+
+ private static DateTimeOffset DayStart(DateOnly day)
+ {
+ var local = day.ToDateTime(TimeOnly.MinValue);
+ return new DateTimeOffset(local, NewYork.GetUtcOffset(local)).ToUniversalTime();
+ }
+
+ private static DateTimeOffset NewYorkMoment(DateOnly day, string time)
+ {
+ var local = day.ToDateTime(TimeOnly.ParseExact(time, "HH:mm", CultureInfo.InvariantCulture));
+ return new DateTimeOffset(local, NewYork.GetUtcOffset(local)).ToUniversalTime();
+ }
+
+ private static string Rfc3339(DateTimeOffset moment) =>
+ Uri.EscapeDataString(moment.UtcDateTime.ToString("yyyy-MM-dd'T'HH:mm:ss.fffffff'Z'", CultureInfo.InvariantCulture));
+
+ private static string? NextPage(JsonElement root) =>
+ root.TryGetProperty("next_page_token", out var token) && token.ValueKind == JsonValueKind.String && token.GetString() is { Length: > 0 } t ? t : null;
+
+ private static DateTimeOffset Moment(string text) =>
+ DateTimeOffset.Parse(text, CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal);
+
+ private static DateOnly Day(JsonElement item, string name) => DateOnly.ParseExact(Text(item, name), "yyyy-MM-dd", CultureInfo.InvariantCulture);
+
+ private static string Text(JsonElement item, string name) =>
+ item.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String ? value.GetString()! : "";
+
+ private static decimal Decimal(JsonElement item, string name) =>
+ item.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number ? value.GetDecimal() : 0m;
+}
diff --git a/src/Anubis/Brokers/Http.cs b/src/Anubis/Brokers/Http.cs
new file mode 100644
index 0000000..862e263
--- /dev/null
+++ b/src/Anubis/Brokers/Http.cs
@@ -0,0 +1,258 @@
+using System.Net;
+using System.Net.WebSockets;
+using System.Text;
+using Anubis.Core;
+using Anubis.Data;
+
+namespace Anubis.Brokers;
+
+///
+/// At most permits requests in any window of window, on the injected clock. Every source keeps under
+/// its published limits (SPEC 2.2: limits are never bypassed).
+///
+public sealed class RateLimiter(IClock clock, int permits, TimeSpan window)
+{
+ private readonly Lock _gate = new();
+ private readonly Queue _recent = new();
+
+ public int Permits { get; } = permits > 0 ? permits : throw new ArgumentOutOfRangeException(nameof(permits));
+
+ public TimeSpan Window { get; } = window;
+
+ public async Task WaitAsync(CancellationToken cancellationToken)
+ {
+ while (true)
+ {
+ DateTimeOffset reopensAt;
+ lock (_gate)
+ {
+ var now = clock.UtcNow;
+ while (_recent.Count > 0 && now - _recent.Peek() >= Window)
+ {
+ _recent.Dequeue();
+ }
+
+ if (_recent.Count < Permits)
+ {
+ _recent.Enqueue(now);
+ return;
+ }
+
+ reopensAt = _recent.Peek() + Window;
+ }
+
+ await clock.WaitUntilAsync(reopensAt, cancellationToken).ConfigureAwait(false);
+ }
+ }
+}
+
+///
+/// GET requests with a rate limiter and a few retries on 429 and server errors, waiting on the injected clock.
+/// Errors never carry request headers, so keys and signatures do not reach the logs (trap 17).
+///
+public sealed class ApiHttp(HttpClient http, IClock clock, string sourceName)
+{
+ public const int Attempts = 4;
+
+ public string SourceName { get; } = sourceName;
+
+ public HttpClient Client { get; } = http;
+
+ public async Task GetStringAsync(Uri url, RateLimiter? limiter, IReadOnlyDictionary? headers, CancellationToken cancellationToken)
+ {
+ var bytes = await GetBytesAsync(url, limiter, headers, cancellationToken).ConfigureAwait(false);
+ return Encoding.UTF8.GetString(bytes ?? throw new MarketDataException($"{SourceName}: nessun dato a {Describe(url)}.", retryable: false));
+ }
+
+ /// The body of a successful response; null for 404, which several archives use for "not published yet".
+ public async Task GetBytesAsync(Uri url, RateLimiter? limiter, IReadOnlyDictionary? headers, CancellationToken cancellationToken)
+ {
+ ArgumentNullException.ThrowIfNull(url);
+ for (var attempt = 1; ; attempt++)
+ {
+ if (limiter is not null)
+ {
+ await limiter.WaitAsync(cancellationToken).ConfigureAwait(false);
+ }
+
+ using var request = new HttpRequestMessage(HttpMethod.Get, url);
+ foreach (var (name, value) in headers ?? new Dictionary())
+ {
+ request.Headers.TryAddWithoutValidation(name, value);
+ }
+
+ HttpResponseMessage response;
+ try
+ {
+ response = await Client.SendAsync(request, cancellationToken).ConfigureAwait(false);
+ }
+ catch (HttpRequestException ex) when (attempt < Attempts)
+ {
+ _ = ex;
+ await BackOffAsync(attempt, null, cancellationToken).ConfigureAwait(false);
+ continue;
+ }
+ catch (HttpRequestException ex)
+ {
+ throw new MarketDataException($"{SourceName}: rete non raggiungibile ({Describe(url)}).", retryable: true, ex);
+ }
+ catch (TaskCanceledException ex) when (!cancellationToken.IsCancellationRequested)
+ {
+ if (attempt < Attempts)
+ {
+ await BackOffAsync(attempt, null, cancellationToken).ConfigureAwait(false);
+ continue;
+ }
+
+ throw new MarketDataException($"{SourceName}: nessuna risposta entro il tempo massimo ({Describe(url)}).", retryable: true, ex);
+ }
+
+ using (response)
+ {
+ if (response.StatusCode == HttpStatusCode.NotFound)
+ {
+ return null;
+ }
+
+ if (response.StatusCode == HttpStatusCode.TooManyRequests || (int)response.StatusCode >= 500)
+ {
+ if (attempt < Attempts)
+ {
+ await BackOffAsync(attempt, RetryAfter(response), cancellationToken).ConfigureAwait(false);
+ continue;
+ }
+
+ throw new MarketDataException($"{SourceName}: risposta {(int)response.StatusCode} ripetuta da {Describe(url)}.", retryable: true);
+ }
+
+ if (!response.IsSuccessStatusCode)
+ {
+ var text = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+ throw new MarketDataException(
+ $"{SourceName}: risposta {(int)response.StatusCode} da {Describe(url)}: {Redactor.Redact(Shorten(text))}",
+ retryable: response.StatusCode is HttpStatusCode.RequestTimeout);
+ }
+
+ return await response.Content.ReadAsByteArrayAsync(cancellationToken).ConfigureAwait(false);
+ }
+ }
+ }
+
+ /// Waits 2, 4, 8 seconds…, or what the server asked for, on the injected clock.
+ public Task BackOffAsync(int attempt, TimeSpan? requested, CancellationToken cancellationToken)
+ {
+ var wait = requested ?? TimeSpan.FromSeconds(Math.Pow(2, attempt));
+ if (wait > TimeSpan.FromMinutes(2))
+ {
+ wait = TimeSpan.FromMinutes(2);
+ }
+
+ return clock.WaitUntilAsync(clock.UtcNow + wait, cancellationToken);
+ }
+
+ /// The address without its query, which may carry a key (FRED, Finnhub).
+ public static string Describe(Uri url) => url?.GetLeftPart(UriPartial.Path) ?? "";
+
+ private TimeSpan? RetryAfter(HttpResponseMessage response)
+ {
+ if (response.Headers.RetryAfter?.Delta is { } delta)
+ {
+ return delta;
+ }
+
+ // Alpaca: X-RateLimit-Reset is the UNIX second at which the window reopens.
+ if (response.Headers.TryGetValues("X-RateLimit-Reset", out var values)
+ && long.TryParse(values.FirstOrDefault(), System.Globalization.NumberStyles.None, System.Globalization.CultureInfo.InvariantCulture, out var reset))
+ {
+ var wait = DateTimeOffset.FromUnixTimeSeconds(reset) - clock.UtcNow;
+ return wait > TimeSpan.Zero ? wait + TimeSpan.FromSeconds(1) : TimeSpan.FromSeconds(1);
+ }
+
+ return null;
+ }
+
+ private static string Shorten(string text) => text.Length <= 300 ? text : text[..300] + "…";
+}
+
+/// A text WebSocket. Behind an interface so tests can play a recorded conversation.
+public interface IWebSocketTransport : IAsyncDisposable
+{
+ Task ConnectAsync(Uri url, IReadOnlyDictionary? headers, CancellationToken cancellationToken);
+
+ Task SendAsync(string text, CancellationToken cancellationToken);
+
+ /// The next text message, or null when the connection closed.
+ Task ReceiveAsync(CancellationToken cancellationToken);
+}
+
+/// The real transport on .
+public sealed class ClientWebSocketTransport : IWebSocketTransport
+{
+ private readonly ClientWebSocket _socket = new();
+
+ public async Task ConnectAsync(Uri url, IReadOnlyDictionary? headers, CancellationToken cancellationToken)
+ {
+ foreach (var (name, value) in headers ?? new Dictionary())
+ {
+ _socket.Options.SetRequestHeader(name, value);
+ }
+
+ _socket.Options.KeepAliveInterval = TimeSpan.FromSeconds(20);
+ await _socket.ConnectAsync(url, cancellationToken).ConfigureAwait(false);
+ }
+
+ public Task SendAsync(string text, CancellationToken cancellationToken) =>
+ _socket.SendAsync(Encoding.UTF8.GetBytes(text), WebSocketMessageType.Text, endOfMessage: true, cancellationToken);
+
+ public async Task ReceiveAsync(CancellationToken cancellationToken)
+ {
+ var buffer = new byte[16 * 1024];
+ using var message = new MemoryStream();
+ while (true)
+ {
+ WebSocketReceiveResult result;
+ try
+ {
+ result = await _socket.ReceiveAsync(buffer, cancellationToken).ConfigureAwait(false);
+ }
+ catch (WebSocketException)
+ {
+ return null;
+ }
+
+ if (result.MessageType == WebSocketMessageType.Close)
+ {
+ return null;
+ }
+
+ message.Write(buffer, 0, result.Count);
+ if (message.Length > 4 * 1024 * 1024)
+ {
+ return null;
+ }
+
+ if (result.EndOfMessage)
+ {
+ return Encoding.UTF8.GetString(message.GetBuffer(), 0, (int)message.Length);
+ }
+ }
+ }
+
+ public async ValueTask DisposeAsync()
+ {
+ if (_socket.State == WebSocketState.Open)
+ {
+ using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(2));
+ try
+ {
+ await _socket.CloseAsync(WebSocketCloseStatus.NormalClosure, "bye", timeout.Token).ConfigureAwait(false);
+ }
+ catch (Exception ex) when (ex is WebSocketException or OperationCanceledException)
+ {
+ // Closing is a courtesy: the socket is dropped anyway.
+ }
+ }
+
+ _socket.Dispose();
+ }
+}
diff --git a/src/Anubis/Brokers/Okx.cs b/src/Anubis/Brokers/Okx.cs
new file mode 100644
index 0000000..4102005
--- /dev/null
+++ b/src/Anubis/Brokers/Okx.cs
@@ -0,0 +1,447 @@
+using System.Globalization;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Channels;
+using Anubis.Core;
+using Anubis.Data;
+
+namespace Anubis.Brokers;
+
+/// Addresses of OKX Europe (SPEC 4.2, docs re-read on 10/11/2026: API-NOTES).
+public sealed record OkxOptions
+{
+ public Uri RestUrl { get; init; } = new("https://eea.okx.com");
+
+ public Uri PublicStreamUrl { get; init; } = new("wss://wseea.okx.com/ws/v5/public");
+
+ /// Candle channels live here, not on the public stream (error 60018 otherwise).
+ public Uri BusinessStreamUrl { get; init; } = new("wss://wseea.okx.com/ws/v5/business");
+
+ /// Demo trading: same REST address with the x-simulated-trading: 1 header, other stream host.
+ public bool Demo { get; init; }
+
+ /// Quote currency traded. Only EUR: USDT is not tradable in Europe (trap 14) and USDC pairs are not used (SPEC 8.1).
+ public string QuoteCurrency { get; init; } = "EUR";
+
+ /// Seconds without messages before the stream sends ping; the server drops a silent connection after 30.
+ public TimeSpan PingAfter { get; init; } = TimeSpan.FromSeconds(20);
+
+ public static OkxOptions ForDemo() => new()
+ {
+ Demo = true,
+ PublicStreamUrl = new("wss://wseeapap.okx.com/ws/v5/public"),
+ BusinessStreamUrl = new("wss://wseeapap.okx.com/ws/v5/business"),
+ };
+}
+
+/// Key, secret and passphrase of an OKX API key. Never logged (trap 17).
+public sealed record OkxCredentials(string Key, string Secret, string Passphrase)
+{
+ public override string ToString() => "OkxCredentials(***)";
+}
+
+///
+/// The REST signature of OKX: Base64(HMAC-SHA256(secret, timestamp + method + path with query + body)), with the
+/// timestamp in ISO 8601 UTC with milliseconds. Used by the order part in Phase 3; written here with its test.
+///
+public static class OkxSigner
+{
+ public static string Timestamp(DateTimeOffset at) => at.UtcDateTime.ToString("yyyy-MM-dd'T'HH:mm:ss.fff'Z'", CultureInfo.InvariantCulture);
+
+ public static string Sign(string timestamp, string method, string requestPath, string body, string secret)
+ {
+ ArgumentNullException.ThrowIfNull(secret);
+ var payload = Encoding.UTF8.GetBytes(timestamp + method.ToUpperInvariant() + requestPath + body);
+ return Convert.ToBase64String(HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), payload));
+ }
+
+ public static Dictionary Headers(OkxCredentials credentials, DateTimeOffset at, string method, string requestPath, string body, bool demo)
+ {
+ ArgumentNullException.ThrowIfNull(credentials);
+ var timestamp = Timestamp(at);
+ var headers = new Dictionary
+ {
+ ["OK-ACCESS-KEY"] = credentials.Key,
+ ["OK-ACCESS-SIGN"] = Sign(timestamp, method, requestPath, body, credentials.Secret),
+ ["OK-ACCESS-TIMESTAMP"] = timestamp,
+ ["OK-ACCESS-PASSPHRASE"] = credentials.Passphrase,
+ };
+ if (demo)
+ {
+ headers["x-simulated-trading"] = "1";
+ }
+
+ return headers;
+ }
+}
+
+/// Funding rate of a perpetual swap: an indicator of crowding (SPEC 10.4).
+public sealed record FundingRate(string InstrumentId, double Rate, DateTimeOffset FundingTime, TimeSpan Interval, DateTimeOffset At);
+
+/// Open interest of a perpetual swap, in coins and dollars.
+public sealed record OpenInterest(string InstrumentId, double Coins, double Usd, DateTimeOffset At);
+
+///
+/// The data part of the OKX Europe adapter (issue #18), written in house: instruments with their rules, daily
+/// candles that close at 00:00 UTC (1Dutc, trap 23), one-minute candles, ticker and the live streams.
+/// Every answer carries code: OKX reports errors with HTTP 200, so the code is what counts.
+///
+public sealed class OkxClient : IMarketDataSource
+{
+ /// Daily bars: 1D opens at 16:00 UTC (Hong Kong midnight), 1Dutc at 00:00 UTC.
+ public const string DailyBar = "1Dutc";
+
+ /// Rows per candle request (the documented maximum for both endpoints).
+ public const int CandleLimit = 300;
+
+ private readonly ApiHttp _http;
+ private readonly IClock _clock;
+ private readonly OkxOptions _options;
+ private readonly Func _sockets;
+
+ // Published limits, with some room: candles 40/2s, history 20/2s, instruments, ticker 20/2s, funding 10/2s.
+ private readonly RateLimiter _candles;
+ private readonly RateLimiter _history;
+ private readonly RateLimiter _public;
+ private readonly RateLimiter _derivatives;
+
+ public OkxClient(HttpClient http, IClock clock, OkxOptions? options = null, Func? sockets = null)
+ {
+ _clock = clock;
+ _options = options ?? new OkxOptions();
+ _http = new ApiHttp(http, clock, "OKX");
+ _sockets = sockets ?? (() => new ClientWebSocketTransport());
+ _candles = new RateLimiter(clock, 30, TimeSpan.FromSeconds(2));
+ _history = new RateLimiter(clock, 15, TimeSpan.FromSeconds(2));
+ _public = new RateLimiter(clock, 15, TimeSpan.FromSeconds(2));
+ _derivatives = new RateLimiter(clock, 8, TimeSpan.FromSeconds(2));
+ }
+
+ public string Venue => Venues.Okx;
+
+ public async Task> ListInstrumentsAsync(CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync("/api/v5/public/instruments?instType=SPOT", _public, cancellationToken).ConfigureAwait(false);
+ var list = new List();
+ foreach (var item in json.RootElement.GetProperty("data").EnumerateArray())
+ {
+ var quote = Text(item, "quoteCcy");
+ if (quote != _options.QuoteCurrency)
+ {
+ continue;
+ }
+
+ var baseCcy = Text(item, "baseCcy");
+ list.Add(new InstrumentSpec(Venues.Okx, Text(item, "instId"), baseCcy + "/" + quote, AssetClasses.Crypto, quote)
+ {
+ BaseCurrency = baseCcy,
+ TickSize = DecimalOrNull(item, "tickSz"),
+ LotSize = DecimalOrNull(item, "lotSz"),
+ MinSize = DecimalOrNull(item, "minSz"),
+ Status = Text(item, "state"),
+ ListedAt = Text(item, "listTime") is { Length: > 0 } ms ? Millis(ms) : null,
+ });
+ }
+
+ return list;
+ }
+
+ public async Task> FetchDailyBarsAsync(string symbol, DateOnly first, DateOnly last, CancellationToken cancellationToken)
+ {
+ var from = QualityChecks.Midnight(first);
+ var until = QualityChecks.Midnight(last.AddDays(1));
+ var rows = await CandlesAsync(symbol, DailyBar, from, until, useHistory: true, cancellationToken).ConfigureAwait(false);
+ var bars = new List(rows.Count);
+ foreach (var row in rows)
+ {
+ if (row.OpensAt.TimeOfDay != TimeSpan.Zero)
+ {
+ throw new MarketDataException($"OKX: la candela giornaliera di {symbol} apre alle {row.OpensAt:HH:mm} UTC e non a mezzanotte.", retryable: false);
+ }
+
+ bars.Add(new DailyBar(DateOnly.FromDateTime(row.OpensAt.UtcDateTime), row.Open, row.High, row.Low, row.Close, row.Volume)
+ {
+ QuoteVolume = row.QuoteVolume,
+ });
+ }
+
+ return bars;
+ }
+
+ public async Task> FetchMinuteBarsAsync(string symbol, DateTimeOffset start, DateTimeOffset until, CancellationToken cancellationToken)
+ {
+ // The recent endpoint holds the last 1,440 candles; older ones come from the history endpoint.
+ var useHistory = start < _clock.UtcNow.AddMinutes(-1400);
+ return await CandlesAsync(symbol, "1m", start, until, useHistory, cancellationToken).ConfigureAwait(false);
+ }
+
+ public async Task FetchQuoteAsync(string symbol, CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync("/api/v5/market/ticker?instId=" + Uri.EscapeDataString(symbol), _public, cancellationToken).ConfigureAwait(false);
+ var data = json.RootElement.GetProperty("data");
+ if (data.GetArrayLength() == 0)
+ {
+ throw new MarketDataException("OKX: nessuna quotazione per " + symbol, retryable: false);
+ }
+
+ return ReadTicker(data[0]);
+ }
+
+ /// Funding rate of a perpetual swap, e.g. BTC-USDT-SWAP: public data, used only as an indicator.
+ public async Task FetchFundingRateAsync(string swap, CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync("/api/v5/public/funding-rate?instId=" + Uri.EscapeDataString(swap), _derivatives, cancellationToken).ConfigureAwait(false);
+ var item = json.RootElement.GetProperty("data")[0];
+ var fundingTime = Millis(Text(item, "fundingTime"));
+ var next = Text(item, "nextFundingTime") is { Length: > 0 } n ? Millis(n) : fundingTime.AddHours(8);
+ return new FundingRate(swap, Double(item, "fundingRate"), fundingTime, next - fundingTime, Millis(Text(item, "ts")));
+ }
+
+ public async Task FetchOpenInterestAsync(string swap, CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync("/api/v5/public/open-interest?instType=SWAP&instId=" + Uri.EscapeDataString(swap), _derivatives, cancellationToken)
+ .ConfigureAwait(false);
+ var item = json.RootElement.GetProperty("data")[0];
+ return new OpenInterest(swap, Double(item, "oiCcy"), Double(item, "oiUsd"), Millis(Text(item, "ts")));
+ }
+
+ /// Server time, to check the local clock.
+ public async Task ServerTimeAsync(CancellationToken cancellationToken)
+ {
+ using var json = await GetAsync("/api/v5/public/time", _public, cancellationToken).ConfigureAwait(false);
+ return Millis(Text(json.RootElement.GetProperty("data")[0], "ts"));
+ }
+
+ public async IAsyncEnumerable StreamAsync(IReadOnlyCollection symbols, [EnumeratorCancellation] CancellationToken cancellationToken)
+ {
+ ArgumentNullException.ThrowIfNull(symbols);
+ if (symbols.Count == 0)
+ {
+ yield break;
+ }
+
+ var channel = Channel.CreateUnbounded(new UnboundedChannelOptions { SingleReader = true });
+ using var stop = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+ var tickers = RunSocketAsync(_options.PublicStreamUrl, symbols.Select(s => ("tickers", s)), channel.Writer, stop.Token);
+ var candles = RunSocketAsync(_options.BusinessStreamUrl, symbols.Select(s => ("candle1m", s)), channel.Writer, stop.Token);
+
+ // The feed ends as soon as one of the two connections drops: the collector reconnects both and recovers the gap.
+ var ended = Task.WhenAny(tickers, candles).ContinueWith(t => channel.Writer.TryComplete(t.Result.Exception?.InnerException),
+ CancellationToken.None, TaskContinuationOptions.ExecuteSynchronously, TaskScheduler.Default);
+ try
+ {
+ await foreach (var item in channel.Reader.ReadAllAsync(cancellationToken).ConfigureAwait(false))
+ {
+ yield return item;
+ }
+ }
+ finally
+ {
+ await stop.CancelAsync().ConfigureAwait(false);
+ await Task.WhenAll(Quietly(tickers), Quietly(candles), ended).ConfigureAwait(false);
+ }
+ }
+
+ private async Task RunSocketAsync(Uri url, IEnumerable<(string Channel, string Symbol)> subscriptions, ChannelWriter writer, CancellationToken cancellationToken)
+ {
+ await using var socket = _sockets();
+ await socket.ConnectAsync(url, null, cancellationToken).ConfigureAwait(false);
+ var args = subscriptions.Select(s => new Dictionary { ["channel"] = s.Channel, ["instId"] = s.Symbol }).ToList();
+ await socket.SendAsync(JsonSerializer.Serialize(new { id = "1", op = "subscribe", args }), cancellationToken).ConfigureAwait(false);
+
+ var receive = socket.ReceiveAsync(cancellationToken);
+ var lastMessage = _clock.UtcNow;
+ var pinged = false;
+ while (true)
+ {
+ using var tick = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+ var timer = _clock.WaitUntilAsync(lastMessage + _options.PingAfter, tick.Token);
+ var done = await Task.WhenAny(receive, timer).ConfigureAwait(false);
+ if (done != timer)
+ {
+ await tick.CancelAsync().ConfigureAwait(false);
+ }
+ else
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ if (pinged)
+ {
+ return; // No pong either: the connection is dead even if it looks open (trap 10).
+ }
+
+ await socket.SendAsync("ping", cancellationToken).ConfigureAwait(false);
+ pinged = true;
+ lastMessage = _clock.UtcNow;
+ continue;
+ }
+
+ var message = await receive.ConfigureAwait(false);
+ if (message is null)
+ {
+ return;
+ }
+
+ lastMessage = _clock.UtcNow;
+ pinged = false;
+ receive = socket.ReceiveAsync(cancellationToken);
+ if (message == "pong")
+ {
+ continue;
+ }
+
+ foreach (var item in ParseStreamMessage(message))
+ {
+ await writer.WriteAsync(item, cancellationToken).ConfigureAwait(false);
+ }
+ }
+ }
+
+ /// Events in one message of the public or business stream. Subscriptions and notices give none.
+ public static IReadOnlyList ParseStreamMessage(string message)
+ {
+ using var json = JsonDocument.Parse(message);
+ var root = json.RootElement;
+ if (root.TryGetProperty("event", out var evt))
+ {
+ if (evt.GetString() == "error")
+ {
+ throw new MarketDataException($"OKX: errore del flusso {Text(root, "code")}: {Text(root, "msg")}", retryable: false);
+ }
+
+ return [];
+ }
+
+ if (!root.TryGetProperty("arg", out var arg) || !root.TryGetProperty("data", out var data))
+ {
+ return [];
+ }
+
+ var channel = Text(arg, "channel");
+ var symbol = Text(arg, "instId");
+ var events = new List();
+ foreach (var item in data.EnumerateArray())
+ {
+ if (channel == "tickers")
+ {
+ events.Add(new QuoteEvent(ReadTicker(item)));
+ }
+ else if (channel.StartsWith("candle", StringComparison.Ordinal))
+ {
+ var bar = ReadCandle(item);
+ events.Add(new BarEvent(symbol, bar.Bar, bar.Confirmed));
+ }
+ }
+
+ return events;
+ }
+
+ /// Candles opening in [from, until), oldest first, closed only. Pages backwards with after (rows older than it).
+ private async Task> CandlesAsync(string symbol, string bar, DateTimeOffset from, DateTimeOffset until, bool useHistory, CancellationToken cancellationToken)
+ {
+ var found = new SortedDictionary();
+ var cursor = until;
+ while (cursor > from)
+ {
+ var path = $"/api/v5/market/{(useHistory ? "history-candles" : "candles")}?instId={Uri.EscapeDataString(symbol)}&bar={bar}" +
+ $"&after={cursor.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture)}&limit={CandleLimit}";
+ using var json = await GetAsync(path, useHistory ? _history : _candles, cancellationToken).ConfigureAwait(false);
+ var rows = json.RootElement.GetProperty("data");
+ if (rows.GetArrayLength() == 0)
+ {
+ break; // Before the first candle of the instrument.
+ }
+
+ var oldest = cursor;
+ foreach (var row in rows.EnumerateArray())
+ {
+ var candle = ReadCandle(row);
+ oldest = candle.Bar.OpensAt < oldest ? candle.Bar.OpensAt : oldest;
+ if (candle.Confirmed && candle.Bar.OpensAt >= from && candle.Bar.OpensAt < until)
+ {
+ found[candle.Bar.OpensAt] = candle.Bar;
+ }
+ }
+
+ if (oldest >= cursor)
+ {
+ break;
+ }
+
+ cursor = oldest;
+ }
+
+ return found.Values.ToList();
+ }
+
+ private async Task GetAsync(string pathAndQuery, RateLimiter limiter, CancellationToken cancellationToken)
+ {
+ var headers = _options.Demo ? new Dictionary { ["x-simulated-trading"] = "1" } : null;
+ for (var attempt = 1; ; attempt++)
+ {
+ var text = await _http.GetStringAsync(new Uri(_options.RestUrl, pathAndQuery), limiter, headers, cancellationToken).ConfigureAwait(false);
+ var json = JsonDocument.Parse(text);
+ var code = Text(json.RootElement, "code");
+ if (code == "0")
+ {
+ return json;
+ }
+
+ var message = Text(json.RootElement, "msg");
+ json.Dispose();
+
+ // 50011 too many requests, 50013 busy, 50001 unavailable, 50026 system error: wait and retry.
+ if (code is "50011" or "50013" or "50001" or "50026" && attempt < ApiHttp.Attempts)
+ {
+ await _http.BackOffAsync(attempt, null, cancellationToken).ConfigureAwait(false);
+ continue;
+ }
+
+ throw new MarketDataException($"OKX: errore {code}: {message}", retryable: code.StartsWith('5') && code.Length == 5 && code[1] == '0');
+ }
+ }
+
+ internal static (Bar Bar, bool Confirmed) ReadCandle(JsonElement row)
+ {
+ // [ts, o, h, l, c, vol (base), volCcy, volCcyQuote (quote), confirm]
+ var bar = new Bar(Millis(row[0].GetString()!), Number(row[1]), Number(row[2]), Number(row[3]), Number(row[4]), Number(row[5]))
+ {
+ QuoteVolume = row.GetArrayLength() > 7 && row[7].GetString() is { Length: > 0 } q ? double.Parse(q, CultureInfo.InvariantCulture) : null,
+ };
+ return (bar, row.GetArrayLength() <= 8 || row[8].GetString() == "1");
+ }
+
+ private static Quote ReadTicker(JsonElement item) =>
+ new(Text(item, "instId"), DecimalOrNull(item, "bidPx") ?? 0m, DecimalOrNull(item, "askPx") ?? 0m, Millis(Text(item, "ts")))
+ {
+ BidSize = DecimalOrNull(item, "bidSz"),
+ AskSize = DecimalOrNull(item, "askSz"),
+ };
+
+ private static async Task Quietly(Task task)
+ {
+ try
+ {
+ await task.ConfigureAwait(false);
+ }
+ catch (Exception ex) when (ex is OperationCanceledException or MarketDataException or System.Net.WebSockets.WebSocketException or JsonException)
+ {
+ // Already reported through the channel, or the feed was stopped on purpose.
+ }
+ }
+
+ private static DateTimeOffset Millis(string text) =>
+ DateTimeOffset.FromUnixTimeMilliseconds(long.Parse(text, NumberStyles.None, CultureInfo.InvariantCulture));
+
+ private static string Text(JsonElement item, string name) =>
+ item.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String ? value.GetString()! : "";
+
+ private static double Number(JsonElement value) => double.Parse(value.GetString()!, CultureInfo.InvariantCulture);
+
+ private static double Double(JsonElement item, string name) =>
+ Text(item, name) is { Length: > 0 } text ? double.Parse(text, CultureInfo.InvariantCulture) : double.NaN;
+
+ private static decimal? DecimalOrNull(JsonElement item, string name) =>
+ Text(item, name) is { Length: > 0 } text ? decimal.Parse(text, NumberStyles.Float, CultureInfo.InvariantCulture) : null;
+}
diff --git a/tests/Anubis.Tests/AlpacaTests.cs b/tests/Anubis.Tests/AlpacaTests.cs
new file mode 100644
index 0000000..383eec3
--- /dev/null
+++ b/tests/Anubis.Tests/AlpacaTests.cs
@@ -0,0 +1,195 @@
+using System.Text.Json;
+using Anubis.Brokers;
+using Anubis.Data;
+
+namespace Anubis.Tests;
+
+///
+/// The data part of the Alpaca adapter on the documentation's examples and synthetic answers (issue #19). Without
+/// the user's keys nothing here touches the network; the real check waits for them (SPEC 2.3).
+///
+[TestClass]
+public sealed class AlpacaTests
+{
+ private static readonly DateTimeOffset _now = new(2026, 11, 10, 15, 0, 0, TimeSpan.Zero);
+ private static readonly AlpacaCredentials _keys = new("PKTEST", "test-secret-value");
+
+ private static (AlpacaClient Client, FakeHttp Http) Create(Action setup, AlpacaCredentials? keys = null)
+ {
+ var http = new FakeHttp();
+ setup(http);
+ return (new AlpacaClient(http.Client(), new FastClock(_now), keys ?? _keys), http);
+ }
+
+ private static string Query(HttpRequestMessage request, string name) =>
+ System.Web.HttpUtility.ParseQueryString(request.RequestUri!.Query)[name] ?? "";
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task WithoutKeysNothingIsSentAndTheReasonIsClear()
+ {
+ var http = new FakeHttp();
+ var alpaca = new AlpacaClient(http.Client(), new FastClock(_now), credentials: null);
+ Assert.IsFalse(alpaca.IsConfigured);
+ var error = await Assert.ThrowsAsync(() => alpaca.FetchQuoteAsync("AAPL", CancellationToken.None)).ConfigureAwait(false);
+ StringAssert.Contains(error.Message, "mancano le chiavi");
+ Assert.IsFalse(error.Retryable);
+ Assert.IsEmpty(http.Requests);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task DailyBarsAreConsolidatedWithRealAndAdjustedPricesByNewYorkDate()
+ {
+ const string raw = """
+ {"bars":{"AAPL":[
+ {"t":"2023-09-29T04:00:00Z","o":172.02,"h":173.07,"l":170.341,"c":171.21,"v":51861083,"n":535134,"vw":171.599691},
+ {"t":"2024-01-02T05:00:00Z","o":187.15,"h":188.44,"l":183.885,"c":185.64,"v":82488674,"n":1009074,"vw":185.9}
+ ]},"next_page_token":null}
+ """;
+ const string adjusted = """
+ {"bars":{"AAPL":[
+ {"t":"2023-09-29T04:00:00Z","o":170.0,"h":171.0,"l":168.3,"c":169.2,"v":51861083,"n":535134,"vw":169.6},
+ {"t":"2024-01-02T05:00:00Z","o":185.0,"h":186.2,"l":181.7,"c":183.4,"v":82488674,"n":1009074,"vw":183.7}
+ ]},"next_page_token":null}
+ """;
+ var (alpaca, http) = Create(h => h.On("adjustment=raw", raw).On("adjustment=all", adjusted));
+ var bars = await alpaca.FetchDailyBarsAsync("AAPL", new DateOnly(2023, 9, 1), new DateOnly(2024, 1, 31), CancellationToken.None).ConfigureAwait(false);
+
+ // T04:00Z in summer and T05:00Z in winter are both midnight in New York.
+ CollectionAssert.AreEqual(new[] { new DateOnly(2023, 9, 29), new DateOnly(2024, 1, 2) }, bars.Select(b => b.Day).ToArray());
+ Assert.AreEqual((172.02, 171.21, 51861083.0), (bars[0].Open, bars[0].Close, bars[0].Volume));
+ Assert.AreEqual(new Ohlc(170.0, 171.0, 168.3, 169.2), bars[0].Adjusted);
+
+ foreach (var request in http.Requests)
+ {
+ // Consolidated volumes, never IEX (trap 8); the feed is always explicit.
+ Assert.AreEqual("sip", Query(request, "feed"));
+ Assert.AreEqual("1Day", Query(request, "timeframe"));
+ Assert.AreEqual("PKTEST", request.Headers.GetValues("APCA-API-KEY-ID").Single());
+ Assert.AreEqual("data.alpaca.markets", request.RequestUri!.Host);
+ }
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task RecentDaysWaitFifteenMinutesForTheConsolidatedTape()
+ {
+ var (alpaca, http) = Create(h => h.On("/v2/stocks/bars", """{"bars":{},"next_page_token":null}"""));
+ await alpaca.FetchDailyBarsAsync("AAPL", new DateOnly(2026, 11, 1), new DateOnly(2026, 11, 10), CancellationToken.None).ConfigureAwait(false);
+ var end = DateTimeOffset.Parse(Query(http.Requests[0], "end"), System.Globalization.CultureInfo.InvariantCulture);
+ Assert.IsLessThanOrEqualTo(_now.AddMinutes(-15), end, "a free plan may ask the SIP only for data at least 15 minutes old");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task PagesAreFollowedUntilTheTokenIsNull()
+ {
+ var (alpaca, http) = Create(h => h
+ .On("page_token=", """{"bars":{},"next_page_token":null}""")
+ .On("/v2/stocks/bars", Fixture.Text("alpaca/stocks-bars.json")));
+ var from = new DateTimeOffset(2022, 1, 3, 9, 0, 0, TimeSpan.Zero);
+ var bars = await alpaca.FetchMinuteBarsAsync("AAPL", from, from.AddMinutes(1), CancellationToken.None).ConfigureAwait(false);
+ Assert.HasCount(2, http.Requests);
+ Assert.AreEqual("QUFQTHxNfDIwMjItMDEtMDNUMDk6MDA6MDAuMDAwMDAwMDAwWg==", Query(http.Requests[1], "page_token"));
+ Assert.AreEqual("sip", Query(http.Requests[0], "feed"), "old minutes come from the consolidated tape");
+ Assert.AreEqual(new Bar(from, 178.26, 178.26, 178.21, 178.21, 1118), bars.Single());
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task RecentMinutesAndQuotesComeFromIex()
+ {
+ var (alpaca, http) = Create(h => h
+ .On("/v2/stocks/bars", """{"bars":{},"next_page_token":null}""")
+ .On("/v2/stocks/quotes/latest", Fixture.Text("alpaca/quotes-latest.json")));
+ await alpaca.FetchMinuteBarsAsync("AAPL", _now.AddMinutes(-10), _now, CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual("iex", Query(http.Requests[0], "feed"));
+
+ var quote = await alpaca.FetchQuoteAsync("AAPL", CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual("iex", Query(http.Requests[1], "feed"));
+ Assert.AreEqual((172.62m, 172.7m, 2m, 1m), (quote.Bid, quote.Ask, quote.BidSize, quote.AskSize));
+ Assert.AreEqual(new DateTimeOffset(2022, 8, 17, 10, 7, 40, TimeSpan.Zero).AddTicks(2865874), quote.At);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public void CorporateActionsOfTheDocumentation()
+ {
+ using var json = JsonDocument.Parse(Fixture.Text("alpaca/corporate-actions.json"));
+ var actions = AlpacaClient.ReadCorporateActions(json.RootElement).ToDictionary(a => a.Symbol);
+
+ Assert.AreEqual((CorporateActionKinds.Split, new DateOnly(2023, 8, 22), (decimal?)2m), (actions["SRE"].Kind, actions["SRE"].ExDate, actions["SRE"].Ratio));
+ Assert.AreEqual(0.02m, actions["MNTS"].Ratio, "1-for-50 reverse split");
+ Assert.AreEqual((CorporateActionKinds.CashDividend, (decimal?)0.125m), (actions["FCF"].Kind, actions["FCF"].CashAmount));
+ Assert.AreEqual((CorporateActionKinds.StockDividend, (decimal?)1.05m), (actions["MSBC"].Kind, actions["MSBC"].Ratio));
+ Assert.AreEqual((CorporateActionKinds.SymbolChange, "VFS"), (actions["BSAQ"].Kind, actions["BSAQ"].NewSymbol));
+ Assert.IsTrue(actions.Values.All(a => a.SourceKey.StartsWith("alpaca:", StringComparison.Ordinal)));
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task CalendarTimesAreNewYorkConvertedToUtc()
+ {
+ const string calendar = """
+ [{"date":"2026-07-02","open":"09:30","close":"16:00","session_open":"0400","session_close":"2000","settlement_date":"2026-07-06"},
+ {"date":"2026-11-27","open":"09:30","close":"13:00","session_open":"0400","session_close":"1700","settlement_date":"2026-11-30"}]
+ """;
+ var (alpaca, http) = Create(h => h.On("/v2/calendar", calendar));
+ var sessions = await alpaca.FetchCalendarAsync(new DateOnly(2026, 7, 1), new DateOnly(2026, 11, 30), CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual("paper-api.alpaca.markets", http.Requests[0].RequestUri!.Host);
+ Assert.AreEqual(new DateTimeOffset(2026, 7, 2, 13, 30, 0, TimeSpan.Zero), sessions[0].OpenUtc, "summer: New York is UTC−4");
+ Assert.AreEqual(new DateTimeOffset(2026, 11, 27, 18, 0, 0, TimeSpan.Zero), sessions[1].CloseUtc, "short session after Thanksgiving, UTC−5");
+
+ using var clock = JsonDocument.Parse(Fixture.Text("alpaca/clock-v2.json"));
+ var read = AlpacaClient.ReadClock(clock.RootElement);
+ Assert.IsTrue(read.IsOpen);
+ Assert.AreEqual(new DateTimeOffset(2025, 6, 24, 20, 0, 0, TimeSpan.Zero), read.NextClose);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public void AssetsKeepExchangeStatusAndFractions()
+ {
+ using var json = JsonDocument.Parse(Fixture.Text("alpaca/assets.json"));
+ var spec = AlpacaClient.ReadAsset(json.RootElement);
+ Assert.AreEqual(("AAPL", "NASDAQ", "active", (bool?)true, "USD"), (spec.Symbol, spec.Exchange, spec.Status, spec.Fractionable, spec.QuoteCurrency));
+ Assert.IsNull(spec.IsFund, "Alpaca has no ETF flag: it comes from nasdaqtraded.txt");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task StreamStaysWithinThirtySymbolsAndReadsBarsAndQuotes()
+ {
+ var socket = new FakeSocket();
+ var alpaca = new AlpacaClient(new FakeHttp().Client(), new FastClock(_now), _keys, sockets: () => socket);
+ var many = Enumerable.Range(0, 31).Select(i => "S" + i).ToList();
+ await Assert.ThrowsAsync(async () =>
+ {
+ await foreach (var unused in alpaca.StreamAsync(many, CancellationToken.None).ConfigureAwait(false))
+ {
+ _ = unused;
+ }
+ }).ConfigureAwait(false);
+
+ socket.Push("""[{"T":"success","msg":"connected"}]""");
+ socket.Push("""[{"T":"success","msg":"authenticated"}]""");
+ socket.Push("""[{"T":"subscription","trades":[],"quotes":["FAKEPACA"],"bars":["FAKEPACA"]}]""");
+ socket.Push("""[{"T":"q","S":"FAKEPACA","bx":"O","bp":133.85,"bs":4,"ax":"R","ap":135.77,"as":5,"c":["R"],"z":"A","t":"2024-07-24T07:56:53.639713735Z"},{"T":"b","S":"FAKEPACA","o":133.8,"h":134.1,"l":133.7,"c":134.0,"v":1200,"t":"2024-07-24T07:56:00Z","n":12,"vw":133.9}]""");
+ socket.Close();
+ var events = new List();
+ await foreach (var item in alpaca.StreamAsync(["FAKEPACA"], CancellationToken.None).ConfigureAwait(false))
+ {
+ events.Add(item);
+ }
+
+ Assert.AreEqual(new Uri("wss://stream.data.alpaca.markets/v2/iex"), socket.Url);
+ StringAssert.Contains(socket.Sent[0], "\"action\":\"auth\"");
+ StringAssert.Contains(socket.Sent[1], "\"bars\":[\"FAKEPACA\"]");
+ Assert.AreEqual(133.85m, events.OfType().Single().Quote.Bid);
+ Assert.AreEqual(134.0, events.OfType().Single().Bar.Close);
+
+ var error = Assert.Throws(() => AlpacaClient.ParseStreamMessage("""[{"T":"error","code":405,"msg":"symbol limit exceeded"}]"""));
+ StringAssert.Contains(error.Message, "405");
+ }
+}
diff --git a/tests/Anubis.Tests/FakeNetwork.cs b/tests/Anubis.Tests/FakeNetwork.cs
new file mode 100644
index 0000000..bcf05ca
--- /dev/null
+++ b/tests/Anubis.Tests/FakeNetwork.cs
@@ -0,0 +1,146 @@
+using System.Net;
+using System.Text;
+using System.Threading.Channels;
+using Anubis.Brokers;
+
+namespace Anubis.Tests;
+
+/// Recorded responses saved under Fixtures/ (trap 12: no network in tests).
+internal static class Fixture
+{
+ public static string Path(string relative) => System.IO.Path.Combine(AppContext.BaseDirectory, "Fixtures", relative);
+
+ public static string Text(string relative) => File.ReadAllText(Path(relative));
+
+ public static byte[] Bytes(string relative) => File.ReadAllBytes(Path(relative));
+}
+
+///
+/// An HTTP handler that answers from a list of rules (first match wins) and records every request.
+/// A request no rule matches fails the test with its address.
+///
+internal sealed class FakeHttp : HttpMessageHandler
+{
+ private readonly List<(Func Match, Func Answer)> _rules = [];
+
+ public List Requests { get; } = [];
+
+ public HttpClient Client() => new(this, disposeHandler: false);
+
+ public FakeHttp On(Func match, Func answer)
+ {
+ _rules.Add((match, answer));
+ return this;
+ }
+
+ public FakeHttp On(string contains, string body, HttpStatusCode status = HttpStatusCode.OK) =>
+ On(u => u.ToString().Contains(contains, StringComparison.Ordinal), _ => Respond(body, status));
+
+ public FakeHttp OnBytes(string contains, byte[] body) =>
+ On(u => u.ToString().Contains(contains, StringComparison.Ordinal), _ => new HttpResponseMessage(HttpStatusCode.OK) { Content = new ByteArrayContent(body) });
+
+ public static HttpResponseMessage Respond(string body, HttpStatusCode status = HttpStatusCode.OK) =>
+ new(status) { Content = new StringContent(body, Encoding.UTF8, "application/json") };
+
+ public IEnumerable Urls => Requests.Select(r => r.RequestUri!);
+
+ protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+ {
+ lock (Requests)
+ {
+ Requests.Add(request);
+ }
+
+ foreach (var (match, answer) in _rules)
+ {
+ if (match(request.RequestUri!))
+ {
+ return Task.FromResult(answer(request));
+ }
+ }
+
+ throw new AssertFailedException("Unexpected request: " + request.RequestUri);
+ }
+}
+
+/// A WebSocket that plays messages pushed by the test and records what the client sends.
+internal sealed class FakeSocket : IWebSocketTransport
+{
+ private readonly Channel _incoming = Channel.CreateUnbounded();
+
+ public Uri? Url { get; private set; }
+
+ public IReadOnlyDictionary? Headers { get; private set; }
+
+ public List Sent { get; } = [];
+
+ public TaskCompletionSource Connected { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+ public bool Disposed { get; private set; }
+
+ public void Push(string message) => _incoming.Writer.TryWrite(message);
+
+ /// The server closes the connection.
+ public void Close() => _incoming.Writer.TryWrite(null);
+
+ public Task ConnectAsync(Uri url, IReadOnlyDictionary? headers, CancellationToken cancellationToken)
+ {
+ Url = url;
+ Headers = headers;
+ Connected.TrySetResult();
+ return Task.CompletedTask;
+ }
+
+ public Task SendAsync(string text, CancellationToken cancellationToken)
+ {
+ lock (Sent)
+ {
+ Sent.Add(text);
+ }
+
+ return Task.CompletedTask;
+ }
+
+ public async Task ReceiveAsync(CancellationToken cancellationToken) =>
+ await _incoming.Reader.ReadAsync(cancellationToken).ConfigureAwait(false);
+
+ public ValueTask DisposeAsync()
+ {
+ Disposed = true;
+ return ValueTask.CompletedTask;
+ }
+}
+
+/// A clock whose waits finish at once by moving time forward: back-offs and rate limits cost nothing in tests.
+internal sealed class FastClock(DateTimeOffset start) : Anubis.Core.IClock
+{
+ private readonly Lock _gate = new();
+ private DateTimeOffset _now = start;
+
+ public DateTimeOffset UtcNow
+ {
+ get
+ {
+ lock (_gate)
+ {
+ return _now;
+ }
+ }
+ }
+
+ public TimeSpan Waited { get; private set; }
+
+ public Task WaitUntilAsync(DateTimeOffset dueUtc, CancellationToken cancellationToken)
+ {
+ lock (_gate)
+ {
+ if (dueUtc > _now)
+ {
+ Waited += dueUtc - _now;
+ _now = dueUtc;
+ }
+ }
+
+ return Task.CompletedTask;
+ }
+}
diff --git a/tests/Anubis.Tests/OkxTests.cs b/tests/Anubis.Tests/OkxTests.cs
new file mode 100644
index 0000000..7a6e998
--- /dev/null
+++ b/tests/Anubis.Tests/OkxTests.cs
@@ -0,0 +1,246 @@
+using System.Security.Cryptography;
+using System.Text;
+using Anubis.Brokers;
+using Anubis.Core;
+using Anubis.Data;
+
+namespace Anubis.Tests;
+
+/// The data part of the OKX Europe adapter on recorded responses (issue #18).
+[TestClass]
+public sealed class OkxTests
+{
+ private static readonly DateTimeOffset _now = new(2026, 11, 10, 13, 45, 0, TimeSpan.Zero);
+
+ private static (OkxClient Client, FakeHttp Http) Create(Action setup, IClock? clock = null, OkxOptions? options = null)
+ {
+ var http = new FakeHttp();
+ setup(http);
+ return (new OkxClient(http.Client(), clock ?? new FastClock(_now), options), http);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task InstrumentsAreOnlyEuroPairsWithTheirRules()
+ {
+ var (okx, http) = Create(h => h.On("/api/v5/public/instruments?instType=SPOT", Fixture.Text("okx/instruments-spot.json")));
+ var list = await okx.ListInstrumentsAsync(CancellationToken.None).ConfigureAwait(false);
+
+ // USDT is not tradable in Europe (trap 14); USDC and PLN pairs are not used (SPEC 8.1).
+ CollectionAssert.AreEqual(new[] { "BTC-EUR", "ETH-EUR", "SOL-EUR" }, list.Select(i => i.Symbol).ToArray());
+ var btc = list[0];
+ Assert.AreEqual(new InstrumentSpec(Venues.Okx, "BTC-EUR", "BTC/EUR", AssetClasses.Crypto, "EUR")
+ {
+ BaseCurrency = "BTC",
+ TickSize = 0.1m,
+ LotSize = 0.00000001m,
+ MinSize = 0.0001m,
+ Status = "live",
+ ListedAt = new DateTimeOffset(2023, 11, 21, 4, 11, 0, TimeSpan.Zero),
+ }, btc);
+ Assert.IsTrue(http.Requests.All(r => r.RequestUri!.Host == "eea.okx.com"), "the European host");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task DailyCandlesCloseAtMidnightUtcAndSkipTheRunningDay()
+ {
+ var (okx, http) = Create(h => h.On("history-candles", Fixture.Text("okx/candles-1Dutc-btc-eur.json")));
+ var bars = await okx.FetchDailyBarsAsync("BTC-EUR", new DateOnly(2026, 11, 6), new DateOnly(2026, 11, 10), CancellationToken.None).ConfigureAwait(false);
+
+ var request = http.Requests.Single().RequestUri!.ToString();
+ StringAssert.Contains(request, "bar=1Dutc", "never 1D, which opens at 16:00 UTC (trap 23)");
+ StringAssert.Contains(request, "after=" + new DateTimeOffset(2026, 11, 11, 0, 0, 0, TimeSpan.Zero).ToUnixTimeMilliseconds());
+
+ // 10 November is still running (confirm 0) and is left out.
+ CollectionAssert.AreEqual(
+ new[] { new DateOnly(2026, 11, 6), new DateOnly(2026, 11, 7), new DateOnly(2026, 11, 8), new DateOnly(2026, 11, 9) },
+ bars.Select(b => b.Day).ToArray());
+ var last = bars[^1];
+ Assert.AreEqual((67102.9, 67730.8, 65957.5, 67058.9, 87.03419039), (last.Open, last.High, last.Low, last.Close, last.Volume));
+ Assert.AreEqual(5799147.867285542, last.QuoteVolume);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task HistoryPagesBackwardsUntilTheFirstCandle()
+ {
+ var first = new DateTimeOffset(2023, 11, 21, 0, 0, 0, TimeSpan.Zero).ToUnixTimeMilliseconds();
+ var (okx, http) = Create(h => h
+ .On("after=" + first, """{"code":"0","data":[],"msg":""}""")
+ .On("history-candles", Fixture.Text("okx/history-candles-1Dutc-btc-eur-first.json")));
+ var bars = await okx.FetchDailyBarsAsync("BTC-EUR", new DateOnly(2017, 1, 1), new DateOnly(2023, 11, 25), CancellationToken.None).ConfigureAwait(false);
+
+ Assert.HasCount(2, http.Requests, "the second page is empty: the history starts on 21 November 2023");
+ Assert.AreEqual(new DateOnly(2023, 11, 21), bars[0].Day);
+ Assert.AreEqual(new DateOnly(2023, 11, 25), bars[^1].Day);
+ Assert.HasCount(5, bars);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task ACandleThatDoesNotOpenAtMidnightIsRefused()
+ {
+ var sixteen = new DateTimeOffset(2026, 11, 8, 16, 0, 0, TimeSpan.Zero).ToUnixTimeMilliseconds();
+ var (okx, _) = Create(h => h.On("history-candles", $$"""{"code":"0","data":[["{{sixteen}}","1","2","0.5","1.5","3","4","4","1"]],"msg":""}"""));
+ var error = await Assert.ThrowsAsync(() =>
+ okx.FetchDailyBarsAsync("BTC-EUR", new DateOnly(2026, 11, 8), new DateOnly(2026, 11, 8), CancellationToken.None)).ConfigureAwait(false);
+ StringAssert.Contains(error.Message, "16:00");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task MinuteCandlesUseTheRecentEndpointForTheLastDay()
+ {
+ var (okx, http) = Create(h => h.On("/market/candles?", Fixture.Text("okx/candles-1m-btc-eur.json")));
+ var start = DateTimeOffset.FromUnixTimeMilliseconds(1794318000000);
+ var bars = await okx.FetchMinuteBarsAsync("BTC-EUR", start, start.AddMinutes(5), CancellationToken.None).ConfigureAwait(false);
+ Assert.HasCount(4, bars, "the running minute is left out");
+ Assert.AreEqual(start, bars[0].OpensAt);
+ StringAssert.Contains(http.Requests[0].RequestUri!.ToString(), "bar=1m");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task ErrorsArriveWithStatus200AndBusyAnswersAreRetried()
+ {
+ var calls = 0;
+ var clock = new FastClock(_now);
+ var (okx, _) = Create(h => h.On(_ => true, _ => ++calls == 1
+ ? FakeHttp.Respond("""{"code":"50011","data":[],"msg":"Rate limit reached"}""")
+ : FakeHttp.Respond(Fixture.Text("okx/ticker-btc-eur.json"))), clock);
+ var quote = await okx.FetchQuoteAsync("BTC-EUR", CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual(2, calls);
+ Assert.IsGreaterThanOrEqualTo(TimeSpan.FromSeconds(2), clock.Waited, "waits before trying again");
+ Assert.AreEqual((65986.1m, 65998.6m), (quote.Bid, quote.Ask));
+ Assert.AreEqual(0.02600011m, quote.BidSize);
+ Assert.AreEqual(DateTimeOffset.FromUnixTimeMilliseconds(1794318312368), quote.At);
+ Assert.AreEqual(1.894, quote.SpreadBp!.Value, 0.001);
+
+ var (unknown, _) = Create(h => h.On("ticker", """{"code":"51001","data":[],"msg":"Instrument ID, Instrument ID code, or Spread ID doesn't exist."}"""));
+ var error = await Assert.ThrowsAsync(() => unknown.FetchQuoteAsync("XXX-EUR", CancellationToken.None)).ConfigureAwait(false);
+ Assert.IsFalse(error.Retryable);
+ StringAssert.Contains(error.Message, "51001");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task DemoAddsTheSimulatedTradingHeader()
+ {
+ var (okx, http) = Create(h => h.On("ticker", Fixture.Text("okx/ticker-btc-eur.json")), options: OkxOptions.ForDemo());
+ await okx.FetchQuoteAsync("BTC-EUR", CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual("1", http.Requests[0].Headers.GetValues("x-simulated-trading").Single());
+ Assert.AreEqual("wseeapap.okx.com", OkxOptions.ForDemo().BusinessStreamUrl.Host);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task FundingRateAndOpenInterestOfBitcoin()
+ {
+ var (okx, _) = Create(h => h
+ .On("funding-rate", Fixture.Text("okx/funding-rate-btc.json"))
+ .On("open-interest", Fixture.Text("okx/open-interest-btc.json")));
+ var funding = await okx.FetchFundingRateAsync("BTC-USDT-SWAP", CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual(-0.0000009390698834, funding.Rate);
+ Assert.AreEqual(TimeSpan.FromHours(8), funding.Interval);
+ var interest = await okx.FetchOpenInterestAsync("BTC-USDT-SWAP", CancellationToken.None).ConfigureAwait(false);
+ Assert.AreEqual(36006.7700000001675, interest.Coins, 1e-6);
+ Assert.AreEqual(2659809297.869, interest.Usd, 0.01);
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public void SignatureIsHmacSha256OfTimestampMethodPathAndBody()
+ {
+ var at = new DateTimeOffset(2026, 11, 10, 13, 45, 1, 234, TimeSpan.Zero);
+ var credentials = new OkxCredentials("key-id", "secret-value", "pass-phrase");
+ var headers = OkxSigner.Headers(credentials, at, "get", "/api/v5/account/balance?ccy=EUR", "", demo: true);
+ Assert.AreEqual("2026-11-10T13:45:01.234Z", headers["OK-ACCESS-TIMESTAMP"]);
+ var expected = Convert.ToBase64String(HMACSHA256.HashData(Encoding.UTF8.GetBytes("secret-value"),
+ Encoding.UTF8.GetBytes("2026-11-10T13:45:01.234ZGET/api/v5/account/balance?ccy=EUR")));
+ Assert.AreEqual(expected, headers["OK-ACCESS-SIGN"]);
+ Assert.AreEqual("1", headers["x-simulated-trading"]);
+ Assert.AreEqual("OkxCredentials(***)", credentials.ToString(), "never printed");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public async Task StreamSubscribesTickersAndCandlesOnTheirHostsAndPingsWhenSilent()
+ {
+ var clock = new ManualClock(_now);
+ var sockets = new List();
+ var okx = new OkxClient(new FakeHttp().Client(), clock, sockets: () =>
+ {
+ var socket = new FakeSocket();
+ lock (sockets)
+ {
+ sockets.Add(socket);
+ }
+
+ return socket;
+ });
+
+ using var stop = new CancellationTokenSource(TimeSpan.FromSeconds(20));
+ var events = new List();
+ var reading = Task.Run(async () =>
+ {
+ await foreach (var item in okx.StreamAsync(["BTC-EUR", "ETH-EUR"], stop.Token).ConfigureAwait(false))
+ {
+ lock (events)
+ {
+ events.Add(item);
+ }
+ }
+ });
+
+ await WaitForAsync(() => sockets.Count == 2 && sockets.All(s => s.Sent.Count == 1)).ConfigureAwait(false);
+ var publicSocket = sockets.Single(s => s.Url!.AbsolutePath.EndsWith("/public", StringComparison.Ordinal));
+ var businessSocket = sockets.Single(s => s.Url!.AbsolutePath.EndsWith("/business", StringComparison.Ordinal));
+ StringAssert.Contains(publicSocket.Sent[0], "\"channel\":\"tickers\",\"instId\":\"ETH-EUR\"");
+ StringAssert.Contains(businessSocket.Sent[0], "\"channel\":\"candle1m\",\"instId\":\"BTC-EUR\"");
+
+ publicSocket.Push("""{"id":"1","event":"subscribe","arg":{"channel":"tickers","instId":"BTC-EUR"},"connId":"53efe456"}""");
+ publicSocket.Push("""{"arg":{"channel":"tickers","instId":"BTC-EUR"},"data":[{"instType":"SPOT","instId":"BTC-EUR","last":"66148.9","lastSz":"0.00010133","askPx":"66134.7","askSz":"0.01847","bidPx":"66129.6","bidSz":"0.0193605","ts":"1794318514123"}]}""");
+ businessSocket.Push("""{"arg":{"channel":"candle1m","instId":"BTC-EUR"},"data":[["1794318180000","65999.8","66069.8","65999.8","66050.5","0.0523422","3457.08","3457.08","1"]]}""");
+ await WaitForAsync(() => events.Count == 2).ConfigureAwait(false);
+ var quote = events.OfType().Single().Quote;
+ Assert.AreEqual((66129.6m, 66134.7m), (quote.Bid, quote.Ask));
+ var bar = events.OfType().Single();
+ Assert.IsTrue(bar.Closed);
+ Assert.AreEqual(66050.5, bar.Bar.Close);
+
+ // Twenty seconds of silence: "ping". The public side answers, the business side does not and is dropped.
+ await WaitForAsync(() => clock.Waiting >= 2).ConfigureAwait(false);
+ clock.Advance(TimeSpan.FromSeconds(21));
+ await WaitForAsync(() => publicSocket.Sent.Contains("ping") && businessSocket.Sent.Contains("ping")).ConfigureAwait(false);
+ publicSocket.Push("pong");
+ await WaitForAsync(() => clock.Waiting >= 2).ConfigureAwait(false);
+ clock.Advance(TimeSpan.FromSeconds(21));
+ await reading.WaitAsync(TimeSpan.FromSeconds(10)).ConfigureAwait(false);
+ Assert.IsTrue(sockets.All(s => s.Disposed), "both connections are closed when the feed ends");
+ }
+
+ [TestMethod]
+ [TestCategory(Category.Unit)]
+ public void StreamErrorsStopTheFeed()
+ {
+ var error = Assert.Throws(() => OkxClient.ParseStreamMessage(
+ """{"event":"error","msg":"Subscribe failed, wrong URL or channel:candle1m,instId:BTC-EUR doesn't exist.","code":"60018","connId":"53efe456","id":"2"}"""));
+ StringAssert.Contains(error.Message, "60018");
+ Assert.IsEmpty(OkxClient.ParseStreamMessage("""{"event":"notice","msg":"WebSocket port 8443 will be retired soon.","code":"64010"}"""));
+ }
+
+ internal static async Task WaitForAsync(Func condition)
+ {
+ var deadline = DateTime.UtcNow.AddSeconds(10);
+ while (!condition())
+ {
+ if (DateTime.UtcNow > deadline)
+ {
+ Assert.Fail("Condition not reached in time.");
+ }
+
+ await Task.Delay(10).ConfigureAwait(false);
+ }
+ }
+}