ib-api 10.33.1

data/LLM_GUIDE.md

@@ -0,0 +1,388 @@
+# LLM Guide for ib-api
+
+**Purpose**: This guide is optimized for LLMs (Large Language Models) to understand and work with the ib-api codebase efficiently.
+
+---
+
+## QUICK MENTAL MODEL
+
+**What is this?**: A Ruby gem that provides a programmatic interface to Interactive Brokers' trading platform (TWS/Gateway).
+
+**Core pattern**: You create a `Connection` object → it opens a TCP socket to IB → you send/recv messages → events trigger callbacks → data flows through plugins.
+
+**Key insight**: Everything is message-driven. Connection manages a state machine, plugins extend functionality, and models represent trading objects.
+
+---
+
+## FILE MAP (WHERE THINGS LIVE)
+
+```
+lib/ib/
+├── connection.rb          # CORE: Main Connection class, workflow state machine
+├── plugins.rb             # Plugin activation system
+├── messages/
+│   ├── outgoing/          # Messages sent TO IB (requests)
+│   └── incoming/          # Messages received FROM IB (responses)
+└── constants.rb           # IB API enums/constants
+
+models/ib/                  # Zeiteerk-loaded models
+├── contract.rb            # Base class for all instruments
+├── stock.rb, option.rb, future.rb, etc.  # Specific contract types
+├── order.rb               # Order objects
+└── bar.rb                 # OHLCV market data
+
+plugins/ib/                 # Plugin implementations (extend Connection)
+├── verify.rb              # Contract verification
+├── market-price.rb        # Current price fetching
+├── managed-accounts.rb    # Account/portfolio management
+└── ...
+
+spec/
+├── spec_helper.rb         # Test config, loads spec.yml
+├── spec.yml               # IB connection settings (REQUIRED for tests)
+└── howto.md               # Guide for implementing new messages
+```
+
+---
+
+## THE CONNECTION OBJECT (CENTRAL HUB)
+
+```ruby
+require 'ib-api'
+
+# Create connection (does NOT connect yet)
+ib = IB::Connection.new(host: '127.0.0.1', port: 7497)
+
+# Connect (triggers workflow state transition)
+ib.try_connection!  # or use the event: ib.try_connection
+
+# The connection is globally accessible
+IB::Connection.current == ib  # => true
+```
+
+**Connection attributes**:
+- `socket`: TCP connection to IB
+- `next_local_id`: Next available order ID
+- `received`: Hash of received messages (by type)
+- `plugins`: Array of activated plugin names
+- `workflow_state`: Current state (virgin, ready, gateway_mode, etc.)
+
+---
+
+## WORKFLOW STATE MACHINE
+
+**States (linear progression typical)**:
+
+```
+virgin (initial)
+    │
+    ├─→ try_connection! → ready
+    │
+    ├─→ activate_managed_accounts! → gateway_mode
+    │
+    └─→ collect_data! → lean_mode
+
+ready
+    │
+    ├─→ initialize_managed_accounts! → account_based_operations
+    │
+    └─→ disconnect! → disconnected
+
+account_based_operations
+    │
+    └─→ initialize_order_handling! → account_based_orderflow
+```
+
+**State meanings**:
+- `virgin`: No connection
+- `ready`: Connected, basic functionality
+- `gateway_mode`: Multi-account gateway access
+- `lean_mode`: Minimal data collection
+- `account_based_operations`: Account/portfolio data loaded
+- `account_based_orderflow`: Order processing active
+
+---
+
+## MESSAGE SYSTEM (THE PROTOCOL)
+
+**Sending messages**:
+```ruby
+# Method 1: Send symbol
+ib.send_message :PlaceOrder, order: my_order, contract: my_contract
+
+# Method 2: Send class
+ib.send_message IB::Messages::Outgoing::PlaceOrder, order: my_order, contract: my_contract
+
+# Method 3: Use instance
+msg = IB::Messages::Outgoing::PlaceOrder.new(order: my_order, contract: my_contract)
+ib.send_message msg
+```
+
+**Receiving messages** (subscribe to events):
+```ruby
+# Subscribe to a message type
+subscription_id = ib.subscribe(:OrderStatus) do |msg|
+  puts "Order #{msg.order_id}: #{msg.status}"
+end
+
+# Wait for a specific message type
+ib.wait_for :OrderStatus, timeout: 5
+
+# Access received messages
+ib.received[:OrderStatus].each { |msg| ... }
+```
+
+**Message structure**:
+- Outgoing messages: defined in `lib/ib/messages/outgoing/`
+- Incoming messages: defined in `lib/ib/messages/incoming/`
+- Messages use `def_message` macro to generate classes
+- Each message has an ID and version for protocol compatibility
+
+---
+
+## PLUGIN SYSTEM (EXTENSIBILITY)
+
+**What plugins do**: Extend `IB::Connection` with additional methods by reopening the module.
+
+**How to use**:
+```ruby
+# Activate plugin(s)
+ib.activate_plugin :verify, :market_price, :connection_tools
+
+# Now methods from those plugins are available
+contract = IB::Stock.new(symbol: 'GE')
+verified = contract.verify  # provided by :verify plugin
+price = contract.market_price  # provided by :market_price plugin
+```
+
+**How plugins are written**:
+```ruby
+# plugins/ib/my_plugin.rb
+module IB
+  module Connection
+    def my_custom_method
+      # Can access @socket, send_message, etc.
+      send_message :SomeRequest
+    end
+  end
+end
+```
+
+**Common plugins**:
+- `connection-tools`: Ensures active connection
+- `verify`: Fetch contract details from TWS
+- `managed-accounts`: Fetch account/portfolio data
+- `market-price`: Get current market price
+- `advanced-account`: Account-based trading operations
+- `greeks`: Option risk calculations
+- `option-chain`: Build option chains
+
+---
+
+## MODELS (DATA STRUCTURES)
+
+**Contracts** (base: `IB::Contract`):
+```ruby
+stock = IB::Stock.new(symbol: 'GE', exchange: 'SMART', currency: 'USD')
+option = IB::Option.new(symbol: 'GE', strike: 50, right: 'CALL', expiry: '20240120')
+future = IB::Future.new(symbol: 'ES', expiry: '202403')
+```
+
+**Orders**:
+```ruby
+order = IB::Order.new(
+  total_quantity: 100,
+  action: :buy,
+  order_type: 'LMT',
+  limit_price: 35.0
+)
+
+# Place order
+local_id = ib.place_order(order, stock)
+```
+
+**Order methods on Connection**:
+- `place_order(order, contract)`: Place new order
+- `modify_order(order, contract)`: Modify existing order
+- `cancel_order(*local_ids)`: Cancel order(s)
+
+---
+
+## TESTING PATTERNS
+
+**Test setup**:
+```ruby
+# spec/spec_helper.rb loads:
+require 'spec_helper'
+
+# Constants available:
+OPTS[:connection]  # Hash from spec.yml
+ACCOUNT            # Account ID from spec.yml
+SAMPLE             # IB::Stock from spec.yml
+
+# Example test:
+describe IB::Stock do
+  subject { IB::Stock.new(symbol: 'GE') }
+
+  it "verifies contract" do
+    verified = subject.verify
+    expect(verified).to be_truthy
+  end
+end
+```
+
+**Running tests**:
+```bash
+# All tests
+bundle exec rspec
+
+# Single file
+bundle exec rspec spec/ib/contract_spec.rb
+
+# Focused (only tests with :focus tag or fit/fdescribe)
+bundle exec rspec --tag focus
+```
+
+**IMPORTANT**: Tests require valid IB credentials in `spec/spec.yml`:
+```yaml
+:connection:
+  :port: 4002
+  :host: 127.0.0.1
+  :account: DU123456  # Your paper account ID
+```
+
+---
+
+## CONSOLE USAGE
+
+```bash
+# Start console (connects to Gateway by default)
+./console g    # or ./console t for TWS
+
+# In console:
+C               # => IB::Connection.current instance
+C.received     # => Hash of received messages
+C.plugins      # => Array of active plugins
+
+# Example session:
+> contract = IB::Stock.new(symbol: 'GE')
+> contract.verify
+> contract.market_price
+```
+
+---
+
+## CODE PATTERNS TO RECOGNIZE
+
+**1. Event subscription pattern**:
+```ruby
+ib.subscribe(:MessageName) { |msg| ... }
+```
+
+**2. Wait for response pattern**:
+```ruby
+ib.send_message :Request
+ib.wait_for :Response
+```
+
+**3. Plugin activation pattern**:
+```ruby
+ib.activate_plugin :plugin_name
+```
+
+**4. Connection state transitions**:
+```ruby
+ib.try_connection!        # Connect
+ib.initialize_managed_accounts!  # Load account data
+```
+
+**5. Order placement**:
+```ruby
+local_id = ib.place_order(order, contract)
+ib.wait_for :OpenOrder
+```
+
+---
+
+## COMMON OPERATIONS
+
+**Get contract details**:
+```ruby
+ib.activate_plugin :verify
+contract = IB::Stock.new(symbol: 'GE')
+details = contract.verify  # Returns array of Contract objects
+```
+
+**Get current price**:
+```ruby
+ib.activate_plugin :market_price
+contract = IB::Stock.new(symbol: 'GE')
+price = contract.market_price
+```
+
+**Place order**:
+```ruby
+contract = IB::Stock.new(symbol: 'GE')
+order = IB::Order.new(limit_price: 35.0, order_type: 'LMT', total_quantity: 100, action: :buy)
+ib.place_order(order, contract)
+```
+
+**Get account/portfolio data**:
+```ruby
+ib.activate_plugin :managed_accounts
+ib.get_account_data
+ib.portfolio_values  # Hash of portfolio positions
+```
+
+---
+
+## DEBUGGING NEW MESSAGES
+
+When implementing a new message type:
+
+1. Uncomment line 37 in `lib/ib/messages/incoming/abstract_message.rb` to see raw TWS output
+2. Use the console (`./console`) to test
+3. Send the request and inspect `C.received[:MessageName]`
+4. Check the buffer attribute for unparsed data
+
+---
+
+## KEY DEPENDENCIES
+
+- **Zeitwerk**: Modern Ruby autoloading (models in `models/ib/` are autoloaded)
+- **ActiveModel**: Base for data models
+- **Workflow**: State machine for Connection
+- **RSpec**: Testing framework
+- **Ox**: XML parsing for some messages
+
+---
+
+## API VERSIONS
+
+- Client version: 66 (API 9.71+)
+- Server version: 165+ (TWS 10.19+)
+- Protocol supports multiple IB API versions via message versioning
+
+---
+
+## MENTAL CHECKLIST FOR TASKS
+
+**Before modifying**:
+1. Read the relevant model or message definition first
+2. Check if a plugin already provides the functionality
+3. Understand the current workflow state
+
+**When adding new messages**:
+1. Define in `lib/ib/messages/outgoing/` (request) or `incoming/` (response)
+2. Use `def_message` macro with proper ID and version
+3. Test in console first, then write spec
+
+**When adding plugins**:
+1. Create file in `plugins/ib/`
+2. Reopen `IB::Connection` module
+3. Activate via `ib.activate_plugin :plugin_name`
+
+**When writing tests**:
+1. Ensure `spec/spec.yml` has valid credentials
+2. Use `SAMPLE` constant for test data
+3. Use `ib.wait_for` to wait for async responses

