Connect a Java trading client to Interactive Brokers

LessonThis is a lesson restated in new words. Any figure in it is an example from the source, not this desk's record.

A Java program talks to Interactive Brokers only after three pieces are in place: a running Gateway or Trader Workstation, the API jar on the project classpath, and a class that receives callbacks. The lecture’s first milestone is a socket that stays open and prints that the server accepted the client. It is not an order, and it is not a gain figure.

Why it matters

The series is a from-scratch grid-style bot, published as a repository named Aurelius, aimed first at cryptocurrency contracts and able to hold other contracts too. Interactive Brokers is the broker on the other side of the socket. An account can be opened without a fee in the lecture’s account, and streaming market data can be requested from Java. Two desktop pieces matter. Gateway is the lighter process for orders and streaming data. Trader Workstation is the terminal for looking at a book and placing orders by hand. The lecture compares that terminal, loosely, with a small Bloomberg-style screen. You do not need the metaphor. You need the process running before eConnect is called.

The idea in plain words

In Eclipse the lecture creates a Java project named Aurelius, copies the API jar into the project, and adds it as an external jar on the classpath. The test that the jar is visible is a one-line construction of a Contract from com.ib.client. The editor’s import hint is the confirmation. A launcher class then needs the usual main method. A launch configuration pointed at that class, plus a println of “ping,” proves the project runs before any broker code does. Other editors are fine. Eclipse is only what the lecture clicked through. Java’s extra ceremony, relative to Python, is acknowledged. The lecture’s reason for paying it is speed. No timing number is given.

Reading the socket is a controller that implements EWrapper. The unimplemented-method fill adds a long list of callbacks. Those methods are where the server pushes changes: a price tick, a position, a connection acknowledgement. The lecture maps a Bitcoin price request to the tick-price callback, and it maps a successful connect to connectAck, which prints “Connected.” The print is not cosmetic. It runs because the server invoked the callback.

Writing to the socket is an EClientSocket held on the controller. Input and output loggers are constructed because the API expects them. The lecture barely uses them, and says a console print is enough when you want a connection time or an error string. A small handler class, copied from the repository rather than derived on camera, implements the logging hooks. The controller’s constructor passes itself, as the wrapper, plus the two loggers, into that handler. One object can then send requests and receive replies.

The port is not invented in code. In Gateway it sits under configuration. In Trader Workstation it sits under the API settings reached from the gear icon. The lecture reads that socket port and, in the sample call, uses host 127.0.0.1, port 4002, and client id 0. The host is the same machine. The client id marks this session.

How to use it

Install matching versions first, 10.2 or newer if you need crypto contracts. Start Gateway or Trader Workstation and confirm the socket port in the API settings. Only then run the launcher. The order is the whole debugging method: a ping without the jar means the project is fine and the API is absent. A jar that imports Contract but never prints “Connected” means the desktop process is down, the port is wrong, or the reader thread is missing.

What usually goes wrong

A version below 10.2 is the crypto-specific failure. Equities might still connect while cryptocurrency contracts are unsupported. Match the three downloads, not just the jar.

Questions people ask

Which version do crypto contracts need?

Version 10.2 or newer, for Gateway, Trader Workstation, and the API. The lecture treats older builds as lacking cryptocurrency contract support.

What did the sample connect call pass?

Host 127.0.0.1, port 4002, and client id 0. The port should match the socket port in your API settings. 4002 is the value they used, not a constant of the protocol.

Why print “Connected” inside a callback?

Because that method runs when the server acknowledges the client. A print placed only on the line after eConnect would not prove the server had answered. The Gateway screen showing an API client is the second check.