buda_api 1.0.0

data/examples/authenticated_api_example.rb

@@ -0,0 +1,213 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Authenticated API usage example
+#
+# This example shows how to use the authenticated API endpoints for trading
+
+require_relative "../lib/buda_api"
+require "dotenv/load"
+
+def main
+  puts "=== Buda API Ruby SDK - Authenticated API Example ==="
+  puts
+
+  # Load credentials from environment variables
+  api_key = ENV["BUDA_API_KEY"]
+  api_secret = ENV["BUDA_API_SECRET"]
+
+  if api_key.nil? || api_secret.nil?
+    puts "ERROR: Please set BUDA_API_KEY and BUDA_API_SECRET environment variables"
+    puts "You can create a .env file with:"
+    puts "BUDA_API_KEY=your_api_key_here"
+    puts "BUDA_API_SECRET=your_api_secret_here"
+    return
+  end
+
+  # Configure the SDK for testing (use staging environment if available)
+  BudaApi.configure do |config|
+    config.debug_mode = true
+    config.timeout = 60
+    # config.base_url = "https://staging.buda.com/api/v2/"  # Uncomment for staging
+  end
+
+  # Create an authenticated client
+  client = BudaApi.authenticated_client(
+    api_key: api_key,
+    api_secret: api_secret
+  )
+
+  market_id = "BTC-CLP"
+
+  begin
+    # 1. Check account balances
+    puts "1. Checking account balances..."
+    
+    ["BTC", "CLP"].each do |currency|
+      balance = client.balance(currency)
+      puts "#{currency} Balance:"
+      puts "  Total: #{balance.amount}"
+      puts "  Available: #{balance.available_amount}"
+      puts "  Frozen: #{balance.frozen_amount}"
+      puts "  Pending withdrawals: #{balance.pending_withdraw_amount}"
+      puts
+    end
+
+    # 2. Get balance events
+    puts "2. Getting recent balance events..."
+    events_result = client.balance_events(
+      currencies: ["BTC", "CLP"],
+      event_names: ["transaction", "deposit_confirm"],
+      page: 1,
+      per_page: 5
+    )
+    
+    puts "Total events: #{events_result[:total_count]}"
+    puts "Events on this page: #{events_result[:events].length}"
+    puts
+
+    # 3. Get order history
+    puts "3. Getting order history for #{market_id}..."
+    orders_result = client.orders(market_id, page: 1, per_page: 10)
+    
+    puts "Orders found: #{orders_result.count}"
+    puts "Current page: #{orders_result.meta.current_page}"
+    puts "Total pages: #{orders_result.meta.total_pages}"
+    
+    if orders_result.count > 0
+      puts "\nRecent orders:"
+      orders_result.orders.first(3).each do |order|
+        puts "  Order ##{order.id}: #{order.type} #{order.amount} at #{order.limit} (#{order.state})"
+        puts "    Created: #{order.created_at}"
+        puts "    Filled: #{order.filled_percentage}%"
+      end
+    end
+    puts
+
+    # 4. Get quotation before placing an order
+    puts "4. Getting quotation for a small test order..."
+    test_amount = 0.0001  # Very small amount for testing
+    
+    quotation = client.quotation(market_id, "bid_given_size", test_amount)
+    puts "To buy #{test_amount} BTC:"
+    puts "  You would pay: #{quotation.quote_balance_change}"
+    puts "  Fee: #{quotation.fee}"
+    puts
+
+    # 5. Simulate a withdrawal
+    puts "5. Simulating a BTC withdrawal..."
+    begin
+      withdrawal_sim = client.simulate_withdrawal("BTC", 0.001)
+      puts "Withdrawal simulation:"
+      puts "  Amount: #{withdrawal_sim.amount}"
+      puts "  Fee: #{withdrawal_sim.fee}"
+      puts "  Currency: #{withdrawal_sim.currency}"
+      puts "  State: #{withdrawal_sim.state}"
+    rescue BudaApi::ApiError => e
+      puts "Could not simulate withdrawal: #{e.message}"
+    end
+    puts
+
+    # 6. Place a very small test order (BE CAREFUL!)
+    puts "6. DEMO: Placing a test order (this is for demonstration only)..."
+    puts "WARNING: This would place an actual order on the exchange!"
+    puts "Skipping order placement in this example for safety."
+    
+    # UNCOMMENT THE FOLLOWING LINES ONLY IF YOU WANT TO PLACE ACTUAL ORDERS:
+    # 
+    # begin
+    #   # Place a limit buy order with a very low price (unlikely to fill)
+    #   order = client.place_order(
+    #     market_id, 
+    #     "Bid",           # Buy order
+    #     "limit",         # Limit order
+    #     0.0001,          # Very small amount
+    #     1000000          # Very low price (unlikely to execute)
+    #   )
+    #   
+    #   puts "Order placed successfully:"
+    #   puts "  Order ID: #{order.id}"
+    #   puts "  Type: #{order.type}"
+    #   puts "  Amount: #{order.amount}"
+    #   puts "  Limit price: #{order.limit}"
+    #   puts "  State: #{order.state}"
+    #   puts
+    #   
+    #   # Wait a moment then cancel the order
+    #   puts "Cancelling the test order..."
+    #   cancelled_order = client.cancel_order(order.id)
+    #   puts "Order cancelled. New state: #{cancelled_order.state}"
+    #   
+    # rescue BudaApi::ApiError => e
+    #   puts "Could not place/cancel order: #{e.message}"
+    # end
+    puts
+
+    # 7. Get recent deposits and withdrawals
+    puts "7. Getting recent deposits and withdrawals..."
+    
+    begin
+      withdrawals = client.withdrawals("BTC", page: 1, per_page: 3)
+      puts "Recent BTC withdrawals: #{withdrawals[:withdrawals].length}"
+      withdrawals[:withdrawals].each do |withdrawal|
+        puts "  #{withdrawal.created_at.strftime('%Y-%m-%d')}: #{withdrawal.amount} (#{withdrawal.state})"
+      end
+      
+      deposits = client.deposits("BTC", page: 1, per_page: 3)
+      puts "Recent BTC deposits: #{deposits[:deposits].length}"
+      deposits[:deposits].each do |deposit|
+        puts "  #{deposit.created_at.strftime('%Y-%m-%d')}: #{deposit.amount} (#{deposit.state})"
+      end
+    rescue BudaApi::ApiError => e
+      puts "Could not fetch deposits/withdrawals: #{e.message}"
+    end
+    puts
+
+    # 8. Demonstrate batch operations
+    puts "8. DEMO: Batch operations (cancel multiple orders)"
+    puts "This would cancel multiple orders at once and optionally place new ones."
+    puts "Skipping for safety in this example."
+    
+    # Example of batch operations:
+    # result = client.batch_orders(
+    #   cancel_orders: [order_id_1, order_id_2],
+    #   place_orders: [
+    #     {
+    #       type: "Bid",
+    #       price_type: "limit", 
+    #       amount: "0.001",
+    #       limit: "50000000"
+    #     }
+    #   ]
+    # )
+
+  rescue BudaApi::AuthenticationError => e
+    puts "Authentication Error: #{e.message}"
+    puts "Please check your API credentials"
+  rescue BudaApi::AuthorizationError => e
+    puts "Authorization Error: #{e.message}"
+    puts "Your API key may not have sufficient permissions"
+  rescue BudaApi::RateLimitError => e
+    puts "Rate Limit Error: #{e.message}"
+    puts "Please wait before making more requests"
+  rescue BudaApi::ApiError => e
+    puts "API Error: #{e.message}"
+    puts "Status code: #{e.status_code}" if e.status_code
+    puts "Response: #{e.response_body}" if e.response_body
+  rescue BudaApi::ValidationError => e
+    puts "Validation Error: #{e.message}"
+  rescue => e
+    puts "Unexpected Error: #{e.class.name} - #{e.message}"
+  end
+
+  puts
+  puts "=== Authenticated API example completed ==="
+  puts
+  puts "IMPORTANT NOTES:"
+  puts "- This example uses very small amounts and low prices for safety"
+  puts "- Always test on staging environment first if available"
+  puts "- Be careful when placing real orders on production"
+  puts "- Monitor your orders and cancel them if needed"
+end
+
+main if __FILE__ == $0

