delta_exchange 0.1.2

data/docs/REST_API_GUIDE.md

@@ -0,0 +1,150 @@
+# REST API Guide
+
+DeltaExchange REST API v2 follows standard JSON patterns. The gem exposes resources through the `Client` object.
+
+## Initializing the Client
+
+```ruby
+client = DeltaExchange::Client.new
+```
+
+## Resources
+
+### Products
+
+Provides data about tradable instruments.
+
+```ruby
+products = client.products.all
+symbol_data = client.products.find('BTCUSD')
+tickers = client.products.tickers
+single_ticker = client.products.ticker('BTCUSD')
+leverage_data = client.products.leverage(1) # For product_id: 1
+client.products.set_leverage(1, leverage: "25")
+```
+
+### Orders
+
+Execution management.
+
+```ruby
+# Create a limit order
+order = client.orders.create(
+  product_id: 1,
+  size: 10,
+  side: 'buy',
+  order_type: 'limit_order',
+  limit_price: '50000.0'
+)
+
+# Edit an order
+client.orders.update(
+  id: order[:id],
+  product_id: 1,
+  size: 12,
+  limit_price: '50100.0'
+)
+
+# Cancel an order
+client.orders.cancel(id: order[:id], product_id: 1)
+
+# Cancel all orders
+client.orders.cancel_all(product_id: 1) # Optional product filter
+
+# Batch orders (up to 50 in one call)
+client.orders.create_batch(
+  product_id: 1,
+  orders: [
+    { size: 5, side: 'buy', order_type: 'limit_order', limit_price: '49000.0' },
+    { size: 5, side: 'buy', order_type: 'limit_order', limit_price: '48000.0' }
+  ]
+)
+```
+
+### Positions
+
+Margin and leverage tracking.
+
+```ruby
+# Fetch all active open positions (uses /v2/positions/margined internally)
+positions = client.positions.margined
+
+# Change leverage for an open position
+client.positions.change_leverage(product_id: 1, leverage: "50")
+
+# Adjust margin (add/remove)
+client.positions.adjust_margin(product_id: 1, amount: "100.0", type: "add")
+
+# Close all positions
+client.positions.close_all
+```
+
+### Market Data
+
+Historical and statistical information.
+
+```ruby
+# Get order book (Level 2)
+book = client.market_data.l2_orderbook('BTCUSD')
+
+# Get recent trades
+trades = client.market_data.trades('BTCUSD')
+
+# Get candles (OHLCV)
+candles = client.market_data.candles(
+  product_id: 1,
+  resolution: '1m',
+  start_time: (Time.now - 3600).to_i,
+  end_time: Time.now.to_i
+)
+
+# Get specialized data
+funding = client.market_data.funding_rates(product_id: 1)
+oi = client.market_data.open_interest(product_id: 1)
+```
+
+### Wallet
+
+Account balances and history.
+
+```ruby
+balances = client.wallet.balances
+history = client.wallet.transactions
+deposits = client.wallet.deposits
+withdrawals = client.wallet.withdrawals
+
+# Sub-account balance transfer
+client.wallet.subaccount_transfer(
+  asset_id: 1, # USDT
+  amount: "500.0",
+  sub_account_id: 1234,
+  method: "deposit" # deposit into sub-account
+)
+```
+
+### Account
+
+User-level configuration and statistics.
+
+```ruby
+profile = client.account.profile
+fee_tiers = client.account.fee_tiers
+referrals = client.account.referrals
+client.account.update_trading_preferences(cancel_on_disconnect: true)
+```
+
+## Error Handling
+
+Standardized API and validation errors.
+
+```ruby
+begin
+  client.orders.create(size: 0) # This will fail validation
+rescue DeltaExchange::ValidationError => e
+  puts "Check your inputs: #{e.message}"
+rescue DeltaExchange::RateLimitError => e
+  puts "Slowing down! Retry after #{e.retry_after_seconds}s"
+rescue DeltaExchange::ApiError => e
+  puts "API Error: #{e.message} (Code: #{e.code})"
+end
+```

data/docs/STANDALONE_RUBY_GUIDE.md

