diff --git a/.cursor/rules/cryptoexchange-net.mdc b/.cursor/rules/cryptoexchange-net.mdc index f1952fc5..865c81c6 100644 --- a/.cursor/rules/cryptoexchange-net.mdc +++ b/.cursor/rules/cryptoexchange-net.mdc @@ -30,6 +30,14 @@ var ticker = await binance.GetSpotTickerAsync(new GetTickerRequest(symbol)); `SharedSymbol(TradingMode.Spot, "BTC", "USDT")` is portable. Each library translates to its native format internally. Don't pass raw strings like `"BTCUSDT"` to shared methods. +## Symbol metadata and catalogs + +In 12.2.0, `SharedSpotSymbol` and `SharedFuturesSymbol` include `DisplayName` and base/quote asset classification through `SharedAssetType` (`Crypto`, `Fiat`, `TradFi`) and `SharedAssetSubType` (`StableCoin`, `Equity`, `Commodity`). Pass the matching base/quote filters to `GetSymbolsRequest` when discovery should return only a class of markets. + +After calling `GetSpotSymbolsAsync`, `ISpotSymbolRestClient.SpotSymbolCatalog` maps asset and symbol names to shared metadata. `IFuturesSymbolRestClient.FuturesSymbolCatalog` works the same way after `GetFuturesSymbolsAsync`. Treat either property as unavailable before its corresponding request has populated the cache. + +When implementing an exchange library, use `LibraryHelpers.IsStableCoin`, `IsCommodity`, and `IsEquity` only as best-effort classifiers and supply exchange-specific additions where needed. + ## Result pattern REST methods return `HttpResult` and websocket subscription methods return `WebSocketResult`. Always check `.Success`. `.Exchange` property identifies which exchange responded — useful for logging. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 899b447b..93abc638 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -24,6 +24,12 @@ var ticker = await binance.GetSpotTickerAsync(new GetTickerRequest(symbol)); Same code works on every exchange that implements the interface. Use `Task.WhenAll` for concurrent multi-exchange calls. +## Shared symbol metadata + +CryptoExchange.Net 12.2.0 classifies the base and quote sides of `SharedSpotSymbol` and `SharedFuturesSymbol` with `SharedAssetType` (`Crypto`, `Fiat`, `TradFi`) and optional `SharedAssetSubType` (`StableCoin`, `Equity`, `Commodity`). The models also expose `DisplayName`. Use the corresponding base/quote fields on `GetSymbolsRequest` to filter symbol discovery. + +`ISpotSymbolRestClient.SpotSymbolCatalog` is populated by `GetSpotSymbolsAsync`; `IFuturesSymbolRestClient.FuturesSymbolCatalog` is populated by `GetFuturesSymbolsAsync`. Do not assume a catalog is available before that request. For exchange-library implementations, `LibraryHelpers.IsStableCoin`, `IsCommodity`, and `IsEquity` offer best-effort classification and can be extended with exchange-specific values. + ## Single-exchange code uses the exchange's own client For Binance-only code, use `BinanceRestClient` directly (see Binance.Net repo `AGENTS.md`). SharedApis is for portability — use it when you need that. diff --git a/AGENTS.md b/AGENTS.md index c3e47557..d3982627 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,24 @@ var btcusdtPerp = new SharedSymbol(TradingMode.PerpetualLinear, "BTC", "USDT"); For exchanges that use exotic asset names, see the AssetAliases configuration. +## Symbol Metadata and Asset Classification + +Since CryptoExchange.Net 12.2.0, shared symbol responses describe both sides of a market with `BaseAssetType`, `BaseAssetSubType`, `QuoteAssetType`, and `QuoteAssetSubType`. `SharedAssetType` distinguishes `Crypto`, `Fiat`, and `TradFi`; `SharedAssetSubType` distinguishes `StableCoin`, `Equity`, and `Commodity`. `SharedSpotSymbol` and `SharedFuturesSymbol` also expose `DisplayName`. + +The same fields on `GetSymbolsRequest` filter spot or futures symbol discovery: + +```csharp +var request = new GetSymbolsRequest( + baseAssetType: SharedAssetType.Crypto, + quoteAssetSubType: SharedAssetSubType.StableCoin); + +var result = await symbolClient.GetSpotSymbolsAsync(request); +``` + +After calling `GetSpotSymbolsAsync` or `GetFuturesSymbolsAsync`, use the client's `SpotSymbolCatalog` or `FuturesSymbolCatalog` to look up normalized asset and symbol metadata by name. The catalog is unavailable until the corresponding symbol request has populated the cache. + +For exchange-library implementations, `LibraryHelpers.IsStableCoin`, `IsCommodity`, and `IsEquity` provide best-effort classification of known assets and accept exchange-specific additions. These helpers are heuristics, not an exhaustive source of truth. + ## Available Shared Interfaces **REST:** diff --git a/CryptoExchange.Net/CryptoExchange.Net.csproj b/CryptoExchange.Net/CryptoExchange.Net.csproj index 8de8c389..4698d2d3 100644 --- a/CryptoExchange.Net/CryptoExchange.Net.csproj +++ b/CryptoExchange.Net/CryptoExchange.Net.csproj @@ -6,9 +6,9 @@ CryptoExchange.Net JKorf CryptoExchange.Net is a base library which is used to implement different cryptocurrency (exchange) API's. It provides a standardized way of implementing different API's, which results in a very similar experience for users of the API implementations. - 12.1.1 - 12.1.1 - 12.1.1 + 12.2.0 + 12.2.0 + 12.2.0 false OKX;OKX.Net;Mexc;Mexc.Net;Kucoin;Kucoin.Net;Kraken;Kraken.Net;Huobi;Huobi.Net;CoinEx;CoinEx.Net;Bybit;Bybit.Net;Bitget;Bitget.Net;Bitfinex;Bitfinex.Net;Binance;Binance.Net;CryptoCurrency;CryptoCurrency Exchange;CryptoExchange.Net git diff --git a/README.md b/README.md index 1657d49b..c0f21208 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,16 @@ Various: * PlatformInfo now required support environment names in the constructor ## Release notes +* Version 12.2.0 - 20 Jul 2026 + * Added SpotSymbolCatalog to Shared ISpotSymbolRestClient interface + * Added FuturesSymbolCatalog to Shared IFuturesSymbolRestClient interface + * Added BaseAssetType, BaseAssetSubType, QuoteAssetType and QuoteAssetSubType to GetSymbolsRequest model + * Added DisplayName to SharedSpotSymbol and SharedFuturesSymbol models + * Added BaseAssetType, BaseAssetSubType, QuoteAssetType and QuoteAssetSubType to SharedSpotSymbol and SharedFuturesSymbol models + * Added IsStableCoin, IsCommodity and IsEquity helper methods to LibraryHelpers + * Added DebuggerDisplay attributes to Shared models + * Fixed socket connection combine calculations + * Version 12.1.1 - 11 Jul 2026 * Added timestamp deserialization support for yyyy-MM-dd HH:mm:ss.ffffff+00:00:00 diff --git a/llms.txt b/llms.txt index 40839458..6b45fb1f 100644 --- a/llms.txt +++ b/llms.txt @@ -2,10 +2,12 @@ > Base C#/.NET library for cryptocurrency exchange API client implementations. Provides a standardized abstraction (REST, WebSocket, authentication, rate limiting, error handling, order book management, shared cross-exchange interfaces) that 28+ exchange-specific libraries are built on top of. -CryptoExchange.Net itself is not used directly — install one of the exchange-specific libraries (Binance.Net, Bybit.Net, OKX.Net, Kraken.Net, Coinbase.Net, etc.) or `CryptoClients.Net` to access all exchanges via a single bundle. The base library is what makes the entire ecosystem feel consistent: same `HttpResult` REST result pattern, same `WebSocketResult` websocket subscription pattern, same DI registration, same shared interfaces across all exchanges. Current version: 12.x. Targets netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0. Native AOT supported. +CryptoExchange.Net itself is not used directly — install one of the exchange-specific libraries (Binance.Net, Bybit.Net, OKX.Net, Kraken.Net, Coinbase.Net, etc.) or `CryptoClients.Net` to access all exchanges via a single bundle. The base library is what makes the entire ecosystem feel consistent: same `HttpResult` REST result pattern, same `WebSocketResult` websocket subscription pattern, same DI registration, same shared interfaces across all exchanges. Current version: 12.2.0. Targets netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0. Native AOT supported. The standout feature for cross-exchange code is `CryptoExchange.Net.SharedApis` — a set of interfaces (`ISpotTickerRestClient`, `ISpotOrderRestClient`, `IBalanceRestClient`, etc.) implemented by every exchange library. Same call signature works against any exchange. +Version 12.2.0 adds typed asset metadata to shared symbol discovery. `SharedSpotSymbol` and `SharedFuturesSymbol` expose `DisplayName` plus base/quote `SharedAssetType` and `SharedAssetSubType` values. `GetSymbolsRequest` can filter on those four type fields. After symbol discovery, `ISpotSymbolRestClient.SpotSymbolCatalog` and `IFuturesSymbolRestClient.FuturesSymbolCatalog` provide asset and symbol dictionaries; each catalog is available only after the corresponding `Get*SymbolsAsync` call. `LibraryHelpers.IsStableCoin`, `IsCommodity`, and `IsEquity` are best-effort helpers for exchange-library implementations. + ## Documentation - [README](https://github.com/JKorf/CryptoExchange.Net/blob/master/README.md): Overview, full ecosystem table (28+ exchange libraries), installation per exchange, complete release notes