data/examples/error_handling_example.rb

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Error handling and debugging example
+#
+# This example demonstrates comprehensive error handling and debugging features
+
+require_relative "../lib/buda_api"
+
+def main
+  puts "=== Buda API Ruby SDK - Error Handling & Debugging Example ==="
+  puts
+
+  # Configure SDK with debug mode enabled
+  BudaApi.configure do |config|
+    config.debug_mode = true
+    config.timeout = 10  # Short timeout to trigger timeout errors
+    config.logger_level = :debug
+  end
+
+  # Example 1: Connection and timeout errors
+  puts "1. Testing connection errors..."
+  begin
+    # Create client with invalid base URL
+    client = BudaApi::PublicClient.new(base_url: "https://invalid-domain-that-does-not-exist.com/api/v2/")
+    client.markets
+  rescue BudaApi::ConnectionError => e
+    puts "✅ Caught ConnectionError as expected: #{e.message}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 2: Timeout errors
+  puts "2. Testing timeout handling..."
+  begin
+    client = BudaApi::PublicClient.new(timeout: 0.001)  # Very short timeout
+    client.markets
+  rescue BudaApi::TimeoutError => e
+    puts "✅ Caught TimeoutError as expected: #{e.message}"
+  rescue BudaApi::ConnectionError => e
+    puts "✅ Connection error (may occur instead of timeout): #{e.message}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 3: Validation errors
+  puts "3. Testing validation errors..."
+  client = BudaApi::PublicClient.new
+
+  begin
+    # Test invalid market ID
+    client.ticker("INVALID-MARKET")
+  rescue BudaApi::ValidationError => e
+    puts "✅ Caught ValidationError as expected: #{e.message}"
+  rescue BudaApi::NotFoundError => e
+    puts "✅ Caught NotFoundError (API-level validation): #{e.message}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+
+  begin
+    # Test missing required parameters
+    client.quotation(nil, "bid_given_size", 0.1)
+  rescue BudaApi::ValidationError => e
+    puts "✅ Caught ValidationError for missing parameter: #{e.message}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 4: Authentication errors
+  puts "4. Testing authentication errors..."
+  begin
+    auth_client = BudaApi::AuthenticatedClient.new(
+      api_key: "invalid_key",
+      api_secret: "invalid_secret"
+    )
+    auth_client.balance("BTC")
+  rescue BudaApi::AuthenticationError => e
+    puts "✅ Caught AuthenticationError as expected: #{e.message}"
+    puts "   Status code: #{e.status_code}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 5: API response errors
+  puts "5. Testing API response handling..."
+  begin
+    # Test with non-existent market (should return 404)
+    client.ticker("FAKE-COIN")
+  rescue BudaApi::NotFoundError => e
+    puts "✅ Caught NotFoundError as expected: #{e.message}"
+    puts "   Status code: #{e.status_code}"
+    puts "   Response headers: #{e.response_headers.keys.join(', ')}" if e.response_headers
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 6: Rate limiting (simulated)
+  puts "6. Testing rate limit handling..."
+  puts "Making multiple rapid requests to potentially trigger rate limiting..."
+  
+  10.times do |i|
+    begin
+      client.ticker("BTC-CLP")
+      print "."
+    rescue BudaApi::RateLimitError => e
+      puts "\n✅ Caught RateLimitError: #{e.message}"
+      break
+    rescue => e
+      puts "\n❌ Unexpected error: #{e.class.name} - #{e.message}"
+      break
+    end
+    
+    # Small delay between requests
+    sleep(0.1)
+  end
+  puts "\nCompleted rate limit test"
+  puts
+
+  # Example 7: Invalid credentials format
+  puts "7. Testing credential validation..."
+  begin
+    BudaApi::AuthenticatedClient.new(api_key: "", api_secret: "secret")
+  rescue BudaApi::ConfigurationError => e
+    puts "✅ Caught ConfigurationError for empty API key: #{e.message}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+
+  begin
+    BudaApi::AuthenticatedClient.new(api_key: "key", api_secret: nil)
+  rescue BudaApi::ConfigurationError => e
+    puts "✅ Caught ConfigurationError for nil API secret: #{e.message}"
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 8: Debugging successful requests
+  puts "8. Demonstrating debug output for successful requests..."
+  puts "Watch the detailed HTTP request/response logs above ☝️"
+  
+  begin
+    markets = client.markets
+    puts "✅ Successfully fetched #{markets.length} markets with debug logging"
+    
+    ticker = client.ticker("BTC-CLP")
+    puts "✅ Successfully fetched ticker with debug logging"
+    
+  rescue => e
+    puts "❌ Unexpected error: #{e.class.name} - #{e.message}"
+  end
+  puts
+
+  # Example 9: Custom error context
+  puts "9. Demonstrating error context and logging..."
+  
+  begin
+    # Simulate a custom error scenario
+    raise BudaApi::ValidationError, "Custom validation failed"
+  rescue BudaApi::ValidationError => e
+    BudaApi::Logger.log_error(e, context: { 
+      user_action: "Testing custom error",
+      market_id: "BTC-CLP",
+      timestamp: Time.now 
+    })
+    puts "✅ Logged custom error with context"
+  end
+  puts
+
+  # Example 10: Recovery strategies
+  puts "10. Demonstrating error recovery strategies..."
+  
+  def retry_with_backoff(max_retries: 3, initial_delay: 1)
+    retries = 0
+    
+    begin
+      yield
+    rescue BudaApi::RateLimitError, BudaApi::ServerError => e
+      retries += 1
+      
+      if retries <= max_retries
+        delay = initial_delay * (2 ** (retries - 1))
+        puts "Retry #{retries}/#{max_retries} after #{delay}s due to: #{e.class.name}"
+        sleep(delay)
+        retry
+      else
+        puts "Max retries exceeded, giving up"
+        raise
+      end
+    end
+  end
+
+  begin
+    retry_with_backoff do
+      # This might fail due to rate limiting or server errors
+      client.markets
+    end
+    puts "✅ Request succeeded (possibly after retries)"
+  rescue => e
+    puts "❌ Request failed after retries: #{e.message}"
+  end
+
+  puts
+  puts "=== Error Handling & Debugging Example Completed ==="
+  puts
+  puts "Key takeaways:"
+  puts "- Always wrap API calls in appropriate exception handlers"
+  puts "- Use debug mode during development to see detailed HTTP logs"
+  puts "- Implement retry logic for transient errors (rate limits, server errors)"
+  puts "- Validate parameters client-side before making API calls"
+  puts "- Log errors with context for easier debugging"
+  puts "- Different error types require different handling strategies"
+end
+
+main if __FILE__ == $0

