my-ib-api 0.0.1

data/lib/ib/symbols.rb

@@ -0,0 +1,35 @@
+# These modules are used to facilitate referencing of most popular IB Contracts.
+# For example, suppose you're explicitly creating such Contract in all your scripts:
+#    wfc = IB::Contract.new(:symbol => "WFC",
+#                           :exchange => "NYSE",
+#                           :currency => "USD",
+#                           :sec_type => :stock,
+#                           :description => "Wells Fargo Stock"),
+#
+# Instead, you can put this contract definition into 'ib/symbols/stocks' and just reference
+# it as IB::Symbols::Stock[:wfc] anywhere you need it.
+#
+# Note that the :description field is local to ib-ruby, and is NOT part of the standard TWS API.
+# It is never transmitted to IB. It's purely used clientside, and you can store any arbitrary
+# string that you may find useful there.
+
+module IB
+  module Symbols
+    def [] symbol
+      if contracts[symbol]
+        return contracts[symbol]
+      else
+        # symbol probably has not been predefined, tell user about it
+        file = self.to_s.split(/::/).last.downcase
+        msg = "Unknown symbol :#{symbol}, please pre-define it in lib/ib/symbols/#{file}.rb"
+        error msg, :symbol
+      end
+    end
+  end
+end
+
+require 'ib/symbols/forex'
+require 'ib/symbols/futures'
+require 'ib/symbols/stocks'
+require 'ib/symbols/options'
+require 'ib/symbols/bonds'

data/lib/ib/symbols/bonds.rb

@@ -0,0 +1,28 @@
+# Sample bond contract definitions
+module IB
+  module Symbols
+    module Bonds
+      extend Symbols
+
+      def self.contracts
+        @contracts ||= {
+          :abbey  => IB::Contract.new(:symbol => "ABBEY",
+                                   :currency => "USD",
+                                   :sec_type => :bond,
+                                   :description => "Any ABBEY bond"),
+
+          :ms => IB::Contract.new(:symbol => "MS",
+                                   :currency => "USD",
+                                   :sec_type => :bond,
+                                   :description => "Any Morgan Stanley bond"),
+
+          :wag => IB::Contract.new(:symbol => "WAG",
+                                   :currency => "USD",
+                                   :sec_type => :bond,
+                                   :description => "Any Wallgreens bond"),
+        }
+      end
+
+    end
+  end
+end

data/lib/ib/symbols/forex.rb

@@ -0,0 +1,41 @@
+module IB
+  module Symbols
+    module Forex
+      extend Symbols
+
+      def self.contracts
+        @contracts ||= define_contracts
+      end
+
+      private
+
+      # IDEALPRO is for orders over 20,000 and routes to the interbank quote stream.
+      # IDEAL is for smaller orders, and has wider spreads/slower execution... generally
+      # used for smaller currency conversions. IB::Symbols::Forex contracts are pre-defined
+      # on IDEALPRO, if you need something else please define forex contracts manually.
+      def self.define_contracts
+        @contracts = {}
+
+        # use combinations of these currencies for pre-defined forex contracts
+        currencies = [ "aud", "cad", "chf", "eur", "gbp", "hkd", "jpy", "nzd", "usd" ]
+
+        # create pairs list from currency list
+        pairs = currencies.product(currencies).
+          map { |pair| pair.join.upcase unless pair.first == pair.last }.compact
+
+        # now define each contract
+        pairs.each do |pair|
+          @contracts[pair.downcase.to_sym] = IB::Contract.new(
+            :symbol => pair[0..2],
+            :exchange => "IDEALPRO",
+            :currency => pair[3..5],
+            :sec_type => :forex,
+            :description => pair
+          )
+        end
+        
+        @contracts
+      end
+    end
+  end
+end

data/lib/ib/symbols/futures.rb