@@ -0,0 +1,73 @@
+# Standalone Ruby Script Guide
+
+The DeltaExchange gem can be used in any Ruby environment, from simple CLI scripts to powerful trading bots.
+
+## Script Structure
+
+```ruby
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+# 1. Inline gem dependency (no need for a Gemfile)
+gemfile do
+  source 'https://rubygems.org'
+  gem 'delta_exchange'
+  gem 'dotenv' # for loading credentials from .env
+end
+
+require 'delta_exchange'
+require 'dotenv/load'
+
+# 2. Configure the client
+DeltaExchange.configure do |config|
+  config.api_key = ENV['DELTA_API_KEY']
+  config.api_secret = ENV['DELTA_API_SECRET']
+  config.testnet = true
+end
+
+# 3. Business logic
+def run_trading_loop
+  client = DeltaExchange::Client.new
+  
+  loop do
+    ticker = client.products.ticker('BTCUSD')
+    puts "BTC Price: #{ticker[:last_price]}"
+    
+    # Place your automated trading strategy here...
+    
+    sleep 10 # Wait 10 seconds before next check
+  end
+rescue Interrupt
+  puts "\nStopping bot..."
+end
+
+run_trading_loop
+```
+
+## Running with `.env` file
+
+Create a file named `.env` in the same directory as your script:
+
+```bash
+DELTA_API_KEY=your_actual_key
+DELTA_API_SECRET=your_actual_secret
+DELTA_TESTNET=true
+```
+
+## Using as a CLI Tool
+
+The gem includes a console for interactive use:
+
+```bash
+# From the project root
+bin/console
+```
+
+Once inside, you can interact with the API directly:
+
+```ruby
+irb(main):001> client = DeltaExchange::Client.new
+irb(main):002> client.products.all.first[:symbol]
+=> "BTCUSD"
+```

data/docs/WEBSOCKET_GUIDE.md

@@ -0,0 +1,160 @@
+# WebSocket Guide
+
+DeltaExchange WebSocket API v2 provides real-time streaming for public market data and private user updates.
+
+## Basic Usage
+
+The WebSocket client runs in a background thread using `EventMachine`.
+
+```ruby
+ws = DeltaExchange::Websocket::Client.new
+
+# Handle public updates
+ws.on :message do |data|
+  case data['type']
+  when 'v2/ticker'
+    puts "Price update: #{data['symbol']} is now #{data['last_price']}"
+  when 'l2_updates'
+    puts "Orderbook update for #{data['symbol']}"
+  end
+end
+
+# Handle specific events
+ws.on :open do
+  puts "WebSocket Connected!"
+  
+  # Subscribe to channels
+  ws.subscribe([
+    { name: "v2/ticker", symbols: ["BTCUSD", "ETHUSD"] },
+    { name: "l2_updates", symbols: ["BTCUSD"] }
+  ])
+end
+
+ws.connect!
+
+# Keep the main process alive (only needed for standalone scripts)
+loop { sleep 1 }
+```
+
+## Private Channels
+
+If you provide an `api_key` and `api_secret`, the gem automatically handles authentication upon connection.
+
+```ruby
+# The gem will use global configuration if not passed explicitly
+ws = DeltaExchange::Websocket::Client.new
+
+ws.on :open do
+  # Authenticated! Now subscribe to private data
+  ws.subscribe([
+    { name: "orders" },
+    { name: "positions" },
+    { name: "margins" }
+  ])
+end
+
+ws.on :message do |data|
+  if data['type'] == 'orders'
+    puts "Order status changed! New status: #{data['status']}"
+  end
+end
+
+ws.connect!
+```
+
+## Available Channels
+
+### Public
+- `v2/ticker`: Live price and 24h stats.
+- `l1_orderbook`: Top of the book.
+- `l2_orderbook`: Full order book (snapshot).
+- `l2_updates`: Incremental order book updates.
+- `all_trades`: Live public trade stream.
+- `mark_price`: Current mark price for perpetuals.
+- `candlesticks`: Live OHLCV candle updates.
+- `spot_price`: Current index spot price.
+
+### Private (Auth Required)
+- `orders`: Personal order fill and status updates.
+- `positions`: Personal position change updates.
+- `user_trades`: Personal execution stream.
+- `margins`: Personal margin balance updates.
+
+## Performance Notes
+
+*   **EM Reactor**: The gem starts an EventMachine reactor in a background thread. This means it won't block your main application (like a Rails server).
+*   **JSON Parsing**: Every message is parsed into a Ruby Hash automatically.
+*   **Reconnection**: The gem includes internal logic to attempt reconnection if the socket drops.
+
+## Advanced: Persistence and Caching
+
+In a production trading application, you often need to access the "Last Traded Price" (LTP) from different parts of your application (e.g., a Rails controller or a background job) without maintaining a constant WebSocket connection in every process.
+
+The best practice is to use a centralized store like **Redis** or **Rails Cache**.
+
+### 1. Storing Ticks in Redis
+
+Using Redis allows multiple processes to read the latest price instantly.
+
+```ruby
+require 'redis'
+redis = Redis.new
+
+ws = DeltaExchange::Websocket::Client.new
+
+ws.on :message do |data|
+  if data['type'] == 'v2/ticker'
+    symbol = data['symbol']
+    price = data['last_price']
+    
+    # Store the latest price in Redis with an optional TTL
+    redis.set("delta:ltp:#{symbol}", price)
+    
+    # Optionally store the full tick as JSON
+    redis.set("delta:tick:#{symbol}", data.to_json)
+  end
+end
+
+ws.connect!
+```
+
+### 2. Storing Ticks in Rails Cache
+
+If you are using Rails, you can utilize the built-in cache (which often uses Redis as a backend).
+
+```ruby
+# Inside your WebSocket worker/task
+ws.on :message do |data|
+  if data['type'] == 'v2/ticker'
+    Rails.cache.write("delta_ltp_#{data['symbol']}", data['last_price'])
+  end
+end
+```
+
+### 3. Accessing LTP from a Controller
+
+Once stored, you can access the data from anywhere in your Rails app:
+
+```ruby
+class TradesController < ApplicationController
+  def current_price
+    # Fast read from cache/redis
+    price = Rails.cache.read("delta_ltp_#{params[:symbol]}")
+    
+    render json: { symbol: params[:symbol], price: price }
+  end
+end
+```
+
+### 4. Background Job Pattern
+
+For complex bots, use the WebSocket to trigger background jobs for execution:
+
+```ruby
+ws.on :message do |data|
+  if data['type'] == 'v2/ticker' && data['last_price'].to_f > 60000.0
+    # Trigger a trade job if price threshold met
+    TradeExecutionJob.perform_later('BTCUSD', 'sell', data['last_price'])
+  end
+end
+```

