Building a Replay-Tested Interactive Brokers Client in Go

Thomas Marcelis — Wed, 15 Apr 2026 11:35:19 +0000

When I started getting more serious about automating parts of my trading (I use Interactive Brokers), the natural first step was finding a library that handles the broker communication. I expected this to be a solved problem. It wasn't.

Every Go library I found follows essentially the same pattern: take the official Java client, the EWrapper/EClient callback surface with all its ceremony, and rewrite it in Go syntax. Different language, same design. And if you're going to do that, I genuinely don't understand why you'd pick Go. The whole reason to use Go for something like this is channels, typed returns, context cancellation. If I'm still embedding callback structs and manually tracking request IDs, you've given me Java with a gopher logo.

The libraries that did try something more idiomatic were either too thin to trust or had been abandoned (one maintainer moved to Rust, which, okay, I get it, but still). So I thought about what I actually want from a library like this: an API that feels like Go, and testing I'd trust my own money with. Think of SQLite and why everyone just trusts it. Not because of marketing or GitHub stars, but because the test suite is so thorough that you just stop worrying.

So I wrote my own. I know, another standard. I'm dogfooding this for my own trading and analysis tools, and I take it seriously as infrastructure. I open sourced it because it can only be useful, and if people end up relying on it, I'm genuinely happy to maintain it.

What "feels like Go" actually means

Let me show you what I mean. Say you want your account summary using the traditional EWrapper callback approach:

type MyWrapper struct {
    ibapi.Wrapper
    values []AccountSummary
    done   chan struct{}
}

func (w *MyWrapper) AccountSummary(reqID int, account, tag, value, currency string) {
    w.values = append(w.values, AccountSummary{account, tag, value, currency})
}

func (w *MyWrapper) AccountSummaryEnd(reqID int) {
    close(w.done)
}

// then somewhere else entirely:
wrapper := &MyWrapper{done: make(chan struct{})}
client := ibapi.NewClient(wrapper)
client.Connect("127.0.0.1", 4002, 1)
client.ReqAccountSummary(1, "All", "NetLiquidation,TotalCashValue")
<-wrapper.done

You embed a wrapper struct, implement two separate callback methods (one per row, one for the end signal), create a channel to synchronize because the data arrives asynchronously, and pick a request ID yourself to correlate everything. That's a lot of ceremony for what should be a function call. And honestly, all of that should be the library's job. Request ID management, response correlation, synchronization, timeouts. I don't want to think about any of it.

So here's the same thing in ibkr-go:

values, err := client.Accounts().Summary(ctx, ibkr.AccountSummaryRequest{
    Account: "All",
    Tags:    []string{"NetLiquidation", "TotalCashValue"},
})

One call, typed return. The library handles everything underneath.

Streaming works the same way. Want live quote updates? You get a subscription with a channel:

sub, err := client.MarketData().SubscribeQuotes(ctx, ibkr.QuoteRequest{
    Contract: ibkr.Contract{
        Symbol:   "AAPL",
        SecType:  ibkr.SecTypeStock,
        Exchange: "SMART",
        Currency: "USD",
    },
})
defer sub.Close()

for update := range sub.Events() {
    fmt.Println(update.Snapshot.Bid, update.Snapshot.Ask)
}

Range over the channel, close when you're done. If the connection drops, you get explicit lifecycle events telling you what happened and whether it's retryable. No silent reconnects that leave you wondering whether you missed data. The library tells you, and you decide what to do about it.

Why Go

People ask why I didn't just write this in Rust. I considered it, and even did a small prototype. But Go is genuinely a great fit here. The protocol work is all about concurrent communication, managing streams, multiplexing requests over a single TCP connection. That's exactly what Go was designed for. On top of that, Go is great for CLI tooling, which matters because my trading and analysis tools are all terminal-based.

There's also a more pragmatic reason. I write a lot of code with LLMs these days, and Go's "one way to do things" philosophy turns out to be an excellent property for AI-assisted development. The language is opinionated enough that there's usually one obvious way to structure something, which means LLMs produce more consistent, idiomatic code. It's a small thing, but it compounds when you're building something this large.

