Getting Started with IbkrApi

View Source

This tutorial will guide you through the process of setting up and using the IbkrApi library to interact with Interactive Brokers' Client Portal API.

Prerequisites

Before you begin, make sure you have:

  1. An Interactive Brokers account with appropriate permissions
  2. The Client Portal Gateway running locally or on a server
  3. Elixir 1.15 or later installed on your system
  4. Java 8 Update 192+ for running the Client Portal Gateway

Installation

Add ibkr_api to your list of dependencies in mix.exs:

def deps do
  [
    {:ibkr_api, "~> 0.1.0"}
  ]
end

Then run:

mix deps.get

Configuration

Configure the library in your application's configuration file (config/config.exs):

config :ibkr_api,
  host: "https://localhost",  # Default Client Portal Gateway host
  port: 5000,  # Default Client Portal Gateway port
  timeout: 30_000  # Request timeout in milliseconds

You can override these settings in your environment-specific configuration files.

Starting the Client Portal Gateway

Before using the library, you need to start the Interactive Brokers Client Portal Gateway:

Prerequisites

  1. Java Runtime Environment (JRE): The gateway requires Java 8 update 192 or later. Check if Java is installed:
    java -version
    If not installed, download from the official Java website

Download and Setup

  1. Download the Client Portal Gateway:

  2. Extract and run the gateway:

    # Extract the downloaded file
unzip clientportal.gw.zip
cd clientportal.gw

# On Unix/Linux/macOS:
bin/run.sh root/conf.yaml

# On Windows:
bin\run.bat root\conf.yaml

Important Security Notes

  • Same-machine requirement: The gateway must run on the same machine where you'll make API calls
  • Default port: 5000 (configurable in root/conf.yaml)
  • Browser authentication: You must authenticate through the browser on the same machine
  • SSL certificates: The gateway uses self-signed certificates by default

Basic Usage

Establishing a Connection

First, you need to authenticate with the IBKR Client Portal API using IbkrApi.ClientPortal.Auth:

# Check if the server is running and authenticate
{:ok, response} = IbkrApi.ClientPortal.Auth.ping_server()

# If you need to reauthenticate
{:ok, _} = IbkrApi.ClientPortal.Auth.reauthenticate()

Listing Accounts

Once authenticated, you can list your accounts using IbkrApi.ClientPortal.Portfolio:

{:ok, accounts} = IbkrApi.ClientPortal.Portfolio.list_accounts()

# Print account IDs
accounts |> Enum.each(fn account -> IO.puts(account.account_id) end)

Getting Account Information

You can retrieve detailed information about a specific account using IbkrApi.ClientPortal.Portfolio:

account_id = "U1234567"  # Replace with your actual account ID
{:ok, summary} = IbkrApi.ClientPortal.Portfolio.account_summary(account_id)

# Access summary data (returns a map with account fields)
IO.inspect(summary, label: "Account Summary")

Next Steps

Now that you've set up the library and made your first API calls, you can:

  1. Learn more about Authentication processes
  2. Explore Account Management operations
  3. Start Trading with the API
  4. Set up WebSocket Streaming for real-time data

For a complete reference of all available functions, check the API Reference.