kraken_bridge 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5397bfb623a5433ebf88507b946ec3536ed334d4af933b02d8eb2f09747bb9f9
-  data.tar.gz: 4fca7ecc5019b00cdf3e83d17df57d65648e9475c02a5de3c74082fec4e8c583
+  metadata.gz: 103cc2bb62587418aaaf66eaa998e57c469595696460f9a3065ed2d6d5c4a5ed
+  data.tar.gz: 76c17abf78c12ba5c7abaaa7de77e795df2f8cf47a8b2564571ee4f8c409bfef
 SHA512:
-  metadata.gz: 1a12ffd53e72cbf456ceb73ec8e9720f7b74bd9092187ac65b874e122bede6b0f61feeed549f76583e4b4832ea230c2073c94861ec0d8a860735b8ebd0a7e441
-  data.tar.gz: 58dcd2398cc142701c2ac3de14c1a4c25e84637ddc900a82f42ee9c52d5f9f1d49d42016e3f1b70192920beefb7da8e3c069fc9689bdfbcfd68e989f81f47ed9
+  metadata.gz: aa6ec0109f7c6de1850e3281d9c03942638cb70591097e2a4202fa597bffeb3579713fb34282fb0beefd0bf7f124631a722d421b1a0200a533ed13e198fbd782
+  data.tar.gz: cbb0985a92677ed4f7cfd4524af587f575b24599aa11aa8f95f93f3a62322cb907dd4ed68bd04d1027284bd238fea545bf443c65676be233f9be6b60a4bece20

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-28
+
+- Added Spot REST trading wrappers for `AmendOrder`, `AddOrderBatch`, `CancelOrderBatch`, and `GetWebSocketsToken`
+- Expanded `CancelOrder` to support `txid`, `userref`, and `cl_ord_id`
+- Added request specs for private trading and account endpoint parameter mapping
+
 ## [0.1.0] - 2025-12-02
 
 - Initial release

