honeymaker 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b69b5d2b1995f1def30eaa09cb003cef99a8763ea383c9f71ea8aa0d05e9ecac
-  data.tar.gz: 54fb293018729bcfd12c26b596da9fae540bfe6574d9de40cae8b6b0407809bb
+  metadata.gz: a49e9be8c0e38711e061c2ea61373bbce84dfe3f779c5e6933fdc2c8185b942b
+  data.tar.gz: c9dda3aa8c109c0db2bdcaf086f4b86fe95214cc7a6690d39b921e1182a08766
 SHA512:
-  metadata.gz: e1903ef50d96bd65cc630b587a2e4d9f8e7e967bd82768fd2c5d883dd06d8e265364fb853949e0f5308a4ba0dfc65980c91c96d9c89f5d1632966dbf756d9d35
-  data.tar.gz: cc74f411106c324c6a12a9b93f02415cc1f14d65d38ee4518b313e487804a87c50c386fb7d9fea0716f21018d46fc42ce82ff9c3496552723c1dfb774318679b
+  metadata.gz: 7fe8a3cd0df1bea5355498e117887e854716d8050bdfe12009c9b1f0225771b1a18ad59030dfdd1418629df8db06805d79e38392ab99f3b300f93e4a87a52c3b
+  data.tar.gz: 49e17edfcc5982629034cc755c315fc772188cc9a232102478eaf984522ed4df261bb55818bb0e62dcbe0b9f3a9a15c20759ef2199015da70d48a1b8098a22b3

data/README.md

