Interactive Brokers Integration Guide

This guide explains how to integrate with Interactive Brokers APIs through PiTrade's bearer token gateway, unlocking advanced trading capabilities.

Overview

The Interactive Brokers integration flow allows you to access the full power of Interactive Brokers' trading APIs while maintaining PiTrade's security standards. You authenticate with PiTrade, receive a bearer token, and then use that token to interact with Interactive Brokers APIs directly.

When to Use Interactive Brokers Integration

Use the Interactive Brokers integration flow when you need:

• Advanced Order Types: Limit orders, stop-loss orders, conditional orders
• Margin Analysis: Real-time margin impact calculations before placing orders
• Extended Order Features: Stop-loss, conditional orders, and more advanced functionalities

Authentication Flow

┌─────────────────┐
│   Your App      │
└────────┬────────┘
         │ 1. Generate PiTrade JWT
         │    (using clientId + apiKey)
         ▼
    ┌────────────────────┐
    │ Get Bearer Token   │
    │ /brokerage-bearer- │
    │ token              │
    └────────┬───────────┘
             │ 3. Return Bearer Token
             ▼
    ┌─────────────────────────────┐
    │ Interactive Brokers APIs    │
    │ (with bearer token)         │
    └─────────────────────────────┘

Key Concepts

PiTrade Authentication

• Create a JWT token using your Partner clientId and apiKey
• Token expires in 15 minutes
• Used only to request a bearer token

Bearer Token

• Obtained from PiTrade's /brokerage-bearer-token endpoint
• Used to authenticate all Interactive Brokers API requests
• Scoped to a specific user session and IP address

Session Management

• Interactive Brokers sessions require initialization and periodic refreshing
• Session validation endpoints keep your connection alive
• Message suppression avoids confirmation dialogs for certain order types

Implementation Steps

1. Generate PiTrade JWT Token - Sign token with your partner apiKey
2. Request Bearer Token - Exchange JWT for Interactive Brokers bearer token
3. Initialize Session - Set up session with Interactive Brokers APIs
4. Maintain Session - Keep session alive with validation and tickle endpoints
5. Execute Trades - Place orders, check status, get margin impact
6. Handle Errors - Implement retry logic and proper error handling

Next Steps

• Bearer Token API - Request bearer tokens
• Interactive Brokers Trading APIs - Place and preview orders
• Interactive Brokers Session Management - Manage sessions
• Complete Interactive Brokers Flow Example - Full working example