bybit-connector-ruby 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e337e2d3927cdb53b707d0bfd441323cb293a43e2c3ded843d273c47f439af5
-  data.tar.gz: c4dfa85d62da8da24fc1cccdc5101631404182a3910de24f65f899ed972771dd
+  metadata.gz: 29c7f3e3612cc7bc336a83b1eaf26480ec881b491e7e3c66d042b9a6a23efb71
+  data.tar.gz: 7d64066ef1795efbdfc0f13c11bda3f8ea5e99e6f0d627fb4a1baf28bd6de99c
 SHA512:
-  metadata.gz: 9bad03bebb0cc8d633b4f014d42da79b592ade8d8f90b77a4a9ed239a0d46ae094aa8ba236a01616abb5b0b7596a85627cccad53ebce950334c544eef3ff0570
-  data.tar.gz: 310c666e1c0b387b84d91ab4fff0f78f401224eb09f74724bd64e021c4bf5fc1ff4f3458e383ed7a040bba69528602bedbb48f2da8b3d54cf1af30a142fa3f42
+  metadata.gz: e767a4025a6b105dad09bd0abb87ad04127183505981a35445e9d699c512ea9c699e769a77bd6b8a899fe7f2a91a073c70d823f822b08383f63ec9d3ef20a728
+  data.tar.gz: 312fd1a206d9513423767aa47d1a1009bbd28883d14367928df5799698c31205f72c661b9efcbfc36f1795b97434147c02a6ff3ba0235a744f616072f4e9213b

data/CHANGELOG.md