Rust's memory safety guarantees are real, but for a protocol library that's mostly parsing text fields over TCP, they're not really buying you much. If performance were the kind of concern where Go doesn't cut it, honestly, neither would Rust. You'd be dropping down to something lower level. For this problem, Go hits the sweet spot.

How I test it without a broker

This is the part I care about most, because the API design is interesting but the testing is the actual moat.

IBKR's protocol is a stateful binary stream over TCP. You send a request, you get back a sequence of messages that can arrive over time, interleaved with responses to other requests. The surface area is large. Hundreds of message types, complex interactions between them, exotic financial instruments with their own edge cases. Testing all of this against a live IB Gateway is possible, but it's slow, it needs credentials, and you can't run it in CI without serious infrastructure.

So we built a replay system. The idea is straightforward: connect to a real, live Gateway, run a scenario (request account summary, place an order, subscribe to quotes), and record all the wire traffic in both directions. Then freeze that recording into a transcript file that gets checked into the repo.

Here's what a transcript looks like. This is the account summary flow:

handshake {"server_version":200,"connection_time":"20260405 12:00:00 CET"}
server managed_accounts {"accounts":["DU12345"]}
server next_valid_id {"order_id":1001}

client req_account_summary {"req_id":"$req1","account":"All","tags":["NetLiquidation","BuyingPower"]}
server account_summary {"req_id":"$req1","account":"DU12345","tag":"NetLiquidation","value":"100000.00","currency":"USD"}
server account_summary {"req_id":"$req1","account":"DU99999","tag":"NetLiquidation","value":"200000.00","currency":"USD"}
server account_summary {"req_id":"$req1","account":"DU12345","tag":"BuyingPower","value":"50000.00","currency":"USD"}
server account_summary_end {"req_id":"$req1"}

client cancel_account_summary {"req_id":"$req1"}
disconnect

Each line is a step. server lines are messages from the Gateway. client lines are messages we expect the library to send. The $req1 bindings let the harness capture dynamic values like request IDs and reuse them across the scenario. When you run a test, the harness spins up a local TCP server, replays the transcript, and the library connects to it like it's a real Gateway.

The important detail is that the replay harness uses the exact same wire codec and framing as the production client. It's not a separate mock layer that approximates the protocol. The transcript gets encoded through the same path that real Gateway traffic would take. Which means if the codec has a bug, the replay tests catch it too.

We have over 100 of these transcripts now, covering everything from basic handshakes to full order lifecycles with cancellations, historical data requests, option calculations, streaming subscriptions, and various error conditions. They all run in CI on every push. No credentials needed, no Docker, no running broker. Just go test ./... and you know whether 100+ real scenarios still work.

What does this catch that traditional mocking wouldn't? Mostly the things you don't think to mock. Real protocol framing edge cases, because the harness can test split messages across TCP packet boundaries. The actual ordering of server responses, which matters more than you'd expect. Regression across every scenario at once, where changing one codec path doesn't silently break an unrelated flow. When you have a hundred frozen scenarios and one of them breaks, you know immediately which message interaction changed and why.

The honest tradeoffs

I'm not going to pretend the testing story is complete. Some areas like the financial advisor features aren't as deeply covered as I'd like. I don't own every custom data source IBKR offers, so there are parts I simply can't test without access. And transcripts are frozen by definition. If IBKR changes protocol behavior in a future server version, the existing replays won't catch it. That's why live integration tests exist behind IBKR_LIVE=1, so you can always verify against the real thing. But for CI, for fast iteration, for knowing that over a hundred real scenarios still work after every change, the replay approach is the right default.

There's also just the sheer size of the financial domain itself. The number of order types, exotic instruments, market-specific exceptions, and edge cases is genuinely enormous. Every trading API carries decades of accumulated complexity, and IBKR's is no different. You can't test what you don't know exists. All you can do is keep expanding the scenario coverage as you encounter new behavior, and freeze each one so it never regresses.

Take a look