data/exe/delta_exchange

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "delta_exchange"

data/lib/delta_exchange/auth.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module DeltaExchange
+  class Auth
+    def self.sign(method, timestamp, path, query_string, payload, secret)
+      prehash = "#{method.upcase}#{timestamp}#{path}#{query_string}#{payload}"
+      OpenSSL::HMAC.hexdigest("SHA256", secret, prehash)
+    end
+  end
+end

data/lib/delta_exchange/client.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "time"
+require "uri"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/time"
+
+module DeltaExchange
+  class Client
+    attr_reader :root_url, :connection
+
+    def initialize(api_key: nil, api_secret: nil, testnet: nil, base_url: nil)
+      DeltaExchange.ensure_configuration!
+      config = DeltaExchange.configuration
+      @api_key = api_key || config.api_key
+      @api_secret = api_secret || config.api_secret
+      @testnet = testnet.nil? ? config.testnet : testnet
+      @root_url = resolve_root_url(config, base_url)
+      @connection = build_connection(@root_url, config)
+    end
+
+    def rebuild_connection!
+      config = DeltaExchange.configuration
+      @connection = build_connection(@root_url, config)
+    end
+
+    def request(method, path, payload = {}, params = {}, authenticate: true)
+      ensure_credentials!(authenticate)
+      timestamp = Time.now.utc.to_i.to_s
+      query_string = params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+      body = payload.empty? ? "" : payload.to_json
+
+      headers = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => DeltaExchange.configuration.user_agent
+      }
+
+      if authenticate
+        headers["api-key"] = @api_key
+        headers["timestamp"] = timestamp
+        headers["signature"] = Auth.sign(method, timestamp, path, query_string, body, @api_secret)
+      end
+
+      response = @connection.send(method) do |req|
+        req.url "#{path}#{query_string}"
+        req.headers.merge!(headers)
+        req.body = body unless body.empty?
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise(NetworkError.new(e.message).tap { |err| err.set_backtrace(e.backtrace) })
+    rescue Faraday::Error => e
+      raise(NetworkError.new("Faraday error: #{e.message}").tap { |err| err.set_backtrace(e.backtrace) })
+    end
+
+    def get(path, params = {}, authenticate: true)
+      request(:get, path, {}, params, authenticate: authenticate)
+    end
+
+    def post(path, payload = {}, authenticate: true)
+      request(:post, path, payload, {}, authenticate: authenticate)
+    end
+
+    def put(path, payload = {}, authenticate: true)
+      request(:put, path, payload, {}, authenticate: authenticate)
+    end
+
+    def patch(path, payload = {}, authenticate: true)
+      request(:patch, path, payload, {}, authenticate: authenticate)
+    end
+
+    def delete(path, payload = {}, params = {}, authenticate: true)
+      request(:delete, path, payload, params, authenticate: authenticate)
+    end
+
+    def products
+      @products ||= Resources::Products.new(self)
+    end
+
+    def orders
+      @orders ||= Resources::Orders.new(self)
+    end
+
+    def positions
+      @positions ||= Resources::Positions.new(self)
+    end
+
+    def account
+      @account ||= Resources::Account.new(self)
+    end
+
+    def wallet
+      @wallet ||= Resources::Wallet.new(self)
+    end
+
+    def assets
+      @assets ||= Resources::Assets.new(self)
+    end
+
+    def indices
+      @indices ||= Resources::Indices.new(self)
+    end
+
+    def fills
+      @fills ||= Resources::Fills.new(self)
+    end
+
+    def market_data
+      @market_data ||= Resources::MarketData.new(self)
+    end
+
+    def heartbeat
+      @heartbeat ||= Resources::Heartbeat.new(self)
+    end
+
+    private
+
+    def ensure_credentials!(authenticate)
+      return unless authenticate
+
+      return if @api_key.present? && @api_secret.present?
+
+      raise DeltaExchange::AuthenticationError, "api_key and api_secret are required for authenticated requests"
+    end
+
+    def resolve_root_url(config, explicit_base_url)
+      return explicit_base_url if explicit_base_url.present?
+
+      base = config.instance_variable_get(:@base_url)
+      return base if base.present?
+
+      @testnet ? DeltaExchange::Configuration::TESTNET_URL : DeltaExchange::Configuration::PRODUCTION_URL
+    end
+
+    def build_connection(url, config)
+      Faraday.new(url: url) do |f|
+        f.request :url_encoded
+        if ENV["DELTA_DEBUG"] == "true"
+          f.response :logger, DeltaExchange.logger, headers: { redact: ["api-key", "signature"] }, bodies: false
+        end
+        f.options.timeout = config.read_timeout
+        f.options.open_timeout = config.connect_timeout
+        f.options.write_timeout = config.write_timeout if f.options.respond_to?(:write_timeout=)
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      body_str = response.body.to_s
+
+      if response.status == 429
+        retry_after = response.headers["X-RATE-LIMIT-RESET"]&.to_i
+        raise DeltaExchange::RateLimitError.new(
+          "Rate limited",
+          retry_after_seconds: retry_after,
+          response_body: parse_json_optional(body_str)
+        )
+      end
+
+      if body_str.blank?
+        raise DeltaExchange::Error, "API returned empty body (HTTP #{response.status})" unless response.success?
+
+        return {}.with_indifferent_access
+      end
+
+      parsed_response = JSON.parse(body_str).with_indifferent_access
+
+      return parsed_response if http_ok_without_api_failure?(response, parsed_response)
+
+      raise DeltaExchange::ApiError.from_hash(parsed_response, status: response.status)
+    rescue JSON::ParserError
+      raise DeltaExchange::Error, "API returned non-JSON response (HTTP #{response.status}): #{body_str[0, 500]}"
+    end
+
+    def parse_json_optional(raw)
+      return {}.with_indifferent_access if raw.blank?
+
+      JSON.parse(raw).with_indifferent_access
+    rescue JSON::ParserError
+      { "raw" => raw }.with_indifferent_access
+    end
+
+    def http_ok_without_api_failure?(response, parsed_response)
+      return false unless response.success?
+
+      return parsed_response[:success] != false if parsed_response.key?(:success)
+
+      true
+    end
+  end
+end