@@ -5,7 +5,136 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.1.0 — 2026-07-20
+## [0.1.3] - 2026-11-06
+
+### Added
+- `AlphaService#get_lp_order_list(...)`
+- `AlphaService#get_lp_pay_token_list(...)`
+- `AlphaService#get_lp_pay_token_price(...)`
+- `AlphaService#get_lp_pool_info(...)`
+- `AlphaService#get_lp_pool_list(...)`
+- `AlphaService#get_lp_position_list(...)`
+- `AlphaService#execute_lp_redeem(...)`
+- `AlphaService#execute_lp_stake(...)`
+- `AlphaService#execute_prediction_buy(...)`
+- `AlphaService#get_prediction_engine_status(...)`
+- `AlphaService#get_prediction_event_detail(...)`
+- `AlphaService#get_prediction_order_book(...)`
+- `AlphaService#get_prediction_order_estimate(...)`
+- `AlphaService#get_prediction_order_list(...)`
+- `AlphaService#get_prediction_pay_token_list(...)`
+- `AlphaService#get_prediction_portfolio_summary(...)`
+- `AlphaService#get_prediction_position_history(...)`
+- `AlphaService#get_prediction_position_list(...)`
+- `AlphaService#get_prediction_price_history(...)`
+- `AlphaService#execute_prediction_sell(...)`
+- `AlphaService#get_prediction_side_market_list(...)`
+- `AlphaService#get_prediction_group_stage_detail(...)`
+- `AlphaService#get_prediction_match_list(...)`
+- `AlphaService#get_prediction_timeline_stages(...)`
+- `AlphaService#get_prediction_token_price(...)`
+- `AlphaService#get_asset_detail(...)`
+- `AlphaService#get_asset_list(...)`
+- `AlphaService#get_biz_token_details(...)`
+- `AlphaService#get_biz_token_list(...)`
+- `AlphaService#get_biz_token_price_list(...)`
+- `AlphaService#get_order_list(...)`
+- `AlphaService#get_pay_token_list(...)`
+- `AlphaService#execute_purchase(...)`
+- `AlphaService#get_trade_quote(...)`
+- `AlphaService#execute_redeem(...)`
+- `EventService#get_ec_order_history(...)`
+- `EventService#get_ec_active_orders(...)`
+- `EventService#get_ec_position_info(...)`
+- `EventService#get_ec_settlements(...)`
+- `EventService#get_ec_trade_history(...)`
+- `TaxService#batch_create_tax_reports(...)`
+- `TaxService#batch_query_tax_reports(...)`
+- `FiatService#query_balance(...)`
+- `FiatService#query_coin_list(...)`
+- `FiatService#query_trade_history(...)`
+- `FiatService#apply_quote(...)`
+- `FiatService#get_reference_price(...)`
+- `FiatService#confirm_quote(...)`
+- `FiatService#query_trade(...)`
+- `InstitutionalLoanService#ins_loan_coin_delta_amount(...)`
+- `InstitutionalLoanService#ins_loan_delay_liq_status(...)`
+- `ReferralService#get_campaign_rewards(...)`
+- `ReferralService#get_commission_records(...)`
+- `ReferralService#get_user_identity_profile(...)`
+- `ReferralService#get_user_invitations(...)`
+- `SpotMarginService#query_fixed_borrow_penalty_interest(...)`
+- `SpotMarginService#cancel_fixed_borrow_order(...)`
+- `SpotXService#get_launchpool_project_list(...)`
+- `SpotXService#get_launchpool_user_activity_log(...)`
+- `SpotXService#get_launchpool_user_current_staking(...)`
+- `SpotXService#get_launchpool_user_history(...)`
+- `SpotXService#get_puzzle_project_list(...)`
+- `SpotXService#get_token_splash_project_list(...)`
+- `SpotXService#get_token_splash_user_activity_params(...)`
+- `SpreadTradeService#get_history(...)`
+- `SpreadTradeService#get_spread_instruments_info(...)`
+- `SpreadTradeService#get_spread_max_qty(...)`
+- `SpreadTradeService#amend_spread_order(...)`
+- `SpreadTradeService#cancel_spread_order(...)`
+- `SpreadTradeService#cancel_all_spread_orders(...)`
+- `SpreadTradeService#create_spread_order(...)`
+- `SpreadTradeService#get_spread_order_history(...)`
+- `SpreadTradeService#get_spread_open_orders(...)`
+- `SpreadTradeService#get_spread_orderbook(...)`
+- `SpreadTradeService#get_spread_recent_trades(...)`
+- `SpreadTradeService#get_spread_tickers(...)`
+- `StrategyService#create_strategy(...)`
+- `StrategyService#query_list(...)`
+- `StrategyService#query_order_list(...)`
+- `StrategyService#stop_strategy(...)`
+
+### Fixed
+- `AlphaService#get_prediction_side_market_list(...)` now requires `event_id` and accepts the documented filters and pagination options.
+
+### Sources
+- OpenAPI: `705f49bf6dba27ecc5b9b402f46ab2423cfb5dd9`
+- Docs: `9cde0843c270dd1e6009fb4593272f43f60cccf0`
+
+## [0.1.2] - 2026-10-13
+
+### Added
+- `AccountService#demo_apply_money(...)`
+- `AccountService#get_option_asset_info(...)`
+- `AccountService#get_pay_info(...)`
+- `AccountService#get_trade_info_for_analysis(...)`
+- `AssetService#limit_order_callback(...)`
+- `CryptoLoanService#get_fixed_available_inventory(...)`
+- `CryptoLoanService#get_fixed_repayment_history(...)`
+- `CryptoLoanService#supply_fixed(...)`
+- `CryptoLoanService#get_flexible_available_inventory(...)`
+- `EarnService#list_auto_savings(...)`
+- `EarnService#edit_earn_auto_savings(...)`
+- `MarketService#get_option_base_coins(...)`
+- `PositionService#get_symbol_info(...)`
+- `SpotMarginService#get_trade_coin_state(...)`
+- `SpotMarginService#query_fixed_available_inventory(...)`
+- `SpotMarginService#account_fixed_borrow(...)`
+- `SpotMarginService#query_fixed_borrow_contracts(...)`
+- `SpotMarginService#query_fixed_borrow_orders(...)`
+- `SpotMarginService#query_fixed_borrow_market(...)`
+- `SpotMarginService#renew_fixed_borrow(...)`
+- `SpotMarginService#get_trade_flexible_available_inventory(...)`
+- `SpotMarginService#get_trade_auto_repay_mode(...)`
+- `SpotMarginService#query_borrow_liability(...)`
+- `SpotMarginService#get_trade_max_borrowable(...)`
+- `SpotMarginService#get_trade_repayment_available_amount(...)`
+- `SpotMarginService#set_auto_repay_mode(...)`
+- `SpotMarginService#spot_margin_set_leverage(...)`
+- `SpotMarginService#get_trade_state(...)`
+- `SpotMarginService#spot_margin_switch_mode(...)`
+- `UserService#query_referral_code(...)`
+
+### Sources
+- OpenAPI: `08130d57323d390dea58f15418758e2667c74ce6`
+- Docs: `59e3d457dea6b419a14987c19a3aabf4ffb38238`
+
+## [0.1.1] - 2026-07-22
 
 ### Added
 - `AccountService#batch_set_collateral(...)`
