binance-connector 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73d340255608f6f2d79cc473c6372a536fe0e38d3cde79683d2acc73de339795
+  data.tar.gz: 8b366e6f5fd8dcc03c75fe3b77d907291f6b5d71b712bbbd3d73907fa17dac07
+SHA512:
+  metadata.gz: 38538d24affa5bd891a0ec42bbb83664f906272bedcdd60600295b83435bde730e06013f8d06fcb7457a6c6a7ed5ab291964644edca28a7fe1ffae2f20aeb865
+  data.tar.gz: 166eac302591ae1545151d996aa532352d311366e7f9e61a987e9f02fcfbc29ce376245ca5482053a2ca148d08c9a4578b6407cea36b92c1974070f1ebbcb421

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+### Added
+- First release, please find details from `README.md`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Binance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# Binance Connector Ruby
+
+[![Gem Version](https://badge.fury.io/rb/binance-connector.svg)](https://badge.fury.io/rb/binance-connector)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+This is a lightweight library that works as a connector to [Binance public API](https://github.com/binance/binance-spot-api-docs). It’s designed to be simple, clean, and easy to use with minimal dependencies.
+
+- Supported APIs:
+    - `/api/*`
+    - `/sapi/*`
+    - Spot Websocket Market Stream
+    - Spot User Data Stream
+- Inclusion of test cases and examples
+- Customizable base URL, request timeout
+- Response metadata can be displayed
+- Customizable Logger
+
+## Installation
+
+1. Include the library in Gemfile and then install it when execute the bundler.
+
+	Add this line in the Gemfile.
+
+	```ruby
+	gem 'binance-connector'
+	```
+
+	And then execute the bundler via CLI:
+
+    	$ bundle
+
+2. Install it with CLI:
+
+    $ gem install binance-connector
+
+## Restful APIs
+
+```ruby
+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](https://testnet.binance.vision/). You can use it by changing the base URL:
+
+```ruby
+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:
+
+- `https://api1.binance.com`
+- `https://api2.binance.com`
+- `https://api3.binance.com`
+
+### 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.
+```ruby
+
+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
+
+```ruby
+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**.
+
+```ruby
+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.
+
+```ruby
+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:
+
+```ruby
+{: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.
+
+```ruby
+client = Binance::Spot.new(show_header: true)
+```
+
+Then, take the same example as above, the response data becomes:
+
+```ruby
+{:data=>{:serverTime=>1589863539220}, :header=>{"content-type"=>"application/json;charset=utf-8",...}}
+```
+
+### Custom Logger Integration
+
+The client class accepts a [Logger](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html) instance as an input parameter.
+
+```ruby
+logger = Logger.new(STDOUT)
+client = Binance::Spot.new(logger: logger)
+logger.info(client.time)
+```
+
+### Exception
+
+There are 3 types of exceptions:
+- `Binance::RequiredParameterError`
+  - When missing required param
+  - Not sending out the request
+- `Binance::ClientError`
+  - This is thrown when API server returns `4XX`, it's an issue from client side.
+  - The following properties may be helpful to resolve the issue:
+    - Response header - Please refer to `Response Metadata` section for more details.
+    - HTTP status code
+    - Error code - Server's error code, e.g. `-1102`
+    - Error message - Server's error message, e.g. `Unknown order sent.`
+    - Request config - Configuration send to the server, which can include URL, request method and headers.
+- `Binance::ServerError`
+  - When API server returning 5XX
+  - sending out the request
+
+They all inherit from `Binance::Error`
+
+```ruby
+begin
+  response = client.time
+rescue Binance::ClientError => e
+  e.response[:status]
+  e.response[:headers]
+  e.response[:body]
+end
+```
+
+## Websocket
+
+```ruby
+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:
+
+  - `/fapi/*`
+  - `/dapi/*`
+  - `/vapi/*`
+  -  Associated Websocket Market and User Data Streams

data/lib/binance/authentication.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Binance
+  # Authentication response to API key and signature
+  class Authentication
+    attr_accessor :key, :secret
+
+    def initialize(key, secret)
+      @key = key
+      @secret = secret
+    end
+  end
+end

data/lib/binance/error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Binance
+  class Error < StandardError; end
+
+  # Client error from 400 - 499
+  class ClientError < Error
+    attr_reader :response
+
+    def initialize(response = nil)
+      @response = response
+      super(response)
+    end
+  end
+
+  # Server side error for 5xx
+  class ServerError < Error
+  end
+
+  # Error when missing required params
+  class RequiredParameterError < Error
+    def initialize(param_name, param_value)
+      super(
+          "ValidationFailed: #{param_name} is required, but provided value: #{param_value}"
+      )
+    end
+  end
+end

data/lib/binance/session.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'binance/utils/faraday/middleware'
+require 'binance/utils/faraday/custom_params_encoder'
+
+module Binance
+  # Session has the http request connection
+  class Session
+    include Binance::Utils::Faraday::Middleware
+
+    def initialize(options = {})
+      @base_url = options[:base_url] || 'https://api.binance.com'
+      @auth = Authentication.new(options[:key], options[:secret])
+      @logger = options[:logger]
+      @show_weight_usage = options[:show_weight_usage] || false
+      @show_header = options[:show_header] || false
+      @timeout = options[:timeout]
+    end
+
+    def public_request(path: '/', params: {})
+      process_request(public_conn, :get, path, params)
+    end
+
+    def limit_request(method: :get, path: '/', params: {})
+      process_request(limit_conn, method, path, params)
+    end
+
+    def sign_request(method, path, params: {})
+      process_request(signed_conn, method, path, params)
+    end
+
+    private
+
+    def process_request(conn, method, path, params)
+      response = conn.send(method, path_with_query(path, params.compact), nil)
+      extract_response(response)
+    rescue Faraday::ClientError => e
+      raise Binance::ClientError, e.response
+    rescue Faraday::ServerError => e
+      raise Binance::ServerError, e
+    end
+
+    def extract_response(response)
+      begin
+        data = JSON.parse(response.body, symbolize_names: true)
+      rescue JSON::ParserError
+        data = response.body
+      end
+
+      return data if !@show_header && !@show_weight_usage
+
+      res = { data: data }
+      res[:header] = response.headers if @show_header
+      res[:weight_usage] = response.headers.select { |k, _| weight_usage?(k) } if @show_weight_usage
+      res
+    end
+
+    def weight_usage?(key)
+      key.start_with?('x-mbx-used-weight') || key.start_with?('x-sapi-used')
+    end
+
+    def path_with_query(path, params)
+      "#{path}?#{Binance::Utils::Url.build_query(params)}"
+    end
+
+    def public_conn
+      build_connection
+    end
+
+    def limit_conn
+      build_connection do |conn|
+        conn.headers['X-MBX-APIKEY'] = @auth.key
+      end
+    end
+
+    def signed_conn
+      build_connection do |conn|
+        conn.headers['X-MBX-APIKEY'] = @auth.key
+        conn.use Timestamp
+        conn.use Signature, @auth.secret
+      end
+    end
+
+    def build_connection
+      Faraday.new(url: @base_url) do |client|
+        prepare_headers(client)
+        client.options.timeout = @timeout
+        client.options.params_encoder = Binance::Utils::Faraday::CustomParamsEncoder
+        yield client if block_given?
+        client.use Faraday::Response::RaiseError
+        logger_response(client)
+        client.adapter Faraday.default_adapter
+      end
+    end
+
+    def logger_response(client)
+      client.response :logger, @logger if @logger
+    end
+
+    def prepare_headers(client)
+      client.headers['Content-Type'] = 'application/json'
+      client.headers['User-Agent'] = "binance-connector-ruby/#{Binance::VERSION}"
+    end
+  end
+end

data/lib/binance/spot/blvt.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Binance
+  class Spot
+    # BLVT endpoints
+    # @see https://binance-docs.github.io/apidocs/spot/en/#blvt-endpoints
+    module Blvt
+      # Get BLVT Info (MARKET_DATA)
+      #
+      # GET /sapi/v1/blvt/tokenInfo
+      #
+      # @param tokenName [String]
+      # @see https://binance-docs.github.io/apidocs/spot/en/#get-blvt-info-market_data
+      def token_info(tokenName: nil)
+        @session.public_request(
+          path: '/sapi/v1/blvt/tokenInfo',
+          params: { tokenName: tokenName }
+        )
+      end
+
+      # Subscribe BLVT (USER_DATA)
+      #
+      # POST /sapi/v1/blvt/subscribe
+      #
+      # @param tokenName [String]
+      # @param cost [Float]
+      # @param kwargs [Hash]
+      # @option kwargs [Integer] :recvWindow The value cannot be greater than 60000
+      # @see https://binance-docs.github.io/apidocs/spot/en/#subscribe-blvt-user_data
+      def subscribe(tokenName:, cost:, **kwargs)
+        Binance::Utils::Validation.require_param('tokenName', tokenName)
+        Binance::Utils::Validation.require_param('cost', cost)
+
+        @session.sign_request(:post, '/sapi/v1/blvt/subscribe', params: kwargs.merge(
+          tokenName: tokenName,
+          cost: cost
+        ))
+      end
+
+      # Query Subscription Record (USER_DATA)
+      #
+      # GET /sapi/v1/blvt/subscribe/record
+      #
+      # @param kwargs [Hash]
+      # @option kwargs [String] :tokenName
+      # @option kwargs [Integer] :id
+      # @option kwargs [Integer] :startTime
+      # @option kwargs [Integer] :endTime
+      # @option kwargs [Integer] :limit
+      # @option kwargs [Integer] :recvWindow The value cannot be greater than 60000
+      # @see https://binance-docs.github.io/apidocs/spot/en/#query-subscription-record-user_data
+      def get_subscribe_record(**kwargs)
+        @session.sign_request(:get, '/sapi/v1/blvt/subscribe/record', params: kwargs)
+      end
+
+      # Redeem BLVT (USER_DATA)
+      #
+      # POST /sapi/v1/blvt/redeem
+      #
+      # @param tokenName [String]
+      # @param amount [Float]
+      # @param kwargs [Hash]
+      # @option kwargs [Integer] :recvWindow The value cannot be greater than 60000
+      # @see https://binance-docs.github.io/apidocs/spot/en/#redeem-blvt-user_data
+      def redeem(tokenName:, amount:, **kwargs)
+        Binance::Utils::Validation.require_param('tokenName', tokenName)
+        Binance::Utils::Validation.require_param('amount', amount)
+
+        @session.sign_request(:post, '/sapi/v1/blvt/redeem', params: kwargs.merge(
+          tokenName: tokenName,
+          amount: amount
+        ))
+      end
+
+      # Query Redemption Record (USER_DATA)
+      #
+      # GET /sapi/v1/blvt/redeem/record
+      #
+      # @param kwargs [Hash]
+      # @option kwargs [String] :tokenName
+      # @option kwargs [Integer] :id
+      # @option kwargs [Integer] :startTime
+      # @option kwargs [Integer] :endTime
+      # @option kwargs [Integer] :limit
+      # @option kwargs [Integer] :recvWindow The value cannot be greater than 60000
+      # @see https://binance-docs.github.io/apidocs/spot/en/#query-redemption-record-user_data
+      def get_redeem_record(**kwargs)
+        @session.sign_request(:get, '/sapi/v1/blvt/redeem/record', params: kwargs)
+      end
+
+      # Get BLVT User Limit Info (USER_DATA)
+      #
+      # GET /sapi/v1/blvt/userLimit
+      #
+      # @param kwargs [Hash]
+      # @option kwargs [String] :tokenName
+      # @option kwargs [Integer] :recvWindow The value cannot be greater than 60000
+      # @see https://binance-docs.github.io/apidocs/spot/en/#get-blvt-user-limit-info-user_data
+      def user_limit(**kwargs)
+        @session.sign_request(:get, '/sapi/v1/blvt/userLimit', params: kwargs)
+      end
+    end
+  end
+end