data/lib/delta_exchange/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DeltaExchange
+  class Configuration
+    PRODUCTION_URL = Constants::Urls::REST_PRODUCTION
+    TESTNET_URL = Constants::Urls::REST_TESTNET
+    DEFAULT_CONNECT_TIMEOUT = 10
+    DEFAULT_READ_TIMEOUT = 30
+    DEFAULT_WRITE_TIMEOUT = 30
+
+    attr_accessor :api_key, :api_secret, :testnet, :connect_timeout, :read_timeout, :write_timeout, :user_agent, :websocket_reconnect_delay, :time_zone, :auto_retry_rate_limit
+
+    # When set, used as the REST base URL instead of {PRODUCTION_URL} / {TESTNET_URL}.
+    attr_writer :base_url
+
+    def initialize
+      @api_key = ENV.fetch("DELTA_API_KEY", nil)
+      @api_secret = ENV.fetch("DELTA_API_SECRET", nil)
+      @testnet = ENV.fetch("DELTA_TESTNET", "false").to_s.casecmp("true").zero?
+      @base_url = nil
+      @connect_timeout = ENV.fetch("DELTA_CONNECT_TIMEOUT", DEFAULT_CONNECT_TIMEOUT).to_i
+      @read_timeout = ENV.fetch("DELTA_READ_TIMEOUT", DEFAULT_READ_TIMEOUT).to_i
+      @write_timeout = ENV.fetch("DELTA_WRITE_TIMEOUT", DEFAULT_WRITE_TIMEOUT).to_i
+      @user_agent = ENV.fetch("DELTA_USER_AGENT", "delta-exchange-ruby")
+      @websocket_reconnect_delay = ENV.fetch("DELTA_WS_RECONNECT_DELAY", 5).to_i
+      @time_zone = ENV.fetch("DELTA_TIME_ZONE", "UTC")
+      @auto_retry_rate_limit = ENV.fetch("DELTA_AUTO_RETRY_RATE_LIMIT", "false").to_s.casecmp("true").zero?
+    end
+
+    def base_url
+      return @base_url if @base_url
+
+      testnet? ? TESTNET_URL : PRODUCTION_URL
+    end
+
+    def testnet?
+      @testnet == true
+    end
+  end
+end