data/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,284 @@
+# KrakenBridge Gem - Complete Implementation Summary
+
+## ✅ Implementation Complete - Ready for Publishing
+
+### What's Included
+
+#### 1. **REST API - Complete Implementation**
+
+**Public Endpoints (Market Data):**
+- `time` - Server time
+- `system_status` - System status
+- `assets` - Asset information
+- `asset_pairs` - Asset pair information
+- `ticker` - Ticker data
+- `ohlc` - OHLC candlestick data
+- `order_book` - Order book (depth)
+- `trades` - Recent trades
+- `spread` - Bid/ask spread
+
+**Private Endpoints (Account):**
+- `balance` - Account balance
+- `extended_balance` - Extended balance
+- `trade_balance` - Trade balance
+- `open_orders` - Open orders
+- `closed_orders` - Closed orders
+- `query_orders` - Query specific orders
+- `trades_history` - Trade history
+- `query_trades` - Query specific trades
+- `open_positions` - Open positions
+- `ledger` - Account ledger
+- `query_ledger` - Query ledger entries
+- `trade_volume` - Trade volume
+- `request_export_report` - Request export
+- `get_export_report` - Get export
+
+**Private Endpoints (Trading):**
+- `add_order` - Place a new order
+- `edit_order` - Edit existing order
+- `cancel_order` - Cancel single order
+- `cancel_all_orders` - Cancel all orders
+- `cancel_all_orders_after` - Cancel after timeout
+
+#### 2. **WebSocket - Public Feeds Implementation**
+
+**Supported Channels:**
+- **Ticker** - Real-time ticker updates
+- **Trades** - Trade feed
+- **OHLC/Klines** - Candlestick data
+- **Spread** - Bid/ask spread updates
+
+**Features:**
+- Automatic connection management
+- Subscribe/unsubscribe functionality
+- Callback-based message handling
+- Error handling and logging
+- Connection status tracking
+
+#### 3. **Authentication & Security**
+
+- ✅ HMAC-SHA512 signature generation (Kraken spec compliant)
+- ✅ Millisecond-precision nonce generation
+- ✅ Automatic nonce injection into all authenticated requests
+- ✅ 2FA (OTP) support on all authenticated endpoints
+- ✅ Base64 secret decoding
+- ✅ Request body ordering for signature validation
+
+#### 4. **Core Features**
+
+- ✅ Rate limiting (configurable)
+- ✅ Automatic retries with exponential backoff
+- ✅ Comprehensive error handling
+- ✅ Request/response logging
+- ✅ Configuration management
+- ✅ Standardized response objects
+- ✅ Custom error classes
+
+#### 5. **Documentation**
+
+**Files Created/Updated:**
+- `README.md` - Comprehensive guide with:
+  - Quick start examples
+  - Configuration options
+  - Full API reference
+  - Error handling patterns
+  - Security recommendations
+  - Troubleshooting guide
+  - References and links
+
+- `AUTHENTICATION_FIXES.md` - Technical details on authentication implementation
+- `TESTING_AUTHENTICATED_ENDPOINTS.md` - Testing guide with examples
+
+### File Structure
+
+```
+kraken_bridge/
+├── lib/
+│   ├── kraken_bridge.rb (main entry point)
+│   └── kraken_bridge/
+│       ├── client.rb (main client)
+│       ├── configuration.rb
+│       ├── version.rb
+│       ├── rest/
+│       │   ├── client.rb
+│       │   ├── connection.rb
+│       │   ├── request.rb
+│       │   ├── response.rb
+│       │   ├── authentication.rb
+│       │   └── endpoints/
+│       │       ├── base.rb
+│       │       ├── market_data.rb
+│       │       ├── account.rb
+│       │       └── trading.rb
+│       ├── websocket/
+│       │   ├── client.rb
+│       │   ├── connection.rb
+│       │   └── message_handler.rb
+│       ├── utils/
+│       │   ├── nonce_generator.rb
+│       │   └── signature.rb
+│       ├── middleware/
+│       │   ├── rate_limiter.rb
+│       │   ├── retry_handler.rb
+│       │   ├── logger.rb
+│       │   └── error_handler.rb
+│       └── errors/
+│           ├── base_error.rb
+│           ├── api_error.rb
+│           ├── authentication_error.rb
+│           ├── rate_limit_error.rb
+│           ├── connection_error.rb
+│           └── validation_error.rb
+├── spec/ (test files)
+├── README.md
+├── CHANGELOG.md
+├── LICENSE.txt
+├── Gemfile
+├── kraken_bridge.gemspec
+└── Rakefile
+```
+
+### Usage Examples
+
+#### Public API
+```ruby
+client = KrakenBridge::Client.new
+ticker = client.market_data.ticker(['XBTUSD'])
+puts ticker.data
+```
+
+#### Private API (with authentication)
+```ruby
+client = KrakenBridge::Client.new(
+  api_key: ENV['KRAKEN_API_KEY'],
+  api_secret: ENV['KRAKEN_API_SECRET']
+)
+balance = client.account.balance
+puts balance.data
+```
+
+#### WebSocket Real-time Data
+```ruby
+client = KrakenBridge::Client.new
+
+client.connect_websocket do |message|
+  puts message
+end
+
+client.subscribe_ticker(['XBTUSD']) do |data|
+  puts "Ticker: #{data}"
+end
+
+sleep(30)
+client.disconnect_websocket
+```
+
+### Dependencies
+
+```ruby
+# Runtime
+websocket-client-simple ~> 0.8
+
+# Development
+bundler ~> 2.0
+rake ~> 13.0
+rspec ~> 3.12
+rubocop ~> 1.50
+rubocop-rspec ~> 2.20
+vcr ~> 6.1
+webmock ~> 3.18
+simplecov ~> 0.22
+yard ~> 0.9
+```
+
+### Publishing Steps
+
+1. **Update version** in `lib/kraken_bridge/version.rb`
+   ```ruby
+   VERSION = '1.0.0'
+   ```
+
+2. **Build the gem**
+   ```bash
+   bundle exec rake build
+   ```
+
+3. **Test locally**
+   ```bash
+   bundle exec rspec
+   ```
+
+4. **Push to RubyGems**
+   ```bash
+   gem push pkg/kraken_bridge-1.0.0.gem
+   ```
+
+5. **Update gemspec metadata**
+   - Set proper homepage URL
+   - Add description
+   - Configure allowed_push_host
+
+### Current Status
+
+✅ **All Features Implemented**
+✅ **Authentication Working**
+✅ **Private APIs Tested**
+✅ **WebSocket Implementation Complete**
+✅ **Documentation Complete**
+✅ **Code Quality**
+✅ **Ready for Publishing**
+
+### Next Steps for Publishing
+
+1. Update `kraken_bridge.gemspec`:
+   ```ruby
+   spec.summary = "Ruby client for Kraken cryptocurrency exchange API"
+   spec.description = "Comprehensive REST and WebSocket integration with Kraken"
+   spec.homepage = "https://github.com/balram/kraken_bridge"
+   spec.metadata['allowed_push_host'] = "https://rubygems.org"
+   spec.metadata['source_code_uri'] = "https://github.com/balram/kraken_bridge"
+   spec.metadata['changelog_uri'] = "https://github.com/balram/kraken_bridge/blob/master/CHANGELOG.md"
+   ```
+
+2. Run final tests
+   ```bash
+   bundle exec rspec
+   bundle exec rubocop
+   ```
+
+3. Create git tag
+   ```bash
+   git tag -a v1.0.0 -m "Release version 1.0.0"
+   ```
+
+4. Push to RubyGems
+   ```bash
+   gem build kraken_bridge.gemspec
+   gem push kraken_bridge-1.0.0.gem
+   ```
+
+### Key Features Implemented
+
+| Feature | Status | Details |
+|---------|--------|---------|
+| REST API (Public) | ✅ | All market data endpoints |
+| REST API (Private) | ✅ | Account & Trading endpoints |
+| WebSocket | ✅ | Ticker, Trades, OHLC, Spread |
+| Authentication | ✅ | HMAC-SHA512 per Kraken spec |
+| Nonce Generation | ✅ | Millisecond precision |
+| 2FA Support | ✅ | OTP parameter support |
+| Rate Limiting | ✅ | Built-in & configurable |
+| Error Handling | ✅ | Custom error classes |
+| Logging | ✅ | Configurable debug logging |
+| Documentation | ✅ | Comprehensive README |
+
+### Security Verified
+
+- ✅ Proper signature generation (HMAC-SHA512)
+- ✅ Base64 secret decoding
+- ✅ Nonce in milliseconds
+- ✅ No API keys in code
+- ✅ Environment variable support
+- ✅ 2FA-ready implementation
+
+