@@ -0,0 +1,117 @@
+# The Futures module tries to guess the front month future using a crude algorithm that
+# does not take into account expiry/rollover day. This will be valid most of the time,
+# but near/after expiry day the next quarter's contract takes over as the volume leader.
+
+module IB
+  module Symbols
+    module Futures
+      extend Symbols
+
+      # Find the next front month of quarterly futures.
+      # N.B. This will not work as expected during the front month before expiration, as
+      # it will point to the next quarter even though the current month is still valid!
+      def self.next_quarter_month time=Time.now
+        [3, 6, 9, 12].find { |month| month > time.month } || 3 # for December, next March
+      end
+
+      def self.next_quarter_year time=Time.now
+        next_quarter_month(time) < time.month ? time.year + 1 : time.year
+      end
+
+      # WARNING: This is currently broken. It returns the next
+      # quarterly expiration month after the current month. Many futures
+      # instruments have monthly contracts for the near months. This
+      # method will not work for such contracts; it will return the next
+      # quarter after the current month, even though the present month
+      # has the majority of the trading volume.
+      #
+      # For example, in early November of 2011, many contracts have the
+      # vast majority of their volume in the Nov 2011 contract, but this
+      # method will return the Dec 2011 contract instead.
+      #
+      def self.next_expiry time=Time.now
+        "#{ next_quarter_year(time) }#{ sprintf("%02d", next_quarter_month(time)) }"
+      end
+
+      # Convenience method; generates an IB::Contract instance for a futures
+      # contract with the given parameters.
+      #
+      # If expiry is nil, it will use the end month of the current
+      # quarter. This will be wrong for most contracts most of the time,
+      # since most contracts have the majority of their volume in a
+      # nearby intraquarter month.
+      #
+      # It is recommended that you specify an expiration date manually
+      # until next_expiry is fixed. Expiry should be a string in the
+      # format "YYYYMM", where YYYY is the 4 digit year and MM is the 2
+      # digit month. For example, November 2011 is "201111".
+      #
+      def self.future(base_symbol, exchange, currency, description="", expiry=nil)
+        IB::Contract.new :symbol => base_symbol,
+          :expiry => expiry || next_expiry,
+          :exchange => exchange,
+          :currency => currency,
+          :sec_type => SECURITY_TYPES[:future],
+          :description => description
+      end
+
+      def self.contracts
+        @contracts ||= {
+          :ym => IB::Contract.new(:symbol => "YM",
+                                  :expiry => next_expiry,
+                                  :exchange => "ECBOT",
+                                  :currency => "USD",
+                                  :sec_type => :future,
+                                  :description => "Mini-DJIA future"),
+
+          :es => IB::Contract.new(:symbol => "ES",
+                                  :expiry => next_expiry,
+                                  :exchange => "GLOBEX",
+                                  :currency => "USD",
+                                  :sec_type => :future,
+                                  :multiplier => 50,
+                                  :description => "E-Mini S&P 500 future"),
+
+          :gbp => IB::Contract.new(:symbol => "GBP",
+                                   :expiry => next_expiry,
+                                   :exchange => "GLOBEX",
+                                   :currency => "USD",
+                                   :sec_type => :future,
+                                   :multiplier => 62500,
+                                   :description => "British Pounds future"),
+
+          :eur => IB::Contract.new(:symbol => "EUR",
+                                   :expiry => next_expiry,
+                                   :exchange => "GLOBEX",
+                                   :currency => "USD",
+                                   :sec_type => :future,
+                                   :multiplier => 12500,
+                                   :description => "Euro FX future"),
+
+          :jpy => IB::Contract.new(:symbol => "JPY",
+                                   :expiry => next_expiry,
+                                   :exchange => "GLOBEX",
+                                   :currency => "USD",
+                                   :sec_type => :future,
+                                   :multiplier => 12500000,
+                                   :description => "Japanese Yen future"),
+
+          :hsi => IB::Contract.new(:symbol => "HSI",
+                                   :expiry => next_expiry,
+                                   :exchange => "HKFE",
+                                   :currency => "HKD",
+                                   :sec_type => :future,
+                                   :multiplier => 50,
+                                   :description => "Hang Seng Index future"),
+
+          :vix => IB::Contract.new(:symbol => "VIX",
+                                   :expiry => next_expiry,
+                                   :exchange => "CFE", #"ECBOT",
+                                   # :currency => "USD",
+                                   :sec_type => :future,
+                                   :description => "CBOE Volatility Index future")
+        }
+      end
+    end
+  end
+end

data/lib/ib/symbols/options.rb

@@ -0,0 +1,39 @@
+# Option contracts definitions.
+# TODO: add next_expiry and other convenience from Futures module.
+module IB
+  module Symbols
+    module Options
+      extend Symbols
+
+      def self.contracts
+        @contracts ||= {
+          :wfc20 => IB::Option.new(:symbol => "WFC",
+                                   :expiry => "201301",
+                                   :right => "CALL",
+                                   :strike => 20.0,
+                                   :description => "Wells Fargo 20 Call 2013-01"),
+          :aapl500 => IB::Option.new(:symbol => "AAPL",
+                                     :expiry => "201301",
+                                     :right => "CALL",
+                                     :strike => 500,
+                                     :description => "Apple 500 Call 2013-01"),
+          :z50 => IB::Option.new(:symbol => "Z",
+                                 :exchange => "LIFFE",
+                                 :expiry => "201301",
+                                 :right => "CALL",
+                                 :strike => 50.0,
+                                 :description => " FTSE-100 index 50 Call 2013-03"),
+          :spy75 => IB::Option.new(:symbol => 'SPY',
+                                   :expiry => "201301",
+                                   :right => "P",
+                                   :currency => "USD",
+                                   :strike => 75.0,
+                                   :description => "SPY 75.0 Put 2014-01"),
+          :spy100 => IB::Option.new(:osi => 'SPY 140118P00100000'),
+          :vix20 => IB::Option.new(:osi =>  'VIX 121121C00020000'),
+          :vxx40 => IB::Option.new(:osi =>  'VXX 121117C00040000'),
+        }
+      end
+    end
+  end
+end