data/examples/public_api_example.rb

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic public API usage example
+#
+# This example shows how to use the public API endpoints that don't require authentication
+
+require_relative "../lib/buda_api"
+
+def main
+  puts "=== Buda API Ruby SDK - Public API Example ==="
+  puts
+
+  # Configure the SDK
+  BudaApi.configure do |config|
+    config.debug_mode = true  # Enable debug logging
+    config.timeout = 60      # Increase timeout to 60 seconds
+  end
+
+  # Create a public client
+  client = BudaApi.public_client
+
+  begin
+    # 1. Get all available markets
+    puts "1. Fetching all available markets..."
+    markets = client.markets
+    puts "Found #{markets.length} markets:"
+    
+    markets.first(5).each do |market|
+      puts "  - #{market.id}: #{market.name} (#{market.base_currency}/#{market.quote_currency})"
+      puts "    Minimum order: #{market.minimum_order_amount}"
+    end
+    puts "  ... and #{markets.length - 5} more" if markets.length > 5
+    puts
+
+    # 2. Get specific market details
+    market_id = "BTC-CLP"
+    puts "2. Getting details for #{market_id}..."
+    market = client.market_details(market_id)
+    puts "Market: #{market.name}"
+    puts "Base currency: #{market.base_currency}"
+    puts "Quote currency: #{market.quote_currency}"
+    puts "Minimum order amount: #{market.minimum_order_amount}"
+    puts
+
+    # 3. Get ticker information
+    puts "3. Getting ticker for #{market_id}..."
+    ticker = client.ticker(market_id)
+    puts "Last price: #{ticker.last_price}"
+    puts "Min ask: #{ticker.min_ask}"
+    puts "Max bid: #{ticker.max_bid}"
+    puts "Volume (24h): #{ticker.volume}"
+    puts "Price change (24h): #{ticker.price_variation_24h}%"
+    puts "Price change (7d): #{ticker.price_variation_7d}%"
+    puts
+
+    # 4. Get order book
+    puts "4. Getting order book for #{market_id}..."
+    order_book = client.order_book(market_id)
+    
+    puts "Best ask: #{order_book.best_ask.price} (#{order_book.best_ask.amount})"
+    puts "Best bid: #{order_book.best_bid.price} (#{order_book.best_bid.amount})"
+    puts "Spread: #{order_book.spread} (#{order_book.spread_percentage}%)"
+    
+    puts "\nTop 3 asks:"
+    order_book.asks.first(3).each_with_index do |ask, i|
+      puts "  #{i + 1}. #{ask.price} x #{ask.amount} = #{ask.total}"
+    end
+    
+    puts "\nTop 3 bids:"
+    order_book.bids.first(3).each_with_index do |bid, i|
+      puts "  #{i + 1}. #{bid.price} x #{bid.amount} = #{bid.total}"
+    end
+    puts
+
+    # 5. Get recent trades
+    puts "5. Getting recent trades for #{market_id}..."
+    trades = client.trades(market_id, limit: 5)
+    
+    puts "Recent trades (#{trades.count} total):"
+    trades.each do |trade|
+      puts "  #{trade.timestamp.strftime('%H:%M:%S')}: #{trade.amount} at #{trade.price} (#{trade.direction})"
+    end
+    puts
+
+    # 6. Get quotation
+    puts "6. Getting quotation for buying 0.001 BTC..."
+    quotation = client.quotation(market_id, "bid_given_size", 0.001)
+    puts "Quotation type: #{quotation.type}"
+    puts "Amount: #{quotation.amount}"
+    puts "You would pay: #{quotation.quote_balance_change}"
+    puts "Fee: #{quotation.fee}"
+    puts
+
+    # 7. Get market reports
+    puts "7. Getting average price report for the last 24 hours..."
+    start_time = Time.now - 86400  # 24 hours ago
+    avg_prices = client.average_prices_report(market_id, start_at: start_time)
+    
+    if avg_prices.any?
+      puts "Average price data points: #{avg_prices.length}"
+      puts "First data point: #{avg_prices.first.average} at #{avg_prices.first.timestamp}"
+      puts "Last data point: #{avg_prices.last.average} at #{avg_prices.last.timestamp}"
+    else
+      puts "No average price data available for the specified period"
+    end
+    puts
+
+    puts "8. Getting candlestick report for the last 24 hours..."
+    candles = client.candlestick_report(market_id, start_at: start_time)
+    
+    if candles.any?
+      puts "Candlestick data points: #{candles.length}"
+      last_candle = candles.last
+      puts "Last candle:"
+      puts "  Time: #{last_candle.timestamp}"
+      puts "  Open: #{last_candle.open}"
+      puts "  High: #{last_candle.high}"
+      puts "  Low: #{last_candle.low}"
+      puts "  Close: #{last_candle.close}"
+      puts "  Volume: #{last_candle.volume}"
+    else
+      puts "No candlestick data available for the specified period"
+    end
+
+  rescue BudaApi::ApiError => e
+    puts "API Error: #{e.message}"
+    puts "Status code: #{e.status_code}" if e.status_code
+    puts "Response: #{e.response_body}" if e.response_body
+  rescue BudaApi::ConnectionError => e
+    puts "Connection Error: #{e.message}"
+  rescue BudaApi::ValidationError => e
+    puts "Validation Error: #{e.message}"
+  rescue => e
+    puts "Unexpected Error: #{e.class.name} - #{e.message}"
+  end
+
+  puts
+  puts "=== Example completed ==="
+end
+
+main if __FILE__ == $0