Module: DhanHQ

Defined in:
lib/dhan_hq.rb,
lib/DhanHQ/ws.rb,
lib/DhanHQ/auth.rb,
lib/DhanHQ/client.rb,
lib/DhanHQ/errors.rb,
lib/DhanHQ/version.rb,
lib/DhanHQ/constants.rb,
lib/DhanHQ/ws/client.rb,
lib/DhanHQ/ws/orders.rb,
lib/DhanHQ/ws/cmd_bus.rb,
lib/DhanHQ/ws/decoder.rb,
lib/DhanHQ/json_loader.rb,
lib/DhanHQ/models/edis.rb,
lib/DhanHQ/ws/registry.rb,
lib/DhanHQ/ws/segments.rb,
lib/DhanHQ/error_object.rb,
lib/DhanHQ/models/funds.rb,
lib/DhanHQ/models/order.rb,
lib/DhanHQ/models/trade.rb,
lib/DhanHQ/rate_limiter.rb,
lib/DhanHQ/ws/sub_state.rb,
lib/DhanHQ/configuration.rb,
lib/DhanHQ/core/auth_api.rb,
lib/DhanHQ/core/base_api.rb,
lib/DhanHQ/models/margin.rb,
lib/DhanHQ/ws/connection.rb,
lib/DhanHQ/models/holding.rb,
lib/DhanHQ/models/profile.rb,
lib/DhanHQ/resources/edis.rb,
lib/DhanHQ/core/base_model.rb,
lib/DhanHQ/models/pnl_exit.rb,
lib/DhanHQ/models/position.rb,
lib/DhanHQ/models/postback.rb,
lib/DhanHQ/resources/funds.rb,
lib/DhanHQ/ws/market_depth.rb,
lib/DhanHQ/resources/orders.rb,
lib/DhanHQ/resources/trades.rb,
lib/DhanHQ/ws/orders/client.rb,
lib/DhanHQ/models/instrument.rb,
lib/DhanHQ/resources/profile.rb,
lib/DhanHQ/ws/packets/header.rb,
lib/DhanHQ/ws/singleton_lock.rb,
lib/DhanHQ/auth/token_manager.rb,
lib/DhanHQ/auth/token_renewal.rb,
lib/DhanHQ/core/base_resource.rb,
lib/DhanHQ/core/error_handler.rb,
lib/DhanHQ/helpers/api_helper.rb,
lib/DhanHQ/models/alert_order.rb,
lib/DhanHQ/models/kill_switch.rb,
lib/DhanHQ/models/market_feed.rb,
lib/DhanHQ/models/super_order.rb,
lib/DhanHQ/resources/holdings.rb,
lib/DhanHQ/resources/ip_setup.rb,
lib/DhanHQ/resources/pnl_exit.rb,
lib/DhanHQ/ws/base_connection.rb,
lib/DhanHQ/models/ledger_entry.rb,
lib/DhanHQ/models/option_chain.rb,
lib/DhanHQ/models/order_update.rb,
lib/DhanHQ/resources/positions.rb,
lib/DhanHQ/auth/token_generator.rb,
lib/DhanHQ/concerns/order_audit.rb,
lib/DhanHQ/helpers/model_helper.rb,
lib/DhanHQ/models/forever_order.rb,
lib/DhanHQ/resources/statements.rb,
lib/DhanHQ/ws/orders/connection.rb,
lib/DhanHQ/ws/packets/oi_packet.rb,
lib/DhanHQ/models/token_response.rb,
lib/DhanHQ/resources/instruments.rb,
lib/DhanHQ/resources/kill_switch.rb,
lib/DhanHQ/resources/market_feed.rb,
lib/DhanHQ/helpers/request_helper.rb,
lib/DhanHQ/models/historical_data.rb,
lib/DhanHQ/resources/alert_orders.rb,
lib/DhanHQ/resources/option_chain.rb,
lib/DhanHQ/resources/super_orders.rb,
lib/DhanHQ/ws/market_depth/client.rb,
lib/DhanHQ/ws/packets/full_packet.rb,
lib/DhanHQ/contracts/base_contract.rb,
lib/DhanHQ/contracts/edis_contract.rb,
lib/DhanHQ/helpers/response_helper.rb,
lib/DhanHQ/utils/network_inspector.rb,
lib/DhanHQ/ws/market_depth/decoder.rb,
lib/DhanHQ/ws/packets/index_packet.rb,
lib/DhanHQ/ws/packets/quote_packet.rb,
lib/DhanHQ/contracts/order_contract.rb,
lib/DhanHQ/contracts/trade_contract.rb,
lib/DhanHQ/helpers/attribute_helper.rb,
lib/DhanHQ/resources/forever_orders.rb,
lib/DhanHQ/resources/trader_control.rb,
lib/DhanHQ/ws/packets/ticker_packet.rb,
lib/DhanHQ/helpers/validation_helper.rb,
lib/DhanHQ/models/instrument_helpers.rb,
lib/DhanHQ/resources/historical_data.rb,
lib/DhanHQ/contracts/user_ip_contract.rb,
lib/DhanHQ/ws/websocket_packet_parser.rb,
lib/DhanHQ/models/expired_options_data.rb,
lib/DhanHQ/resources/margin_calculator.rb,
lib/DhanHQ/ws/packets/disconnect_packet.rb,
lib/DhanHQ/ws/packets/prev_close_packet.rb,
lib/DhanHQ/ws/packets/depth_delta_packet.rb,
lib/DhanHQ/ws/packets/market_depth_level.rb,
lib/DhanHQ/contracts/alert_order_contract.rb,
lib/DhanHQ/contracts/market_feed_contract.rb,
lib/DhanHQ/contracts/place_order_contract.rb,
lib/DhanHQ/contracts/slice_order_contract.rb,
lib/DhanHQ/resources/expired_options_data.rb,
lib/DhanHQ/contracts/modify_order_contract.rb,
lib/DhanHQ/contracts/option_chain_contract.rb,
lib/DhanHQ/ws/packets/market_status_packet.rb,
lib/dhanhq/analysis/options_buying_advisor.rb,
lib/DhanHQ/contracts/forever_order_contract.rb,
lib/DhanHQ/contracts/trade_history_contract.rb,
lib/dhanhq/analysis/helpers/bias_aggregator.rb,
lib/DhanHQ/contracts/pnl_based_exit_contract.rb,
lib/dhanhq/analysis/helpers/moneyness_helper.rb,
lib/dhanhq/analysis/multi_timeframe_analyzer.rb,
lib/DhanHQ/contracts/historical_data_contract.rb,
lib/DhanHQ/contracts/instrument_list_contract.rb,
lib/DhanHQ/contracts/margin_calculator_contract.rb,
lib/DhanHQ/contracts/trade_by_order_id_contract.rb,
lib/DhanHQ/models/concerns/api_response_handler.rb,
lib/DhanHQ/contracts/position_conversion_contract.rb,
lib/DhanHQ/contracts/expired_options_data_contract.rb,
lib/dhanhq/contracts/options_buying_advisor_contract.rb,
lib/DhanHQ/contracts/intraday_historical_data_contract.rb,
lib/DhanHQ/contracts/multi_scrip_margin_calc_request_contract.rb