@@ -8,7 +8,7 @@ Ruby clients for cryptocurrency exchange APIs. Originally extracted from [Deltab
 
 ## Supported Exchanges
 
-Binance, Binance US, Kraken, Coinbase, Bybit, KuCoin, Bitget, MEXC, Bitvavo, Gemini, Hyperliquid, BingX, Bitrue, BitMart.
+Binance, Binance US, Kraken, Kraken Futures, Coinbase, Bybit, KuCoin, Bitget, MEXC, Bitvavo, Gemini, Hyperliquid, BingX, Bitrue, BitMart.
 
 ## Installation
 
@@ -18,24 +18,163 @@ gem "honeymaker"
 
 ## Usage
 
+### Market Data
+
 ```ruby
 require "honeymaker"
 
-# Get an exchange client
 exchange = Honeymaker.exchange("binance")
-
-# Fetch trading pair info (symbols, decimals, min/max amounts)
 result = exchange.get_tickers_info
 
 if result.success?
   result.data.each do |ticker|
     puts "#{ticker[:ticker]} — min: #{ticker[:minimum_quote_size]}, decimals: #{ticker[:base_decimals]}"
   end
-else
-  puts "Error: #{result.errors.join(', ')}"
 end
 ```
 
+### Balances
+
+```ruby
+client = Honeymaker.client("binance", api_key: "...", api_secret: "...")
+result = client.get_balances
+
+if result.success?
+  result.data.each do |symbol, balance|
+    puts "#{symbol}: free=#{balance[:free]}, locked=#{balance[:locked]}"
+  end
+end
+# => { "BTC" => { free: BigDecimal("0.5"), locked: BigDecimal("0.1") }, ... }
+```
+
+Coinbase auto-resolves the default portfolio, or pass one explicitly:
+
+```ruby
+client.get_balances(portfolio_uuid: "...")
+```
+
+### Placing Orders
+
+Order placement returns a normalized `{ order_id:, raw: }` hash:
+
+```ruby
+client = Honeymaker.client("binance", api_key: "...", api_secret: "...")
+
+result = client.new_order(symbol: "BTCUSDT", side: "BUY", type: "MARKET", quote_order_qty: "100")
+if result.success?
+  puts result.data[:order_id]  # => "BTCUSDT-123456"
+  puts result.data[:raw]       # full exchange response
+end
+```
+
+Method names vary by exchange (`new_order`, `create_order`, `add_order`, `place_order`, `submit_order`) but the return format is the same.
+
+### Querying Orders
+
+Order queries return a normalized hash with unified status, amounts, and the raw response:
+
+```ruby
+result = client.query_order(symbol: "BTCUSDT", order_id: 123456)
+if result.success?
+  order = result.data
+  order[:order_id]          # => "BTCUSDT-123456"
+  order[:status]            # => :open, :closed, :cancelled, :failed, :unknown
+  order[:side]              # => :buy, :sell
+  order[:order_type]        # => :market, :limit
+  order[:price]             # => BigDecimal — avg fill price
+  order[:amount]            # => BigDecimal — requested base qty (nil if quote-denominated)
+  order[:quote_amount]      # => BigDecimal — requested quote qty (nil if base-denominated)
+  order[:amount_exec]       # => BigDecimal — filled base qty
+  order[:quote_amount_exec] # => BigDecimal — filled quote qty
+  order[:raw]               # => Hash — full exchange response
+end
+```
+
+### Account History (Tax Reporting)
+
+History endpoints for margin, futures, staking/earn, and other tax-relevant events:
+
+```ruby
+# Margin
+client.margin_borrow_repay_history(type: "BORROW")   # Binance
+client.margin_interest_history                         # Binance, KuCoin, Bitget
+client.margin_force_liquidation                        # Binance
+
+# Futures
+client.futures_income_history(income_type: "REALIZED_PNL")  # Binance USDT-M
+client.coin_futures_income_history                          # Binance Coin-M
+client.futures_account_bills(product_type: "USDT-FUTURES")  # Bitget
+client.futures_income                                       # BingX
+
+# Staking / Earn
+client.simple_earn_flexible_rewards                    # Binance
+client.simple_earn_locked_subscriptions                # Binance
+client.earn_yield_history                              # Bybit
+client.staking_rewards                                 # Gemini
+client.staking_rewards_history                         # Binance US
+
+# Other
+client.universal_transfer_history(type: "MAIN_MARGIN") # Binance
+client.dust_log                                        # Binance
+client.asset_dividend                                  # Binance
+```
+
+Coverage varies by exchange. Kraken's `get_ledgers(type:)` covers margin, staking, and trades in a single endpoint. Coinbase's `list_transactions` covers 30+ event types.
+
+### Kraken Futures
+
+Kraken Futures uses separate API keys and a different auth scheme — it's a standalone client:
+
+```ruby
+client = Honeymaker.client("kraken_futures", api_key: "...", api_secret: "...")
+
+client.get_accounts                                  # wallet balances, margin, PnL
+client.get_fills                                     # trade fills
+client.get_open_positions                            # open positions
+client.historical_funding_rates(symbol: "PF_XBTUSD") # funding rate history
+```
+
+### Credential Validation
+
+```ruby
+client = Honeymaker.client("binance", api_key: "...", api_secret: "...")
+result = client.validate(:trading)
+result.success? # => true if credentials have trading permissions
+```
+
+### Rate Limits
+
+Each exchange exposes rate limit metadata (milliseconds between requests):
+
+```ruby
+Honeymaker::Clients::Binance.rate_limits
+# => { default: 100, orders: 200 }
+
+Honeymaker::Clients::Kraken.rate_limits
+# => { default: 1000, orders: 1000 }
+```
+
+### Proxy Support
+
+```ruby
+client = Honeymaker.client("binance",
+  api_key: "...", api_secret: "...",
+  proxy: "http://proxy:8100"
+)
+```
+
+## Result Objects
+
+All methods return `Result::Success` or `Result::Failure`:
+
+```ruby
+result = client.get_balances
+result.success?  # true/false
+result.failure?  # true/false
+result.data      # response payload
+result.errors    # array of error messages (empty on success)
+```
+
 ## License
 
 MIT

data/lib/honeymaker/client.rb

@@ -3,6 +3,7 @@
 require "openssl"
 require "base64"
 require "securerandom"
+require "bigdecimal"
 
 module Honeymaker
   class Client
@@ -14,6 +15,11 @@ module Honeymaker
       }
     }.freeze
 
+    RATE_LIMITS = {
+      default: 100,
+      orders: 100
+    }.freeze
+
     attr_reader :api_key, :api_secret
 
     def initialize(api_key: nil, api_secret: nil, proxy: nil, logger: nil)
@@ -23,6 +29,14 @@ module Honeymaker
       @logger = logger
     end
 
+    def self.rate_limits
+      self::RATE_LIMITS
+    end
+
+    def get_balances
+      raise NotImplementedError, "#{self.class} must implement #get_balances"
+    end
+
     def validate(type = :trading)
       return Result::Failure.new("No credentials provided") unless authenticated?
 

data/lib/honeymaker/clients/binance.rb

@@ -4,6 +4,7 @@ module Honeymaker
   module Clients
     class Binance < Client
       URL = "https://api.binance.com"
+      RATE_LIMITS = { default: 100, orders: 200 }.freeze
 
       def exchange_information(symbol: nil, symbols: nil, permissions: nil, show_permission_sets: nil, symbol_status: nil)
         with_rescue do
@@ -75,6 +76,22 @@ module Honeymaker
         end
       end
 
