Binance::Api

Features

• Spot & Margin Trading
• 100% test coverage (stable!)
• Exception handling
• Automatic timestamp and signature generation
• Support for United States (binance.us)

Installation

Add this line to your application's Gemfile:

gem 'binance-ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install binance-ruby

Setup

API Keys

At minimum, you must configure the following environment variables:

BINANCE_API_KEY
BINANCE_SECRET_KEY

or as instance variables:

Binance::Api::Configuration.api_key = nil
Binance::Api::Configuration.secret_key = nil

Additionally, Binance allows granular API key access based on the action being taken. For example, it is possible to use one API key for only trade actions, while using another for withdrawal actions. You can configure this using any of the following keys:

BINANCE_READ_INFO_API_KEY
BINANCE_TRADING_API_KEY
BINANCE_WITHDRAWALS_API_KEY

or as instance variables:

Binance::Api::Configuration.read_info_api_key = nil
Binance::Api::Configuration.trading_api_key = nil
Binance::Api::Configuration.withdrawals_api_key = nil

If any one of these keys are not defined, binance-ruby will fallback to BINANCE_API_KEY/Binance::Api::Configuration.api_key.

If you want to use binance test net to test the feature, you could configure the following environment variable:

BINANCE_TEST_NET_ENABLE=true

Accounts in the USA

If your Binance account is based in the United States (www.binance.us), you will need to specify that in an environment variable:

BINANCE_TLD = US

Usage

API Examples

Binance::Api.ping!

Binance::Api::Order.create!(
  quantity: '100.0', side: 'BUY', symbol: 'XRPBTC', type: 'MARKET'
)

WebSocket Examples

Candlesticks:

on_open = ->(event) { puts '>> Websocket opened' }
on_close =
  ->(event) { puts ">> Websocket closed (#{event.code}): #{event.reason}" }
EM.run do
  websocket = Binance::WebSocket.new(on_open: on_open, on_close: on_close)

  websocket.candlesticks!(%w[ETHBTC], '1h') do |stream_name, kline_candlestick|
    symbol = kline_candlestick[:s]
  end
end

Trades:

on_open = ->(event) { puts '>> Websocket opened' }
on_close =
  ->(event) { puts ">> Websocket closed (#{event.code}): #{event.reason}" }
EM.run do
  websocket = Binance::WebSocket.new(on_open: on_open, on_close: on_close)

  websocket.trades!(%w[ETHBTC]) { |stream_name, trade| symbol = trade[:s] }
end

User Data:

EM.run do
  websocket = Binance::WebSocket.new

  listen_key = Binance::Api::UserDataStream.start!
  websocket.user_data_stream!(listen_key) do |listen_key, data|
    case data[:e].to_sym
    when :outboundAccountPosition
    when :balanceUpdate
    when :executionReport
    end
  end
end

You can find more info on all kline_candlestick attributes & available intervals in the binance documentation.

Binance::Api class methods

• candlesticks!: Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
• compressed_aggregate_trades!: Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.
• depth!: Get your order book.
• exchange_info!: Current exchange trading rules and symbol information.
• historical_trades!: Get older trades.
• ping!: Test connectivity to the Rest API.
• ticker!: Price change statistics. Careful when accessing this with no symbol.
• time!: Test connectivity to the Rest API and get the current server time.
• trades!: Get recent trades (up to last 500).

Binance::Api::Account class methods

• fees!: Get withdrawal information (status, minimum amount and fees) for all symbols.
• info!: Get current account information.
• trades!: Get trades for a specific account and symbol.
• withdraw!: Submit a withdraw request. I haven't confirmed this works for binance.us yet. If you find that it does, please submit a PR!

Binance::Api::DataStream class methods

• start!: Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent.
• keepalive!: Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes.
• stop!: Close out a user data stream.

Binance::Api::Order class methods

• all!: Get all account orders; active, canceled, or filled.
• all_open!: Get all open orders on a symbol. Careful when accessing this with no symbol.
• cancel!: Cancel an active order.
• create!: Send in a new order. Use test: true for test orders.
• status!: Check an order's status.

Binance::Api::Margin::Order class methods

• create!: Create a new margin order.

Binance::WebSocket instance methods

• candlesticks!: Kline/candlestick bars for a symbol.
• trades!: The Trade Streams push raw trade information.
• user_data_stream!: account updates, balances changes, and order updates.

See the rubydoc for information about parameters for each method listed above.

For more information, please refer to the official Rest API documentation written by the Binance team.

Author

Jake Peterson

If this library helped you please consider donating (send whatever crypto you want): 0xB5BaA3D2056be942a9F61Cc015b83562DA3C15B2

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Troubleshooting

(-2015) Invalid API-key, IP, or permissions for action.

Are your API keys from a binance.us account? How-to configure.

"(-1021) Timestamp for this request was 1000ms ahead of the server's time."

The operational system clock is ahead/behind regarding the Binance's timestamp clock.

Resolution: Linux

Use the command: sudo ntpdate time.nist.gov.

If ntpdate is not installed: sudo apt install ntpdate.

Resolution: Windows

Use the path: Right-click on tray clock > Adjust date/time > Additional date, time & regional settings > Date and Time > Internet time > Change settings...

• Option "Syncronize with an Internet time server" should be enabled;
• "Server" should be "time.nist.org".

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jakenberg/binance-ruby.

TODO

• DateTime parameters (in addition to milliseconds).

License

The gem is available as open source under the terms of the MIT License.