added bts.api.csharp launchSettings.json to .gitignore

.gitignore

@@ -18,6 +18,7 @@ src/client/spark/Properties/launchSettings.json
 compile_commands.json
 .cquery_cached_index/
 src/client/sparkcmd/Properties/launchSettings.json
+src/sdk/examples/client_sdk/bts.api.csharp/src/Properties/launchSettings.json
 node_modules
 paket-files
 project.lock.json

src/sdk/examples/client_sdk/bts.api.csharp/src/bts.api.csharp.csproj

@@ -1,15 +1,18 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1</TargetFrameworks>
+    <TargetFrameworks>netcoreapp2.1</TargetFrameworks>
     <OutputType>Exe</OutputType>
+    <RuntimeIdentifier>win7-x64</RuntimeIdentifier>
   </PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="CommandLineParser" Version="2.8.0" />
+    <PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
     <PackageReference Include="spark_sdk" Version="2.15.10" />
     <PackageReference Include="System.Reactive" Version="4.4.1" />
     <PackageReference Include="System.Reactive.Core" Version="4.4.1" />
+    <PackageReference Include="System.Reactive.Interfaces" Version="4.4.1" />
     <PackageReference Include="System.Reactive.Linq" Version="4.4.1" />
   </ItemGroup>
 </Project>

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/CLIOptions.cs