data/lib/ib/symbols/stocks.rb

@@ -0,0 +1,37 @@
+# Frequently used stock contracts definitions
+# TODO: auto-request :ContractDetails from IB if unknown symbol is requested?
+module IB
+  module Symbols
+    module Stocks
+      extend Symbols
+
+      def self.contracts
+        @contracts ||= {
+          :aapl => IB::Contract.new(:symbol => "AAPL",
+                                    :currency => "USD",
+                                    :sec_type => :stock,
+                                    :description => "Apple Inc."),
+
+          :vxx => IB::Contract.new(:symbol => "VXX",
+                                   :exchange => "ARCA",
+                                   # :currency => "USD",
+                                   :sec_type => :stock,
+                                   :description => "iPath S&P500 VIX short term Futures ETN"),
+
+          :wfc => IB::Contract.new(:symbol => "WFC",
+                                   :exchange => "NYSE",
+                                   :currency => "USD",
+                                   :sec_type => :stock,
+                                   :description => "Wells Fargo"),
+
+          :wrong => IB::Contract.new(:symbol => "QEEUUE",
+                                     :exchange => "NYSE",
+                                     :currency => "USD",
+                                     :sec_type => :stock,
+                                     :description => "Non-existent stock"),
+        }
+      end
+
+    end
+  end
+end

data/lib/ib/version.rb

@@ -0,0 +1,6 @@
+require 'pathname'
+
+module IB
+  VERSION_FILE = Pathname.new(__FILE__).dirname + '../../VERSION' # :nodoc:
+  VERSION = VERSION_FILE.exist? ? VERSION_FILE.read.strip : nil
+end

data/lib/models/ib/bag.rb

@@ -0,0 +1,51 @@
+require 'models/ib/contract'
+
+module IB
+
+  # "BAG" is not really a contract, but a combination (combo) of securities.
+  # AKA basket or bag of securities. Individual securities in combo are represented
+  # by ComboLeg objects.
+  class Bag < Contract
+    # General Notes:
+    # 1. :exchange for the leg definition must match that of the combination order.
+    # The exception is for a STK legs, which must specify the SMART exchange.
+    # 2. :symbol => "USD" For combo Contract, this is an arbitrary value (like "USD")
+
+    validates_format_of :sec_type, :with => /\Abag\z/, :message => "should be a bag"
+    validates_format_of :right, :with => /\Anone\z/, :message => "should be none"
+    validates_format_of :expiry, :with => /\A\z/, :message => "should be blank"
+
+    def default_attributes
+      super.merge :sec_type => :bag #,:legs => Array.new,
+    end
+
+    def description
+      self[:description] || to_human
+    end
+
+    def to_human
+      "<Bag: #{[symbol, exchange, currency].join(' ')} legs: #{legs_description} >"
+    end
+
+    ### Leg-related methods
+
+    # TODO: Rewrite with legs and legs_description being strictly in sync...
+    # TODO: Find a way to serialize legs without references...
+    # IB-equivalent leg description.
+    def legs_description
+      self[:legs_description] || legs.map { |leg| "#{leg.con_id}|#{leg.weight}" }.join(',')
+    end
+
+    # Check if two Contracts have same legs (maybe in different order)
+    def same_legs? other
+      legs == other.legs ||
+        legs_description.split(',').sort == other.legs_description.split(',').sort
+    end
+
+    # Contract comparison
+    def == other
+      super && same_legs?(other)
+    end
+
+  end # class Bag
+end # IB

data/lib/models/ib/bar.rb

