ib-api 10.33.1

data/plugins/ib/order-flow.rb

@@ -0,0 +1,157 @@
+module IB
+
+=begin
+
+Plugin to support a simple Order-Flow
+
+Public API
+==========
+
+Extends IB::Order
+
+* check_margin
+  * depends on a previously submitted `what-if' order
+  * on success it returns the order-object for further processing, otherwise nil.
+* place
+  * submit the order
+  * return a order-object for further processing
+* modify
+  * modify price or quantity of the submitted order
+* cancel
+  * submit a cancel request
+
+=end
+ module OrderFlow
+    # Placement
+    #
+    # The Order is only placed, if local_id is not set
+    #
+    # Modifies the Order-Object and returns the assigned local_id
+    def place
+      connection = IB::Connection.current
+      error "Unable to place order, next_local_id not known" unless connection.next_local_id
+      error "local_id present. Order is already placed.  Do you want to modify?"  unless  local_id.nil?
+   #   self.client_id = connection.client_id
+      self.local_id = connection.next_local_id
+      connection.next_local_id += 1
+      self.placed_at = Time.now
+      #connection.place_order self.dup.then{|y| y.contract = nil; y}, contract
+      modify
+    end
+
+    # Modify Order (convenience wrapper for send_message :PlaceOrder), returns order record received trom tws
+    def modify
+      error "Unable to modify order; local_id not specified" if local_id.nil?
+      error "Unable to place order, contract has to be specified" unless contract.is_a?( IB::Contract )
+
+      ib = IB::Connection.current
+      q =  Queue.new
+      is =  ib.subscribe( :OpenOrder ) do | msg |
+        puts msg.to_human
+        if msg.order.local_id ==  local_id
+          q << msg.order
+        end
+      end
+      ia =  ib.subscribe( :Alert ) do | msg|
+        ib.logger.error msg.to_human
+      end
+
+      self.modified_at =  Time.now
+      ib.send_message :PlaceOrder,
+                      :local_id => local_id,
+                      :order => self.dup.then{|y| y.contract = nil; y},
+                      :contract => if contract.con_id.to_i > 0
+                                      Contract.new con_id: the_contract.con_id,
+                                                 exchange: the_contract.exchange
+                                   else
+                                      contract
+                                   end
+
+      th =  Thread.new{ sleep 1 ; q.close  }
+      received_order = q.pop        # synchronize
+      ib.unsubscribe ia, is
+      if q.closed?
+        error "order #{to_human} is not accepted",  :reader
+        self  # return original error after error handling
+      else
+        Thread.kill th
+        q.close
+        received_order
+      end
+    end
+
+    # returns the order if the margin-requirements are met
+    #
+    # Details of the test are published in the log (level: LOGGER::INOT)
+    #
+    # typical setup
+    # ```ruby
+    #  ib =  IB::Connection.new
+    #  ib.activate_plugin ...
+    #  u =  ib.clients.last
+    #  submitted_order = u.preview( order: some_order, contract: some_contract ) 
+    #                     .check_margin( 0.25 ) &.place
+    #  place order only if after its placement Equity-with-loan ist minimal 25 percent higher then the margin requirements
+    #  i.e.  the margin utilization is max. 75 %. 
+    # 
+    # ```
+    def check_margin treshold = 0.1
+      error "Unable to check margin, forcast is not initialized" if order_state.nil? or order_state.init_margin_after.nil?
+      utilization = order_state.init_margin_after / order_state.equity_with_loan_after
+     if  1 - utilization >  treshold 
+       Connection.current.logger.info "Margin OK:  #{action} #{total_quantity} of #{contract.to_human}: requirements: #{order_state.init_margin_change.round} #{contract.currency} equals to #{utilization.round(1) *100} % margin utilization"
+       self 
+     else
+       Connection.current.logger.info "Margin requirements NOT met, utilization: #{utilization.round(2) *100} % ( margin requirement: #{order_state.init_margin_change.round} #{contract.currency})"
+       nil
+     end
+    end
+    #
+    # Auto Adjust implements a simple algorithm  to ensure that an order is accepted
+
+    # It reads `contract_detail.min_tick`.
+    #
+    # For min-tick smaller then 0.01, the value is rounded to the next higer digit.
+    #
+    # The method mutates the Order-Object.
+    #
+    # | min-tick     |  round     |
+    # |--------------|------------|
+    # |   10         |   110      |
+    # |    1         |   111      |
+    # |    0.1       |   111.1    |
+    # |    0.01      |   111.11   |
+    # |    0.001     |   111.111  |
+    # |    0.0001    |   111.111  |
+    # |--------------|------------|
+    #
+    def auto_adjust
+      # lambda to perform the calculation
+      adjust_price = ->(a,b) do
+        count = -Math.log10(b).round.to_i
+        count = count -1 if count > 2
+        a.round count
+
+      end
+
+
+      error "No Contract provided to Auto adjust" unless contract.is_a? IB::Contract
+
+      unless contract.is_a? IB::Bag
+
+        min_tick = contract.then{ |y| y.contract_detail.is_a?( IB::ContractDetail ) ? y.contract_detail.min_tick : y.verify.first.contract_detail.min_tick }
+        # there are two attributes to consider: limit_price and aux_price
+        # limit_price +  aux_price may be nil or an empty string. Then ".to_f.zero?" becomes true
+        self.limit_price = adjust_price.call(limit_price.to_d, min_tick) unless limit_price.to_f.zero?
+        self.aux_price   = adjust_price.call(aux_price.to_d, min_tick)   unless aux_price.to_f.zero?
+      end
+    end
+
+ end # module OrderFlow
+
+  class Order
+    include OrderFlow
+  end  # class
+#  Connection.current.activate_plugin 'process-orders'
+end # module IB
+

