coindcx-client 0.1.0

data/README.md

@@ -0,0 +1,224 @@
+# coindcx-client
+
+`coindcx-client` is a CoinDCX-specific Ruby client built from a layered exchange-client architecture rather than a thin wrapper.
+
+## Documentation
+
+- [Docs index](./docs/README.md)
+- [Core usage](./docs/core.md)
+- [Rails integration](./docs/rails_integration.md)
+- [Standalone trading bot](./docs/standalone_bot.md)
+
+## Design goals
+
+- keep transport, auth, resources, models, and websockets separate
+- model CoinDCX namespaces explicitly: public, spot, margin, user, transfers, and futures
+- keep the gem stateless and leave strategy, position tracking, and risk logic to the host app
+- preserve CoinDCX websocket constraints instead of flattening them into a generic websocket abstraction
+- enforce endpoint-aware rate limiting at the transport boundary
+- fail with structured errors that trading code can classify cleanly
+
+## Structure
+
+```
+lib/coindcx.rb
+lib/coindcx/version.rb
+lib/coindcx/configuration.rb
+lib/coindcx/client.rb
+lib/coindcx/transport/
+lib/coindcx/errors/
+lib/coindcx/auth/
+lib/coindcx/rest/
+lib/coindcx/ws/
+lib/coindcx/models/
+lib/coindcx/contracts/
+lib/coindcx/utils/
+docs/
+```
+
+## Installation
+
+```ruby
+gem 'coindcx-client'
+```
+
+For local development:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+```ruby
+require 'logger'
+require 'coindcx'
+
+CoinDCX.configure do |config|
+  config.api_key = ENV.fetch('COINDCX_API_KEY')
+  config.api_secret = ENV.fetch('COINDCX_API_SECRET')
+  config.logger = Logger.new($stdout)
+
+  # HTTP retry tuning
+  config.max_retries = 2
+  config.retry_base_interval = 0.25
+  config.market_data_retry_budget = 2
+  config.private_read_retry_budget = 1
+  config.idempotent_order_retry_budget = 1
+
+  # Socket reconnect tuning
+  config.socket_reconnect_attempts = 5
+  config.socket_reconnect_interval = 1.0
+  config.socket_heartbeat_interval = 10.0
+  config.socket_liveness_timeout = 60.0
+
+  # Critical order-endpoint protection
+  config.circuit_breaker_threshold = 3
+  config.circuit_breaker_cooldown = 30.0
+end
+```
+
+By default the websocket layer uses `socket.io-client-simple`. You can still override the backend with `socket_io_backend_factory` when you need a custom adapter.
+
+## REST usage
+
+```ruby
+client = CoinDCX.client
+
+client.public.market_data.list_tickers
+client.public.market_data.list_market_details
+client.public.market_data.list_trades(pair: 'B-BTC_USDT', limit: 50)
+
+client.spot.orders.create(
+  side: 'buy',
+  order_type: 'limit_order',
+  market: 'SNTBTC',
+  price_per_unit: '0.03244',
+  total_quantity: 400,
+  client_order_id: SecureRandom.uuid
+)
+
+client.user.accounts.list_balances
+client.transfers.wallets.transfer(
+  source_wallet_type: 'spot',
+  destination_wallet_type: 'futures',
+  currency_short_name: 'USDT',
+  amount: 1
+)
+
+client.futures.market_data.list_active_instruments(margin_currency_short_names: ['USDT'])
+client.futures.market_data.fetch_instrument(pair: 'B-BTC_USDT', margin_currency_short_name: 'USDT')
+client.futures.market_data.current_prices
+client.futures.market_data.stats(pair: 'B-BTC_USDT')
+client.futures.market_data.conversions
+client.futures.orders.list(status: 'open', margin_currency_short_name: ['USDT'])
+client.futures.orders.list_trades(page: 1, size: 50)
+
+client.funding.orders.list
+client.funding.orders.lend(currency_short_name: 'USDT', amount: '10')
+client.funding.orders.settle(id: 'funding-order-id')
+```
+
+## Websocket usage
+
+CoinDCX documents Socket.io for websocket access. This gem keeps that boundary explicit and now tracks connection state, heartbeat liveness, private auth renewal, and subscription replay after reconnects.
+
+Socket.IO often delivers **multiple data arguments** after the event name (for example a channel string plus the quote object). The client **coalesces** those into a single Hash (merging multiple Hash frames) before invoking your block, so handlers always see one payload object.
+
+Live streams frequently wrap quotes as `{ "event" => "price-change", "data" => "<JSON string>" }`. The client **parses** that `data` string and **merges** the inner object to the top level before dispatch, so fields like `p` and `s` are directly on the hash passed to your block.
+
+**Fan-out:** one underlying listener is registered per `event_name` (for example all `price-change` subscriptions share it). Every handler for that event runs on **every** message. For multiple instruments, filter using payload hints such as `s`, `pair`, or `market` (see `scripts/futures_ws_subscription_smoke.rb`).
+
+```ruby
+client = CoinDCX.client
+prices_channel = CoinDCX::WS::PublicChannels.price_stats(pair: 'B-BTC_USDT')
+
+client.ws.connect
+client.ws.subscribe_public(channel_name: prices_channel, event_name: 'price-change') do |payload|
+  puts payload
+end
+```
+
+## Trading safety rules
+
+- Always supply `client_order_id` when placing orders. The gem will not retry mutable order creation without it.
+- Persist `client_order_id` in your host application so a timeout can be reconciled safely.
+- Order create and transfer requests validate required fields before sending them to CoinDCX.
+- WebSocket subscriptions are replayed automatically after reconnect, and private subscriptions rebuild auth payloads on every reconnect.
+- WebSocket delivery is `at_least_once`. Consumers must tolerate duplicates after reconnect.
+- The gem does not guarantee lossless recovery of events missed while CoinDCX was disconnected.
+
+Private subscriptions use the documented `coindcx` channel signing flow:
+
+```ruby
+client.ws.subscribe_private(event_name: CoinDCX::WS::PrivateChannels::ORDER_UPDATE_EVENT) do |payload|
+  puts payload
+end
+```
+
+## Error handling
+
+The transport raises structured errors so calling code can branch intentionally without parsing strings:
+
+- `CoinDCX::Errors::AuthError`
+- `CoinDCX::Errors::RateLimitError`
+- `CoinDCX::Errors::RetryableRateLimitError`
+- `CoinDCX::Errors::RemoteValidationError`
+- `CoinDCX::Errors::UpstreamServerError`
+- `CoinDCX::Errors::TransportError`
+- `CoinDCX::Errors::CircuitOpenError`
+- `CoinDCX::Errors::RequestError`
+- `CoinDCX::Errors::SocketConnectionError`
+- `CoinDCX::Errors::SocketAuthenticationError`
+- `CoinDCX::Errors::SocketStateError`
+
+Every API error exposes normalized metadata through `status`, `category`, `code`, `request_context`, and `retryable`.
+
+## Rate limiting
+
+`CoinDCX::Configuration` ships with named buckets for authenticated endpoint families and enforces them before the request is sent.
+
+Read and write paths are separated so market data traffic does not consume order-placement capacity. Private endpoints require an explicit bucket definition.
+
+Spot order buckets include:
+
+- `spot_create_order_multiple`
+- `spot_create_order`
+- `spot_cancel_all`
+- `spot_order_status_multiple`
+- `spot_order_status`
+- `spot_cancel_multiple_by_id`
+- `spot_cancel_order`
+- `spot_active_order`
+- `spot_active_order_count`
+- `spot_trade_history`
+- `spot_edit_price`
+
+Additional private endpoint families ship with conservative defaults until exchange-specific limits are confirmed.
+
+## Stateless boundary
+
+This gem is intentionally limited to:
+
+- API calls
+- signing
+- socket connection management
+- lightweight parsing and typed facades
+
+This gem intentionally does **not** own:
+
+- position tracking
+- order lifecycle orchestration outside the API response shape
+- strategy logic
+- risk management
+- application caching
+- persistence of idempotency keys
+- reconciliation of missed websocket events after downtime
+
+## Notes
+
+- spot market data stays under `rest/public`
+- futures market data lives under `rest/futures`, even when it uses public hosts
+- websocket order book parsing is snapshot-oriented and preserves CoinDCX's "up to 50 recent orders" constraint
+- the websocket layer uses Socket.io and does not masquerade as a plain websocket client
+- release tags are expected to be immutable once published

