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 JWT
         │    (using clientId + apiKey)
         ▼
    ┌─────────────────────────┐
    │ Native API Auth         │
    │ POST /auth/token        │
    └────────┬────────────────┘
             │ 2. Receive IdToken
             ▼
    ┌────────────────────────────┐
    │ Get Bearer Token           │
    │ POST /user/bearer-token    │
    │ (auth: IdToken)            │
    └────────┬───────────────────┘
             │ 3. Return Bearer Token
             ▼
    ┌─────────────────────────────┐
    │ Interactive Brokers APIs    │
    │ (with bearer token)         │
    └─────────────────────────────┘

Key Concepts

PiTrade Native API Authentication

• Create a JWT token using your PiTrade clientId and apiKey
• Exchange JWT at /auth/token to receive IdToken (and RefreshToken, AccessToken)
• IdToken is used to request the Interactive Brokers bearer token
• See PiTrade Native APIs Authentication for detailed instructions

Bearer Token

• Obtained from PiTrade's /user/bearer-token endpoint using IdToken
• 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 client apiKey
2. Obtain IdToken - Exchange JWT for IdToken via Native API auth endpoint
3. Request Bearer Token - Exchange IdToken for Interactive Brokers bearer token
4. Initialize Session - Set up session with Interactive Brokers APIs
5. Maintain Session - Keep session alive with validation and tickle endpoints
6. Execute Trades - Place orders, check status, get margin impact
7. 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