data/plugins/ib/order-prototypes/abstract.rb

@@ -0,0 +1,67 @@
+# These modules are used to facilitate referencing of most common Ordertypes
+
+module IB
+  module OrderPrototype
+
+
+
+
+    def order **fields
+
+      # special treatment of size:  positive numbers --> buy order, negative: sell 
+      if fields[:size].present? && fields[:action].blank?
+        error "Size = 0 is not possible" if fields[:size].zero?
+        fields[:action] = fields[:size] >0 ? :buy  : :sell
+        fields[:size] = fields[:size].abs
+      end
+      # change aliases  to the original. We are modifying the fields-hash.
+      fields.keys.each{|x| fields[aliases.key(x)] = fields.delete(x) if aliases.has_value?(x)}
+      # inlcude defaults (arguments override defaults)
+      the_arguments = defaults.merge fields
+      # check if requirements are fullfilled
+      necessary = requirements.keys.detect{|y| the_arguments[y].nil?}
+      if necessary.present?
+        msg =self.name + ".order -> A necessary field is missing: #{necessary}: --> #{requirements[necessary]}"
+        error msg, :args, nil
+      end
+      if alternative_parameters.present?
+        unless ( alternative_parameters.keys  & the_arguments.keys ).size == 1
+          msg =self.name + ".order -> One of the alternative fields needs to be specified: \n\t:" +
+            "#{alternative_parameters.map{|x| x.join ' => '}.join(" or \n\t:")}"
+          error msg, :args, nil
+        end
+      end
+
+      # initialise order with given attributes  
+      IB::Order.new the_arguments
+    end
+
+    def alternative_parameters
+      {}
+    end
+    def requirements
+      { action: IB::VALUES[:side], total_quantity: 'also aliased as :size' }
+    end
+
+    def defaults
+      {  tif: :good_till_cancelled }
+    end
+
+    def optional
+      { account: 'Account(number) to trade on' }
+    end
+
+    def aliases
+      {  total_quantity: :size }
+    end
+
+    def parameters
+      the_output = ->(var){ var.map{|x| x.join(" --> ") }.join("\n\t: ")}
+
+      "Required : " + the_output[requirements] + "\n --------------- \n" +
+        "Optional : " + the_output[optional] + "\n --------------- \n" 
+
+    end
+
+  end
+end

data/plugins/ib/order-prototypes/adaptive.rb