data/README.md

@@ -0,0 +1,114 @@
+# ib-api
+Ruby interface to Interactive Brokers' TWS API 
+
+Reimplementation of ib-ruby
+
+---
+__STATUS: Gem-Release is still pending
+
+---
+
+*    Zeitwerk integration.  
+*    Plugin's to ease automations
+---
+
+__Documentation: [https://ib-ruby.github.io/ib-doc/](https://ib-ruby.github.io/ib-doc/)__  (_work in progress_)
+
+----
+`ib-api`   offers a modular access to the TWS-API-Interface of Interactive Brokers.
+
+----
+
+Install in the usual way
+
+```
+$ gem install ib-api
+```
+
+In its plain vanilla usage, it just exchanges messages with the TWS. Any response is stored in the `received-array`.
+
+It needs just a few lines of code to place an order
+
+```ruby
+require 'ib-api'
+# connect with default parameters 
+ib =  IB::Connection.new 
+
+# define a contract to deal with
+the_stock =  IB::Stock.new symbol: 'TAP'
+
+# order 100 shares for 35 $ 
+limit_order = IB::Order.new  limit_price: 35, order_type: 'LMT',  total_quantity: 100, action: :buy
+ib.send_message :PlaceOrder,
+        :order => limit_order,
+        :contract => the_stock,
+        :local_id => ib.next_local_id
+
+# wait until the orderstate message returned
+ib.wait_for :OrderStatus
+
+# print the Orderstatus
+puts ib.recieved[:OrderStatus].to_human
+
+# => ["<OrderState: Submitted #17/1528367295 from 2000 filled 0.0/100.0 at 0.0/0.0 why_held >"]
+
+```
+
+## Plugins
+
+**IB-API** ships with simple plugins to facilitate automations 
+
+```ruby
+require 'ib-api'
+# connect with default parameters 
+ib =  IB::Connection.new do | c |
+  c.activate_plugin "verify"
+end
+
+g =  IB::Stock.new symbol: 'GE'
+puts g.verify.first.attributes
+{:symbol=>"GE", :sec_type=>"STK", :last_trading_day=>"", :strike=>0.0, :right=>"", :exchange=>"SMART", :currency=>"USD", :local_symbol=>"GE", :trading_class=>"GE", :con_id=>498843743, :multiplier=>0, :primary_exchange=>"NYSE", }
+```
+
+Currently implemented plugins
+
+* connection-tools: ensure that a connection is established and active
+* verify:  get contract details from the tws
+* symbols: use predefined symbols 
+* managed-accounts: fetch and organize account- and portfoliovalues
+* advanced-account: perform account-based previewing, opening, modifying and closing of Positions
+* process-orders: account-based bookkeeping of orders
+* auto-adjust: properly adjust the orderprice to the next valid min-tick of the contract
+* market-price: fetch the current market-price of a contract
+* eod:  retrieve EOD-Data for the given contract
+* greeks: read current option greeks
+* roll: easy rolling of futures and options
+* option-chain: build option-chains for given strikes and expiries 
+* spread-prototypes:  create limit, stop, market, etc. orders through prototypes
+* probability-of-expiring: calculate the probability of expiring for the option-contract
+
+
+## Minimal TWS-Version
+
+`ib-api` is tested via the _stable IB-Gateway_ (Version 10.33) and should work with any current tws-installation. 
+
+## Tests
+
+are invoked by 
+
+```
+bundle exec guard
+# or
+bundle exec rake spec
+```
+Integration tests on order-placements are not included. To run the test suite its thus safe to use a _real Account_.
+You have to edit `spec/spec.yml` and replace the `:account`-Setting with your own `AccountID`, even if you connect to a single account. 
+ 
+
+## Contributing
+
+Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Code of Conduct
+
+Everyone interacting in the Core project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/ib-api/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require "rake"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = Dir.glob("spec/**/*_spec.rb")
+  t.rspec_opts = "--format documentation"
+end
+
+task default: :spec

data/VERSION

@@ -0,0 +1 @@
+10.33.1

data/api.gemspec

@@ -0,0 +1,50 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "ib/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "ib-api"
+  spec.version       = IB::VERSION
+  spec.authors       = ["Hartmut Bischoff"]
+  spec.email         = ["topofocus@gmail.com"]
+  spec.license       = "MIT"
+
+  spec.summary       = %q{Ruby Implementation of the Interactive Brokers TWS API}
+  spec.description   = %q{Ruby Implementation of the Interactive Brokers TWS API}
+  spec.homepage      = "https://github.com/ib-ruby"
+  spec.required_ruby_version = ">= 3.0"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+#    spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/ib-ruby/ib-api"
+#    spec.metadata["changelog_uri"] = "https://github.com/ib-ruby/ib-api/CHANGELOG.md"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_dependency 'activesupport', '~> 6.0'
+  spec.add_dependency 'activemodel', '~> 7.0'
+  spec.add_dependency 'ox', '~> 2.14'
+  spec.add_dependency 'terminal-table', '~> 3.0'
+  spec.add_dependency 'zeitwerk', '~> 2.6'
+  spec.add_dependency 'workflow', '~> 3.1'
+
+end

data/bin/console

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+### loads the active-orient environment
+### and starts an interactive shell
+###
+### Parameter: t)ws | g)ateway (or number of port ) Default: Gateway ,
+###							client_id , Default 2000
+###
+### Define Parameter in  file console.yml
+###
+require 'bundler/setup'
+require 'yaml'
+
+require 'ib-api'
+
+class Array
+  # enables calling members of an array. which are hashes  by it name
+  # i.e
+  #
+  #  2.5.0 :006 > C.received[:OpenOrder].local_id
+  #   => [16, 17, 21, 20, 19, 8, 7]
+  #   2.5.0 :007 > C.received[:OpenOrder].contract.to_human
+  #    => ["<Bag: IECombo SMART USD legs:  >", "<Stock: GE USD>", "<Stock: GE USD>", "<Stock: GE USD>", "<Stock: GE USD>", "<Stock: WFC USD>", "<Stock: WFC USD>"]
+  #
+  # its included only in the console, for inspection purposes
+
+  def method_missing(method, *key)
+    unless method == :to_hash || method == :to_str #|| method == :to_int
+      return self.map{|x| x.public_send(method, *key)}
+    end
+
+  end
+end # Array
+
+class Object
+  def inspect
+    respond_to?(:to_human) ? to_human : super
+  end
+end
+
+# read items from console.yml
+  read_yml = -> (key) do
+		YAML::load_file( File.expand_path('../console.yml',__FILE__))[key]
+	end
+
+  puts
+  puts ">> IB-API Interactive Console <<"
+  puts '-'* 45
+  puts
+  puts "Namespace is IB ! "
+  puts
+  puts '-'* 45
+  include IB
+  require 'irb'
+  client_id = ARGV[1] || read_yml[:client_id]
+  specified_host = ARGV[0] || 'Gateway'
+	host =  case specified_host
+					when /^[gG]/ 
+						read_yml[:gateway]
+					when /^[Tt]/
+						read_yml[:tws]
+          else
+            raise "Specify target from console.yml: `g|t` instead of #{specified_host}"
+					end
+  ARGV.clear
+
+  C =  Connection.new  client_id: client_id, host: host
+  C.logger.level = Logger::WARN
+
+  C.subscribe(:Alert){ |m| puts "A: "+ m.message }
+  C.subscribe(:AccountUpdateTime){  }
+
+  C.received = true
+  C.activate_plugin :connection_tools, :symbols, :market_price,
+                    "order-prototypes", "spread-prototypes",
+                    "advanced_account", 'process_orders'
+  C.logger.level = Logger::INFO
+  puts C.workflow_state
+  C.get_account_data
+  C.request_open_orders
+  C.logger.level = Logger::ERROR
+  puts  "Connection established on  #{host}"
+
+  unless  C.received[:OpenOrder].blank?
+        puts "---------------------------------------- OpenOrders -------------------------------------------"
+        puts C.clients.map{ |c| c.orders.map &:to_human }.flatten.join("\n")
+  end
+  puts ""
+  puts  Terminal::Table.new title: 'Active Plugins',
+                             rows: C.plugins.delete_if{ |x| x =~ /\// }.sort.each_slice(4),
+                            style: { border: :unicode  }
+  puts
+  puts  "----> C    points to the connection-instance"
+  puts
+  puts '-'* 45
+
+  IRB.start(__FILE__)

data/bin/console.yml

@@ -0,0 +1,3 @@
+:gateway:  "localhost:4002"
+:tws: "tws:7496"
+:client_id: 2000

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here