+      def get_balances
+        result = account_information(omit_zero_balances: true)
+        return result if result.failure?
+
+        balances = {}
+        Array(result.data["balances"]).each do |balance|
+          symbol = balance["asset"]
+          free = BigDecimal(balance["free"].to_s)
+          locked = BigDecimal(balance["locked"].to_s)
+          next if free.zero? && locked.zero?
+          balances[symbol] = { free: free, locked: locked }
+        end
+
+        Result::Success.new(balances)
+      end
+
       def account_trade_list(symbol:, order_id: nil, start_time: nil, end_time: nil, from_id: nil, limit: 500, recv_window: 5000)
         with_rescue do
           response = connection.get do |req|
@@ -104,7 +121,8 @@ module Honeymaker
             }.compact
             req.params[:signature] = sign_params(req.params)
           end
-          response.body
+          raw = response.body
+          normalize_order("#{symbol}-#{raw['orderId']}", raw)
         end
       end
 
@@ -145,7 +163,8 @@ module Honeymaker
             }.compact
             req.params[:signature] = sign_params(req.params)
           end
-          response.body
+          raw = response.body
+          { order_id: "#{symbol}-#{raw['orderId']}", raw: raw }
         end
       end
 
@@ -363,8 +382,251 @@ module Honeymaker
         end
       end
 
