mircofx/futurebinanceapi

A simple library for working with Future Binance API supporting all types of orders, endpoints for market, order and account

Future Binance API

This library allows to you use simply an API of crypto exchange Future Binance

In this moment the library supports main methods of API and has a custom request

0. Clients

There are 3 clients: AuthClient, DefaultClient and StreamClient.

AuthClient has API-key and Secret-Key for HTTP-request.
DefaultClient will use for non-auth request(Endpoint's Market and etc...)
StreamClient will use for stream events(see 4. Stream)

Note: To set parametr "useTestnet" in true for use API of Binance Futures Testnet(https://testnet.binancefuture.com). Else if you use the main exchange (https://www.binance.com/ru/futures/BTCUSDT) then set "useTestnet" in false or just ignore it

In depending of type a constructor has another arguments:

AuthClient(string _APIKey, string _SecretKey, bool useTestnet = false)
...
DefaultClient(bool useTestnet = false)
...
StreamClient(string userListenKey, bool useTestnet = false)
...
StreamClient(string userListenKey, string webSocketUrl)

Create a client:

AuthClient authClient = new AuthClient("my_api_key", "my_secret_key"); // Create the client for an auth request
DefaultClient defaultClient = new DefaultClient(); // Create the client for no auth request
StreamClient streamClient = new StreamClient("listener_key"); // Create the client for stream events

You can change RecvWindow for a client

...
authClient.RecvWindow = 5000;

1. EndPoints

Using a client object(IClient) you can use anymore endpoint. A list of endpoints:

1. TickerEndPoint
2. TradeEndPoint
3. OrderEndPoint
4. AccountEndPoint
5. StreamEndPoint

1.1. TickerEndPoint

DefaultClient client = new DefaultClient(true); // Create a default client
TickerEndPoint market = new TickerEndPoint(client); // Create a market endpoint

The endpoint has methods:

GetPriceTicker

Fetch latest price for a symbol or symbols.

public async Task<IEnumerable<PriceTicker>> GetPriceTickerAsync()
public async Task<PriceTicker> GetPriceTickerAsync(TraidingPair symbol)

Example:

...
IEnumerable<PriceTicker> priceSymbols = await market.GetPriceTickerAsync();
PriceTicker priceSymbol = await market.GetPriceTickerAsync(TraidingPair.BTCUSDT);

GetBookTicker

Fetch best price/qty on the order book for a symbol or symbols.

public async Task<IEnumerable<BookTicker>> GetBookTickerAsync()
public async Task<BookTicker> GetBookTickerAsync(TraidingPair symbol)

Example:

...
IEnumerable<BookTicker> bestPriceForSymbols = await market.GetBookTickerAsync();
BookTicker bestPrice = await market.GetBookTickerAsync(TraidingPair.BTCUSDT);

1.2. TradeEndPoint

AuthClient is mandatory for this endpoint

AuthClient client = new AuthClient("API_key", "Secret_key", true); // Create an auth client
TradeEndPoint trade = new TradeEndPoint(client); // Create a trade endpoint

The endpoint has methods:

SetLeverage

Will set a leverage for a given symbol

public async Task<Leverage> SetLeverageAsync(TraidingPair symbol, int value)

Example:

...
Leverage setLeverage = await trade.SetLeverageAsync(TraidingPair.BTCUSDT, 25); // Set 25 leverage for BTCUSDT

SetMarginType

Will set a margin type(CROSSED or ISOLATED) for a given symbol

public async Task<bool> SetMarginTypeAsync(TraidingPair symbol, MarginType marginType)

Example:

...
public bool changedMarginType = trade.SetMarginTypeAsync(TraidingPair.BTCUSDT, MarginType.CROSSED); // Set a margin type CROSSED

ModifiyIsolatedPositionMarge

public async Task<bool> ModifiyIsolatedPositionMarge(TraidingPair traidingPair, decimal amount, int type, PositionSide positionSide = PositionSide.BOTH)

GetMarginChangesAsync

Get history of changes margin positions. startTime and endTime have unix format

limit can contain a number at most 500

public async Task<IEnumerable<MarginChange>> GetMarginChangesAsync(TraidingPair traidingPair, int limit = 100)

public async Task<IEnumerable<MarginChange>> GetMarginChangesAsync(TraidingPair traidingPair, int type, int limit = 100)

public async Task<IEnumerable<MarginChange>> GetMarginChangesAsync(TraidingPair traidingPair, int type, long startTime, long endTime, int limit = 100)

1.3. OrderEndPoint

AuthClient is mandatory for this endpoint

AuthClient client = new AuthClient("API_key", "Secret_key", true); // Create an auth client
OrderEndPoint order = new OrderEndPoint(client); // Create an order endpoint

Set

Will send a new order to exchange. To create an order in code, you need create an object from FutureBinanceAPI.Models.Orders namespace. Each an order has own class (See 1.3.1)

public async Task<Order> SetAsync(Orders.IOrder order)

Example:

...
MarketOrder marketOrder = new MarketOrder(TraidingPair.BTCUSDT, 0.100m); // Create a market order
Order newOrder = await order.SetAsync(marketOrder); // Send our market order to an exchange

Console.WriteLine(newOrder.OrderId); // We received response from exchange and will write in a console

1.3.1. Types of orders:

-MarketOrder

public MarketOrder(TraidingPair symbol, Side side, decimal quantity)

-LimitOrder

public LimitOrder(TraidingPair symbol, Side side, decimal quantity, decimal price, TimeInForceType timeInForce)

-StopOrder

public StopOrder(TraidingPair symbol, Side side, decimal quantity, decimal price, decimal stopPrice)

-TakeProfit

public TakeProfit(TraidingPair symbol, Side side, decimal quantity, decimal price, decimal stopPrice)

-StopMarket

public StopMarket(TraidingPair symbol, Side side, decimal quantity, decimal stopPrice)

-TakeProfitMarket

public TakeProfitMarket(TraidingPair symbol, Side side, decimal quantity, decimal stopPrice)

-TrailingStopMarket

public TrailingStopMarket(TraidingPair symbol, Side side, decimal quantity, decimal callbackRate)

Get

Fetch info of order from an exchange

public async Task<Order> GetAsync(TraidingPair symbol, long orderId)

Example:

...
Order order = await order.GetAsync(TraidingPair.BTCUSDT, 10000045);

Cancel

Will cancel a given order or all

public async Task<Order> CancelAsync(TraidingPair symbol, long orderId)
public async Task<bool> CancelAsync(TraidingPair symbol)

Example:

...
Order canceledOrder = await order.CancelAsync(TraidingPair.BTCUSDT, 10000045);
bool AreCanceledAllOrders = await order.CancelAsync(TraidingPair.BTCUSDT);

1.4. AccountEndPoint

AuthClient is mandatory for this endpoint

AuthClient client = new AuthClient("API_key", "Secret_key", true); // Create an auth client
AccountEndPoint account = new AccountEndPoint(client); // Create an account endpoint

Get

public async Task<Account> GetAsync()

...
Account account = await account.GetAsync();

1.5. StreamEndPoint

This endpoint has methods for working with stream FutureBinance. You can start stream, delete strean and update stream's key

AuthClient client = new AuthClient("apikey", "secretkey");
StreamEndPoint streamPoint = new StreamEndPoint(client); // only AuthClient

To get your_listened_key you need use method:

StartAsync

Close old connection tokens and create a new connection with token(listenKey)

public Task<string> StartAsync()

Example

AuthClient client = new AuthClient("apikey", "secretkey");
StreamEndPoint streamPoint = new StreamEndPoint(client); // only AuthClient
string listenKey = await streamPoint.StartAsync();

DeleteAsync

Close the connection

public void DeleteAsync()

KeepAliveAsync

Update the connnection's token

public void KeepAliveAsync()

Section with full description of stream located in page's bottom

2. Exception

In case of an error when requesting the exchange, an exception will be thrown FutureBinanceAPI.Exceptions.APIException

try {
    ...
    Order newOrder = await order.SetAsync(marketOrder);
} catch (FutureBinanceAPI.Exceptions.APIException e)
{
    Console.WriteLine(e.Details.Msg);
    Console.WriteLine(e.Details.Code);
}

3. Custom requests

If a library doesn't have any methods, you can simple build your custom requests

timestamp and recvWindow will be set automatically

public Request(Client client)
public Task<string> SendAsync(IEnumerable<KeyValuePair<string, string>> args, HttpMethod method, string endpoint)

AuthClient authClient = new AuthClient("API_key", "Secret_key", true); // Create an auth client
AuthClient defaultClient = new AuthClient(true); // Create a default client

CustomRequest.Request customRequest = new CustomRequest.Request(authClient);
string response = await customRequest.SendAsync(null, HttpMethod.Get, "/fapi/v1/positionSide/dual");

Console.WriteLine(response); // Output in JSON

4. Stream

FutureBinance give an ability to listen events from their servers. And with a help this library, you can do it easily

First, create new API Client type - StreamClient. It use in conustrctor 2 parameters: listenKey and webSocketUrl

StreamClient(string userListenKey)

StreamClient(string userListenKey, string webSocketUrl)

Examples:

StreamClient client = StreamClinet("listenKey");
StreamClient specificClient = new StreamClient("listenKey", "newWebSocketUrl");

Second, create Stream object. It allows you register new event-callbacks

StreamClient client = new StreamClient("listenKey");
Stream stream = new Stream(client);

stream.ConnectAsync((error) => {
    // You get created ClientWebSocket object
    Console.WriteLine('whoops..something error');
});

stream.Events.Add(new MarginListener((model) => {
    Console.WriteLine("event from marginListener");
    Console.WriteLine(model.EventType);
}));

A collection of Listeners:

AccountUpdateListener
MarginListener
OrderTradeUpdateListener
StreamExpired

There are a basic listeners. You can create your custom listeners. Your listener need implemented interface IEvent

Important note: you have an ability to create custom listener, but they can implemented only basic event models: StreamExpired, StreamMarginCall, OrderTradeUpdateCall, AccountUpdateCall

In this example it shows custom listener

public class MyListener : IListener
{
    #region Var
    public EventType Type => EventType.MARGIN_CALL;
    
    private Action<EventModel.StreamMarginCall> Callback { get; }
    #endregion

    #region Init
    public MyListener(Action<EventModel.StreamMarginCall> callback)
    {
        Callback = callback;
    }
    #endregion
    
    #region Methods
    public void Update(string message)
    {
        EventModel.StreamMarginCall parsedModel = JsonConvert.DeserializeObject<EventModel.StreamMarginCall>(message);
        
        // Here there is an ability to implemented somethings(check database, send request to api, change parsedModel and etc)
        
        UserCallback(parsedModel);
    }
    #endregion
}

...
stream.Events.Add(new MyListener((model) => {
    Console.WriteLine(model);
});