data/README.md

@@ -1,10 +1,10 @@
 # KrakenBridge
 
-A comprehensive Ruby gem for seamless integration with Kraken cryptocurrency exchange APIs. Supports both REST and WebSocket protocols for public market data and authenticated trading operations.
+A Ruby gem for Kraken cryptocurrency exchange APIs. Supports Spot REST workflows for market data and core authenticated trading, plus public WebSocket feeds.
 
 ## Features
 
-- ✅ **Complete REST API Support**: Public and private endpoints
+- ✅ **Spot REST Coverage for Core Workflows**: Market data, account queries, and trading operations
 - ✅ **WebSocket Real-time Feeds**: Ticker, trades, OHLC/Klines, and spread data
 - ✅ **Automatic Nonce Generation**: Millisecond-precision timestamps
 - ✅ **Signature Generation**: HMAC-SHA512 authentication per Kraken specs
@@ -179,10 +179,15 @@ client.account.get_export_report(report: 'trades')
 
 ```ruby
 client.trading.add_order(pair: 'XBTUSD', type: 'buy', ordertype: 'limit', volume: 0.01, price: 25000)
+client.trading.amend_order(txid: 'order_id', order_qty: 0.02, limit_price: '26000')
+client.trading.add_order_batch(pair: 'XBTUSD', orders: [{ ordertype: 'limit', type: 'buy', volume: '0.01', price: '25000' }, { ordertype: 'limit', type: 'sell', volume: '0.01', price: '26000' }])
+client.trading.get_websockets_token
 client.trading.edit_order(txid: 'order_id', volume: 0.02, price: 26000)
 client.trading.cancel_order('order_id')
+client.trading.cancel_order(cl_ord_id: 'client-order-id')
 client.trading.cancel_all_orders
 client.trading.cancel_all_orders_after(timeout: 300)
+client.trading.cancel_order_batch(txid: ['order_id_1', 'order_id_2'])
 ```
 
 ### WebSocket (Public Feeds)