@@ -0,0 +1,40 @@
+
+module IB
+#  module OrderPrototype
+    module Adaptive
+      extend OrderPrototype
+      class << self
+
+      def defaults
+        Limit.defaults.merge algo_strategy: "Adaptive",
+                            algo_params: { "adaptivePriority" => "Normal" }
+      end
+
+      def aliases
+        Limit.aliases
+      end
+
+      def requirements
+        Limit.requirements
+      end
+
+
+      def summary
+  <<-HERE
+  The Adaptive Algo combines IB’s Smart routing capabilities with user-defined
+  priority settings in an effort to achieve further cost efficiency at the
+  point of execution. Using the Adaptive algo leads to better execution prices
+  on average than for regular limit or market orders.
+
+  Algo Strategy Value: Adaptive
+
+  adaptivePriority: String. The ‘Priority’ selector determines the time taken
+  to scan for better execution prices. The ‘Urgent’ setting scans only briefly,
+    while the ‘Patient’ scan works more slowly and has a higher chance of
+      achieving a better overall fill for your order.  Valid Value/Format:
+        Urgent > Normal > Patient
+  HERE
+      end
+      end
+    end
+end

data/plugins/ib/order-prototypes/all-in-one.rb

@@ -0,0 +1,46 @@
+module IB
+
+#Combo-Orders are used for NonGuaranteed Orders only.
+#»Normal« Option-Spreads are transmited by ordinary Limit-Orders
+    module Combo
+      ### Basic Order Prototype: Combo with two limits
+      extend OrderPrototype
+      class << self
+      def defaults
+  ## todo implement serialisation of  key/tag Hash to camelCased-keyValue-List 
+#      super.merge order_type: :limit , combo_params: { non_guaranteed: true} 
+  #      for the time being, we use the array representation
+      super.merge order_type: :limit , combo_params: [ ['NonGuaranteed', true] ]
+      end
+
+
+      def requirements
+        Limit.requirements
+      end
+
+      def aliases
+        Limit.aliases
+      end
+
+
+      def summary
+  <<-HERE
+  Create combination orders. It is constructed through  options, stock and futures legs 
+  (stock legs can be included if the order is routed through SmartRouting). 
+  
+  Although a combination/spread order is constructed of separate legs, it is executed 
+  as a single transaction if it is routed directly to an exchange. For combination orders 
+  that are SmartRouted, each leg may be executed separately to ensure best execution. 
+
+  The »NonGuaranteed«-Flag is set to "false". A Pair of two securites should always be
+  routed »Guaranteed«, otherwise separate orders are prefered.
+
+  If a Bag-Order with »NonGuarateed :true« should be submitted, the Order-Type would be 
+  REL+MKT, LMT+MKT, or REL+LMT 
+  --------
+  Products: Options, Stocks, Futures
+  HERE
+      end # def
+      end # class
+    end # module combo
+end  # module ib

data/plugins/ib/order-prototypes/combo.rb

@@ -0,0 +1,46 @@
+module IB
+
+#Combo-Orders are used for NonGuaranteed Orders only.
+#»Normal« Option-Spreads are transmited by ordinary Limit-Orders
+    module Combo
+      ### Basic Order Prototype: Combo with two limits
+      extend OrderPrototype
+      class << self
+      def defaults
+  ## todo implement serialisation of  key/tag Hash to camelCased-keyValue-List 
+#      super.merge order_type: :limit , combo_params: { non_guaranteed: true} 
+  #      for the time being, we use the array representation
+      super.merge order_type: :limit , combo_params: [ ['NonGuaranteed', true] ]
+      end
+
+
+      def requirements
+        Limit.requirements
+      end
+
+      def aliases
+        Limit.aliases
+      end
+
+
+      def summary
+  <<-HERE
+  Create combination orders. It is constructed through  options, stock and futures legs 
+  (stock legs can be included if the order is routed through SmartRouting). 
+  
+  Although a combination/spread order is constructed of separate legs, it is executed 
+  as a single transaction if it is routed directly to an exchange. For combination orders 
+  that are SmartRouted, each leg may be executed separately to ensure best execution. 
+
+  The »NonGuaranteed«-Flag is set to "false". A Pair of two securites should always be
+  routed »Guaranteed«, otherwise separate orders are prefered.
+
+  If a Bag-Order with »NonGuarateed :true« should be submitted, the Order-Type would be 
+  REL+MKT, LMT+MKT, or REL+LMT 
+  --------
+  Products: Options, Stocks, Futures
+  HERE
+      end # def
+      end # class
+    end # module combo
+end  # module ib

data/plugins/ib/order-prototypes/forex.rb