+      # --- Margin ---
+
+      def margin_borrow_repay_history(type:, asset: nil, isolated_symbol: nil, start_time: nil, end_time: nil,
+                                      current: nil, size: nil, recv_window: 5000)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/margin/borrow-repay"
+            req.headers = headers
+            req.params = {
+              type: type, asset: asset, isolatedSymbol: isolated_symbol,
+              startTime: start_time, endTime: end_time,
+              current: current, size: size,
+              recvWindow: recv_window, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def margin_interest_history(asset: nil, isolated_symbol: nil, start_time: nil, end_time: nil,
+                                  current: nil, size: nil, archived: nil, recv_window: 5000)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/margin/interestHistory"
+            req.headers = headers
+            req.params = {
+              asset: asset, isolatedSymbol: isolated_symbol,
+              startTime: start_time, endTime: end_time,
+              current: current, size: size, archived: archived,
+              recvWindow: recv_window, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def margin_force_liquidation(start_time: nil, end_time: nil, isolated_symbol: nil,
+                                   current: nil, size: nil, recv_window: 5000)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/margin/forceLiquidationRec"
+            req.headers = headers
+            req.params = {
+              startTime: start_time, endTime: end_time,
+              isolatedSymbol: isolated_symbol,
+              current: current, size: size,
+              recvWindow: recv_window, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      # --- Futures ---
+
+      def futures_income_history(symbol: nil, income_type: nil, start_time: nil, end_time: nil,
+                                 page: nil, limit: 1000, recv_window: 5000)
+        with_rescue do
+          response = usdt_futures_connection.get do |req|
+            req.url "/fapi/v1/income"
+            req.headers = headers
+            req.params = {
+              symbol: symbol, incomeType: income_type,
+              startTime: start_time, endTime: end_time,
+              page: page, limit: limit,
+              recvWindow: recv_window, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def coin_futures_income_history(symbol: nil, income_type: nil, start_time: nil, end_time: nil,
+                                      page: nil, limit: 1000, recv_window: 5000)
+        with_rescue do
+          response = coin_futures_connection.get do |req|
+            req.url "/dapi/v1/income"
+            req.headers = headers
+            req.params = {
+              symbol: symbol, incomeType: income_type,
+              startTime: start_time, endTime: end_time,
+              page: page, limit: limit,
+              recvWindow: recv_window, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      # --- Simple Earn ---
+
+      def simple_earn_flexible_subscriptions(product_id: nil, purchase_id: nil, asset: nil,
+                                             start_time: nil, end_time: nil, current: nil, size: nil)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/simple-earn/flexible/history/subscriptionRecord"
+            req.headers = headers
+            req.params = {
+              productId: product_id, purchaseId: purchase_id, asset: asset,
+              startTime: start_time, endTime: end_time,
+              current: current, size: size, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def simple_earn_flexible_redemptions(product_id: nil, redeem_id: nil, asset: nil,
+                                           start_time: nil, end_time: nil, current: nil, size: nil)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/simple-earn/flexible/history/redemptionRecord"
+            req.headers = headers
+            req.params = {
+              productId: product_id, redeemId: redeem_id, asset: asset,
+              startTime: start_time, endTime: end_time,
+              current: current, size: size, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def simple_earn_locked_subscriptions(product_id: nil, purchase_id: nil, asset: nil,
+                                           start_time: nil, end_time: nil, current: nil, size: nil)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/simple-earn/locked/history/subscriptionRecord"
+            req.headers = headers
+            req.params = {
+              productId: product_id, purchaseId: purchase_id, asset: asset,
+              startTime: start_time, endTime: end_time,
+              current: current, size: size, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def simple_earn_locked_redemptions(product_id: nil, redeem_id: nil, asset: nil,
+                                         start_time: nil, end_time: nil, current: nil, size: nil)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/simple-earn/locked/history/redemptionRecord"
+            req.headers = headers
+            req.params = {
+              productId: product_id, redeemId: redeem_id, asset: asset,
+              startTime: start_time, endTime: end_time,
+              current: current, size: size, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      # --- Transfers ---
+
+      def universal_transfer_history(type:, start_time: nil, end_time: nil, current: nil, size: nil, recv_window: 5000)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/sapi/v1/asset/transfer"
+            req.headers = headers
+            req.params = {
+              type: type, startTime: start_time, endTime: end_time,
+              current: current, size: size,
+              recvWindow: recv_window, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
       private
 
+      def usdt_futures_connection
+        @usdt_futures_connection ||= build_client_connection("https://fapi.binance.com")
+      end
+
+      def coin_futures_connection
+        @coin_futures_connection ||= build_client_connection("https://dapi.binance.com")
+      end
+
+      def normalize_order(order_id, raw)
+        order_type = parse_order_type(raw["type"])
+        side = raw["side"]&.downcase&.to_sym
+        status = parse_order_status(raw["status"])
+
+        amount = BigDecimal(raw["origQty"].to_s)
+        amount = nil if amount.zero?
+        quote_amount = BigDecimal(raw["origQuoteOrderQty"].to_s)
+        quote_amount = nil if quote_amount.zero?
+
+        amount_exec = BigDecimal(raw["executedQty"].to_s)
+        quote_amount_exec = BigDecimal(raw["cummulativeQuoteQty"].to_s)
+        quote_amount_exec = nil if quote_amount_exec.negative?
+
+        price = BigDecimal(raw["price"].to_s)
+        if price.zero? && quote_amount_exec&.positive? && amount_exec.positive?
+          price = quote_amount_exec / amount_exec
+        end
+        price = nil if price.zero?
+
+        {
+          order_id: order_id,
+          status: status,
+          side: side,
+          order_type: order_type,
+          price: price,
+          amount: amount,
+          quote_amount: quote_amount,
+          amount_exec: amount_exec,
+          quote_amount_exec: quote_amount_exec,
+          raw: raw
+        }
+      end
+
+      def parse_order_type(type)
+        case type
+        when "MARKET" then :market
+        when "LIMIT" then :limit
+        else :unknown
+        end
+      end
+
+      def parse_order_status(status)
+        case status
+        when "PENDING_CANCEL" then :unknown
+        when "NEW", "PENDING_NEW", "PARTIALLY_FILLED" then :open
+        when "FILLED" then :closed
+        when "CANCELED", "EXPIRED", "EXPIRED_IN_MATCH" then :cancelled
+        when "REJECTED" then :failed
+        else :unknown
+        end
+      end
+
       def validate_trading_credentials
         # Try cancelling a non-existent order — error -2011 (ORDER_DOES_NOT_EXIST) means key is valid with trade permission
         result = cancel_order(symbol: "ETHBTC", order_id: "9999999999")

data/lib/honeymaker/clients/binance_us.rb

@@ -4,6 +4,39 @@ module Honeymaker
   module Clients
     class BinanceUs < Binance
       URL = "https://api.binance.us"
+
+      # --- Staking ---
+
+      def staking_history(staking_type: nil, asset: nil, start_time: nil, end_time: nil, page: nil, limit: nil)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/staking/v1/history"
+            req.headers = headers
+            req.params = {
+              stakingType: staking_type, asset: asset,
+              startTime: start_time, endTime: end_time,
+              page: page, limit: limit, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
+
+      def staking_rewards_history(asset: nil, start_time: nil, end_time: nil, page: nil, limit: nil)
+        with_rescue do
+          response = connection.get do |req|
+            req.url "/staking/v1/rewardsHistory"
+            req.headers = headers
+            req.params = {
+              asset: asset, startTime: start_time, endTime: end_time,
+              page: page, limit: limit, timestamp: timestamp_ms
+            }.compact
+            req.params[:signature] = sign_params(req.params)
+          end
+          response.body
+        end
+      end
     end
   end
 end