data/examples/test.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+
+require_relative 'lib/kraken_bridge'
+
+# Initialize client
+client = KrakenBridge::Client.new(
+  api_key: ENV.fetch('KRAKEN_API_KEY', nil),
+  api_secret: ENV.fetch('KRAKEN_API_SECRET', nil)
+)
+
+puts('=' * 80)
+puts 'KRAKEN BRIDGE - API EXAMPLES'
+puts('=' * 80)
+
+# PUBLIC API EXAMPLES
+puts "\n\n"
+puts('=' * 80)
+puts 'PUBLIC API EXAMPLES (No Authentication Required)'
+puts('=' * 80)
+
+puts "\n1. SERVER TIME"
+puts('-' * 80)
+time_response = client.market_data.time
+puts time_response.data if time_response.success?
+
+puts "\n2. SYSTEM STATUS"
+puts('-' * 80)
+status_response = client.market_data.system_status
+puts status_response.data if status_response.success?
+
+puts "\n3. ASSET INFORMATION"
+puts('-' * 80)
+assets_response = client.market_data.assets(assets: %w[BTC ETH])
+puts assets_response.data if assets_response.success?
+
+puts "\n4. ASSET PAIRS"
+puts('-' * 80)
+pairs_response = client.market_data.asset_pairs(pairs: %w[XBTUSD ETHUSD])
+puts pairs_response.data if pairs_response.success?
+
+puts "\n5. TICKER INFORMATION"
+puts('-' * 80)
+ticker_response = client.market_data.ticker(%w[XBTUSD ETHUSD])
+puts ticker_response.data if ticker_response.success?
+
+puts "\n6. OHLC DATA"
+puts('-' * 80)
+ohlc_response = client.market_data.ohlc('XBTUSD', interval: 1)
+puts ohlc_response.data if ohlc_response.success?
+
+puts "\n7. ORDER BOOK (Depth)"
+puts('-' * 80)
+orderbook_response = client.market_data.order_book('XBTUSD')
+puts orderbook_response.data if orderbook_response.success?
+
+puts "\n8. RECENT TRADES"
+puts('-' * 80)
+trades_response = client.market_data.trades('XBTUSD')
+puts trades_response.data if trades_response.success?
+
+puts "\n9. SPREAD"
+puts('-' * 80)
+spread_response = client.market_data.spread('XBTUSD')
+puts spread_response.data if spread_response.success?
+
+# PRIVATE API EXAMPLES (Requires API Credentials)
+if ENV['KRAKEN_API_KEY'] && ENV['KRAKEN_API_SECRET']
+  puts "\n\n"
+  puts('=' * 80)
+  puts 'PRIVATE API EXAMPLES (Requires Authentication)'
+  puts('=' * 80)
+
+  puts "\n10. ACCOUNT BALANCE"
+  puts('-' * 80)
+  balance_response = client.account.balance
+  puts balance_response.data if balance_response.success?
+  puts balance_response.errors unless balance_response.success?
+
+  puts "\n11. EXTENDED BALANCE"
+  puts('-' * 80)
+  ext_balance_response = client.account.extended_balance
+  puts ext_balance_response.data if ext_balance_response.success?
+
+  puts "\n12. TRADE BALANCE"
+  puts('-' * 80)
+  trade_balance_response = client.account.trade_balance
+  puts trade_balance_response.data if trade_balance_response.success?
+
+  puts "\n13. OPEN ORDERS"
+  puts('-' * 80)
+  open_orders_response = client.account.open_orders
+  puts open_orders_response.data if open_orders_response.success?
+
+  puts "\n14. CLOSED ORDERS"
+  puts('-' * 80)
+  closed_orders_response = client.account.closed_orders
+  puts closed_orders_response.data if closed_orders_response.success?
+
+  puts "\n15. TRADES HISTORY"
+  puts('-' * 80)
+  trades_history_response = client.account.trades_history
+  puts trades_history_response.data if trades_history_response.success?
+
+  puts "\n16. OPEN POSITIONS"
+  puts('-' * 80)
+  positions_response = client.account.open_positions
+  puts positions_response.data if positions_response.success?
+
+  puts "\n17. LEDGER"
+  puts('-' * 80)
+  ledger_response = client.account.ledger
+  puts ledger_response.data if ledger_response.success?
+
+  puts "\n18. TRADE VOLUME"
+  puts('-' * 80)
+  volume_response = client.account.trade_volume
+  puts volume_response.data if volume_response.success?
+end
+
+puts "\n\n"
+puts('=' * 80)
+puts 'WEBSOCKET EXAMPLES (Public Feeds)'
+puts('=' * 80)
+
+puts "\nWebSocket Features Available:"
+puts '- Subscribe to ticker data'
+puts '- Subscribe to trades'
+puts '- Subscribe to OHLC/Klines'
+puts '- Subscribe to spread data'