@@ -0,0 +1,40 @@
+module IB
+#  module UseOrder
+    module  ForexLimit
+      extend OrderPrototype
+      class << self
+
+
+      def defaults
+    super.merge order_type: :limit , tif: :day
+      end
+
+
+      def requirements
+  super.merge cash_qty: '(true/false) to indicate to let IB calculate the cash-quantity of the alternate currency'
+     end
+
+
+      def summary
+  <<-HERE
+  Forex orders can be placed in denomination of second currency in pair using cashQty field.
+  Don't specify a limit-price to force immidiate execution.
+  HERE
+      end
+      end
+=begin
+2.5.0 :001 > f =  Symbols::Forex[:eurusd]
+ => #<IB::Contract:0x0000000003299458 @attributes={"symbol"=>"EUR", "exchange"=>"IDEALPRO", "currency"=>"USD", "sec_type"=>"CASH", "created_at"=>2018-01-20 05:21:01 +0100, "updated_at"=>2018-01-20 05:21:01 +0100, "con_id"=>0, "right"=>"", "include_expired"=>false}, @description="EURUSD"> 
+
+2.5.0 :002 > uf =  ForexLimit.order action: :buy, size: 15000, cash_qty: true
+{:action=>:buy, :cash_qty=>true, :total_quantity=>15000}
+ => #<IB::Order:0x0000000002f45a40 @attributes={"tif"=>"DAY", "order_type"=>"LMT", "side"=>"B", "cash_qty"=>true, "total_quantity"=>15000, "created_at"=>2018-01-20 05:21:06 +0100, "updated_at"=>2018-01-20 05:21:06 +0100, "active_start_time"=>"", "active_stop_time"=>"", "algo_strategy"=>"", "algo_id"=>"", "auction_strategy"=>0, "conditions"=>[], "continuous_update"=>0, "delta_neutral_designated_location"=>"", "delta_neutral_con_id"=>0, "delta_neutral_settling_firm"=>"", "delta_neutral_clearing_account"=>"", "delta_neutral_clearing_intent"=>"", "designated_location"=>"", "display_size"=>0, "discretionary_amount"=>0, "etrade_only"=>true, "exempt_code"=>-1, "ext_operator"=>"", "firm_quote_only"=>true, "not_held"=>false, "oca_type"=>0, "open_close"=>1, "opt_out_smart_routing"=>false, "origin"=>0, "outside_rth"=>false, "parent_id"=>0, "random_size"=>false, "random_price"=>false, "scale_auto_reset"=>false, "scale_random_percent"=>false, "scale_table"=>"", "short_sale_slot"=>0, "solicided"=>false, "transmit"=>true, "trigger_method"=>0, "what_if"=>false, "leg_prices"=>[], "algo_params"=>{}, "combo_params"=>[], "soft_dollar_tier_params"=>{"name"=>"", "val"=>"", "display_name"=>""}}, @order_states=[#<IB::OrderState:0x0000000002f44258 @attributes={"status"=>"New", "filled"=>0, "remaining"=>0, "price"=>0, "average_price"=>0, "created_at"=>2018-01-20 05:21:06 +0100, "updated_at"=>2018-01-20 05:21:06 +0100}>]> 
+ 2.5.0 :004 > C.place_order uf, f
+ => 4 
+ 2.5.0 :005 > 05:21:23.606 Got message 4 (IB::Messages::Incoming::Alert)
+ I, [2018-01-20T05:21:23.606819 #31020]  INFO -- : TWS Warning 10164: Traders are responsible for understanding cash quantity details, which are provided on a best efforts basis only.
+ Restriction is specified in Precautionary Settings of Global Configuration/Presets.
+
+=end
+    end
+end

data/plugins/ib/order-prototypes/limit.rb

@@ -0,0 +1,193 @@
+
+module IB
+    module Limit
+      extend OrderPrototype
+      class << self
+
+      def defaults
+    super.merge order_type: :limit
+      end
+
+      def aliases
+  super.merge  limit_price: :price
+      end
+
+      def requirements
+  super.merge limit_price: "also aliased as :price"
+      end
+
+
+      def summary
+  <<-HERE
+  A Limit order is an order to buy or sell at a specified price or better. 
+  The Limit order ensures that if the order fills, it will not fill at a price less favorable than 
+  your limit price, but it does not guarantee a fill. 
+  It appears in the orderbook.
+  HERE
+      end
+      end
+    end
+    module  Discretionary
+      extend OrderPrototype
+      class << self
+
+    def defaults
+     Limit.defaults
+    end
+
+      def aliases
+  Limit.aliases.merge  discretionary_amount: :dc
+      end
+
+      def requirements
+  Limit.requirements
+      end
+
+      def optional
+   super.merge discretionary_amount: :decimal
+      end
+
+      def summary
+  <<-HERE
+  A Discretionary order is a Limitorder submitted with a hidden, 
+  specified 'discretionary' amount off the limit price which  may be used
+  to increase the price range over which the limit order is eligible to execute.
+  The market sees only the limit price.
+  The discretionary amount adds to the given limit price. The main effort is
+  to hide your real intentions from the public. Discretionary orders can be placed
+  for stocks and option on us exchanges, using 'SMART' routing.
+  HERE
+      end
+
+      def example
+  <<-HERE
+  You want to by a stock for 65 $ or less. Its trading is volatile, the spread is large.
+  There is a technical resistence at 64.5 $ and you think, that there will be a price
+  floor somewhere between 64.5 and 65 $. You place a limit order
+  at 64.5 $, which appears in the order book. Secretly, you instruct your broker to
+  fill the order, if the price is lower then 65 $. Chances for a filling are inceased.
+
+  ```
+  dc_order =  IB::Discretionary.order size: 1000, price: 65, dc: 0.5
+  account.place order: dc_order, contract: IB::Stock.new( symbol: 'BN' )
+  ```
+  HERE
+      end
+      end
+    end
+#  module OrderPrototype
+    module  Sweep2Fill
+      extend OrderPrototype
+      class << self
+
+      def defaults
+    super.merge order_type: ':limit' , tif: :day, sweep_to_fill: true
+      end
+
+      def aliases
+  Limit.aliases 
+      end
+
+      def requirements
+  Limit.requirements
+      end
+
+
+      def summary
+  <<-HERE
+  Sweep-to-fill orders are useful when a trader values speed of execution over price. A sweep-to-fill
+  order identifies the best price and the exact quantity offered/available at that price, and 
+  transmits the corresponding portion of your order for immediate execution. Simultaneously it 
+  identifies the next best price and quantity offered/available, and submits the matching quantity 
+  of your order for immediate execution.
+
+  ------------------------
+        Products: CFD, STK, WAR (SMART only)
+
+  HERE
+      end
+      end
+    end
+    module  LimitIfTouched
+      extend OrderPrototype
+      class << self
+
+      def defaults
+    Limit.defaults.merge order_type: :limit_if_touched
+      end
+
+      def aliases
+  Limit.aliases.merge  aux_price: :trigger_price 
+      end
+
+      def requirements
+  Limit.requirements.merge aux_price: 'also aliased as :trigger_price ' 
+      end
+
+
+      def summary
+  <<-HERE
+  A Limit if Touched is an order to buy (or sell) a contract at a specified price or better, 
+  below (or above) the market. This order is held in the system until the trigger price is touched. 
+  An LIT order is similar to a stop limit order, except that an LIT sell order is placed above 
+  the current market price, and a stop limit sell order is placed below. 
+  HERE
+      end
+      end
+    end
+
+
+    module  LimitOnClose
+      extend OrderPrototype
+      class << self
+
+      def defaults
+    Limit.defaults.merge order_type: :limit_on_close 
+      end
+
+      def aliases
+  Limit.aliases 
+      end
+
+      def requirements
+  Limit.requirements 
+      end
+
+
+      def summary
+  <<-HERE
+  A Limit-on-close (LOC) order will be submitted at the close and will execute if the 
+  closing price is at or better than the submitted limit price. 
+  HERE
+      end
+      end
+    end
+    
+    module  LimitOnOpen
+      extend OrderPrototype
+      class << self
+
+      def defaults
+    super.merge order_type: :limit_on_open , tif: :opening_price
+      end
+
+      def aliases
+  Limit.aliases 
+      end
+
+      def requirements
+  Limit.requirements
+      end
+
+
+      def summary
+  <<-HERE
+  A Limit-on-Open (LOO) order combines a limit order with the OPG time in force to create an 
+  order that is submitted at the market's open, and that will only execute at the specified 
+  limit price or better. Orders are filled in accordance with specific exchange rules. 
+  HERE
+      end
+      end
+    end
+ # end
+end