@@ -34,9 +163,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `AccountService#upgrade_to_uta_pro(...)`
 - `AffiliateService#get_sub_list(...)`
 - `AffiliateService#get_user_list(...)`
+- `AssetService#account_coin_balance_query(...)`
+- `AssetService#asset_info_query(...)`
+- `AssetService#cancel_withdraw(...)`
+- `AssetService#coin_convert_limit_query(...)`
+- `AssetService#coin_list_query(...)`
+- `AssetService#convert_execute(...)`
+- `AssetService#convert_history_query(...)`
+- `AssetService#get_asset_overview(...)`
 - `AssetService#get_coin_balance(...)`
 - `AssetService#get_coin_greeks(...)`
+- `AssetService#get_coin_info(...)`
+- `AssetService#get_convert_result(...)`
+- `AssetService#get_delivery_record(...)`
+- `AssetService#get_deposit_address(...)`
+- `AssetService#get_portfolio_margin(...)`
+- `AssetService#get_settlement_record(...)`
+- `AssetService#get_sub_member_deposit_address(...)`
+- `AssetService#get_total_members_assets(...)`
+- `AssetService#get_vasp_list(...)`
+- `AssetService#get_withdrawable_amount_by_coin(...)`
+- `AssetService#inter_transfer(...)`
+- `AssetService#inter_transfer_list_query(...)`
+- `AssetService#list_convert_orders(...)`
+- `AssetService#list_convert_orders_by_page(...)`
+- `AssetService#list_deposit_records(...)`
 - `AssetService#list_funding_history(...)`
+- `AssetService#list_internal_deposit_records(...)`
+- `AssetService#list_small_balance_coins(...)`
+- `AssetService#list_small_balance_history(...)`
+- `AssetService#list_sub_member_deposit_records(...)`
+- `AssetService#list_withdraw_addresses(...)`
+- `AssetService#list_withdraw_records(...)`
+- `AssetService#quote_apply(...)`
+- `AssetService#send_withdraw(...)`
+- `AssetService#set_default_deposit_to_account(...)`
+- `AssetService#small_asset_convert(...)`
+- `AssetService#small_asset_quote(...)`
+- `AssetService#sub_member_list_query(...)`
+- `AssetService#transfer_coin_list_query(...)`
+- `AssetService#transfer_sub_member_save(...)`
+- `AssetService#universal_transfer(...)`
+- `AssetService#universal_transfer_list_query(...)`
 - `BrokerService#distribute_award(...)`
 - `BrokerService#get_award_info(...)`
 - `BrokerService#get_distribution_record(...)`
@@ -257,3 +425,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `UserService#sign_agreement(...)`
 - `UserService#update_api_key(...)`
 - `UserService#update_sub_api_key(...)`
+- `InstitutionalLoanService#get_product_info(...)`
+- `InstitutionalLoanService#get_margin_coin_info(...)`
+- `InstitutionalLoanService#get_loan_orders(...)`
+- `InstitutionalLoanService#get_repayment_orders(...)`
+- `InstitutionalLoanService#get_ltv(...)`
+- `InstitutionalLoanService#bind_or_unbind_uid(...)`
+- `InstitutionalLoanService#repay_loan(...)`
+- `MiscService#get_announcements(...)`
+- `MiscService#get_system_status(...)`
+- `PreUpgradeService#get_order_history(...)`
+- `PreUpgradeService#get_trade_history(...)`
+- `PreUpgradeService#get_closed_pnl(...)`
+- `PreUpgradeService#get_transaction_log(...)`
+- `PreUpgradeService#get_option_delivery_record(...)`
+- `PreUpgradeService#get_usdc_session_settlement(...)`
+- `Bybit::WebSocket::Client` — public (spot/linear/inverse/option), private,
+  and trade streams; HMAC-SHA256 auth, ping/pong, deferred subscribe (topics
+  buffered until socket opens; private streams wait for auth OK), idempotent
+  `#connect` (second call replays buffered subscriptions), testnet host
+  support. Load via `require 'bybit/websocket'` (opt-in dep on
+  `websocket-client-simple`).
+- VCR-driven end-to-end specs asserting the exact wire bytes and X-BAPI-SIGN
+  header for signed GET (query) and signed POST (body) routing.
+- SimpleCov floor coverage gate for `lib/bybit/rest_api/*_service.rb` — new
+  services without matching specs now drop CI.
+- README: WebSocket usage section.
+
+### Fixed
+- `Session#parse_response` now maps HTTP 401/403 → `Bybit::AuthError` and 429
+  → `Bybit::RateLimitError` even when the response body is non-JSON
+  (CDN/WAF path), matching the contract in README.md#Error-Handling.
+- `BrokerService#list_broker_earnings` — caller-facing kwargs renamed from
+  `:begin_` / `:end_` to `:start_date` / `:end_date`; internal rewrite now
+  goes through `WireKeys::RESERVED_ALIASES` instead of hand-rolled shim.