data/lib/kraken_bridge/client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  class Client
+    attr_reader :rest, :websocket, :config
+
+    def initialize(api_key: nil, api_secret: nil, **options)
+      @config = KrakenBridge.configuration.dup
+      @config.api_key = api_key if api_key
+      @config.api_secret = api_secret if api_secret
+
+      options.each do |key, value|
+        @config.send("#{key}=", value) if @config.respond_to?("#{key}=")
+      end
+
+      @rest = Rest::Client.new(@config)
+      @websocket = Websocket::Client.new(@config)
+    end
+
+    def market_data
+      rest.market_data
+    end
+
+    def account
+      rest.account
+    end
+
+    def trading
+      rest.trading
+    end
+
+    def ticker(pair)
+      rest.market_data.ticker(pair)
+    end
+
+    def trades(pair, since: nil)
+      rest.market_data.trades(pair, since: since)
+    end
+
+    def ohlc(pair, interval: 1, since: nil)
+      rest.market_data.ohlc(pair, interval: interval, since: since)
+    end
+
+    def balance
+      rest.account.balance
+    end
+
+    def place_order(pair:, type:, order_type:, volume:, **options)
+      rest.trading.add_order(
+        pair: pair,
+        type: type,
+        ordertype: order_type,
+        volume: volume,
+        **options
+      )
+    end
+
+    def subscribe_ticker(pairs, &)
+      websocket.subscribe_ticker(pairs, &)
+    end
+
+    def subscribe_trades(pairs, &)
+      websocket.subscribe_trades(pairs, &)
+    end
+
+    def subscribe_ohlc(pairs, interval: 1, &block)
+      websocket.subscribe_ohlc(pairs, interval: interval, &block)
+    end
+
+    def subscribe_klines(pairs, interval: 1, &block)
+      websocket.subscribe_klines(pairs, interval: interval, &block)
+    end
+
+    def connect_websocket(&)
+      websocket.connect(&)
+    end
+
+    def disconnect_websocket
+      websocket.disconnect
+    end
+  end
+end

data/lib/kraken_bridge/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  class Configuration
+    attr_accessor :api_key, :api_secret, :rest_url, :ws_url,
+                  :timeout, :open_timeout, :logger, :log_level,
+                  :rate_limit_enabled, :retry_enabled, :max_retries
+
+    def initialize
+      @api_key = ENV.fetch('KRAKEN_API_KEY', nil)
+      @api_secret = ENV.fetch('KRAKEN_API_SECRET', nil)
+      @rest_url = ENV['KRAKEN_API_URL'] || 'https://api.kraken.com'
+      @ws_url = ENV['KRAKEN_WEBSOCKET_URL'] || 'wss://ws.kraken.com'
+      @timeout = 30
+      @open_timeout = 10
+      @log_level = Logger::INFO
+      @logger = Middleware::Logger.new(::Logger.new($stdout))
+      @rate_limit_enabled = true
+      @retry_enabled = true
+      @max_retries = 3
+
+      configure_logger
+    end
+
+    def credentials_present?
+      !api_key.nil? && !api_secret.nil?
+    end
+
+    private
+
+    def configure_logger
+      @logger.logger.level = @log_level
+      @logger.logger.formatter = proc do |severity, datetime, _progname, msg|
+        "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity} -- #{msg}\n"
+      end
+    end
+  end
+end

data/lib/kraken_bridge/errors/api_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  module Errors
+    class ApiError < BaseError
+      attr_reader :error_codes, :response
+
+      def initialize(message, error_codes = [], response = nil)
+        @error_codes = error_codes
+        @response = response
+        super(message)
+      end
+
+      def error_messages
+        error_codes.join(', ')
+      end
+    end
+  end
+end

data/lib/kraken_bridge/errors/authentication_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  module Errors
+    class AuthenticationError < BaseError
+      def initialize(message = 'Authentication failed')
+        super
+      end
+    end
+  end
+end

data/lib/kraken_bridge/errors/base_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  module Errors
+    class BaseError < StandardError
+      attr_reader :original_error
+
+      def initialize(message = nil, original_error = nil)
+        @original_error = original_error
+        super(message)
+      end
+    end
+  end
+end

data/lib/kraken_bridge/errors/connection_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  module Errors
+    class ConnectionError < BaseError
+      def initialize(message = 'Connection failed', original_error = nil)
+        super
+      end
+    end
+  end
+end

data/lib/kraken_bridge/errors/rate_limit_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  module Errors
+    class RateLimitError < BaseError
+      attr_reader :retry_after
+
+      def initialize(message, retry_after = nil)
+        @retry_after = retry_after
+        super(message)
+      end
+    end
+  end
+end

data/lib/kraken_bridge/errors/validation_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module KrakenBridge
+  module Errors
+    class ValidationError < BaseError
+      attr_reader :field, :value
+
+      def initialize(message, field: nil, value: nil)
+        @field = field
+        @value = value
+        super(message)
+      end
+    end
+  end
+end