data/bin/console

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# IRB with CoinDCX loaded and configured from ENV (and optional repo-root .env).
+#
+#   bundle exec bin/console
+#
+# Typical ENV: COINDCX_API_KEY, COINDCX_API_SECRET
+# Optional: COINDCX_API_BASE_URL, COINDCX_PUBLIC_BASE_URL, COINDCX_SOCKET_BASE_URL
+
+require "bundler/setup"
+require_relative "../lib/coindcx"
+
+# Socket.IO delivers events on the WebSocket thread; IRB often delays plain puts until you press Enter.
+$stdout.sync = true
+$stderr.sync = true
+
+root = File.expand_path("..", __dir__)
+env_path = File.join(root, ".env")
+if File.file?(env_path)
+  File.foreach(env_path) do |line|
+    line = line.strip
+    next if line.empty? || line.start_with?("#")
+
+    key, _, value = line.partition("=")
+    next if key.empty?
+
+    ENV[key.strip] = value.strip.gsub(/\A["']|["']\z/, "")
+  end
+  warn "Loaded #{env_path}"
+end
+
+CoinDCX.configure do |config|
+  config.api_key = ENV.fetch("COINDCX_API_KEY", nil)
+  config.api_secret = ENV.fetch("COINDCX_API_SECRET", nil)
+  unless (v = ENV["COINDCX_API_BASE_URL"].to_s.strip).empty?
+    config.api_base_url = v
+  end
+  unless (v = ENV["COINDCX_PUBLIC_BASE_URL"].to_s.strip).empty?
+    config.public_base_url = v
+  end
+  unless (v = ENV["COINDCX_SOCKET_BASE_URL"].to_s.strip).empty?
+    config.socket_base_url = v
+  end
+end
+
+client = CoinDCX.client
+
+warn <<~BANNER
+  CoinDCX ready — locals: client, client.ws, CoinDCX.configuration
+  WebSocket: use warn(...) inside subscribe blocks (not only puts), then client.ws.connect last.
+  Spot smoke (liquid pair):
+    pc = CoinDCX::WS::PublicChannels
+    client.ws.subscribe_public(channel_name: pc.price_stats(pair: "B-BTC_USDT"), event_name: "price-change") { |p| warn(p.inspect) }
+    client.ws.connect
+  If you see a Hash with a "data" key (like the JS docs), print p["data"] || p
+BANNER
+
+binding.irb # rubocop:disable Lint/Debugger -- interactive entry point

data/docs/README.md

@@ -0,0 +1,29 @@
+# CoinDCX Ruby Client
+
+Production-grade Ruby client for CoinDCX REST + Socket.io APIs.
+
+## Docs
+
+- [Core Usage](./core.md)
+- [Rails Integration](./rails_integration.md)
+- [Standalone Trading Bot](./standalone_bot.md)
+
+## Philosophy
+
+- Stateless client
+- No trading logic
+- Deterministic execution
+- Event-driven compatible
+
+## Notes
+
+These docs use the current implemented `CoinDCX` namespace and API surface from this repository.
+Application-level concerns like `EventBus`, position tracking, caching, and exit logic remain outside the gem.
+
+### Runtime contract
+
+- REST requests are validated locally before serialization when the gem knows the required boundary rules.
+- Mutable order endpoints are never auto-retried unless the caller supplies an idempotency key such as `client_order_id`.
+- WebSocket delivery is at-least-once across reconnects. Consumers must tolerate duplicate events.
+- Public and private subscriptions are replayed after reconnect. Private subscriptions regenerate auth payloads on every reconnect.
+- The gem does not guarantee durable event replay from CoinDCX. If the socket dies, missed events during downtime are the host app's responsibility.

data/docs/coindcx_docs_gaps.md

@@ -0,0 +1,3 @@
+# CoinDCX Docs Coverage Gaps (REST + WebSocket)
+
+- None identified on audit date **2026-04-10** against `https://docs.coindcx.com/?javascript`.

data/docs/core.md

@@ -0,0 +1,179 @@
+# Core Usage
+
+## 1. Initialization
+
+```ruby
+require 'logger'
+require 'coindcx'
+require 'securerandom'
+
+CoinDCX.configure do |config|
+  config.api_key = ENV.fetch('COINDCX_API_KEY')
+  config.api_secret = ENV.fetch('COINDCX_API_SECRET')
+  config.logger = Logger.new($stdout)
+  config.max_retries = 2
+  config.retry_base_interval = 0.25
+  config.socket_reconnect_attempts = 3
+  config.socket_reconnect_interval = 1.0
+  config.socket_heartbeat_interval = 10.0
+  config.socket_liveness_timeout = 60.0
+end
+
+client = CoinDCX.client
+```
+
+## 2. Public APIs
+
+```ruby
+tickers = client.public.market_data.list_tickers
+markets = client.public.market_data.list_markets
+market_details = client.public.market_data.list_market_details
+candles = client.public.market_data.list_candles(pair: 'B-BTC_USDT', interval: '1m')
+order_book = client.public.market_data.fetch_order_book(pair: 'B-BTC_USDT')
+trades = client.public.market_data.list_trades(pair: 'B-BTC_USDT', limit: 50)
+```
+
+## 3. Private APIs
+
+### Spot orders
+
+```ruby
+order = client.spot.orders.create(
+  side: 'buy',
+  order_type: 'limit_order',
+  market: 'SNTBTC',
+  price_per_unit: '0.03244',
+  total_quantity: 400,
+  client_order_id: SecureRandom.uuid
+)
+```
+
+### Balances and account info
+
+```ruby
+balances = client.user.accounts.list_balances
+info = client.user.accounts.fetch_info
+```
+
+### Wallet transfers
+
+```ruby
+transfer = client.transfers.wallets.transfer(
+  source_wallet_type: 'spot',
+  destination_wallet_type: 'futures',
+  currency_short_name: 'USDT',
+  amount: 1
+)
+```
+
+## 4. Futures APIs
+
+```ruby
+active_instruments = client.futures.market_data.list_active_instruments(
+  margin_currency_short_names: ['USDT']
+)
+
+instrument = client.futures.market_data.fetch_instrument(
+  pair: 'B-BTC_USDT',
+  margin_currency_short_name: 'USDT'
+)
+
+futures_order_book = client.futures.market_data.fetch_order_book(
+  instrument: 'B-BTC_USDT',
+  depth: 50
+)
+
+positions = client.futures.positions.list
+```
+
+## 5. WebSocket Usage
+
+```ruby
+ws = client.ws
+channel = CoinDCX::WS::PublicChannels.price_stats(pair: 'B-BTC_USDT')
+
+ws.connect
+
+ws.subscribe_public(channel_name: channel, event_name: 'price-change') do |data|
+  puts data
+end
+```
+
+To exercise **all documented Spot** public streams (and private `coindcx` events when `COINDCX_API_KEY` / `COINDCX_API_SECRET` are set), run from the repo root:
+
+```bash
+bundle exec ruby scripts/spot_sockets_smoke.rb
+```
+
+See the script header for `COINDCX_PAIR`, candle interval, order book depth, and throttling options.
+
+**Futures** streams use the same client and `coindcx` private channel; builders live on `CoinDCX::WS::PublicChannels` (`futures_candlestick`, `futures_order_book`, `futures_ltp`, `futures_new_trade`, `current_prices_futures`) and private event names `DF_POSITION_UPDATE_EVENT`, `DF_ORDER_UPDATE_EVENT`, plus shared `BALANCE_UPDATE_EVENT`. Run:
+
+```bash
+bundle exec ruby scripts/futures_sockets_smoke.rb
+```
+
+Use `scripts/futures_stream_eth_sol.rb` or `scripts/futures_ws_subscription_smoke.rb` for narrower checks.
+
+The websocket client guarantees:
+
+- bounded reconnect attempts with exponential backoff
+- liveness checks for quiet streams
+- automatic replay of subscription intent after reconnect
+- at-least-once event delivery semantics after reconnect
+
+The websocket client does **not** guarantee:
+
+- gap-free market data during disconnect windows
+- exactly-once event delivery
+- application-level deduplication
+
+### Private stream usage
+
+```ruby
+ws.subscribe_private(
+  event_name: CoinDCX::WS::PrivateChannels::ORDER_UPDATE_EVENT
+) do |data|
+  puts data
+end
+```
+
+## 6. Error Handling
+
+```ruby
+begin
+  client.spot.orders.create(
+    side: 'buy',
+    order_type: 'limit_order',
+    market: 'SNTBTC',
+    price_per_unit: '0.03244',
+    total_quantity: 400,
+    client_order_id: SecureRandom.uuid
+  )
+rescue CoinDCX::Errors::AuthError => e
+  warn("authentication failed: #{e.message}")
+rescue CoinDCX::Errors::RateLimitError => e
+  warn("rate limited: #{e.message}")
+rescue CoinDCX::Errors::RetryableRateLimitError => e
+  warn("rate limited, retryable: #{e.retryable}")
+rescue CoinDCX::Errors::UpstreamServerError => e
+  warn("upstream failure: #{e.body[:error][:category]}")
+rescue CoinDCX::Errors::RequestError => e
+  warn("request failed: #{e.message}")
+end
+```
+
+Every raised API error exposes:
+
+- `category`
+- `code`
+- `retryable`
+- `request_context`
+- normalized `body[:error]`
+
+## 7. Critical Rules
+
+- Keep the gem as an API client only
+- Keep strategy, risk, and position tracking in your app
+- Prefer websocket feeds over polling when CoinDCX provides them
+- Route all authenticated calls through the provided resource classes, not ad-hoc HTTP code

data/docs/rails_integration.md

@@ -0,0 +1,151 @@
+# Rails Integration
+
+## Architecture
+
+```
+CoinDCX Gem -> Adapter Layer -> AlgoTradingApi -> Strategy -> Execution
+```
+
+## 1. Initializer
+
+```ruby
+# config/initializers/coindcx.rb
+CoinDCX.configure do |config|
+  config.api_key = ENV.fetch('COINDCX_API_KEY')
+  config.api_secret = ENV.fetch('COINDCX_API_SECRET')
+  config.logger = Rails.logger
+  config.max_retries = 2
+  config.retry_base_interval = 0.25
+  config.socket_reconnect_attempts = 3
+  config.socket_reconnect_interval = 1.0
+end
+
+COINDCX_CLIENT = CoinDCX.client
+```
+
+## 2. Adapter Layer (MANDATORY)
+
+Do **not** call the gem directly from controllers, jobs, or domain services.
+
+```ruby
+# app/services/brokers/coindcx/client.rb
+module Brokers
+  module Coindcx
+    class Client
+      def initialize(client: COINDCX_CLIENT)
+        @client = client
+      end
+
+      def place_limit_buy(market:, price_per_unit:, total_quantity:)
+        @client.spot.orders.create(
+          side: 'buy',
+          order_type: 'limit_order',
+          market: market,
+          price_per_unit: price_per_unit,
+          total_quantity: total_quantity,
+          client_order_id: SecureRandom.uuid
+        )
+      end
+
+      def fetch_ltp(market:)
+        @client.public.market_data.list_tickers.find { |ticker| ticker.market == market }
+      end
+
+      def balances
+        @client.user.accounts.list_balances
+      end
+    end
+  end
+end
+```
+
+## 3. WebSocket -> Event System
+
+Replace a polling-first flow with an event-driven flow:
+
+```
+CoinDCX WS -> EventBus -> Positions::Manager -> Exit Engine
+```
+
+The gem does not ship an `EventBus`; keep it in the Rails app.
+
+```ruby
+# config/initializers/event_bus.rb
+module EventBus
+  @listeners = Hash.new { |hash, key| hash[key] = [] }
+
+  class << self
+    def subscribe(event, &block)
+      @listeners[event] << block
+    end
+
+    def publish(event, payload)
+      @listeners[event].each { |listener| listener.call(payload) }
+    end
+  end
+end
+```
+
+```ruby
+# config/initializers/coindcx_ws.rb
+Thread.new do
+  ws = COINDCX_CLIENT.ws
+  channel = CoinDCX::WS::PublicChannels.price_stats(pair: 'B-BTC_USDT')
+
+  ws.connect
+  ws.subscribe_public(channel_name: channel, event_name: 'price-change') do |data|
+    EventBus.publish(:ltp_update, data)
+  end
+end
+```
+
+## 4. LTP Cache (CRITICAL)
+
+```ruby
+# app/services/positions/ltp_cache.rb
+module Positions
+  class LtpCache
+    def self.update(symbol, price)
+      Rails.cache.write("ltp:#{symbol}", price)
+    end
+
+    def self.get(symbol)
+      Rails.cache.read("ltp:#{symbol}")
+    end
+  end
+end
+```
+
+```ruby
+EventBus.subscribe(:ltp_update) do |payload|
+  symbol = payload.fetch('s', 'UNKNOWN')
+  price = payload.fetch('p', payload['last_price'])
+  Positions::LtpCache.update(symbol, price)
+end
+```
+
+## 5. Risk Manager Integration
+
+```ruby
+ltp = Positions::LtpCache.get(symbol)
+
+if ltp && ltp <= stop_loss
+  exit_position
+end
+```
+
+## 6. Order Execution Flow
+
+```
+Signal -> Adapter -> CoinDCX -> Order ID -> Track -> WS updates -> Exit
+```
+
+## 7. Critical Rules
+
+- Never call the gem directly from controllers
+- Always go through the adapter layer
+- Send websocket events into your app event bus
+- Prefer websocket market data over polling when available
+- Keep all strategy and risk logic in Rails, not in the gem
+- Persist `client_order_id` in your Rails app before calling create-order endpoints
+- Treat websocket events as at-least-once delivery and deduplicate in the app if needed