Overview

The top-level module for the DhanHQ client library.

Provides configuration management for setting credentials and API-related settings.

Defined Under Namespace

Modules: APIHelper, Analysis, AttributeHelper, Auth, Concerns, Constants, Contracts, JSONLoader, ModelHelper, Models, RequestHelper, Resources, ResponseHelper, Utils, ValidationHelper, WS Classes: AuthAPI, AuthenticationError, AuthenticationFailedError, BaseAPI, BaseModel, BaseResource, Client, Configuration, DataError, Error, ErrorHandler, ErrorObject, InputExceptionError, InternalServerError, InvalidAccessError, InvalidAuthenticationError, InvalidClientIDError, InvalidRequestError, InvalidTokenError, LiveTradingDisabledError, ModificationLimitError, NetworkError, NoHoldingsError, NotFoundError, OrderError, OtherError, RateLimitError, RateLimiter, TokenEndpointError, TokenExpiredError, UserAccountError, ValidationError

Constant Summary collapse

LOADER = 
Zeitwerk::Loader.new
BASE_URL =

Default REST API host used when no custom base URL is provided.

Returns:

  • (String) 
Constants::Urls::REST_API_BASE
VERSION =

Semantic version of the DhanHQ client gem.

"3.0.0"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.configuration ⇒ DhanHQ::Configuration?

The current configuration instance.

Returns:



55
56
57
 
# File 'lib/dhan_hq.rb', line 55

def configuration
  @configuration
end

.logger ⇒ Logger

default logger so calls like DhanHQ.logger&.info never explode Accessor for the logger instance used by the SDK.

Returns:

  • (Logger) —

    The configured logger, defaulting to STDOUT at INFO level.



79
80
81
 
# File 'lib/dhan_hq.rb', line 79

def logger
  @logger ||= Logger.new($stdout, level: Logger::INFO)
end

Class Method Details

.configure {|configuration| ... } ⇒ void

This method returns an undefined value.

Configures the DhanHQ client with user-defined settings.

Examples:

DhanHQ.configure do |config|
  config.access_token = 'your_access_token'
  config.client_id = 'your_client_id'
end

Yield Parameters:



69
70
71
72
73
 
# File 'lib/dhan_hq.rb', line 69

def configure
  self.configuration ||= Configuration.new
  yield(configuration)
  self.logger ||= Logger.new($stdout, level: Logger::INFO)
end

.configure_from_token_endpoint(base_url: nil, bearer_token: nil) ⇒ DhanHQ::Configuration

Configures the DhanHQ client by fetching credentials from a token endpoint.

Performs GET <base_url>/auth/dhan/token with Authorization: Bearer <bearer_token>. Expects JSON with at least access_token and client_id. Optional base_url in the response overrides the Dhan API base URL.

Examples:

Explicit

DhanHQ.configure_from_token_endpoint(base_url: "https://myapp.com", bearer_token: "secret-token")

From ENV (DHAN_TOKEN_ENDPOINT_BASE_URL and DHAN_TOKEN_ENDPOINT_BEARER set)

DhanHQ.configure_from_token_endpoint

Parameters:

  • base_url (String, nil) (defaults to: nil) —

    Base URL of your app (e.g. myapp.com). If nil, uses ENV.

  • bearer_token (String, nil) (defaults to: nil) —

    Secret token for the endpoint. If nil, uses ENV.

Returns:

Raises:



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/dhan_hq.rb', line 126

def configure_from_token_endpoint(base_url: nil, bearer_token: nil)
  base_url ||= ENV.fetch("DHAN_TOKEN_ENDPOINT_BASE_URL", nil)
  bearer_token ||= ENV.fetch("DHAN_TOKEN_ENDPOINT_BEARER", nil)

  raise DhanHQ::TokenEndpointError, "base_url and bearer_token (or ENV DHAN_TOKEN_ENDPOINT_*) are required" if base_url.to_s.empty? || bearer_token.to_s.empty?

  url = "#{base_url.to_s.chomp("/")}/auth/dhan/token"
  conn = ::Faraday.new(url: url) do |c|
    c.response :json, content_type: /\bjson$/
    c.adapter ::Faraday.default_adapter
  end

  response = conn.get("") do |req|
    req.headers["Authorization"] = "Bearer #{bearer_token}"
    req.headers["Accept"] = "application/json"
  end

  unless response.success?
    body = parse_json_body(response.body)
    msg = body["error"] || body["message"] || body["errorMessage"] || response.body.to_s
    raise DhanHQ::TokenEndpointError, "Token endpoint returned #{response.status}: #{msg}"
  end

  data = parse_json_body(response.body)
  data = data.transform_keys(&:to_s) if data.is_a?(Hash)

  access_token = data["access_token"] || data[:access_token]
  client_id = data["client_id"] || data[:client_id]
  raise DhanHQ::TokenEndpointError, "Token endpoint response missing access_token or client_id" if access_token.to_s.empty? || client_id.to_s.empty?

  self.configuration ||= Configuration.new
  configuration.access_token = access_token.to_s
  configuration.client_id = client_id.to_s
  dhan_base = data["base_url"] || data[:base_url]
  configuration.base_url = dhan_base.to_s if dhan_base.to_s != ""
  configuration
end

.configure_with_env ⇒ void

This method returns an undefined value.

Configures the DhanHQ client using environment variables.

When credentials are injected via ‘DHAN_ACCESS_TOKEN` and `DHAN_CLIENT_ID` this helper can be used to initialise a configuration without a block.

Examples:

DhanHQ.configure_with_env


92
93
94
 
# File 'lib/dhan_hq.rb', line 92

def configure_with_env
  self.configuration = Configuration.new
end

.ensure_configuration! ⇒ DhanHQ::Configuration

Ensures configuration exists, bootstrapping from ENV when nil. Called automatically when building a Client so env-only integrations work without an explicit configure/configure_with_env call. Idempotent when configuration is already set.

Returns:



101
102
103
 
# File 'lib/dhan_hq.rb', line 101

def ensure_configuration!
  self.configuration ||= Configuration.new
end

.parse_json_body(body) ⇒ Hash

Returns Parsed hash; empty hash on parse failure or empty string.

Parameters:

  • body (String, Hash) —

    Raw response body

Returns:

  • (Hash) —

    Parsed hash; empty hash on parse failure or empty string



166
167
168
169
170
171
172
173
174
 
# File 'lib/dhan_hq.rb', line 166

def parse_json_body(body)
  return {} if body.nil?
  return body if body.is_a?(Hash)
  return {} if body.to_s.strip.empty?

  JSON.parse(body.to_s)
rescue StandardError
  {}
end

.reset_configuration! ⇒ Object

Resets the configuration to nil.



106
107
108
 
# File 'lib/dhan_hq.rb', line 106

def reset_configuration!
  self.configuration = nil
end