data/README.md

@@ -1,8 +1,26 @@
 # bybit-connector-ruby
 
+[![Gem Version](https://img.shields.io/gem/v/bybit-connector-ruby)](https://rubygems.org/gems/bybit-connector-ruby) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/bybit-exchange/bybit.ruby.api/blob/main/LICENSE)
+
 Official lightweight Ruby connector for the [Bybit V5 REST API](https://bybit-exchange.github.io/docs/v5/intro).
 
-`bybit-connector-ruby` wraps the Bybit V5 HTTP endpoints as a set of typed Ruby methods with keyword-arg signatures. Its goal is the same as [`pybit`](https://github.com/bybit-exchange/pybit) on the Python side: an easy-to-use, high-performance connector with a small dependency footprint.
+`bybit-connector-ruby` wraps the Bybit V5 HTTP endpoints as a set of typed Ruby methods with keyword-arg signatures. 
+## Prerequisites
+
+Before you write any code you need a Bybit API key. Two accounts to know
+about:
+
+- **Testnet** — [testnet.bybit.com](https://testnet.bybit.com) → sign up →
+  API Management → *Create New Key*. This is where you should point every
+  new integration until you're confident about behavior. Testnet balances
+  are virtual; nothing you do here touches real funds.
+- **Mainnet** — [bybit.com](https://www.bybit.com) → API Management. Real
+  money. Enable only the permissions you actually need (spot / derivatives /
+  withdrawals) and prefer IP-restricted keys.
+
+Testnet and mainnet keys are **separate** — an API key issued on one won't
+work against the other. The SDK selects the environment via
+`testnet: true|false` (or an explicit `base_url:` override).
 
 ## Installation
 
@@ -23,30 +41,43 @@ gem 'bybit-connector-ruby'
 ```ruby
 require 'bybit'
 
+# All calls below run against testnet — swap testnet: false for mainnet
+# once you're happy with the behavior.
 Bybit.configure do |c|
-  c.api_key    = ENV['BYBIT_KEY']
-  c.api_secret = ENV['BYBIT_SECRET']
-  c.testnet    = true      # omit / false for mainnet
+  c.api_key    = ENV['BYBIT_TESTNET_KEY']
+  c.api_secret = ENV['BYBIT_TESTNET_SECRET']
+  c.testnet    = true
 end
 
 client = Bybit::Client.new
 
-# Public endpoint — no auth needed
+# 1. Public endpoint — no auth needed.
 puts client.market.get_server_time
 
-# Signed endpoint — apiKey + apiSecret required
+# 2. Signed endpoint — api_key + api_secret required.
 wallet = client.account.get_wallet_balance(account_type: 'UNIFIED')
 puts wallet['result']['list']
 
-# Place an order
+# 3. Place a LIMIT order well below market so it sits on the book and does
+#    NOT fill (safe to run repeatedly). Adjust `price:` if BTC ever trades
+#    at $10k again — otherwise this stays a resting order you can cancel.
 order = client.trade.create_order(
   category: 'linear', symbol: 'BTCUSDT',
   side: 'Buy', order_type: 'Limit', qty: '0.01',
-  price: '30000', time_in_force: 'GTC',
+  price: '10000', time_in_force: 'GTC'
 )
-puts "orderId: #{order['result']['orderId']}"
+order_id = order['result']['orderId']
+puts "orderId: #{order_id}"
+
+# 4. Cancel it before moving on.
+client.trade.cancel_order(category: 'linear', symbol: 'BTCUSDT', order_id: order_id)
 ```
 
+> ⚠️ **Before switching `testnet: false`**: verify the price / qty in
+> `create_order` won't cross the top of the book — a Limit Buy at $10k on
+> mainnet becomes a market fill instantly (if BTC ever drops that low),
+> and a Limit Sell at $1M does the reverse.
+
 See `examples/quickstart.rb` for a runnable script.
 
 ## Configuration
@@ -58,12 +89,17 @@ Bybit.configure do |c|
   c.api_key    = ENV['BYBIT_KEY']
   c.api_secret = ENV['BYBIT_SECRET']
   c.testnet    = false             # default false
-  c.recv_window = '5000'           # ms, X-BAPI-RECV-WINDOW header
+  c.recv_window = '5000'           # milliseconds — Bybit rejects requests
+                                   # whose signed timestamp is older than
+                                   # this window. Bump to 10000+ if your
+                                   # clock drifts or the network is noisy.
   c.timeout    = 10                # Faraday timeout, seconds
 end
 ```
 
-Or pass overrides to `Client.new`:
+Or pass overrides to `Client.new` — **per-client overrides win over
+`Bybit.configure`**, so you can share defaults globally and still spin up a
+dedicated client with a different key or environment:
 
 ```ruby
 client = Bybit::Client.new(api_key: '...', api_secret: '...', testnet: true)
@@ -92,16 +128,27 @@ Each API group is a property on `Bybit::Client`:
 - `client.trade` — orders (create / amend / cancel / batch / history)
 - `client.position` — positions, leverage, TP/SL, move-position
 - `client.account` — wallet, margin, collateral, fee-rate, transaction log
+- `client.alpha` — Alpha liquidity pools, prediction markets, and on-chain token trading
 - `client.asset` — coin balance, coin greeks, funding history
 - `client.user` — sub-accounts, API-key management
 - `client.affiliate` — sub-affiliate lists
 - `client.broker` — broker earnings, distributions
 - `client.crypto_loan` — flexible / fixed crypto loans
+- `client.event` — event contracts, positions, settlements, and executions
+- `client.fiat` — fiat convert balances, quotes, trades, and history
+- `client.institutional_loan` — /v5/ins-loan/* (OTC institutional loans)
 - `client.rfq` — request-for-quote (block trades)
 - `client.spot_margin` — UTA spot margin
+- `client.spot_x` — Launchpool, Puzzle Hunt, and Token Splash
+- `client.spread_trade` — spread instruments, orders, orderbook, and executions
+- `client.strategy` — strategy creation, queries, and lifecycle operations
+- `client.tax` — private tax report generation and status queries
 - `client.earn` — earn, liquidity mining, RWA, PWM, hold-to-earn
 - `client.p2p` — P2P advertise / order / chat
 - `client.bot` — DCA / grid / futures-combo / futures-grid / martingale
+- `client.pre_upgrade` — /v5/pre-upgrade/* historical queries for Classic → UTA upgrades
+- `client.referral` — campaign rewards, commissions, profiles, and invitations
+- `client.misc` — /v5/announcements/index, /v5/system/status
 
 ## Error Handling
 
@@ -139,6 +186,12 @@ Full hierarchy:
 
 Every `ApiError` exposes `#ret_code`, `#ret_msg`, `#result`, `#time`, `#http_status`. See the [Bybit V5 error-code list](https://bybit-exchange.github.io/docs/v5/error) for meanings.
 
+> The `sleep 1 && retry` shown above is fine for exploration, **not** for
+> production — Bybit will escalate throttling on tight retry loops. For
+> real workloads, wire a `Faraday::Retry` middleware with exponential
+> backoff via the "bring your own Faraday connection" hook in
+> [Configuration](#configuration) above.
+
 ## Return Value
 
 Every service method returns the raw parsed JSON as a `Hash`:
@@ -151,14 +204,106 @@ response['result']     # => { 'category' => 'spot', 'symbol' => 'BTCUSDT', 'list
 response['time']       # => 1234567890000
 ```
 
-## Testnet
+> Keys are **strings, not symbols** — `response[:result]` is `nil`. This is
+> a common first-hour gotcha; pass through `JSON.parse` semantics rather
+> than converting.
+
+## Method Reference
+
+Method names follow the Bybit V5 endpoint slug in snake_case, grouped by
+domain. A few illustrative mappings:
+
+| Bybit V5 path                         | SDK method                                |
+| ------------------------------------- | ----------------------------------------- |
+| `GET  /v5/market/kline`               | `client.market.get_kline`                 |
+| `GET  /v5/market/tickers`             | `client.market.get_tickers`               |
+| `POST /v5/order/create`               | `client.trade.create_order`               |
+| `POST /v5/order/cancel`               | `client.trade.cancel_order`               |
+| `GET  /v5/position/list`              | `client.position.get_positions`           |
+| `GET  /v5/account/wallet-balance`     | `client.account.get_wallet_balance`       |
+
+For the full list, generate YARD docs locally:
+
+```
+bundle exec yard doc
+open doc/index.html
+```
+
+or browse the published copy on
+[rubydoc.info/gems/bybit-connector-ruby](https://rubydoc.info/gems/bybit-connector-ruby).
+
+## Pagination
+
+Bybit V5 uses **opaque cursor pagination** — the response's
+`result['nextPageCursor']` (empty string when the page is the last one)
+feeds back in as the `cursor:` argument on the next call:
+
+```ruby
+cursor = nil
+loop do
+  resp = client.trade.get_order_history(category: 'linear', limit: 50, cursor: cursor)
+  resp['result']['list'].each { |order| process(order) }
+  cursor = resp['result']['nextPageCursor']
+  break if cursor.nil? || cursor.empty?
+end
+```
+
+The same pattern works for `get_positions`, `get_execution_history`,
+`get_transaction_log`, and every other paginated endpoint.
+
+## WebSockets
 
-Toggle `testnet: true` for [https://testnet.bybit.com](https://testnet.bybit.com):
+Hosts (mirror the REST split):
+
+- Mainnet — `wss://stream.bybit.com/v5/{public/<category>|private|trade}`
+- Testnet — `wss://stream-testnet.bybit.com/v5/{public/<category>|private|trade}`
+
+WebSocket support ships behind an opt-in require so REST-only consumers don't
+load the underlying `websocket-client-simple` dependency at boot. Four
+callbacks are available; all are optional but you'll almost always want at
+least `on_message`.
 
 ```ruby
-client = Bybit::Client.new(api_key: ENV['BYBIT_TESTNET_KEY'], api_secret: ENV['BYBIT_TESTNET_SECRET'], testnet: true)
+require 'bybit/websocket'
+
+# Public stream — no auth needed.
+public_ws = Bybit::WebSocket::Client.new(
+  channel: :linear,           # :spot / :linear / :inverse / :option
+  testnet: true,
+  on_open:    -> { puts 'connected' },
+  on_message: ->(msg) { puts msg.inspect },              # your handler
+  on_close:   ->(_ev) { puts 'closed'  },
+  on_error:   ->(err) { warn "ws error: #{err}" }
+).connect
+
+public_ws.subscribe('tickers.BTCUSDT', 'orderbook.1.BTCUSDT')
+
+# Private stream — HMAC-SHA256 auth over "GET/realtime" + expiry.
+private_ws = Bybit::WebSocket::Client.new(
+  channel:    :private,
+  testnet:    true,
+  api_key:    ENV['BYBIT_TESTNET_KEY'],
+  api_secret: ENV['BYBIT_TESTNET_SECRET'],
+  on_message: ->(msg) { puts msg.inspect }               # your handler
+).connect
+
+# Subscribe returns immediately; the actual `op:subscribe` frame is deferred
+# until the private-stream auth reply lands, so you can call subscribe
+# anytime — before or after `#connect`.
+private_ws.subscribe('position', 'order', 'wallet')
+
+# Later:
+private_ws.unsubscribe('wallet')
+private_ws.disconnect
 ```
 
+Supported channels: `:spot`, `:linear`, `:inverse`, `:option`, `:private`,
+`:trade`. `testnet: true` swaps in the `stream-testnet.bybit.com` host.
+Pings ship every 20 seconds — Bybit closes idle sockets after ~20s of
+silence. There is no automatic reconnect on network drop: callers listening
+on `on_close` can invoke `#connect` again to reopen the socket and replay
+the buffered `#subscriptions`.
+
 ## Development
 
 ```

data/examples/quickstart.rb

@@ -1,29 +1,35 @@
 # frozen_string_literal: true
 
-# End-to-end quickstart — public + signed calls + rescue matrix.
-# Run with:  BYBIT_KEY=... BYBIT_SECRET=... ruby examples/quickstart.rb
+# End-to-end quickstart — mirrors README's Quick Start:
+#   1. public unsigned call
+#   2. signed GET (wallet balance)
+#   3. safe LIMIT order well below market (does not fill)
+#   4. cancel that order
+# Run with:
+#   BYBIT_TESTNET_KEY=... BYBIT_TESTNET_SECRET=... ruby examples/quickstart.rb
 
 require 'bybit'
 
 Bybit.configure do |c|
-  c.api_key    = ENV['BYBIT_KEY']
-  c.api_secret = ENV['BYBIT_SECRET']
-  c.testnet    = true          # flip to false for mainnet
+  c.api_key    = ENV.fetch('BYBIT_TESTNET_KEY')
+  c.api_secret = ENV.fetch('BYBIT_TESTNET_SECRET')
+  c.testnet    = true          # flip to false for mainnet — see README warning
 end
 
 client = Bybit::Client.new
 
-# 1. Public endpoint — server time (no auth needed)
+# 1. Public endpoint — server time (no auth needed).
 puts '--- server time ---'
 puts client.market.get_server_time.inspect
 
-# 2. Signed endpoint — wallet balance
+# 2. Signed endpoint — wallet balance.
 puts '--- wallet balance ---'
 begin
   wallet = client.account.get_wallet_balance(account_type: 'UNIFIED')
   puts wallet['result']['list'].inspect
 rescue Bybit::AuthError => e
   warn "auth failed: [#{e.ret_code}] #{e.ret_msg}"
+  exit 1
 rescue Bybit::RateLimitError => e
   warn "rate-limited: #{e.ret_msg}"
 rescue Bybit::TimeoutError => e
@@ -33,3 +39,26 @@ rescue Bybit::NetworkError => e
 rescue Bybit::ApiError => e
   warn "api error [#{e.ret_code}]: #{e.ret_msg}"
 end
+
+# 3. Place a LIMIT order well below market so it sits on the book and does
+#    NOT fill (safe to run repeatedly). Adjust price if BTC ever trades that
+#    low; otherwise this stays a resting order you can cancel below.
+puts '--- place limit order ---'
+begin
+  order = client.trade.create_order(
+    category: 'linear', symbol: 'BTCUSDT',
+    side: 'Buy', order_type: 'Limit', qty: '0.01',
+    price: '10000', time_in_force: 'GTC'
+  )
+  order_id = order['result']['orderId']
+  puts "orderId: #{order_id}"
+
+  # 4. Cancel it before exiting so we don't leave test orders on the book.
+  puts '--- cancel order ---'
+  cancel = client.trade.cancel_order(
+    category: 'linear', symbol: 'BTCUSDT', order_id: order_id
+  )
+  puts cancel['result'].inspect
+rescue Bybit::ApiError => e
+  warn "api error [#{e.ret_code}]: #{e.ret_msg}"
+end

data/lib/bybit/client.rb

@@ -8,13 +8,24 @@ require 'bybit/rest_api/bot_service'
 require 'bybit/rest_api/broker_service'
 require 'bybit/rest_api/crypto_loan_service'
 require 'bybit/rest_api/earn_service'
+require 'bybit/rest_api/institutional_loan_service'
 require 'bybit/rest_api/market_service'
+require 'bybit/rest_api/misc_service'
 require 'bybit/rest_api/p2p_service'
 require 'bybit/rest_api/position_service'
+require 'bybit/rest_api/pre_upgrade_service'
 require 'bybit/rest_api/rfq_service'
 require 'bybit/rest_api/spot_margin_service'
 require 'bybit/rest_api/trade_service'
 require 'bybit/rest_api/user_service'
+require 'bybit/rest_api/alpha_service'
+require 'bybit/rest_api/event_service'
+require 'bybit/rest_api/fiat_service'
+require 'bybit/rest_api/referral_service'
+require 'bybit/rest_api/spot_x_service'
+require 'bybit/rest_api/spread_trade_service'
+require 'bybit/rest_api/strategy_service'
+require 'bybit/rest_api/tax_service'
 # gen-sdk-ruby:service-requires:end
 
 module Bybit
@@ -33,8 +44,10 @@ module Bybit
 
   class Client
     # gen-sdk-ruby:client-readers:start
-    attr_reader :account, :affiliate, :asset, :bot, :broker, :crypto_loan, :earn,
-                :market, :p2p, :position, :rfq, :spot_margin, :trade, :user
+    attr_reader :account, :affiliate, :alpha, :asset, :bot, :broker, :crypto_loan, :earn,
+                :event, :fiat, :institutional_loan, :market, :misc, :p2p, :position,
+                :pre_upgrade, :referral, :rfq, :spot_margin, :spot_x, :spread_trade,
+                :strategy, :tax, :trade, :user
 
     # gen-sdk-ruby:client-readers:end
 
@@ -45,20 +58,35 @@ module Bybit
       @config = cfg
 
       # gen-sdk-ruby:client-inits:start
-      @account = RestApi::AccountService.new(session)
-      @affiliate = RestApi::AffiliateService.new(session)
-      @asset = RestApi::AssetService.new(session)
-      @bot = RestApi::BotService.new(session)
-      @broker = RestApi::BrokerService.new(session)
-      @crypto_loan = RestApi::CryptoLoanService.new(session)
-      @earn = RestApi::EarnService.new(session)
-      @market = RestApi::MarketService.new(session)
-      @p2p = RestApi::P2pService.new(session)
-      @position = RestApi::PositionService.new(session)
-      @rfq = RestApi::RfqService.new(session)
-      @spot_margin = RestApi::SpotMarginService.new(session)
-      @trade = RestApi::TradeService.new(session)
-      @user = RestApi::UserService.new(session)
+      {
+        account: RestApi::AccountService,
+        affiliate: RestApi::AffiliateService,
+        alpha: RestApi::AlphaService,
+        asset: RestApi::AssetService,
+        bot: RestApi::BotService,
+        broker: RestApi::BrokerService,
+        crypto_loan: RestApi::CryptoLoanService,
+        earn: RestApi::EarnService,
+        event: RestApi::EventService,
+        fiat: RestApi::FiatService,
+        institutional_loan: RestApi::InstitutionalLoanService,
+        market: RestApi::MarketService,
+        misc: RestApi::MiscService,
+        p2p: RestApi::P2pService,
+        position: RestApi::PositionService,
+        pre_upgrade: RestApi::PreUpgradeService,
+        referral: RestApi::ReferralService,
+        rfq: RestApi::RfqService,
+        spot_margin: RestApi::SpotMarginService,
+        spot_x: RestApi::SpotXService,
+        spread_trade: RestApi::SpreadTradeService,
+        strategy: RestApi::StrategyService,
+        tax: RestApi::TaxService,
+        trade: RestApi::TradeService,
+        user: RestApi::UserService
+      }.each do |name, service_class|
+        instance_variable_set("@#{name}", service_class.new(session))
+      end
       # gen-sdk-ruby:client-inits:end
     end
 

data/lib/bybit/error.rb

@@ -22,16 +22,24 @@ module Bybit
 
   # Raised when the server returns HTTP 200 + retCode != 0 (the V5 norm),
   # or when a transport-level error is enriched with a Bybit body payload.
+  # Accepts either a V5 response Hash (extracts retCode/retMsg/result/time)
+  # or a plain String message (used for HTTP-status mapping when the CDN/WAF
+  # returns a non-JSON body — e.g. 401/403/429 → AuthError/RateLimitError
+  # without a decodable retCode).
   class ApiError < Error
     attr_reader :ret_code, :ret_msg, :result, :time, :http_status
 
     def initialize(response, http_status: nil)
-      @ret_code    = response['retCode']
-      @ret_msg     = response['retMsg']
-      @result      = response['result']
-      @time        = response['time']
       @http_status = http_status
-      super("[#{@ret_code}] #{@ret_msg}")
+      if response.is_a?(Hash)
+        @ret_code = response['retCode']
+        @ret_msg  = response['retMsg']
+        @result   = response['result']
+        @time     = response['time']
+        super("[#{@ret_code}] #{@ret_msg}")
+      else
+        super(response.to_s)
+      end
     end
   end