@@ -0,0 +1,68 @@
+using bts.api.orderman;
+using CommandLine;
+
+namespace bts.api.csharp {
+   [Verb("watch", HelpText = "List items in the system.")]
+   class WatchOptions {
+      [Option("accounts", Required = false, SetName = "Accounts", HelpText = "print accounts in the system.")]
+      public bool accounts { get; set; }
+
+      [Option("securities", Required = false, SetName = "Securities", HelpText = "print securities in the system (may be combined with --filter-symbols, or --filter-securities).")]
+      public bool securities { get; set; }
+
+      [Option("symbols", Required = false, SetName = "Symbols", HelpText = "print all symbols in the system (may not be combined with other options).")]
+      public bool symbols { get; set; }
+
+      [Option("bbo", Required = false, SetName = "Books", HelpText = "print bbo for an optionally filtered set of securities/symbols.")]
+      public bool bbo { get; set; }
+
+      [Option("orders", Required = false, SetName = "Orders", HelpText = "print orders in the system.")]
+      public bool orders { get; set; }
+
+      [Option("positions", Required = false, SetName = "Positions", HelpText = "print positions in the system (may be combined with --filter-symbols, --filter-securities, and --filter-accounts).")]
+      public bool positions { get; set; }
+
+      // auxiliary filters
+      [Option("filter-securities", Required = false, HelpText = "filter securities with a regular expression (may be combined with --securities, and --bbo).")]
+      public string filter_securities { get; set; }
+
+      [Option("filter-symbols", Required = false, HelpText = "filter securities for a particular set of symbols (may be combined with --securities, and --bbo).  Do not confuse with the --symbols option, which prints all symbols in the system.")]
+      public string filter_symbols { get; set; }
+
+      [Option("filter-accounts", Required = false, HelpText = "filter for a particular set of accounts.")]
+      public string filter_accounts { get; set; }
+   }
+
+   [Verb("send-order", HelpText = "Send orders.")]
+   class SendOrdersOptions {
+      // this option only applies to Iceberg orders
+      [Option("show-quantity", Required = false, SetName = "Iceberg")]
+      public double show_quantity { get; set; } = 5;
+
+      [Option("price", Required = false, HelpText = "specify the order price.")]
+      public double price { get; set; } = 100;
+
+      [Option("quantity", Required = false, HelpText = "specify the order quantity.")]
+      public uint quantity { get; set; } = 1;
+
+      [Option("account", Required = false, HelpText = "specify the account with which the order should be sent.")]
+      public string account { get; set; }
+
+      [Option("order-type", Required = false, HelpText = "specify the order type (limit, market, or iceberg).")]
+      public CustomOrderDefinition.CustomOneofCase order_type { get; private set; } = CustomOrderDefinition.CustomOneofCase.Limit;
+
+      /// Run the program with the argument <see cref="WatchOptions.securities"/> to display securities/security keys:
+      ///   - display all securities:
+      ///       bts.api.csharp.exe watch securities
+      ///   - display all 'ES' securities:
+      ///       bts.api.csharp.exe watch securities --symbols "ES"
+      ///   - display all 'ES' and 'GC' securities:
+      ///       bts.api.csharp.exe watch securities --symbols "ES,GC"
+      /// If no security key is specified, a random security is used.
+      [Option("security", Required = false, HelpText = "specify the order security by name, or id.")]
+      public string security { get; set; }
+
+      [Option("side", Required = false, HelpText = "specify the order side (buy/sell).")]
+      public Side side { get; set; } = Side.Buy;
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/Program.cs

@@ -1,74 +1,88 @@
-using bts.api.core;
-using bts.api.csharp.examples;
+using bts.api.admin;
+using bts.api.core;
+using bts.api.csharp.data;
+using bts.api.csharp.utils;
+using bts.api.csharp.watch;
 using bts.api.orderman;
 using bts.api.position;
 using CommandLine;
 using System;
-using System.Collections.Generic;
 using System.Threading;
 
 namespace bts.api.csharp {
    class Program {
-      static void Main(string[] args) =>
-         Parser.Default.ParseArguments<Options>(args).WithParsed(_run);
-
-      static void _run(Options options) {
-         var exit_event = new ManualResetEvent(false);
-         SynchronizationContext.SetSynchronizationContext(new SynchronizationContext());
-         var service_context = new ServiceContext();
-         var login = service_context.login("bts", "");
-         login.Wait();
-         var examples = new List<IDisposable>();
-         if (options.subscribe_securities ||! options.any_enabled) {
-            examples.Add(new SecurityExample(service_context.locate<MarketDataService>()));
-         }
-         if (options.subscribe_positions || !options.any_enabled) {
-            examples.Add(new PositionExample(service_context.locate<PositionService>()));
-         }
-         if (options.subscribe_orders || !options.any_enabled) {
-            examples.Add(new OrderExample(service_context.locate<OrderService>()));
-         }
-         if (options.subscribe_book || !options.any_enabled) {
-            examples.Add(new BookExample(service_context.locate<MarketDataService>()));
-         }
-         if (options.send_orders || !options.any_enabled) {
-            examples.Add(SendOrderLoop.init_loop(service_context.locate<OrderService>(), service_context.locate<MarketDataService>()));
-         }
-         Console.CancelKeyPress += on_cancel_key_press;
-         exit_event.WaitOne();
-         foreach (var ex in examples)
-            ex.Dispose();
-         //
-         void on_cancel_key_press(object sender, ConsoleCancelEventArgs e) {
-            exit_event.Set();
-            e.Cancel = true;
-         }
+      static void Main(string[] args) {
+         new Parser(cfg => cfg.CaseInsensitiveEnumValues = true)
+            .ParseArguments<WatchOptions, SendOrdersOptions>(args)
+            .MapResult(
+               _execution_shell<WatchOptions>(_watch),
+               _execution_shell<SendOrdersOptions>(_send_orders, true),
+               errors => 1);
       }
 
-      class Options {
-         [Option("subscribe-securities", Required = false, HelpText = "run security-subscription example.")]
-         public bool subscribe_securities { get; set; }
+      static Func<T, int> _execution_shell<T>(Func<ServiceContext, T, IDisposable> execute, bool auto_quit = false) {
+         return opts => {
+            var exit_event = new ManualResetEvent(auto_quit);
+            Console.CancelKeyPress += on_cancel_key_press;
+            var service_context = new ServiceContext();
+            service_context.login("bts", "").Wait();
+            execute(service_context, opts);
+            exit_event.WaitOne();
+            return 0;
+            //
+            void on_cancel_key_press(object sender, ConsoleCancelEventArgs e) {
+               exit_event.Set();
+               e.Cancel = true;
+            }
+         };
+      }
 
-         [Option("subscribe-orders", Required = false, HelpText = "run order-subscription example.")]
-         public bool subscribe_orders { get; set; }
+      static IDisposable _watch(ServiceContext service_context, WatchOptions options) {
+         if (options.accounts) {
+            // watch accounts
+            return WatchAccounts.run(service_context.locate<AdminService>());
+         } else if (options.securities) {
+            // watch securities
+            var security_predicate = CLIUtils.parse_security_predicate(options.filter_symbols, options.filter_securities);
+            return WatchSecurities.run(service_context.locate<MarketDataService>(), security_predicate);
+         } else if (options.bbo) {
+            // watch bbo
+            return WatchBooks.run(new bts.md.MarketDataClient(),
+               CLIUtils.parse_security_predicate(options.filter_symbols, options.filter_securities));
+         } else if (options.symbols) {
+            // watch symbols
+            return WatchSymbols.run(service_context.locate<MarketDataService>());
+         } else if (options.orders) {
+            // watch orders (optionally filtered by account)
+            var account_predicate = CLIUtils.parse_delimited_predicate<OrderRecordImmutable>(
+               options.filter_accounts, order => order.Def.Account);
+            return WatchOrders.run(service_context.locate<OrderService>(), account_predicate);
+         } else if (options.positions) {
+            // watch positions (optionally filtered by account)
+            var account_predicate = CLIUtils.parse_delimited_predicate<PositionUnitImmutable>(
+               options.filter_accounts, pos => pos.Account);
+            return WatchPositions.run(service_context.locate<PositionService>(), account_predicate);
+         }
+         return null;
+      }
 
-         [Option("subscribe-positions", Required = false, HelpText = "run position-subscription example.")]
-         public bool subscribe_positions { get; set; }
-
-         [Option("subscribe-books", Required = false, HelpText = "run book-subscription example.")]
-         public bool subscribe_book { get; set; }
-
-         [Option("send-orders", Required = false, HelpText = "run send-orders example.")]
-         public bool send_orders { get; set; }
-
-         // if none are enabled, all options will be flipped on,
-         // so the user need not specify a single argument to see the examples run.
-         public bool any_enabled =>
-            subscribe_securities ||
-            subscribe_orders ||
-            subscribe_positions ||
-            subscribe_book ||
-            send_orders;
+      static IDisposable _send_orders(ServiceContext service_context, SendOrdersOptions options) {
+         var custom_order_def = OrderUtils.custom_order_definitioni(options.order_type);
+         if (!custom_order_def.HasValue) {
+            Console.WriteLine($"Unable to create order of type '{options.order_type}.'  The following types are available:\n\t{string.Join("\n\t", OrderUtils.known_order_types)}");
+            return null;
+         }
+         var user = new NameIDPair(service_context.user, service_context.user_id);
+         var admin_service = service_context.locate<AdminService>();
+         var account = AdminUtils.get_account_async(user, admin_service, options.account).WaitResult();
+         var md_service = service_context.locate<MarketDataService>();
+         var security = SecurityUtils.get_security_async(md_service.subscribei_securities(), options.security).WaitResult();
+         var model = new OrderModel(service_context.locate<OrderService>());
+         /// Note that the call below (<see cref="OrderModel.send_order(NameIDPair, NameIDPair, uint, Side, uint, double, CustomOrderDefinition)"/>)
+         /// blocks the current thread until an ack is received from the server.  If you wish to avoid blocking the thread as such,
+         /// use the following method instead: <see cref="OrderModel.send_order_async(NameIDPair, NameIDPair, uint, Side, uint, double, CustomOrderDefinition)"/>.
+         model.send_order(user, account, security.Id, options.side, options.quantity, options.price, custom_order_def.Value.CloneToMutable());
+         return null;
       }
    }
 }

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/data/NameIDPair.cs

@@ -1,6 +1,6 @@
 using System;
 
-namespace bts.api.csharp {
+namespace bts.api.csharp.data {
    readonly struct NameIDPair {
       public NameIDPair(string name, uint id) {
          this.name = name ?? throw new ArgumentNullException(nameof(name));

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/data/OrderModel.cs

@@ -0,0 +1,71 @@
+using bts.api.csharp.utils;
+using bts.api.orderman;
+using System;
+using System.Threading.Tasks;
+
+namespace bts.api.csharp.data {
+   /// <summary>
+   /// Exemplifies how the <see cref="OrderService"/> api may be used to send orders.
+   /// </summary>
+   class OrderModel {
+      readonly OrderService _service;
+
+      public OrderModel(OrderService service) =>
+         _service = service;
+
+      public static OrderDefinition create_order_definition(NameIDPair user, NameIDPair account, uint security_key, Side side, CustomOrderDefinition custom_def) {
+         return new OrderDefinition {
+            Account = account.name,
+            AccountId = account.id,
+            User = user.name,
+            UserId = user.id,
+            SecurityKey = security_key,
+            Side = side,
+            CustomDef = custom_def
+         };
+      }
+
+      /// <summary>
+      /// Sends an order of the type specified by <paramref name="custom_order_definition"/> (asynchronous).
+      /// </summary>
+      /// <returns>The order id if the submission was successful, otherwise null.</returns>
+      public async Task<uint?> send_order_async(NameIDPair user, NameIDPair account, uint security_key, Side side, uint quantity, double price, CustomOrderDefinition custom_order_definition) {
+         Console.WriteLine($"Creating order {OrderUtils.fmt_order(side, quantity, price, user.name, account.name, custom_order_definition)}");
+         var response = await _service.create_order_async(new Create {
+            Quantity = quantity,
+            Price = price,
+            NewOrder = create_order_definition(user, account, security_key, side, custom_order_definition)
+         });
+         if (response.success) {
+            Console.WriteLine($"Order submission succeeded.  Order id is {response.value.OrderKey}.");
+            return response.value.OrderKey;
+         } else {
+            Console.WriteLine($"Order submission failed: [{response.value.ErrorCode}] {response.value.Msg}.");
+            return null;
+         }
+      }
+
+      /// <summary>
+      /// Sends an order with specified parameters (the thread will be blocked until an ack is received from the server).
+      /// </summary>
+      public uint? send_order(NameIDPair user, NameIDPair account, uint security_key, Side side, uint quantity, double price, CustomOrderDefinition custom_order_definition) {
+         /// Note, the thread will be blocked until a response is received from the server.
+         /// For this reason, <see cref="OrderService.create_order_async(Create)"/> is usually preferred.
+         /// An example of how to use that method is provided in <see cref="send_order_async(NameIDPair, NameIDPair, CustomOrderDefinition, uint, double)"/>.
+         Console.WriteLine($"Creating order {OrderUtils.fmt_order(side, quantity, price, user.name, account.name, custom_order_definition)}");
+         var response = _service.create_order(new Create {
+            Quantity = quantity,
+            Price = price,
+            NewOrder = create_order_definition(user, account, security_key, side, custom_order_definition)
+         });
+         switch (response.ErrorCode) {
+            case OrderError.Ok:
+               Console.WriteLine($"Order submission succeeded.  Order id is {response.OrderKey}.");
+               return response.OrderKey;
+            default:
+               Console.WriteLine($"Order submission failed: [{response.ErrorCode}] {response.Msg}.");
+               return null;
+         }
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/examples/BookExample.cs

@@ -1,60 +0,0 @@
-using bts.api.core;
-using bts.api.csharp.utils;
-using System;
-using System.Collections.Generic;
-using System.Diagnostics;
-using System.Linq;
-using System.Reactive.Linq;
-using System.Threading;
-using SecurityKey = System.UInt32;
-
-namespace bts.api.csharp.examples {
-   /// <summary>
-   /// Uses the <see cref="MarketDataService"/> api to observe book updates
-   /// for security in the system, and organize them into a Dictionary.
-   /// </summary>
-   class BookExample : IDisposable {
-      readonly Dictionary<SecurityKey, BookEntryImmutable> _books = new Dictionary<SecurityKey, BookEntryImmutable>();
-      readonly IDisposable _subscription;
-
-      public BookExample(MarketDataService market_data_service) {
-         _subscription = market_data_service.subscribei_book()
-            .ObserveOn(SynchronizationContext.Current)
-            .Subscribe(_on_book_update);
-      }
-
-      public void Dispose() {
-         _subscription.Dispose();
-      }
-
-      void _on_book_update(Update<BookEntryImmutable, uint> update) {
-         foreach (var new_book in update.added) {
-            // of course, we shouldn't have entries for any books in update.added yet
-            Debug.Assert(!_books.ContainsKey(new_book.Key));
-            // display bbo in the console window
-            _print_book_info(new_book.Key, $"book received for the first time, bbo is: {BookUtils.fmt_bbo(new_book)}");
-            // add the new book to our map
-            _books.Add(new_book.Key, new_book);
-         }
-         foreach (var change in update.changes) {
-            // of course, the security key shouldn't change
-            Debug.Assert(change.Old.Key == change.New.Key);
-            // our book entry for this security should be identitical to change.Old
-            Debug.Assert(change.Old.Bid.SequenceEqual(_books[change.Old.Key].Bid));
-            Debug.Assert(change.Old.Ask.SequenceEqual(_books[change.Old.Key].Ask));
-            // display the current book in the console window
-            _print_book_info(change.New.Key, $"book changed, now bbo is: {BookUtils.fmt_bbo(change.New)}");
-            // update our map with the changed book
-            _books[change.New.Key] = change.New;
-         }
-         foreach (var old_book in update.removed) {
-            // of course, we should have entries for all books in update.removed
-            Debug.Assert(_books.Remove(old_book.Key));
-         }
-      }
-
-      static void _print_book_info(SecurityKey key, string message) {
-         Console.WriteLine($"Security {key}: {message}.");
-      }
-   }
-}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/examples/OrderExample.cs

@@ -1,139 +0,0 @@
-using bts.api.core;
-using bts.api.orderman;
-using System;
-using System.Collections.Generic;
-using System.Diagnostics;
-using System.Linq;
-using System.Reactive.Linq;
-using System.Threading;
-using AccountKey = System.UInt32;
-using OrderKey = System.UInt32;
-
-namespace bts.api.csharp.examples {
-   /// <summary>
-   /// Uses the <see cref="OrderService"/> to observe order updates,
-   /// and group them by account.
-   /// </summary>
-   class OrderExample : IDisposable {
-      readonly Dictionary<AccountKey, Dictionary<OrderKey, OrderRecordImmutable>> _data = new Dictionary<AccountKey, Dictionary<AccountKey, OrderRecordImmutable>>();
-      IDisposable _subscription;
-
-      public OrderExample(OrderService order_service) {
-         /// 'OrderService' has 2 methods which can be used to subscribe to order updates.
-         ///  -------------------------------------------------------------------------------------
-         /// 1) <see cref="OrderService.subscribe_orders(string)"/>.
-         /// 2) <see cref="OrderService.subscribei_orders(string)"/>.
-         /// This method (no. 2) is typically preferrable because the data it provides is immutable.
-         /// --------------------------------------------------------------------------------------
-         _subscription = order_service.subscribei_orders()
-            // the 'ObserveOn' call below ensures that the
-            // callback will be invoked this thread.
-            // Be sure to do this if you don't want to worry
-            // about multi-threading issues (locking, etc).
-            .ObserveOn(SynchronizationContext.Current)
-            .Subscribe(_on_update);
-
-      }
-
-      public event Action<AccountKey> account_orders_changed;
-
-      public void Dispose() {
-         _subscription.Dispose();
-      }
-
-      public IEnumerable<OrderRecordImmutable> get_account_orders(AccountKey account) {
-         if (_data.TryGetValue(account, out var account_orders)) {
-            return account_orders.Values;
-         }
-         return Enumerable.Empty<OrderRecordImmutable>();
-      }
-
-      void _on_order_added(OrderRecordImmutable new_order) {
-         if (!_data.TryGetValue(new_order.Def.AccountId, out var account_orders)) {
-            // this is the first order for this account.
-            // initialize the account orders dictionary, and add it to our data.
-            account_orders = new Dictionary<AccountKey, OrderRecordImmutable>();
-            _data.Add(new_order.Def.AccountId, account_orders);
-         }
-         // now add the order to account_orders
-         account_orders.Add(new_order.Key, new_order);
-      }
-
-      void _on_order_changed(Change<OrderRecordImmutable> change) {
-         // ch.New and ch.Old have the same key.
-         Debug.Assert(change.New.Key == change.Old.Key);
-         var key = change.New.Key;
-         // react to a changed order
-         if (change.New.State.FilledQuantity != change.Old.State.FilledQuantity) {
-            // Display new fills in the console window.
-            var num_new_fills = change.New.State.FilledQuantity - change.Old.State.FilledQuantity;
-            _print_order_info(key, $"received {num_new_fills} new fills.");
-            // Be mindful that orders can be overfilled.
-            if (change.New.State.FilledQuantity > change.New.State.Quantity) {
-               // Display overfills in the console window.
-               var num_over_fills = change.New.State.FilledQuantity - change.New.State.Quantity;
-               _print_order_info(key, $"overfilled by {num_over_fills}");
-            } else {
-               // Display working qty in the console window.
-               var working_qty = change.New.State.Quantity - change.New.State.FilledQuantity;
-               _print_order_info(key, $"still working {working_qty}.");
-            }
-         }
-         // Display order status changes in the console window.
-         if (change.New.State.Status != change.Old.State.Status) {
-            _print_order_info(key, $"status changed from {change.Old.State.Status} to {change.New.State.Status}.");
-         }
-         // Account will not change, so our dictionary will definitely have a key for this account.
-         Debug.Assert(_data.ContainsKey(change.New.Def.AccountId));
-         var account_orders = _data[change.New.Def.AccountId];
-         // The value for this key in account_orders should equal ch.Old.
-         Debug.Assert(account_orders[key].Equals(change.Old));
-         // update account orders with the changed order. 
-         account_orders[key] = change.New;
-      }
-
-      void _on_order_removed(OrderRecordImmutable old_val) {
-         // An entry for this order should be present in our data,
-         // as it is in the 'removed' items.
-         // Assert this is the case to illustrate the point.
-         Debug.Assert(_data.ContainsKey(old_val.Def.AccountId));
-         var account_orders = _data[old_val.Def.AccountId];
-         // the removed value should match the one currently in our data.
-         // Assert this is the case, then remove the order.
-         Debug.Assert(account_orders[old_val.Key].Equals(old_val));
-         account_orders.Remove(old_val.Key);
-         _print_order_info(old_val.Key, "has been removed.");
-      }
-
-      void _on_update(Update<OrderRecordImmutable, OrderKey> update) {
-         // record which accounts experienced an order update, then
-         // at the end of this method, fire the account_orders_changed event for each 
-         var accounts_with_order_updates = new HashSet<AccountKey>();
-         foreach (OrderRecordImmutable new_order in update.added) {
-            _on_order_added(new_order);
-            accounts_with_order_updates.Add(new_order.Def.AccountId);
-         }
-         foreach (Change<OrderRecordImmutable> change in update.changes) {
-            _on_order_changed(change);
-            accounts_with_order_updates.Add(change.New.Def.AccountId);
-         }
-         foreach (OrderRecordImmutable old_order in update.removed) {
-            _on_order_removed(old_order);
-            accounts_with_order_updates.Add(old_order.Def.AccountId);
-         }
-         // display all accounts with order updates in the Console window.
-         Console.WriteLine("The following accounts experienced order changes: ");
-         foreach (var account in accounts_with_order_updates) {
-            Console.WriteLine("\n\t" + account);
-         }
-         // lastly, fire the account_orders_changed event for each account experienced an order update.
-         foreach (var account in accounts_with_order_updates) {
-            account_orders_changed?.Invoke(account);
-         }
-      }
-
-      void _print_order_info(OrderKey order_key, string message) {
-         Console.WriteLine($"Order {order_key}: {message}.");
-      }
-   }
-}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/examples/PositionExample.cs

@@ -1,125 +0,0 @@
-using bts.api.core;
-using bts.api.position;
-using System;
-using System.Collections.Generic;
-using System.Diagnostics;
-using System.Reactive.Linq;
-using System.Threading;
-
-namespace bts.api.csharp.examples {
-   /// <summary>
-   /// A pair of security, and account id,
-   /// which uniquely identifies each PositionUnit.
-   /// </summary>
-   readonly struct PositionKey {
-      public PositionKey(uint security_id, uint account_id) {
-         this.security_id = security_id;
-         this.account_id = account_id;
-      }
-
-      public uint security_id { get; }
-      public uint account_id { get; }
-
-      public static PositionKey from_position(PositionUnitImmutable p) =>
-         new PositionKey(p.SecurityId, p.AccountId);
-
-      public override string ToString() =>
-         $"Sec {security_id}, Acc {account_id}";
-   }
-
-   /// <summary>
-   /// Uses the <see cref="PositionService"/> api to monitor positions
-   /// for every account/security pair, and organize them into a Dictionary.
-   /// </summary>
-   class PositionExample : IDisposable {
-      readonly Dictionary<PositionKey, PositionUnitImmutable> _data = new Dictionary<PositionKey, PositionUnitImmutable>();
-      IDisposable _subscription;
-
-      public PositionExample(PositionService position_service) {
-         /// 'PositionService' has 2 methods which can be used to subscribe to position updates.
-         ///  -------------------------------------------------------------------------------------
-         /// 1) <see cref="PositionService.subscribe_position_data(string)"/>.
-         /// 2) <see cref="PositionService.subscribei_position_data(string)"/>.
-         /// This method (no. 2) is typically preferrable because the data it provides is immutable.
-         /// --------------------------------------------------------------------------------------
-         _subscription = position_service.subscribei_position_data()
-            // the 'ObserveOn' call below ensures that the
-            // callback will be invoked this thread.
-            // Be sure to do this if you don't want to worry
-            // about multi-threading issues (locking, etc).
-            .ObserveOn(SynchronizationContext.Current)
-            .Subscribe(_on_update);
-      }
-
-      public event Action data_changed;
-
-      public IReadOnlyDictionary<PositionKey, PositionUnitImmutable> data => _data;
-
-      public void Dispose() =>
-         _subscription.Dispose();
-
-      void _on_position_added(PositionUnitImmutable new_val) {
-         var k = PositionKey.from_position(new_val);
-         // this entry should NOT be present in our _data, as it is in the 'added' items.
-         // Assert this is the case to illustrate the point.
-         Debug.Assert(!_data.ContainsKey(k));
-         _print_position_info(k, $"initial position received.  Day: Long {new_val.DayLongPos}, Short {new_val.DayShortPos}, Net {new_val.DayLongPos - new_val.DayShortPos}.");
-         // add the new position unit to _data
-         _data.Add(k, new_val);
-      }
-
-      void _on_position_changed(Change<PositionUnitImmutable> change) {
-         var k = PositionKey.from_position(change.New);
-         // ch.New and ch.Old have the same key (i.e., the Account/Security pair),
-         Debug.Assert(change.New.AccountId == change.Old.AccountId);
-         Debug.Assert(change.New.SecurityId == change.Old.SecurityId);
-         // of course, the value for this key in our dictionary should equal ch.Old.
-         Debug.Assert(_data[k].Equals(change.Old));
-         // Display changes to the day position in the console window.
-         // 1) check if the day long changed
-         if (change.New.DayLongPos != change.Old.DayLongPos) {
-            Console.WriteLine($"[{k}] day long changed from {change.Old.DayLongPos} to {change.New.DayLongPos}.");
-         }
-         // 2) check if day short changed
-         if (change.New.DayShortPos != change.Old.DayShortPos) {
-            Console.WriteLine($"[{k}] day short changed from {change.Old.DayShortPos} to {change.New.DayShortPos}.");
-         }
-         // 3) check if net day position changed
-         var new_net_day_pos = change.New.DayLongPos - change.New.DayShortPos;
-         var old_net_day_pos = change.Old.DayLongPos - change.Old.DayShortPos;
-         if (new_net_day_pos != old_net_day_pos) {
-            Console.WriteLine($"[{k}] day net changed from {old_net_day_pos} to {new_net_day_pos}.");
-         }
-         // update _data with the changed position.
-         _data[k] = change.New;
-      }
-
-      void _on_position_removed(PositionUnitImmutable old_val) {
-         var k = PositionKey.from_position(old_val);
-         // this entry should be present in our _data, as it is in the 'removed' items.
-         // Assert this is the case to illustrate the point.
-         Debug.Assert(_data.ContainsKey(k));
-         // this should match our data.  Assert this is the case.
-         Debug.Assert(_data[k].Equals(old_val));
-         _data.Remove(k);
-         Console.WriteLine($"[{k}] position has been removed.");
-      }
-
-      void _on_update(Update<PositionUnitImmutable, int> update) {
-         foreach (PositionUnitImmutable p in update.added) {
-            _on_position_added(p);
-         }
-         foreach (Change<PositionUnitImmutable> ch in update.changes) {
-            _on_position_changed(ch);
-         }
-         foreach (PositionUnitImmutable p in update.removed) {
-            _on_position_removed(p);
-         }
-         data_changed?.Invoke();
-      }
-
-      void _print_position_info(PositionKey position_key, string message) {
-         Console.WriteLine($"Position {position_key}: {message}.");
-      }
-   }
-}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/examples/SecurityExample.cs

@@ -1,48 +0,0 @@
-using bts.api.core;
-using System;
-using System.Collections.Generic;
-using System.Diagnostics;
-using System.Linq;
-using System.Reactive.Linq;
-using System.Threading;
-using SecurityKey = System.UInt32;
-
-namespace bts.api.csharp.examples {
-   /// <summary>
-   /// Uses the <see cref="MarketDataService"/> api to observe the
-   /// state of securities in the system.
-   /// </summary>
-   class SecurityExample : IDisposable {
-      readonly IDisposable _subscription;
-      readonly Dictionary<SecurityKey, SecurityImmutable> _securities = new Dictionary<SecurityKey, SecurityImmutable>();
-
-      public SecurityExample(MarketDataService market_data_service) {
-         _subscription = market_data_service.subscribei_securities()
-            .ObserveOn(SynchronizationContext.Current)
-            .Subscribe(_on_securities_update);
-      }
-
-      public void Dispose() {
-         _subscription.Dispose();
-      }
-
-      void _on_securities_update(Update<SecurityImmutable, uint> update) {
-         foreach (var new_security in update.added) {
-            // of course, we shouldn't have entries for any books in update.added yet
-            Debug.Assert(!_securities.ContainsKey(new_security.Id));
-            // display bbo in the console window
-            Console.WriteLine($"received new security: {new_security}.");
-            // add the new security to our map
-            _securities.Add(new_security.Id, new_security);
-         }
-         // As you may have noticed, all of the subcribe methods in the api
-         // return an IObservable<Update<T>>.  It is worth noting that for security updates,
-         // 'changes' will always be empty.
-         Debug.Assert(!update.changes.Any());
-         foreach (var old_security in update.removed) {
-            // of course, we should have entries for all books in update.removed
-            Debug.Assert(_securities.Remove(old_security.Id));
-         }
-      }
-   }
-}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/examples/SendOrderModel.cs

@@ -1,110 +0,0 @@
-using bts.api.csharp.utils;
-using bts.api.orderman;
-using System;
-using System.Threading.Tasks;
-
-namespace bts.api.csharp.examples {
-   static class OrderTemplates {
-      public static CustomOrderDefinition limit() => new CustomOrderDefinition { Limit = new LimitOrderDefinition() };
-      public static CustomOrderDefinition market() => new CustomOrderDefinition { Market = new MarketOrderDefinition() };
-      public static CustomOrderDefinition iceberg(double show_quantity) => iceberg(show_quantity, limit());
-      public static CustomOrderDefinition iceberg(double show_quantity, CustomOrderDefinition child) =>
-         new CustomOrderDefinition {
-            Iceberg = new IcebergOrderDefinition {
-               ShowQuantity = show_quantity,
-               Child = child
-            }
-         };
-   }
-
-   /// <summary>
-   /// Exemplifies how the <see cref="OrderService"/> api may be used to
-   /// send several common order types (limit, market, and iceberg).
-   /// </summary>
-   class SendOrderModel {
-      readonly OrderService _service;
-
-      public SendOrderModel(OrderService service) {
-         _service = service;
-      }
-
-      public OrderDefinition create_order_definition(NameIDPair user, NameIDPair account, uint security_key, CustomOrderDefinition custom_def) {
-         return new OrderDefinition {
-            Account = account.name,
-            AccountId = account.id,
-            User = user.name,
-            UserId = user.id,
-            SecurityKey = security_key,
-            CustomDef = custom_def
-         };
-      }
-
-      /// <summary>
-      /// Sends a limit order (asynchronous).
-      /// </summary>
-      /// <returns>The order id if the submission was successful, otherwise null.</returns>
-      public Task<uint?> send_limit_order_async(NameIDPair user, NameIDPair account, uint security_key, uint quantity, double price) {
-         return send_order_async(user, account, security_key, OrderTemplates.limit(), quantity, price);
-      }
-
-      /// <summary>
-      /// Sends a market order (asynchronous).  Note no price parameter is required for market orders.
-      /// </summary>
-      /// <returns>The order id if the submission was successful, otherwise null.</returns>
-      public Task<uint?> send_market_order_async(NameIDPair user, NameIDPair account, uint security_key, uint quantity) {
-         return send_order_async(user, account, security_key, OrderTemplates.market(), quantity, 0.0);
-      }
-
-      /// <summary>
-      /// Sends an iceberg of limit orders (asynchronous).
-      /// </summary>
-      /// <returns>The order id if the submission was successful, otherwise null.</returns>
-      public Task<uint?> send_iceberg_order_async(NameIDPair user, NameIDPair account, uint security_key, uint quantity, double price, double show_quantity) {
-         return send_order_async(user, account, security_key, OrderTemplates.iceberg(show_quantity), quantity, price);
-      }
-
-      /// <summary>
-      /// Sends an order of the type specified by <paramref name="custom_order_definition"/> (asynchronous).
-      /// </summary>
-      /// <returns>The order id if the submission was successful, otherwise null.</returns>
-      public async Task<uint?> send_order_async(NameIDPair user, NameIDPair account, uint security_key, CustomOrderDefinition custom_order_definition, uint quantity, double price) {
-         Console.WriteLine($"submitting order for user ({user}), account ({account}): {OrderUtils.fmt_order(quantity, price, custom_order_definition)}.");
-         var reply = await _service.create_order_async(new Create {
-            Quantity = quantity,
-            Price = price,
-            NewOrder = create_order_definition(user, account, security_key, custom_order_definition)
-         });
-         if (reply.success) {
-            Console.WriteLine($"received ack that order has been submitted.  Order id is {reply.value.OrderKey}.");
-            return reply.value.OrderKey;
-         } else {
-            Console.WriteLine($"order submission was unsuccessful: [{reply.value.ErrorCode}] {reply.value.Msg}.");
-            return null;
-         }
-      }
-
-      public void send_order(NameIDPair user, NameIDPair account, uint security_key, CustomOrderDefinition custom_order_definition, uint quantity, double price) {
-         /// Note, the thread will be blocked until a response is received from the server.
-         /// For this reason, <see cref="OrderService.create_order_async(Create)"/> is usually preferred.
-         /// An example of how to use that method is provided in <see cref="send_order_async(NameIDPair, NameIDPair, CustomOrderDefinition, uint, double)"/>.
-         Console.WriteLine($"Creating order {OrderUtils.fmt_order(quantity, price, custom_order_definition)}");
-         var response = _service.create_order(new Create {
-            Quantity = quantity,
-            Price = price,
-            NewOrder = create_order_definition(user, account, security_key, custom_order_definition)
-         });
-         switch (response.ErrorCode) {
-            case OrderError.Ok:
-               _print_order_info(response.OrderKey, "successfully created.");
-               break;
-            default:
-               Console.WriteLine($"Failed to create order: [{response.ErrorCode}] {response.Msg}.");
-               break;
-         }
-      }
-
-      static void _print_order_info(uint order_key, string message) {
-         Console.WriteLine($"Order {order_key}: {message}.");
-      }
-   }
-}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/examples/SendOrdersContinously.cs

@@ -1,100 +0,0 @@
-using bts.api.core;
-using bts.api.orderman;
-using mbts;
-using System;
-using System.Linq;
-using System.Reactive.Linq;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace bts.api.csharp.examples {
-   /// <summary>
-   /// The code in this example is a bit more advanced than the others,
-   /// as it is designed to send orders, asynchronously, in a continuous loop.
-   /// For straightforward examples of how to send orders with the api,
-   /// check out <see cref="SendOrderModel"/>.
-   /// </summary>
-   static class SendOrderLoop {
-      /// <summary>
-      /// As a security key is required to send an order, this method
-      /// uses the <see cref="MarketDataService"/> to observe the securities stream,
-      /// then on the first update, initializes the send-order-loop <see cref="LoopImpl"/>
-      /// with one of the newly received security keys.
-      /// </summary>
-      public static IDisposable init_loop(OrderService order_service, MarketDataService market_data_service) {
-         // If you need to familiarize yourself with the IObservable pattern, check out the official docs:
-         // https://docs.microsoft.com/en-us/dotnet/api/system.iobservable-1?view=netcore-3.1
-
-         var single_security_stream = market_data_service.subscribei_securities()
-            .Where(u => u.all.Any())
-            .Take(1)
-            .Select(u => u.all.FirstOrDefault());
-
-         return init_loop(single_security_stream, create_loop);
-         IDisposable create_loop(SecurityImmutable sec) {
-            return new LoopImpl(order_service, sec.Id);
-         }
-      }
-
-      /// <summary>
-      /// Observes the security stream and creates a new send-order-loop
-      /// whenever a new security arrives.  The previous send-order-loop
-      /// is disposed when the next security arrives, so only one send-order-loop
-      /// shall be active at a time.
-      /// </summary>
-      /// <param name="security">The security stream used to initialize send-order-loops.</param>
-      /// <returns>An IDisposable that unsubsribes from the securities stream, and disposes the active send-order-loop.</returns>
-      public static IDisposable init_loop(IObservable<SecurityImmutable> security, Func<SecurityImmutable, IDisposable> factory) {
-         IDisposable active_loop = null;
-         var security_sub = security.Subscribe(s =>
-            Interlocked.Exchange(ref active_loop, factory(s))?.Dispose());
-         return Disposable.Create(dispose);
-         void dispose() {
-            security_sub.Dispose();
-            active_loop?.Dispose();
-         }
-      }
-
-      class LoopImpl : IDisposable {
-         bool _is_disposed;
-
-         public LoopImpl(OrderService service, uint security_key)
-            : this(service, Users.Default, Accounts.Default, security_key, 10, TimeSpan.FromSeconds(3)) { }
-
-         public LoopImpl(OrderService service, NameIDPair user, NameIDPair account, uint security_key, int max_orders, TimeSpan delay_between_orders) {
-            var model = new SendOrderModel(service);
-            send_orders_continuously();
-
-            async void send_orders_continuously() {
-               // Periodically send an order with one of the CustomOrderDefinitions below.
-               // If you are unfamiliar with async/await, this will also serve as a simple example
-               // of how those keywords may be used.  However, there is no substite for the official docs:
-               // https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/
-               var order_templates = new CustomOrderDefinitionImmutable[] {
-                  new CustomOrderDefinitionImmutable(OrderTemplates.limit()),
-                  new CustomOrderDefinitionImmutable(OrderTemplates.market()),
-                  new CustomOrderDefinitionImmutable(OrderTemplates.iceberg(5))
-               };
-               for (int num_orders_sent = 0; num_orders_sent < max_orders && !_is_disposed; num_orders_sent++) {
-                  int template_index = num_orders_sent % order_templates.Length;
-                  CustomOrderDefinitionImmutable templatei = order_templates[template_index];
-                  // The order templates we created are immutable, however the api uses the mutable form.
-                  // Not to worry tho, there is a nifty method called 'CloneToMutable.'
-                  // Note that all of the non-primitive immutable parameters in the api methods have a 'CloneToMutable' method,
-                  // it is not unique to CustomOrderDefinitionImmutable.
-                  CustomOrderDefinition template = templatei.CloneToMutable();
-                  await model.send_order_async(user, account, security_key, template, 12, 100);
-                  // pause for a moment before sending the next order
-                  await Task.Delay(delay_between_orders);
-               }
-            }
-         }
-
-         public void Dispose() {
-            // flip _is_disposed to true, so the 'send_orders_continuously' loop
-            // knows it's time to stop.
-            _is_disposed = true;
-         }
-      }
-   }
-}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/AdminUtils.cs

@@ -0,0 +1,79 @@
+using bts.api.admin;
+using bts.api.csharp.data;
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Collections.ObjectModel;
+using System.Linq;
+using System.Reactive.Linq;
+using System.Threading.Tasks;
+
+namespace bts.api.csharp.utils {
+   static class AdminUtils {
+      public static IReadOnlyDictionary<uint, NameIDPair> map_accounts(AdminDataImmutable admin_datai) {
+         return admin_datai.Accounts.ToDictionary(acc => acc.Id, acc => new NameIDPair(acc.Name, acc.Id));
+      }
+
+      /// <summary>
+      /// Links users to the set of accounts on which they have trading permissions.
+      /// </summary>
+      public static IEnumerable<(NameIDPair user, IEnumerable<uint> accounts)> user_account_permissions(AdminDataImmutable admin_datai) {
+         return admin_datai.Users
+            .Select(user => (new NameIDPair(user.Name, user.Id), _user_tradable_accounts(user)));
+      }
+
+      public static IReadOnlyDictionary<NameIDPair, ImmutableHashSet<NameIDPair>> map_user_account_permissions(AdminDataImmutable admin_datai) {
+         var account_lookup = admin_datai.Accounts.ToLookup(acc => acc.Id);
+         return admin_datai.Users.ToDictionary(
+            user => new NameIDPair(user.Name, user.Id),
+            user => ImmutableHashSet.CreateRange(_user_tradable_accounts(user)
+               .Select(acc_id => new NameIDPair(account_lookup[acc_id].Single().Name, acc_id))));
+      }
+
+      static IEnumerable<uint> _user_tradable_accounts(BTSUserImmutable user) {
+         return user.UserData.AccountPermissions.AccountPermissions
+            .Where(kv => kv.Value.TradingPermission.HasPermissions)
+            .Select(kv => kv.Key);
+      }
+
+      public static NameIDPair get_account(NameIDPair user, AdminService admin_service, string account_name = null) {
+         var task = get_account_async(user, admin_service, account_name);
+         task.Wait();
+         return task.Result;
+      }
+
+      /// <summary>
+      /// Either searches for the account with the specified name,
+      /// or picks a random account for which the specified user has trading permissions.
+      /// </summary>
+      public static async Task<NameIDPair> get_account_async(NameIDPair user, AdminService admin_service, string account_name = null) {
+         return await (account_name == null ? auto_account(user, admin_service) : find_account(admin_service, account_name).FirstAsync());
+      }
+
+      public static IObservable<NameIDPair> auto_account(NameIDPair user, AdminService admin_service) {
+         return admin_service.subscribei_admin_data()
+            .Where(update => update.all.Any())
+            .Select(update => map_user_account_permissions(update.all.First()))
+            .Select(account_perms => account_perms.TryGetValue(user, out var accs) ? accs : ImmutableHashSet<NameIDPair>.Empty)
+            .Where(accs => accs.Count > 0)
+            .Select(accs => accs.First())
+            .Take(1);
+      }
+
+      public static IObservable<NameIDPair> find_account(AdminService admin_service, string account) {
+         return admin_service.subscribei_admin_data()
+            .Select(update => {
+               foreach (var admin_data in update.all) {
+                  foreach (var acc in admin_data.Accounts) {
+                     if (acc.Name == account)
+                        return new NameIDPair(acc.Name, acc.Id);
+                  }
+               }
+               return (NameIDPair?)null;
+            })
+            .Where(acc => acc.HasValue)
+            .Select(acc => acc.Value)
+            .Take(1);
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/CLIUtils.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+
+namespace bts.api.csharp.utils {
+   static class CLIUtils {
+      public static IEnumerable<string> parse_delimited(string cli_arg, string file_arg, string delimiter) {
+         var cli_items = _parse_delimited(cli_arg, delimiter);
+         if (file_arg != null) {
+            try {
+               var items = _parse_delimited(File.ReadAllText(file_arg), delimiter);
+               return cli_items is null ? items : cli_items.Concat(items);
+            } catch { }
+         }
+         return cli_items;
+      }
+
+      public static Func<SecurityImmutable, bool> parse_security_predicate(string cli_symbols = null, string cli_security_regex = null) {
+         return _merge_predicates(
+            parse_delimited_predicate<SecurityImmutable>(cli_symbols, sec => sec.Symbol),
+            RegexUtils.default_regex(cli_security_regex)?.to_predicate<SecurityImmutable>());
+      }
+
+      public static Func<T, bool> parse_delimited_predicate<T>(string cli_arg, Func<T, string> get) =>
+         parse_delimited_predicate(cli_arg, null, ",", get);
+
+      public static Func<T, bool> parse_delimited_predicate<T>(string cli_arg, string file_arg, string delimiter, Func<T, string> get) {
+         var items = new HashSet<string>(parse_delimited(cli_arg, file_arg, delimiter));
+         if (items.Count == 0)
+            return null;
+         return sec => items.Contains(get(sec));
+      }
+
+      static IEnumerable<string> _parse_delimited(string delimited_string, string delimiter) {
+         return delimited_string
+            ?.Split(new[] { delimiter }, StringSplitOptions.RemoveEmptyEntries)
+            ?.Select(sym => sym.Trim())
+            ?? Enumerable.Empty<string>();
+      }
+
+     static Func<T, bool> _merge_predicates<T>(params Func<T, bool>[] predicates) {
+         Func<T, bool> result = null;
+         for (int i = 0; i < predicates.Length; i++) {
+            if (predicates[i] != null) {
+               if (result == null) {
+                  result = predicates[i];
+               } else {
+                  result += predicates[i];
+               }
+            }
+         }
+         return result;
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/CollectionUtils.cs

@@ -0,0 +1,23 @@
+using System;
+using System.Collections.Generic;
+
+namespace bts.api.csharp.utils {
+   static class CollectionUtils {
+      public static bool insert_sorted<T>(List<T> list, T value) =>
+         insert_sorted(list, value, Comparer<T>.Default);
+
+      public static bool insert_sorted<T>(List<T> list, T value, IComparer<T> comparer) {
+         if (list is null)
+            throw new ArgumentNullException(nameof(list));
+         if (comparer is null)
+            throw new ArgumentNullException(nameof(comparer));
+         var sorted_index = list.BinarySearch(value, comparer);
+         if (sorted_index < 0) {
+            // this is a new symbol
+            list.Insert(~sorted_index, value);
+            return true;
+         }
+         return false;
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/DelegateUtils.cs

@@ -0,0 +1,8 @@
+using System;
+
+namespace bts.api.csharp.utils {
+   static class DelegateUtils {
+      public static Func<TOuter, TResult> wrap<TInner, TOuter, TResult>(this Func<TInner, TResult> func, Func<TOuter, TInner> get_inner) =>
+         outer => func(get_inner(outer));
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/OrderUtils.cs

@@ -1,9 +1,32 @@
 using bts.api.orderman;
+using System.Collections.Generic;
+using System.Linq;
 
 namespace bts.api.csharp.utils {
    static class OrderUtils {
+      // add new templates as needed
+      static readonly IReadOnlyDictionary<CustomOrderDefinition.CustomOneofCase, CustomOrderDefinitionImmutable>
+         _custom_def_templates = new Dictionary<CustomOrderDefinition.CustomOneofCase, CustomOrderDefinitionImmutable> {
+            { CustomOrderDefinition.CustomOneofCase.Limit, new CustomOrderDefinitionImmutable(new CustomOrderDefinition{ Limit = new LimitOrderDefinition() }) },
+            { CustomOrderDefinition.CustomOneofCase.Market, new CustomOrderDefinitionImmutable(new CustomOrderDefinition{ Market = new MarketOrderDefinition() }) },
+            { CustomOrderDefinition.CustomOneofCase.Iceberg, new CustomOrderDefinitionImmutable(new CustomOrderDefinition{ Iceberg = new IcebergOrderDefinition() }) }
+         };
+
+      public static IEnumerable<CustomOrderDefinition.CustomOneofCase> known_order_types => _custom_def_templates.Keys;
+
+      public static CustomOrderDefinitionImmutable? custom_order_definitioni(CustomOrderDefinition.CustomOneofCase order_type) {
+         if (_custom_def_templates.TryGetValue(order_type, out var templatei)) {
+            return templatei.CloneToMutable();
+         }
+         return null;
+      }
+
       public static string fmt_order(uint quantity, double price, CustomOrderDefinition custom_order_definition) {
          return $"{quantity} @ {price}: {custom_order_definition}";
       }
+
+      public static string fmt_order(Side side, uint quantity, double price, string user, string account, CustomOrderDefinition custom_order_definition) {
+         return $"[{user}][{account}] {side} {fmt_order(quantity, price, custom_order_definition)}.";
+      }
    }
 }

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/RegexUtils.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Text.RegularExpressions;
+
+namespace bts.api.csharp.utils {
+   static class RegexUtils {
+      public static Regex default_regex(string pattern) {
+         // these patterns typically come from the user,
+         // so the 'should_ignore' delegate below allows them
+         // to include all results by specifying "all" or "*".
+         return default_regex(pattern, p => string.IsNullOrEmpty(p) || p == "*" || p.ToLower() == "all");
+      }
+
+      public static Regex default_regex(string pattern, Func<string, bool> should_ignore) {
+         if (pattern == null)
+            return null;
+         pattern = pattern.Trim();
+         if (pattern == string.Empty)
+            return null;
+         return new Regex(pattern, RegexOptions.IgnoreCase | RegexOptions.IgnorePatternWhitespace);
+      }
+
+      public static Func<T, bool> to_predicate<T>(this Regex regex) =>
+         regex == null ? null : new Func<T, bool>(val => regex.IsMatch(val.ToString()));
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/SecurityUtils.cs

@@ -1,8 +1,52 @@
-using System;
+using bts.api.core;
+using System;
 using System.Collections.Generic;
-using System.Text;
+using System.Linq;
+using System.Reactive.Linq;
+using System.Threading.Tasks;
+using SymbolTableGroup = bts.api.core.TableUpdateGrouping<bts.api.SecurityImmutable, uint, string>;
 
 namespace bts.api.csharp.utils {
    static class SecurityUtils {
+      public static IObservable<TableUpdate<SymbolTableGroup, string>> GroupBySymbols(this IObservable<TableUpdate<SecurityImmutable, uint>> securities_source) =>
+         securities_source.GroupTable(sec => sec.Id, sec => sec.Symbol);
+
+      public static async Task<SecurityImmutable> get_security_async(IObservable<Update<SecurityImmutable, uint>> source, string security_str = null) {
+         if (!string.IsNullOrEmpty(security_str)) {
+            Func<SecurityImmutable, bool> is_match;
+            // the user may specify the security string, or security key
+            if (uint.TryParse(security_str, out var sec_key)) {
+               is_match = sec => sec.Id == sec_key;
+            } else {
+               // ignore case and white space
+               security_str = security_str.Replace(" ", "").ToLower();
+               is_match = sec => sec.ToString().Replace(" ", "").ToLower() == security_str;
+            }
+            return await source.Select(update => {
+               foreach (var sec in update.all) {
+                  if (is_match(sec))
+                     return sec;
+               }
+               return (SecurityImmutable?)null;
+            })
+            .Where(sec => sec.HasValue)
+            .Select(sec => sec.Value)
+            .FirstAsync();
+         } else {
+            return await source.Where(update => update.all.Any())
+               .Select(update => update.all.First())
+               .FirstAsync();
+         }
+      }
+
+      public static class Predicates {
+         public static Func<SecurityImmutable, bool> symbols(IEnumerable<string> symbols) {
+            if (symbols is null)
+               return sec => true;
+            // use hashset for quicker Contains check
+            var symbols_set = new HashSet<string>(symbols);
+            return sec => symbols_set.Contains(sec.Symbol);
+         }
+      }
    }
 }

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/StringUtils.cs

@@ -0,0 +1,40 @@
+using bts.api.core;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace bts.api.csharp.utils {
+   static class StringUtils {
+      public static IEnumerable<string> format_columns(IEnumerable<IEnumerable<string>> columns, int min_width = 8, int padding = 3) =>
+         format_columns(columns.Select(lines => (Math.Max(min_width, lines.Max(l => l.Length) + padding), lines)));
+
+      public static IEnumerable<string> format_columns(IEnumerable<(int width, IEnumerable<string> lines)> columns) {
+         var column_layout = columns.Select((column, index) => (column.lines.GetEnumerator(), column.width, index)).ToList();
+         int num_active = column_layout.Count;
+         if (num_active == 0)
+            yield break;
+         while (true) {
+            var sb = new StringBuilder();
+            for (int i = 0; i < column_layout.Count; i++) {
+               var (en, width, pos) = column_layout[i];
+               if (en != null && en.MoveNext()) {
+                  sb.Append(string.Format($"{{{0},{-width}}}", en.Current));
+                  sb.Append(string.Format($"{{{0,1}}}", "| "));
+               } else {
+                  sb.Append(string.Format($"{{{0},{-width}}}", ""));
+                  sb.Append(string.Format($"{{{0,1}}}", "| "));
+                  if (en != null) {
+                     // set the enumerable to null to inidicate this column is empty for the remaining rows
+                     en.Dispose();
+                     column_layout[i] = (null, width, pos);
+                     if (--num_active == 0)
+                        yield break;
+                  }
+               }
+            }
+            yield return sb.ToString();
+         }
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/TaskExtensions.cs

@@ -0,0 +1,10 @@
+using System.Threading.Tasks;
+
+namespace bts.api.csharp.utils {
+   static class TaskExtensions {
+      public static T WaitResult<T>(this Task<T> task) {
+         task.Wait();
+         return task.Result;
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/utils/UpdateUtils.cs

@@ -0,0 +1,114 @@
+using bts.api.core;
+using mbts;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace bts.api.csharp.utils {
+   static class UpdateUtils {
+      /// <summary>
+      /// Uses a value-subscription delegate to create subscriptions (incrementally) for each value in the update sequence.
+      /// When a value is removed or changed, its corresponding subscription is disposed; if it changed, a new subscription is created with the new value.
+      /// </summary>
+      /// <typeparam name="T">The type of values in the updates.</typeparam>
+      /// <typeparam name="TKey">The type of keys in the updates.</typeparam>
+      /// <param name="update_stream">The update sequence.</param>
+      /// <param name="subscribe_value">The delegate to create a subscription for a particular value.</param>
+      /// <returns>An IDisposable that, upon being disposed, disposes the subscription to the update sequence, and all active value subscriptions.</returns>
+      public static IDisposable subscribe_incremental_values<T, TKey>(IObservable<Update<T, TKey>> update_stream, Func<T, IDisposable> subscribe_value)
+         where TKey : IEquatable<TKey> {
+         var locker = new object();
+         var value_subs = new Dictionary<TKey, IDisposable>();
+         var source_sub = update_stream.Subscribe(on_update);
+         return Disposable.Create(dispose);
+
+         // local methods
+         void on_update(Update<T, TKey> update) {
+            lock (locker) {
+               foreach (var value in update.removed) {
+                  var k = update.key(value);
+                  value_subs[k].Dispose();
+                  value_subs.Remove(k);
+               }
+               foreach (var ch in update.changes) {
+                  var k = update.key(ch.New);
+                  value_subs[k].Dispose();
+                  value_subs[k] = subscribe_value(ch.New);
+               }
+               foreach (var value in update.added) {
+                  value_subs.Add(update.key(value), subscribe_value(value));
+               }
+            }
+         }
+
+         void dispose() {
+            lock (locker) {
+               source_sub.Dispose();
+               foreach (var loop in value_subs.Values) {
+                  loop.Dispose();
+               }
+            }
+         }
+      }
+
+      public static IObservable<TableUpdate<T, TKey>> SafeFilter<T, TKey>(this IObservable<TableUpdate<T, TKey>> source, Func<T, bool> filter) where TKey : IEquatable<TKey> =>
+         filter == null ? source : source.Filter(filter);
+
+      public static bool is_empty<T, TKey>(this TableUpdate<T, TKey> table) where TKey : IEquatable<TKey> =>
+         !table.added.Any() && !table.changes.Any() && !table.removed.Any();
+
+      public static void print_incremental_changes<T, TKey>(Update<T, TKey> update, Func<T, TKey> key_fn, Func<T, string> fmt_value, string title) where TKey :IEquatable<TKey> {
+         print_incremental_changes<T, TKey>(update.added, update.changes, update.removed, v => $"{key_fn(v)}: {fmt_value(v)}", title);
+      }
+
+      public static void print_incremental_changes<T, TKey>(TableUpdate<T, TKey> table, Func<T, TKey> key_fn, Func<T, string> fmt_value, string title) where TKey :IEquatable<TKey> {
+         if (fmt_value is null)
+            fmt_value = v => v.ToString();
+         print_incremental_changes<T, TKey>(table.added, table.changes, table.removed, v => $"{key_fn(v)}: {fmt_value(v)}", title);
+      }
+
+      public static void print_incremental_changes<T, TKey>(IEnumerable<T> added, IEnumerable<Change<T>> changes, IEnumerable<T> removed, Func<T, string> fmt, string title) {
+         if (fmt is null)
+            fmt = v => v?.ToString() ?? "(null)";
+         var console_out = new StringBuilder();
+         Console.WriteLine($"Received {title} update");
+         var lines = StringUtils.format_columns(new[] {
+            added.Select(fmt).Prepend("  Added  "),
+            changes.Select(ch => ch.New).Select(fmt).Prepend("  Changed  "),
+            removed.Select(fmt).Prepend("  Removed  ")
+         });
+         foreach (var l in lines)
+            Console.WriteLine("\t" + l);
+      }
+
+      public static void _print_incremental_changes<T, TKey>(IEnumerable<T> added, IEnumerable<Change<T>> changes, IEnumerable<T> removed, Func<T, string> fmt, string title) {
+         if (fmt is null)
+            fmt = v => v?.ToString() ?? "(null)";
+         var console_out = new StringBuilder();
+         console_out.AppendLine($"Received {title} update");
+         using (var added_en = added.GetEnumerator()) {
+            if (added_en.MoveNext()) {
+               console_out.AppendLine("  Added:");
+               do console_out.AppendLine("    " + fmt(added_en.Current));
+               while (added_en.MoveNext());
+            }
+         }
+         using (var changes_en = changes.GetEnumerator()) {
+            if (changes_en.MoveNext()) {
+               console_out.AppendLine("  Changes");
+               do console_out.AppendLine($"    {fmt(changes_en.Current.Old)} --> {fmt(changes_en.Current.New)}");
+               while (changes_en.MoveNext());
+            }
+         }
+         using (var removed_en = removed.GetEnumerator()) {
+            if (removed_en.MoveNext()) {
+               console_out.AppendLine("  Removed");
+               do console_out.AppendLine("    " + fmt(removed_en.Current));
+               while (removed_en.MoveNext());
+            }
+         }
+         Console.Write(console_out.ToString());
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/watch/WatchAccounts.cs

@@ -0,0 +1,46 @@
+using bts.api.admin;
+using bts.api.core;
+using bts.api.csharp.data;
+using bts.api.csharp.utils;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reactive.Concurrency;
+using System.Reactive.Linq;
+
+namespace bts.api.csharp.watch {
+   static class WatchAccounts {
+      /// <summary>
+      /// Uses the <see cref="AdminService"/> to subscribe to administrative data (users, accounts, permissions, etc.),
+      /// and displays account updates in the console window.
+      /// </summary>
+      public static IDisposable run(AdminService admin_service) {
+         // extract accounts from the admin data into an IObservable<IReadOnlyDictionary<uint, NameIDPair>>.
+         IObservable<IReadOnlyDictionary<uint, NameIDPair>> accounts_source =
+            admin_service.subscribei_admin_data()
+            .Select(update => {
+               // Note that update.all is an IEnumerable<AdminDataImmutable>,
+               // however, it should only have one element.  Pass the first element
+               // to the _map_accounts method, and return the resultant IReadOnlyDictionary.
+               return _map_accounts(update.all.FirstOrDefault());
+            });
+
+         // Use the 'Table' extension method to transform the accounts source from an IObservable<IReadOnlyDictionary<TKey, TValue>>
+         // into an IObservable<TableUpdate<TKey, TValue>> (the latter includes incremental update properties).
+         /// <see cref="TableUpdate{T, TKey}.added"/>
+         /// <see cref="TableUpdate{T, TKey}.changes"/>
+         /// <see cref="TableUpdate{T, TKey}.removed"/>
+         IObservable<TableUpdate<NameIDPair, uint>> incremental_accounts_source =
+            accounts_source.Table(account => account.id);
+
+         // subscribe to the incremental account updates,
+         // and print the changes in the console window.
+         return incremental_accounts_source
+            .ObserveOn(ThreadPoolScheduler.Instance)
+            .Subscribe(upd => UpdateUtils.print_incremental_changes(upd, acc => acc.id, acc => acc.name, "Accounts"));
+      }
+
+      static IReadOnlyDictionary<uint, NameIDPair> _map_accounts(AdminDataImmutable admin_data) =>
+         admin_data.Accounts.ToDictionary(acc => acc.Id, acc => new NameIDPair(acc.Name, acc.Id));
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/watch/WatchBooks.cs

@@ -0,0 +1,48 @@
+using bts.md;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reactive.Concurrency;
+using System.Reactive.Linq;
+using SecurityKey = System.UInt32;
+
+namespace bts.api.csharp.watch {
+   static class WatchBooks {
+      /// <summary>
+      /// Uses the <see cref="MarketDataService"/> to observe book updates
+      /// for an optionally filtered list of securities in the system,
+      /// and organize them into a dictionary.
+      /// </summary>
+      public static IDisposable run(MarketDataClient md_client, Func<SecurityImmutable, bool> security_predicate = null) {
+         var books = new Dictionary<SecurityKey, IMDBook>();
+         object locker = new object();
+         if (md_client is null)
+            throw new ArgumentNullException(nameof(md_client));
+         if (security_predicate is null)
+            security_predicate = new Func<SecurityImmutable, bool>(sec => true);
+         /// unlike the other api subscriptions, which publish <see cref="core.Update{T, TKey}"/>
+         /// this subscription publishes an <see cref="IEnumerable{T}"/>, so the updates are not incremental
+         /// (i.e., don't have added/removed/changed items).
+         return md_client.subscribe_book(security_predicate)
+            .ObserveOn(ThreadPoolScheduler.Instance)
+            .Subscribe(on_update);
+
+         void on_update(IEnumerable<IMDBook> new_books) {
+            lock (locker) {
+               foreach (var book in new_books) {
+                  Console.WriteLine($"{book.security} book updated: {_fmt_bbo(book)}.");
+                  books[book.security.Id] = book;
+               }
+            }
+         }
+      }
+
+      static string _fmt_bbo(IMDBook book) {
+         return $"{_fmt_price_size(book.bids.FirstOrDefault())} <--> {_fmt_price_size(book.asks.FirstOrDefault())}";
+      }
+
+      static string _fmt_price_size(PriceSize price_size) {
+         return price_size == null ? "N/A" : $"{price_size.size} @ {price_size.price}";
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/watch/WatchOrders.cs

@@ -0,0 +1,109 @@
+using bts.api.core;
+using bts.api.orderman;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Reactive.Concurrency;
+using System.Reactive.Linq;
+using AccountKey = System.UInt32;
+using OrderKey = System.UInt32;
+
+namespace bts.api.csharp.watch {
+   static class WatchOrders {
+      /// <summary>
+      /// Uses the <see cref="OrderService"/> to observe order updates, and group them by account.
+      /// Fills and status changes are displayed in the console window.
+      /// </summary>
+      public static IDisposable run(OrderService order_service, Func<OrderRecordImmutable, bool> predicate) {
+         /// 'OrderService' has 2 methods which can be used to subscribe to order updates.
+         ///  -------------------------------------------------------------------------------------
+         /// 1) <see cref="OrderService.subscribe_orders(string)"/>.
+         /// 2) <see cref="OrderService.subscribei_orders(string)"/>.
+         /// This method (no. 2) is typically preferrable because the data it provides is immutable.
+         /// --------------------------------------------------------------------------------------
+         var orders_source = order_service.subscribei_orders();
+         if (predicate != null)
+            orders_source = orders_source.Filter(predicate);
+         return run(orders_source.ObserveOn(ThreadPoolScheduler.Instance));
+      }
+
+      public static IDisposable run(IObservable<Update<OrderRecordImmutable, uint>> orders_source) {
+         object locker = new object();
+         var account_order_map = new Dictionary<AccountKey, Dictionary<OrderKey, OrderRecordImmutable>>();
+         return orders_source.Subscribe(on_update);
+
+         void on_order_added(OrderRecordImmutable new_order) {
+            if (!account_order_map.TryGetValue(new_order.Def.AccountId, out var account_orders)) {
+               // this is the first order for this account.
+               // initialize the account orders dictionary, and add it to our data.
+               account_orders = new Dictionary<AccountKey, OrderRecordImmutable>();
+               account_order_map.Add(new_order.Def.AccountId, account_orders);
+            }
+            _print_order_info(new_order, $"observed for the first time.");
+            // now add the order to account_orders
+            account_orders.Add(new_order.Key, new_order);
+         }
+
+         void on_order_changed(Change<OrderRecordImmutable> change) {
+            // ch.New and ch.Old have the same key.
+            Debug.Assert(change.New.Key == change.Old.Key);
+            var key = change.New.Key;
+            // detect fills
+            if (change.New.State.FilledQuantity != change.Old.State.FilledQuantity) {
+               if (change.New.State.FilledQuantity > change.New.State.Quantity) {
+                  // order has been overfilled
+                  var num_over_fills = change.New.State.FilledQuantity - change.New.State.Quantity;
+                  _print_order_info(change.New, $"overfilled by {num_over_fills}.");
+               } else if (change.New.State.FilledQuantity == change.New.State.Quantity) {
+                  // order has been filled to completion
+                  _print_order_info(change.New, "filled to completion");
+               } else if (change.New.State.Status == OrderStatus.Working) {
+                  // order is still working.
+                  var working_qty = change.New.State.Quantity - change.New.State.FilledQuantity;
+                  _print_order_info(change.New, $"still working {working_qty}");
+               } else {
+                  // order has stopped working prematurely (perhaps it was canceled)
+                  _print_order_info(change.New, $"is inactive");
+               }
+            }
+            // Account will not change, so our dictionary will definitely have a key for this account.
+            Debug.Assert(account_order_map.ContainsKey(change.New.Def.AccountId));
+            var account_orders = account_order_map[change.New.Def.AccountId];
+            // The value for this key in account_orders should equal ch.Old.
+            Debug.Assert(account_orders[key].Equals(change.Old));
+            // update account orders with the changed order. 
+            account_orders[key] = change.New;
+         }
+
+         void on_order_removed(OrderRecordImmutable old_val) {
+            // An entry for this order should be present in our data,
+            // as it is in the 'removed' items.
+            // Assert this is the case to illustrate the point.
+            Debug.Assert(account_order_map.ContainsKey(old_val.Def.AccountId));
+            var account_orders = account_order_map[old_val.Def.AccountId];
+            // the removed value should match the one currently in our data.
+            // Assert this is the case, then remove the order.
+            Debug.Assert(account_orders[old_val.Key].Equals(old_val));
+            account_orders.Remove(old_val.Key);
+         }
+
+         void on_update(Update<OrderRecordImmutable, OrderKey> update) {
+            lock (locker) {
+               foreach (OrderRecordImmutable new_order in update.added) {
+                  on_order_added(new_order);
+               }
+               foreach (Change<OrderRecordImmutable> change in update.changes) {
+                  on_order_changed(change);
+               }
+               foreach (OrderRecordImmutable old_order in update.removed) {
+                  on_order_removed(old_order);
+               }
+            }
+         }
+      }
+
+      static void _print_order_info(OrderRecordImmutable order, string message) {
+         Console.WriteLine($"Order {order.Key} ({order.State.Status}, filled {order.State.FilledQuantity}/{order.State.Quantity}): {message}.");
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/watch/WatchPositions.cs

@@ -0,0 +1,112 @@
+using bts.api.core;
+using bts.api.position;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Reactive.Concurrency;
+using System.Reactive.Linq;
+
+namespace bts.api.csharp.watch {
+   /// <summary>
+   /// A pair of security, and account id,
+   /// which uniquely identifies each PositionUnit.
+   /// </summary>
+   readonly struct PositionKey {
+      public PositionKey(uint security_id, uint account_id) {
+         this.security_id = security_id;
+         this.account_id = account_id;
+      }
+
+      public uint security_id { get; }
+      public uint account_id { get; }
+
+      public static PositionKey from_position(PositionUnitImmutable p) =>
+         new PositionKey(p.SecurityId, p.AccountId);
+
+      public override string ToString() =>
+         $"Sec {security_id}, Acc {account_id}";
+   }
+
+   static class WatchPositions {
+      /// <summary>
+      /// Uses the <see cref="PositionService"/> api to monitor positions
+      /// for every account/security pair, and organize them into a Dictionary.
+      /// </summary>
+      public static IDisposable run(PositionService position_service, Func<PositionUnitImmutable, bool> predicate) {
+         /// 'PositionService' has 2 methods which can be used to subscribe to position updates.
+         ///  -------------------------------------------------------------------------------------
+         /// 1) <see cref="PositionService.subscribe_position_data(string)"/>.
+         /// 2) <see cref="PositionService.subscribei_position_data(string)"/>.
+         /// This method (no. 2) is typically preferrable because the data it provides is immutable.
+         /// --------------------------------------------------------------------------------------
+         return run(position_service.subscribei_position_data().Filter(predicate).ObserveOn(ThreadPoolScheduler.Instance));
+      }
+
+      public static IDisposable run(IObservable<Update<PositionUnitImmutable, int>> position_source) {
+         var data = new Dictionary<PositionKey, PositionUnitImmutable>();
+         return position_source.Subscribe(on_update);
+
+         void on_position_added(PositionUnitImmutable new_val) {
+            var k = PositionKey.from_position(new_val);
+            // this entry should NOT be present in our _data, as it is in the 'added' items.
+            // Assert this is the case to illustrate the point.
+            Debug.Assert(!data.ContainsKey(k));
+            print_position_info(k, $"initial position received.  Day: Long {new_val.DayLongPos}, Short {new_val.DayShortPos}, Net {new_val.DayLongPos - new_val.DayShortPos}.");
+            // add the new position unit to _data
+            data.Add(k, new_val);
+         }
+
+         void on_position_changed(Change<PositionUnitImmutable> change) {
+            var k = PositionKey.from_position(change.New);
+            // ch.New and ch.Old have the same key (i.e., the Account/Security pair),
+            Debug.Assert(change.New.AccountId == change.Old.AccountId);
+            Debug.Assert(change.New.SecurityId == change.Old.SecurityId);
+            // of course, the value for this key in our dictionary should equal ch.Old.
+            Debug.Assert(data[k].Equals(change.Old));
+            // Display changes to the day position in the console window.
+            // 1) check if the day long changed
+            if (change.New.DayLongPos != change.Old.DayLongPos) {
+               print_position_info(k, $"day long changed from {change.Old.DayLongPos} to {change.New.DayLongPos}.");
+            }
+            // 2) check if day short changed
+            if (change.New.DayShortPos != change.Old.DayShortPos) {
+               print_position_info(k, $"day short changed from {change.Old.DayShortPos} to {change.New.DayShortPos}.");
+            }
+            // 3) check if net day position changed
+            var new_net_day_pos = change.New.DayLongPos - change.New.DayShortPos;
+            var old_net_day_pos = change.Old.DayLongPos - change.Old.DayShortPos;
+            if (new_net_day_pos != old_net_day_pos) {
+               print_position_info(k, $"day net changed from {old_net_day_pos} to {new_net_day_pos}.");
+            }
+            // update _data with the changed position.
+            data[k] = change.New;
+         }
+
+         void on_position_removed(PositionUnitImmutable old_val) {
+            var k = PositionKey.from_position(old_val);
+            // this entry should be present in our _data, as it is in the 'removed' items.
+            // Assert this is the case to illustrate the point.
+            Debug.Assert(data.ContainsKey(k));
+            // this should match our data.  Assert this is the case.
+            Debug.Assert(data[k].Equals(old_val));
+            data.Remove(k);
+         }
+
+         void on_update(Update<PositionUnitImmutable, int> update) {
+            foreach (PositionUnitImmutable p in update.added) {
+               on_position_added(p);
+            }
+            foreach (Change<PositionUnitImmutable> ch in update.changes) {
+               on_position_changed(ch);
+            }
+            foreach (PositionUnitImmutable p in update.removed) {
+               on_position_removed(p);
+            }
+         }
+
+         void print_position_info(PositionKey position_key, string message) {
+            Console.WriteLine($"Position {position_key}: {message}.");
+         }
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/watch/WatchSecurities.cs

@@ -0,0 +1,22 @@
+using bts.api.core;
+using bts.api.csharp.utils;
+using System;
+using System.Reactive.Concurrency;
+using System.Reactive.Linq;
+
+namespace bts.api.csharp.watch {
+   static class WatchSecurities {
+      public static IDisposable run(MarketDataService market_data_service, Func<SecurityImmutable, bool> predicate) {
+         // watch securities
+         var securities = market_data_service.subscribei_securities().Table();
+         if (predicate != null)
+            securities = securities.Filter(predicate);
+         return securities
+            .ObserveOn(ThreadPoolScheduler.Instance)
+            .Subscribe(upd => {
+               if (!upd.is_empty())
+                  UpdateUtils.print_incremental_changes(upd, sec => sec.Id, null, "Securities");
+            });
+      }
+   }
+}

src/sdk/examples/client_sdk/bts.api.csharp/src/bts/api/csharp/watch/WatchSymbols.cs

@@ -0,0 +1,48 @@
+using bts.api.core;
+using System;
+using System.Linq;
+using System.Reactive.Concurrency;
+using System.Reactive.Linq;
+using SymbolTableGroup = bts.api.core.TableUpdateGrouping<bts.api.SecurityImmutable, uint, string>;
+
+namespace bts.api.csharp.watch {
+   static class WatchSymbols {
+      /// <summary>
+      /// Observes securities via <see cref="MarketDataService.subscribei_securities(string)"/>, and prints newly received symbols to the console.
+      /// </summary>
+      /// <returns>An IDisposable to dispose the subscription to the securities source.</returns>
+      public static IDisposable run(MarketDataService market_data_service) {
+         return run(market_data_service.subscribei_securities().Table());
+      }
+
+      /// <summary>
+      /// Observes a security update sequence, and prints newly received symbols to the console.
+      /// </summary>
+      /// <returns>An IDisposable to dispose the subscription to the securities source.</returns>
+      public static IDisposable run(IObservable<TableUpdate<SecurityImmutable, uint>> securities_source) {
+         ushort update_count = 0;
+         object locker = new object();
+         return securities_source.GroupTable(sec => sec.Id, sec => sec.Symbol)
+            .ObserveOn(ThreadPoolScheduler.Instance)
+            .Subscribe(on_update);
+
+         void on_update(TableUpdate<SymbolTableGroup, string> group_update) {
+            lock (locker) {
+               var num_new_securities = group_update.added.Concat(group_update.changed).Sum(grp => grp.table.added.Count());
+
+               Console.WriteLine(
+                  $"Security update number {++update_count} provided {num_new_securities} new securities " +
+                  $"on {group_update.added.Count()} new symbols.");
+
+               var new_symbols = group_update.added
+                  .Select(table_group => table_group.group_key)
+                  .OrderBy(sym => sym);
+
+               foreach (var new_symbol in new_symbols) {
+                  Console.WriteLine("\t" + new_symbol);
+               }
+            }
+         }
+      }
+   }
+}