Home

Awesome

Binance Connector Ruby

Gem Version Ruby Style Guide License: MIT

This is a lightweight library that works as a connector to Binance public API. It’s designed to be simple, clean, and easy to use with minimal dependencies.

Installation

  1. Include the library in Gemfile and then install it when execute the bundler.

    Add this line in the Gemfile.

    gem 'binance-connector-ruby'

    And then execute the bundler via CLI:

 bundle
  1. Install it with CLI:
gem install binance-connector-ruby

Documentation

https://www.rubydoc.info/gems/binance-connector-ruby

Restful APIs

require 'binance'

# Create a new client instance.
# If the APIs do not require the keys, (e.g. market data), key and secret can be omitted.
client = Binance::Spot.new(key: key, secret: secret)

# Send a request to query server time
puts client.time

# Send a request to query BTCUSDT ticker
puts client.ticker_24hr(symbol: 'BTCUSDT')

# Send a request to get account information
puts client.account

# Place an order
response = client.new_order(symbol: 'BNBUSDT', side: 'BUY', price: 20, quantity: 1, type: 'LIMIT', timeInForce: 'GTC')

Please find examples folder to check for more endpoints.

Testnet

While /sapi/* endpoints don't have testnet environment yet, /api/* endpoints can be tested in Spot Testnet. You can use it by changing the base URL:

client = Binance::Spot.new(base_url: 'https://testnet.binance.vision')
puts client.time

Base URL

If base_url is not provided, it defaults to api.binance.com.

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

RSA Signature

Binance support both HMAC and RSA signature. Please find the example at examples/trade/account.rb for how to sign in both solutions.

RecvWindow

From Binance API, recvWindow is available for all endpoints require signature. By default, it's 5000ms. You are allowed to set this parameter to any value less than 60000, number beyond this limit will receive error from Binance server.


response = client.account(recvWindow: 2_000)

Optional parameters

For the optional parameters in the endpoint, pass exactly the field name from API document into method. e.g

client = Binance::Spot.new

# correct
response = client.cancel_order(symbol: 'BNBUSDT', orderId: 25)

# this is incorrect
response = client.cancel_order(symbol: 'BNBUSDT', order_id: 25)

Timeout

Timeout (unit: second) can be specified when initializing a client instance. If timeout is not set, the default is no timeout.

client = Binance::Spot.new(timeout: 2)

Response Metadata

The Binance API server provides weight usages in the headers of each response. This information can be fetched from headers property. x-mbx-used-weight and x-mbx-used-weight-1m show the total weight consumed within 1 minute. This is very useful to indentify the current usage. To display this value, specify show_weight_usage: true when intializing a new client instance.

client = Binance::Spot.new(show_weight_usage: true)

Then, take server time API (GET /api/v3/time) as an example, the response data is shown as below:

{:data=>{:serverTime=>1589860878546}, :weight_usage=>{"x-mbx-used-weight"=>"1", "x-mbx-used-weight-1m"=>"1"}}

When show_header: true, the library has the ability to print out all response headers, which may be very helpful for debugging the program.

client = Binance::Spot.new(show_header: true)

Then, take the same example as above, the response data becomes:

{:data=>{:serverTime=>1589863539220}, :header=>{"content-type"=>"application/json;charset=utf-8",...}}

Custom Logger Integration

The client class accepts a Logger instance as an input parameter.

logger = Logger.new(STDOUT)
client = Binance::Spot.new(logger: logger)
logger.info(client.time)

Exception

There are 3 types of exceptions:

They all inherit from Binance::Error

begin
  response = client.time
rescue Binance::ClientError => e
  e.response[:status]
  e.response[:headers]
  e.response[:body]
end

Websocket

require 'binance'
require 'eventmachine'

client = Binance::Spot::WebSocket.new

EM.run do
  onopen = proc { logger.info('connected to server') }
  onmessage = proc { |msg, _type| logger.info(msg) }
  onerror   = proc { |e| logger.error(e) }
  onclose   = proc { logger.info('connection closed') }

  callbacks = {
    onopen: onopen,
    onmessage: onmessage,
    onerror: onerror,
    onclose: onclose
  }

  client.kline(symbol: 'btcusdt', interval: '30m', callbacks: callbacks)
end

More websocket examples are available in the examples folder

Auto response

Binance requires pong for heartbeat, response is sent automatically.

Limitation

Futures and Vanilla Options APIs are not supported: