bybit-connector-ruby 0.1.0

data/lib/bybit/session.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'timeout'
+require 'uri'
+
+module Bybit
+  # Session owns the Faraday connection + auth-header assembly. Every service
+  # class receives a Session instance and dispatches through public_request /
+  # sign_request. Modeled after binance-connector-ruby's Session pattern.
+  #
+  # Signing invariant: the payload signed and the query string sent on the
+  # wire MUST be byte-identical. We enforce this by building ONE query_str
+  # (via encode_query after key-sort) and using it verbatim for both
+  # the signature payload AND the request URL — never letting Faraday's
+  # NestedParamsEncoder re-serialize the params. This avoids the classic
+  # array-value / nested-hash reorder bug.
+  class Session
+    PAYLOAD_QUERY_METHODS = %i[get delete].freeze
+
+    def initialize(config)
+      @config = config
+      @conn = config.faraday_connection || build_connection
+    end
+
+    # Public unsigned endpoint — no X-BAPI-* headers attached.
+    #   session.public_request(path: '/v5/market/kline', params: {...})
+    def public_request(path:, method: :get, params: nil, body: nil)
+      dispatch(method: method, path: path, signed: false, params: params, body: body)
+    end
+
+    # Signed endpoint — X-BAPI-* headers computed via Authentication.
+    def sign_request(method:, path:, params: nil, body: nil)
+      dispatch(method: method, path: path, signed: true, params: params, body: body)
+    end
+
+    private
+
+    def dispatch(method:, path:, signed:, params:, body:)
+      # Only GET / DELETE carry params on the query string. Silently dropping
+      # params on POST / PUT / PATCH used to leave codegen typos undiagnosed
+      # for weeks — now they raise loudly.
+      if params && !PAYLOAD_QUERY_METHODS.include?(method) && !body.nil?
+        raise Bybit::ConfigurationError,
+              "params: is only valid on GET/DELETE — #{method.to_s.upcase} must pass data via body:"
+      end
+      clean_params = compact(params)
+      clean_body   = compact(body)
+      query_str = clean_params ? encode_query(clean_params) : ''
+      body_str  = clean_body ? JSON.generate(clean_body) : ''
+      headers = build_headers(signed: signed, method: method, query_str: query_str, body_str: body_str)
+
+      # Build URL manually with our own query_str so the wire bytes match
+      # what we signed. `req.params =` would re-serialize through
+      # Faraday::NestedParamsEncoder which key-orders and array-brackets
+      # differently, breaking the signature.
+      full_url = if !query_str.empty? && PAYLOAD_QUERY_METHODS.include?(method)
+                   "#{path}?#{query_str}"
+                 else
+                   path
+                 end
+
+      resp = @conn.send(method) do |req|
+        req.url full_url
+        req.headers.update(headers)
+        req.body = body_str if clean_body
+      end
+      parse_response(resp)
+    rescue Faraday::TimeoutError => e
+      raise Bybit::TimeoutError, e.message
+    rescue Faraday::ConnectionFailed => e
+      raise Bybit::TimeoutError, e.message if connect_timeout?(e)
+
+      raise Bybit::NetworkError, e.message
+    rescue Faraday::SSLError => e
+      raise Bybit::NetworkError, e.message
+    rescue Faraday::Error => e
+      # Catch-all for Faraday::ParsingError / ClientError / ServerError etc.
+      # that surface when the caller wires their own error-raising middleware.
+      raise Bybit::TransportError, e.message
+    end
+
+    # Faraday 2's net_http adapter wraps Net::OpenTimeout / Timeout::Error /
+    # Errno::ETIMEDOUT in ConnectionFailed (only Net::ReadTimeout becomes
+    # Faraday::TimeoutError). Callers still want these surfaced as TimeoutError.
+    def connect_timeout?(err)
+      cause = err.respond_to?(:wrapped_exception) ? err.wrapped_exception : nil
+      cause.is_a?(Timeout::Error) || cause.is_a?(Errno::ETIMEDOUT)
+    end
+
+    # Deterministic `&`-joined encoding, keys sorted, values URI-escaped.
+    # Arrays become repeated keys (`symbol=BTCUSDT&symbol=ETHUSDT`) — this
+    # matches Bybit V5's flat-list expectation.
+    def encode_query(params)
+      params.sort_by { |k, _| k.to_s }.flat_map do |k, v|
+        key_enc = URI.encode_www_form_component(k.to_s)
+        Array(v).map { |single| "#{key_enc}=#{URI.encode_www_form_component(single.to_s)}" }
+      end.join('&')
+    end
+
+    def build_headers(signed:, method:, query_str:, body_str:)
+      h = {}
+      h['Content-Type'] = 'application/json' unless body_str.empty?
+      return h unless signed
+      raise Bybit::ConfigurationError, 'signed endpoint requires api_key + api_secret' if @config.api_key.nil? || @config.api_secret.nil?
+
+      ts = (Time.now.to_f * 1000).to_i.to_s
+      # payload for GET/DELETE is query string; for POST/PUT/PATCH it's the
+      # JSON body. Both branches use the SAME predicate as dispatch above.
+      payload = PAYLOAD_QUERY_METHODS.include?(method) ? query_str : body_str
+      h['X-BAPI-API-KEY']     = @config.api_key
+      h['X-BAPI-TIMESTAMP']   = ts
+      h['X-BAPI-RECV-WINDOW'] = @config.recv_window.to_s
+      h['X-BAPI-SIGN']        = Authentication.sign_v5(
+        @config.api_secret, ts, @config.api_key, @config.recv_window.to_s, payload
+      )
+      h['X-BAPI-SIGN-TYPE'] = '2'
+      h
+    end
+
+    def parse_response(response)
+      status = response.status
+      raw    = response.body
+      body   = raw.is_a?(String) ? safe_parse_json(raw) : raw
+      body   = normalize_legacy_body(body) if body.is_a?(Hash)
+
+      # HTTP status wins over retCode when the body isn't a valid ApiResponse.
+      # 5xx / non-auth 4xx get their own class so retries and pager logic can
+      # tell them apart from client / auth errors.
+      if !body.is_a?(Hash) || !body['retCode'].is_a?(Integer)
+        preview = truncate_for_error(raw)
+        if status >= 500
+          raise Bybit::ServerError, "Bybit server error (status=#{status}): #{preview}"
+        elsif status >= 400
+          raise Bybit::ClientError, "Bybit client error (status=#{status}): #{preview}"
+        else
+          raise Bybit::ParseError.new(
+            "Response is not a valid Bybit V5 ApiResponse (status=#{status}): #{preview}",
+            body: raw, http_status: status
+          )
+        end
+      end
+      return body if body['retCode'].zero?
+
+      raise Bybit.api_error_from(body, http_status: status)
+    end
+
+    # P2P endpoints (and a few legacy V3-derived paths) return the pre-V5
+    # envelope: { ret_code, ret_msg, ext_code, ext_info, time_now, result }.
+    # Alias the legacy keys into the V5 shape so the rest of the parser and
+    # error mapper works uniformly. If the response is already V5, no-op.
+    LEGACY_KEY_MAP = {
+      'ret_code' => 'retCode',
+      'ret_msg' => 'retMsg',
+      'ext_info' => 'retExtInfo',
+      'time_now' => 'time'
+    }.freeze
+
+    def normalize_legacy_body(body)
+      return body if body.key?('retCode')
+      return body unless body.key?('ret_code')
+
+      LEGACY_KEY_MAP.each do |legacy, v5|
+        body[v5] = body.delete(legacy) if body.key?(legacy)
+      end
+      # `time_now` is a Bybit-legacy float-string; V5 exposes `time` as an
+      # integer millisecond epoch. Best-effort coerce so downstream code that
+      # compares against V5 `time` doesn't hit a type mismatch.
+      body['time'] = (body['time'].to_f * 1000).to_i if body['time'].is_a?(String)
+      body
+    end
+
+    def safe_parse_json(str)
+      JSON.parse(str)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def truncate_for_error(raw)
+      return '(nil body)' if raw.nil?
+
+      s = raw.is_a?(String) ? raw : raw.inspect
+      s.length > 2048 ? "#{s[0, 2048]}…(truncated)" : s
+    end
+
+    # Shallow compact only — inner Hash / Array-of-Hash values pass through.
+    # Recursion happens on the wire-key side via WireKeys.camelize.
+    def compact(hash)
+      return nil if hash.nil?
+
+      hash.reject { |_, v| v.nil? }
+    end
+
+    def build_connection
+      Faraday.new(url: @config.resolved_base_url, request: { timeout: @config.timeout })
+    end
+  end
+end

data/lib/bybit/utils/wire_keys.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Bybit
+  module Utils
+    # snake_case <-> camelCase key translation for wire payloads.
+    # Bot-family endpoints keep snake_case (identity mapping) — call sites
+    # skip WireKeys.camelize. Everyone else runs camelize on the params/body
+    # hash right before dispatch.
+    #
+    # Recursion: batch endpoints (trade#batch_amend_orders,
+    # account#batch_set_collateral, etc.) carry Array<Hash> or nested Hash
+    # payloads whose inner keys must ALSO be camelized. A non-recursive
+    # camelize was the PR#1 blocker (retCode 10001/10004 on every batch call).
+    module WireKeys
+      # Ruby-reserved-word arg aliases: :end_ → :end on the wire. Codegen
+      # emits arg names with the trailing '_'; camelize normalizes them back
+      # to the spec name so service methods no longer need per-method
+      # `params[:end] = params.delete(:end_)` shims.
+      RESERVED_ALIASES = {
+        end_: :end, begin_: :begin, class_: :class, next_: :next,
+        return_: :return, do_: :do, if_: :if, else_: :else
+      }.freeze
+
+      module_function
+
+      # Convert every key of a hash from :some_key / 'some_key' to camelCase.
+      # Recurses into Hash and Array-of-Hash values. Non-hash/array values
+      # pass through unchanged. Reserved-word aliases (:end_ etc.) get
+      # rewritten to their bare form.
+      def camelize(hash)
+        return hash if hash.nil?
+
+        hash.each_with_object({}) do |(k, v), out|
+          out[to_camel(unalias(k))] = camelize_value(v)
+        end
+      end
+
+      def camelize_value(value)
+        case value
+        when Hash  then camelize(value)
+        when Array then value.map { |el| el.is_a?(Hash) ? camelize(el) : el }
+        else value
+        end
+      end
+
+      def unalias(key)
+        return key unless key.is_a?(Symbol) || key.is_a?(String)
+
+        aliased = RESERVED_ALIASES[key.to_s.to_sym]
+        return key unless aliased
+
+        key.is_a?(Symbol) ? aliased : aliased.to_s
+      end
+
+      def to_camel(key)
+        return key unless key.is_a?(Symbol) || key.is_a?(String)
+
+        parts = key.to_s.split('_')
+        return key if parts.size < 2
+
+        camel = parts[0] + parts[1..].reject(&:empty?).map(&:capitalize).join
+        key.is_a?(Symbol) ? camel.to_sym : camel
+      end
+    end
+  end
+end

data/lib/bybit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bybit
+  VERSION = '0.1.0'
+end

data/lib/bybit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bybit/version'
+require 'bybit/error'
+require 'bybit/configuration'
+require 'bybit/authentication'
+require 'bybit/session'
+require 'bybit/utils/wire_keys'
+require 'bybit/rest_api/base_service'
+require 'bybit/client'

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: bybit-connector-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bybit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Ruby connector for the Bybit V5 REST API — keyword-arg method signatures,
+  HMAC-SHA256 signing, typed error hierarchy, Faraday-based transport.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- examples/quickstart.rb
+- lib/bybit.rb
+- lib/bybit/authentication.rb
+- lib/bybit/client.rb
+- lib/bybit/configuration.rb
+- lib/bybit/error.rb
+- lib/bybit/rest_api/account_service.rb
+- lib/bybit/rest_api/affiliate_service.rb
+- lib/bybit/rest_api/asset_service.rb
+- lib/bybit/rest_api/base_service.rb
+- lib/bybit/rest_api/bot_service.rb
+- lib/bybit/rest_api/broker_service.rb
+- lib/bybit/rest_api/crypto_loan_service.rb
+- lib/bybit/rest_api/earn_service.rb
+- lib/bybit/rest_api/market_service.rb
+- lib/bybit/rest_api/p2p_service.rb
+- lib/bybit/rest_api/position_service.rb
+- lib/bybit/rest_api/rfq_service.rb
+- lib/bybit/rest_api/spot_margin_service.rb
+- lib/bybit/rest_api/trade_service.rb
+- lib/bybit/rest_api/user_service.rb
+- lib/bybit/session.rb
+- lib/bybit/utils/wire_keys.rb
+- lib/bybit/version.rb
+homepage: https://github.com/bybit-exchange/bybit.ruby.api
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bybit-exchange/bybit.ruby.api
+  documentation_uri: https://bybit-exchange.github.io/docs/v5/intro
+  changelog_uri: https://github.com/bybit-exchange/bybit.ruby.api/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Bybit V5 REST API connector for Ruby
+test_files: []