@@ -0,0 +1,45 @@
+module IB
+  # This is a single data point delivered by HistoricData or RealTimeBar messages.
+  # Instantiate with a Hash of attributes, to be auto-set via initialize in Model.
+  class Bar < IB::Model
+    include BaseProperties
+
+    has_one :contract # The bar represents timeseries info for this Contract
+
+    prop :open, #   The bar opening price.
+      :high, #   The high price during the time covered by the bar.
+      :low, #    The low price during the time covered by the bar.
+      :close, #  The bar closing price.
+      :volume, # Volume
+      :wap, #    Weighted average price during the time covered by the bar.
+      :trades, # int: When TRADES data history is returned, represents number
+      #           of trades that occurred during the time period the bar covers
+      :time, # TODO: convert into Time object?
+      #        The date-time stamp of the start of the bar. The format is
+      #        determined by the reqHistoricalData() formatDate parameter.
+      :has_gaps => :bool # Whether or not there are gaps in the data.
+
+      validates_numericality_of :open, :high, :low, :close, :volume
+
+    # Order comparison
+    def == other
+      super(other) ||
+        other.is_a?(self.class) &&
+        time == other.time &&
+        open == other.open &&
+        high == other.high &&
+        low == other.low &&
+        close == other.close &&
+        wap == other.wap &&
+        trades == other.trades &&
+        volume == other.volume
+    end
+
+    def to_human
+      "<Bar: #{time} wap #{wap} OHLC #{open} #{high} #{low} #{close} " +
+        (trades ? "trades #{trades}" : "") + " vol #{volume} gaps #{has_gaps}>"
+    end
+
+    alias to_s to_human
+  end # class Bar
+end # module IB

data/lib/models/ib/combo_leg.rb

@@ -0,0 +1,103 @@
+module IB
+
+  # ComboLeg is essentially a join Model between Combo (BAG) Contract and
+  # individual Contracts (securities) that this BAG contains.
+  class ComboLeg < IB::Model
+    include BaseProperties
+
+    # BAG Combo Contract that contains this Leg
+    belongs_to :combo, :class_name => 'Contract'
+    # Contract that constitutes this Leg
+    belongs_to :leg_contract, :class_name => 'Contract', :foreign_key => :leg_contract_id
+
+    # General Notes:
+    # 1. The exchange for the leg definition must match that of the combination order.
+    # The exception is for a STK leg definition, which must specify the SMART exchange.
+
+    prop :con_id, # int: The unique contract identifier specifying the security.
+      :ratio, # int: Select the relative number of contracts for the leg you
+      #              are constructing. To help determine the ratio for a
+      #              specific combination order, refer to the Interactive
+      #              Analytics section of the User's Guide.
+
+      :exchange, # String: exchange to which the complete combo order will be routed.
+      # For institutional customers only! For stock legs when doing short sale
+      :short_sale_slot, # int: 0 - retail(default), 1 = clearing broker, 2 = third party
+      :designated_location, # String: Only for shortSaleSlot == 2.
+      #                    Otherwise leave blank or orders will be rejected.
+      :exempt_code, # int: ?
+      [:side, :action] => PROPS[:side], # String: Action/side: BUY/SELL/SSHORT/SSHORTX
+      :open_close => PROPS[:open_close]
+    # int: Whether the order is an open or close order. Values:
+    # SAME = 0 Same as the parent security. The only option for retail customers.
+    # OPEN = 1 Open. This value is only valid for institutional customers.
+    # CLOSE = 2 Close. This value is only valid for institutional customers.
+    # UNKNOWN = 3
+
+    # Extra validations
+    validates_numericality_of :ratio, :con_id
+    validates_format_of :designated_location, :with => /\A\z/,
+      :message => "should be blank or orders will be rejected"
+
+    def default_attributes
+      super.merge :con_id => 0,
+        :ratio => 1,
+        :side => :buy,
+        :open_close => :same, # The only option for retail customers.
+        :short_sale_slot => :default,
+        :designated_location => '',
+        :exchange => 'SMART', # Unless SMART, Order modification fails
+        :exempt_code => -1
+    end
+
+    #  Leg's weight is a combination of action and ratio
+    def weight
+      side == :buy ? ratio : -ratio
+    end
+
+    def weight= value
+      value = value.to_i
+      if value > 0
+        self.side = :buy
+        self.ratio = value
+      else
+        self.side = :sell
+        self.ratio = -value
+      end
+    end
+
+    # Some messages include open_close, some don't. wtf.
+    def serialize *fields
+      [con_id,
+       ratio,
+       side.to_sup,
+       exchange,
+       (fields.include?(:extended) ?
+        [self[:open_close],
+         self[:short_sale_slot],
+         designated_location,
+         exempt_code] :
+        [])
+       ].flatten
+    end
+
+    def to_human
+      "<ComboLeg: #{side} #{ratio} con_id #{con_id} at #{exchange}>"
+    end
+
+    # Order comparison
+    def == other
+      super(other) ||
+        other.is_a?(self.class) &&
+        con_id == other.con_id &&
+        ratio == other.ratio &&
+        open_close == other.open_close && 
+        short_sale_slot == other.short_sale_slot &&
+        exempt_code == other.exempt_code &&
+        side == other.side &&
+        exchange == other.exchange &&
+        designated_location == other.designated_location
+    end
+
+  end # ComboLeg
+end # module IB