data/lib/delta_exchange/constants.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DeltaExchange
+  module Constants
+    module Urls
+      REST_PRODUCTION = "https://api.india.delta.exchange"
+      REST_TESTNET = "https://cdn-ind.testnet.deltaex.org"
+      WEBSOCKET_PRODUCTION = "wss://socket.india.delta.exchange"
+      WEBSOCKET_TESTNET = "wss://socket.testnet.deltaex.org"
+    end
+
+    module ContractType
+      PERPETUAL_FUTURES = "perpetual_futures"
+      CALL_OPTIONS = "call_options"
+      PUT_OPTIONS = "put_options"
+      MOVE_OPTIONS = "move_options"
+      SPREADS = "spreads"
+      FUTURES = "futures"
+
+      ALL = [PERPETUAL_FUTURES, CALL_OPTIONS, PUT_OPTIONS, MOVE_OPTIONS, SPREADS, FUTURES].freeze
+    end
+
+    module OrderType
+      LIMIT = "limit_order"
+      MARKET = "market_order"
+      STOP_LIMIT = "stop_limit_order"
+      STOP_MARKET = "stop_market_order"
+
+      ALL = [LIMIT, MARKET, STOP_LIMIT, STOP_MARKET].freeze
+    end
+
+    module Side
+      BUY = "buy"
+      SELL = "sell"
+
+      ALL = [BUY, SELL].freeze
+    end
+
+    module TimeInForce
+      GTC = "gtc"
+      IOC = "ioc"
+      FOK = "fok"
+
+      ALL = [GTC, IOC, FOK].freeze
+    end
+
+    module ProductState
+      UPCOMING = "upcoming"
+      LIVE = "live"
+      EXPIRED = "expired"
+      SETTLED = "settled"
+
+      ALL = [UPCOMING, LIVE, EXPIRED, SETTLED].freeze
+    end
+
+    module OrderState
+      OPEN = "open"
+      PENDING = "pending"
+      CLOSED = "closed"
+      CANCELLED = "cancelled"
+
+      ALL = [OPEN, PENDING, CLOSED, CANCELLED].freeze
+    end
+
+    module MarginMode
+      CROSS = "cross"
+      ISOLATED = "isolated"
+
+      ALL = [CROSS, ISOLATED].freeze
+    end
+  end
+end