A .Net wrapper for the Binance API as described on Binance, including all features.
Binance.Net is available on Nuget.
pm> Install-Package Binance.Net
Two examples have been provided, a console application providing the basis interaction with the API wrapper, and a WPF application showing some more advanced use casus. Both can be found in the Examples folder.
Start using the API by including using Binance.Net;
in your usings.
Binance.Net provides two clients to interact with the Binance API. The BinanceClient
provides all rest API calls. The BinanceSocketClient
provides functions to interact with the Websockets provided by the Binance API. Both clients are disposable and as such can be used in a using
statement:
using(var client = new BinanceClient())
{
}
using(var client = new BinanceSocketClient())
{
}
For most API methods Binance.Net provides two versions, synchronized and async calls.
For private endpoints (trading, order history, account info etc) an API key and secret has to be provided. For this the SetApiCredentials
method can be used in both clients, or the credentials can be provided as arguments:
using(var client = new BinanceClient("APIKEY", "APISECRET"))
{
client.SetApiCredentials("APIKEY", "APISECRET");
}
Alternatively the credentials can be set as default in BinanceDefaults to provide them to all new clients.
BinanceDefaults.SetDefaultApiCredentials("APIKEY", "APISECRET");
API credentials can be managed at https://www.binance.com/userCenter/createApi.html. Make sure to enable the required permission for the right API calls.
All API requests will respond with an BinanceApiResult object. This object contains whether the call was successful, the data returned from the call and an error if the call wasn't successful. As such, one should always check the Success flag when processing a response. For example:
using(var client = new BinanceClient())
{
var allPrices = client.GetAllPrices();
if (allPrices.Success)
{
foreach (var price in allPrices.Data)
Console.WriteLine($"{price.Symbol}: {price.Price}");
}
else
Console.WriteLine($"Error: {allPrices.Error.Message}");
}
If not successful the Error object will contain an error code and an error message as to what went wrong. Error codes are divided in 3 categories. Any errors outside these categories are generated by Binance self.
- 5000 - 5999: input errors. There was a problem when validating the input for a method. Check the input and try again.
- 6000 - 6999: returned errors. The server returned a service error. If this error is persistent check if Binance is online or has any status updates regarding connectivity. If this issue persists please open an Issue.
- 7000 - 7999: output errors. The server returned data, but we we're unable to successfully parse the response. If this error is persistent please open an Issue.
The BinanceClient
provides an automatic retry for when the server returns error status codes, for example when a gateway timeout occurs or the service is temporarily unavailable.
The amount of retries can be set in the client by setting the MaxRetry
property. This can also be set to a default value by the SetDefaultRetries
funtion in BinanceDefaults.
:
// On a single client
var client = new BinanceClient();
client.MaxRetries = 3;
// On all new clients:
BinanceDefaults.SetDefaultRetries(3);
The default amount of retries is 2, setting it to 0 will disable the functionality.
Public requests:
using(var client = new BinanceClient())
{
// Pings the API to check the connection
var ping = client.Ping();
// Gets the server time
var serverTime = client.GetServerTime();
// Gets the order book for specified symbol
var orderBook = client.GetOrderBook("BNBBTC", 10);
// Gets a compresed view of trades for specified symbol
var aggTrades = client.GetAggregatedTrades("BNBBTC", startTime: DateTime.UtcNow.AddMinutes(-2), endTime: DateTime.UtcNow, limit: 10);
// Gets klines data for the specified symbol
var klines = client.GetKlines("BNBBTC", KlineInterval.OneHour, startTime: DateTime.UtcNow.AddHours(-10), endTime: DateTime.UtcNow, limit: 10);
// Gets prices and changes in the last 24 hours for specified symbol
var prices24h = client.Get24HPrice("BNBBTC");
// Gets all symbols and latest prices
var allPrices = client.GetAllPrices();
// Gets book prices (asks/bids) for all symbols
var allBookPrices = client.GetAllBookPrices();
}
Private requests:
using(var client = new BinanceClient())
{
// Gets all open orders for specified symbol
var openOrders = client.GetOpenOrders("BNBBTC");
// Gets all orders for specified symbol
var allOrders = client.GetAllOrders("BNBBTC");
// Places a test order to test the API functionality. No order will actually be placed
var testOrderResult = client.PlaceTestOrder("BNBBTC", OrderSide.Buy, OrderType.Limit, 1, price: 1, timeInForce: TimeInForce.GoodTillCancel);
// Request information about an order
var queryOrder = client.QueryOrder("BNBBTC", allOrders.Data[0].OrderId);
// Places an order. `price` is optional parameter, if not set, order price will use market value
var orderResult = client.PlaceOrder("BNBBTC", OrderSide.Sell, OrderType.Limit, 10, price: 0.0002m, timeInForce: TimeInForce.GoodTillCancel);
// Cancels an existing order
var cancelResult = client.CancelOrder("BNBBTC", orderResult.Data.OrderId);
// Gets information about your account
var accountInfo = client.GetAccountInfo();
// Gets all trades for specified symbol
var myTrades = client.GetMyTrades("BNBBTC");
// Gets your deposit history
var depositHistory = client.GetDepositHistory();
// Gets your withdraw history
var withdrawalHistory = client.GetWithdrawHistory();
// Requests a withdraw
var withdraw = client.Withdraw("TEST", "Address", 1, "TestWithdraw");
}
The Binance.Net socket client provides several socket endpoint to which can be subsribed.
Public socket endpoints:
using(var client = new BinanceSocketClient())
{
var successDepth = client.SubscribeToDepthStream("bnbbtc", (data) =>
{
// handle data
});
var successTrades = client.SubscribeToTradesStream("bnbbtc", (data) =>
{
// handle data
});
var successKline = client.SubscribeToKlineStream("bnbbtc", KlineInterval.OneMinute, (data) =>
{
// handle data
});
}
Private socket endpoints:
For the private endpoints a user stream has to be started on the Binance server. This can be done using the client.StartUserStream()
command in the BinanceClient
. This command will return a listen key which can then be provided to the private socket subscriptions:
using(var client = new BinanceSocketClient())
{
var successAccount = client.SubscribeToAccountUpdateStream(listenKey, (data) =>
{
// handle data
});
var successOrder = client.SubscribeToOrderUpdateStream(listenKey, (data) =>
{
// handle data
});
}
Unsubscribing from socket endpoints:
Public socket endpoints can be unsubscribed by using the client.UnsubscribeFromStream
method in combination with the stream ID received from subscribing:
using(var client = new BinanceSocketClient())
{
var successDepth = client.SubscribeToDepthStream("bnbbtc", (data) =>
{
// handle data
});
client.UnsubscribeFromStream(successDepth.Data);
}
Private socket endpoints can be unsubscribed using the specific methods client.UnsubscribeFromAccountUpdateStream
and client.UnsubscribeFromOrderUpdateStream
.
Additionaly, all sockets can be closed with the UnsubscribeAllStreams
method. Beware that when a client is disposed the sockets are automatically disposed. This means that if the code is no longer in the using statement the eventhandler won't fire anymore. To prevent this from happening make sure the code doesn't leave the using statement or don't use the socket client in a using statement:
// Doesn't leave the using block
using(var client = new BinanceSocketClient())
{
var successDepth = client.SubscribeToDepthStream("bnbbtc", (data) =>
{
// handle data
});
Console.ReadLine();
}
// Without using block
var client = new BinanceSocketClient();
client.SubscribeToDepthStream("bnbbtc", (data) =>
{
// handle data
});
When no longer listening to private endpoints the client.StopUserStream
method in BinanceClient
should be used to signal the Binance server the stream can be closed.
For some private calls a timestamp has to be send to the Binance server. This timestamp in combination with the recvWindow parameter in the request will determine how long the request will be valid. If more than the recvWindow in miliseconds has passed since the provided timestamp the request will be rejected.
While testing I found that my local computer time was offset to the Binance server time, which made it reject all my requests. I added a fix for this in the Binance.Net client which will automatically calibrate the timestamp to the Binance server time. This behaviour is turned off by default and can be turned on using the client.AutoTimeStamp
property.
The Binance API provides some basic filters to which orders should comply. These include a min/max price and quantity and step sizes. Binance.Net can automatically check these rules when placing an order, before actually sending it to the server. This is managed with the TradeRulesBehaviour
property on BinanceClient
(also available in BinanceDefaults
).
There are 3 options:
None
: Binance.Net will not validate the order and send it to the Binance server as is.ThrowError
: Binance.Net will check if the order complies with the trade rules. If it does not the order will not be placed and an error is returned.AutoComply
: Binance.Net will check if the order complies with the trade rules. If it does not the invalid parameters will be automatically adjusted to the nearest valid value.
Note that if the TradeRulesBehaviour
is set to ThrowError
or AutoComply
Binance.Net will internally do a GetExchangeInfo
request initialy to request the current rules. After that it will update these rules every 60 minutes with new data by doing a new GetExchangeInfo
request.
The interval at which this happens can be controlled by the TradeRulesUpdateInterval
property (also available in BinanceDefaults
).
Binance.Net will by default log warning and error messages. To change the verbosity SetLogVerbosity
can be called on a client. The default log verbosity for all new clients can also be set using the SetDefaultLogVerbosity
in BinanceDefaults
.
Binance.Net logging will default to logging to the Trace (Trace.WriteLine). This can be changed with the SetLogOutput
method on clients. Alternatively a default output can be set in the BinanceDefaults
using the SetDefaultLogOutput
method:
BinanceDefaults.SetDefaultLogOutput(Console.Out);
BinanceDefaults.SetDefaultLogVerbosity(LogVerbosity.Debug);
-
Version 2.2.5 - 24 jan 2018
- Added optional automated checking of trading rules when placing an order
- Added
BinanceHelpers
static class containing some basic helper functions - Fix for default logger not writing on a new line
- Simplified internal defaults
-
Version 2.2.4 - 23 jan 2018
- Fix for RateLimit type in GetExchangeInfo
- Split the BinanceSymbolFilter in 3 classes
-
Version 2.2.3 - 15 jan 2018
- Fix for calls freezing when made from UI thread
-
Version 2.2.2 - 15 jan 2018
- Fix in PlaceOrder using InvariantCulture
- Fix for FirstId property in 24h price
- Added symbol property to 24h price
-
Version 2.2.1 - 12 jan 2018
- Fix for parse error in StreamOrderUpdate
-
Version 2.2.0 - 08 jan 2018
- Updated according to latest documentation, adding various endpoints
-
Version 2.1.3 - 9 nov 2017
- Added automatic configurable retry on server errors
- Refactor on error returns
- Renamed ApiResult to BinanceApiResult
-
Version 2.1.2 - 31 okt 2017
- Added alot of code documentation
- Small cleanups and fix
-
Version 2.1.1 - 30 okt 2017
- Fix for socket closing
-
Version 2.1.0 - 30 okt 2017
- Small rename/refactor, BinanceSocketClient also use ApiResult now
-
Version 2.0.1 - 30 okt 2017
- Improved error messages/handling in BinanceClient
- Extra unit tests for failing requests
-
Version 2.0.0 - 25 okt 2017
- Changed from static class to object orriented, added IDisposable interface to be able to use
using
statements - Split websocket and restapi functionality in BinanceClient and BinanceSocketClient
- Added method to set log output writer
- Added abitlity to set defaults for new clients
- Fixed unit tests for new setup
- Updated documentation
- Changed from static class to object orriented, added IDisposable interface to be able to use
-
Version 1.1.2 - 25 okt 2017
- Added
UnsubscribeAllStreams
method
- Added
-
Version 1.1.1 - 20 okt 2017
- Fix for withdrawal/deposit filter
-
Version 1.1.0 - 20 okt 2017
- Updated withdrawal/deposit functionality according to API changes
- Cleaned up BinanceClient a bit
-
Version 1.0.9 - 19 okt 2017
- Added withdrawal/deposit functionality