Skip to content

Latest commit

 

History

History
296 lines (212 loc) · 8.26 KB

README.md

File metadata and controls

296 lines (212 loc) · 8.26 KB
Raw

Binance Public API Connector DotNET

[Nuget] License: MIT

This is a lightweight library that works as a connector to Binance public API

  • Supported APIs:
    • /api/*
    • /sapi/*
    • Spot WebSocket Market Stream
    • Spot User Data Stream
    • Spot WebSocket API
  • Test cases and examples
  • Customizable base URL, request timeout and HTTP proxy
  • Response Metadata

Installation

dotnet add package Binance.Spot

RESTful APIs

Usage example

using System;
using System.Threading.Tasks;
using Binance.Spot;

class Program
{
    static async Task Main(string[] args)
    {
        Market market = new Market();

        string serverTime = await market.CheckServerTime();

        Console.WriteLine(serverTime);
    }
}

Please find Examples folder to check for more endpoints.

WebSocket Stream

Usage Example

using System;
using System.Threading;
using System.Threading.Tasks;
using Binance.Spot;

class Program
{
    static async Task Main(string[] args)
    {
        var websocket = new MarketDataWebSocket("btcusdt@aggTrade");

        websocket.OnMessageReceived(
            (data) =>
        {
            Console.WriteLine(data);

            return Task.CompletedTask;
        }, CancellationToken.None);

        await websocket.ConnectAsync(CancellationToken.None);
    }
}

More websocket examples are available in the Examples folder

WebSocket API

Usage Example

using System.Threading;
using System.Threading.Tasks;
using Binance.Common;
using Binance.Spot;

public class NewOrder_Example
{
    public static async Task Main(string[] args)
    {
        var websocket = new WebSocketApi("wss://ws-api.testnet.binance.vision/ws-api/v3", "apiKey", new BinanceHmac("apiSecret"));

        websocket.OnMessageReceived(
            async (data) =>
        {
            Console.WriteLine(data);
            await Task.CompletedTask;
        }, CancellationToken.None);

        await websocket.ConnectAsync(CancellationToken.None);

        await websocket.AccountTrade.NewOrderAsync(symbol: "BNBUSDT", side: Models.Side.BUY, type: Models.OrderType.LIMIT, timeInForce: Models.TimeInForce.GTC, price: 300, quantity: 1, cancellationToken: CancellationToken.None);

        await Task.Delay(5000);
        Console.WriteLine("Disconnect with WebSocket API Server");
        await websocket.DisconnectAsync(CancellationToken.None);
    }
}
  • The requestId param is optional. If not sent, it defaults to a randomly created GUID (Globally Unique Identifier).
  • The cancellationToken is optional. If not sent, it defaults to CancellationToken.None.

More websocket API examples are available in the Examples folder

Authentication - RESTful APIs

For API endpoints that requires signature, new authentication interfaces are introduced to generate the signature since V2.

// HMAC signature
new SpotAccountTrade(httpClient, new BinanceHmac("apiSecret"), apiKey: "apiKey")

// RSA signature
string privateKey = File.ReadAllText("/Users/john/ssl/PrivateKey.pem");
new SpotAccountTrade(httpClient, new BinanceRsa(privateKey), apiKey: "apiKey")

// Encrypted RSA signature
new SpotAccountTrade(httpClient, new BinanceRsa(privateKey, "thePrivateKeyPassword"), apiKey: "apiKey")

For V1.x, it's required to pass apiKey and apiSecret directly.

new SpotAccountTrade(httpClient, apiKey: apiKey, apiSecret: apiSecret)

For more details, please find the example from the endpoints /api/v3/account in file AccountInformation_Example.

Authentication - WebSocket API

// HMAC signature
new WebSocketApi(apiKey: "apiKey", signatureService: new BinanceHmac("apiSecret"));

// RSA signature
string privateKey = File.ReadAllText("/Users/john/ssl/PrivateKey.pem");
new WebSocketApi(apiKey: "apiKey", signatureService: new BinanceRsa(privateKey));

// Encrypted RSA signature
new WebSocketApi(apiKey: "apiKey", signatureService: new BinanceRsa(privateKey, "thePrivateKeyPassword"));

Heartbeat

Once connected, the websocket server sends a ping frame every 3 minutes and requires a response pong frame back within a 10 minutes period. This package handles the pong responses automatically.

Testnet

Spot Testnet can be used to test /api/* endpoints, Spot Websocket Stream and WebSocket API.

using Binance.Spot;

Wallet wallet = new Wallet(baseUrl: "https://testnet.binance.vision");

Base URL

If baseUrl is not provided, it defaults to https://api.binance.com.

It's recommended to pass in the baseUrl parameter, even in production as Binance provides alternative URLs in case of performance issues:

  • https://api1.binance.com
  • https://api2.binance.com
  • https://api3.binance.com
  • https://api4.binance.com

For Websocket Stream, baseUrl defaults to wss://stream.binance.com:9443". For Websocket API, baseUrl defaults to wss://ws-api.binance.com:443/ws-api/v3.

RecvWindow parameter

Additional parameter recvWindow is available for endpoints requiring signature.

It defaults to 5000 (milliseconds) and can be any value lower than 60000(milliseconds). Anything beyond the limit will result in an error response from Binance server.

using Binance.Spot;

Wallet wallet = new Wallet();

await wallet.AccountStatus(recvWindow=4000)

Timeout

The default timeout is 100,000 milliseconds (100 seconds).

Usage Example

using System;
using System.Net.Http;
using Binance.Spot;

HttpClient httpClient = new HttpClient() { 
    Timeout = TimeSpan.FromSeconds(10)
}

Wallet wallet = new Wallet(httpClient: httpClient);

Proxy

Usage Example

using System;
using System.Net;
using System.Net.Http;
using Binance.Spot;

WebProxy proxy = new WebProxy(new Uri("http://1.2.3.4:8080"));
HttpClientHandler proxyHandler = new HttpClientHandler { Proxy = proxy };
HttpClient httpClient = new HttpClient(handler: proxyHandler);

Wallet wallet = new Wallet(httpClient: httpClient);

Exceptions

There are 2 types of exceptions returned from the library:

  • Binance.Common.BinanceClientException
    • This is thrown when server returns 4XX, it's an issue from client side.
    • Properties:
      • Code - Server's error code, e.g. -1102
      • Message - Server's error message, e.g. Unknown order sent.
  • Binance.Common.BinanceServerException
    • This is thrown when server returns 5XX, it's an issue from server side.

Both exceptions inherit Binance.Common.BinanceHttpException along with the following properties:

  • StatusCode - Response http status code, e.g. 401
  • Headers - Dictionary with response headers

Logging

This library implements the .NET logging API that works with a variety of built-in and third-party logging providers.

For more information on how to configure logging in .NET, visit Microsoft's logging article

Usage Example

using System;
using System.Net;
using System.Net.Http;
using Binance.Spot;

public async Task LoggingExample(ILogger logger) {
    BinanceLoggingHandler loggingHandler = new BinanceLoggingHandler(logger: logger);
    HttpClient httpClient = new HttpClient(handler: loggingHandler);

    Wallet wallet = new Wallet(httpClient: httpClient);

    await wallet.SystemStatus();
}

Sample Output

Method: GET, RequestUri: 'https://www.binance.com/?timestamp=1631525776809&signature=f07558c98cb82bcb3556a6a21b8a8a2582bae93d0bb9604a0df72cae8c1c6642', Version: 1.1, Content: <null>, Headers: { }
StatusCode: 200, ReasonPhrase: 'OK', Version: 1.1, Content: <null>, Headers: {}
{"status": 0,"msg": "normal"}

Test Cases

dotnet test

Limitations

Futures and Vanilla Options APIs are not supported:

  • /fapi/*
  • /dapi/*
  • /vapi/*
  • Associated WebSocket Market and User Data Streams

Contributing

Contributions are welcome.

If you've found a bug within this project, please open an issue to discuss what you would like to change.

If it's an issue with the API, please open a topic at Binance Developer Community