ib-ruby

Ruby Implementation of the Interactive Brokers Trader Workstation (TWS) API v.965-967.

WARNING: This software is provided AS-IS with NO WARRANTY, express or implied. Your use of this software is at your own risk. It may contain any number of bugs, known or unknown, which might cause you to lose money if you use it. You've been warned.

This code is not sanctioned or supported by Interactive Brokers.

REQUIREMENTS:

Either the Interactive Brokers TWS or Gateway software must be installed and configured to allow API connections from the computer you plan to run ib-ruby on, which is typically localhost if you're running ib-ruby on the same machine as TWS.

As a rule of thumb, most recent version of ib-ruby gem only supports latest versions of TWS/Gateway API. Older versions of API are supported by previous gem versions:

ib-ruby gem TWS version API version 0.5.21 918-920 965 0.6.1 921-923 966 0.7.1 924+ 967

INSTALLATION:

From RubyGems

$ sudo gem install ib-ruby

From Source

$ git clone https://github.com/ib-ruby/ib-ruby
$ cd ib-ruby; rake gem:install

SYNOPSIS:

First, start up Interactive Broker's Trader Work Station or Gateway. Make sure it is configured to allow API connections on localhost. Note that TWS and Gateway listen to different ports, this library assumes connection to Gateway (localhost:4001) by default, this can changed via :host and :port options given to IB::Connection.new.

require 'ib-ruby'

ib = IB::Connection.new :port => 7496 # TWS on localhost
ib.subscribe(:Alert, :AccountValue) { |msg| puts msg.to_human }
ib.send_message :RequestAccountData
ib.wait_for :AccountDownloadEnd

ib.subscribe(:OpenOrder) { |msg| puts "Placed: #{msg.order}!" }
ib.subscribe(:ExecutionData) { |msg| puts "Filled: #{msg.execution}!" }
contract = IB::Models::Contract.new :symbol => 'WFC',
                                    :exchange => 'NYSE'
                                    :currency => 'USD',
                                    :sec_type => IB::SECURITY_TYPES[:stock]
buy_order = IB::Models::Order.new :total_quantity => 100,
                                  :limit_price => 21.00,
                                  :action => 'BUY',
                                  :order_type => 'LMT'
ib.place_order buy_order, contract
ib.wait_for :ExecutionData

Your code interacts with TWS via exchange of messages. Messages that you send to TWS are called 'Outgoing', messages your code receives from TWS - 'Incoming'.

First, you need to subscribe to incoming message types you're interested in using Connection#subscribe. The code block (or proc) given to #subscribe will be executed when an incoming message of the requested type is received from TWS, with the received message as its argument.

Then, you request specific data from TWS using Connection#send_message or place your order using Connection#place_order. TWS will respond with messages that you should have subscribed for, and these messages will be processed in a code block given to #subscribe.

In order to give TWS time to respond, you either run a message processing loop or just wait until Connection receives the messages type you requested.

See lib/ib-ruby/messages for a full list of supported incoming/outgoing messages and their attributes. The original TWS docs and code samples can be found in misc directory.

The sample scripts in bin directory provide examples of how common tasks can be achieved using ib-ruby. You may also want to look into spec/integration directory for more scenarios and examples of handling IB messages.

RUNNING TESTS:

The gem comes with a spec suit that may be used to test ib-ruby compatibility with your specific TWS/Gateway installation. The test suit should be run ONLY against your IB paper trading account. Running it against live account may result in financial losses.

In order to run tests, you should set up your IB paper trading connection parameters in 'spec/spec_helper' file. Modify account_name, host and port under section 'Your IB PAPER ACCOUNT'. Do not change the client_id.

Before running tests, you need to start your TWS/Gateway and allow API connection. You should not have any open/pending orders on your IB paper trading account prior to running tests, otherwise some tests will fail. Use 'bin/cancel_orders' script for bulk cancelling of open orders before running tests as needed.

You can easily create your own tests following the guide in 'spec/README'. Help the development! See 'spec/TODO' for the list of use cases/scenarios that still need to be tested.

LICENSE:

This software is available under the LGPL.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file LICENSE for full licensing details of GNU Lesser General Public License.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA