IBKR Trading APIs

Execute trades through Interactive Brokers using the bearer token authentication. These endpoints support market orders, limit orders, and advanced order types.

Getting Contract IDs (CONID)

Before placing orders, you need the Contract ID (CONID) for each security. IBKR provides a CSV file with contract IDs for fractional share trading:

Download: IBKR Fractional Shares CSV

File Format:

#SYMBOL,MAIN_EXCHANGE,DESCRIPTION,IB_CONTRACT_ID,SCHEDULED_INELIGIBILTY_DATE
AAP,NYSE,ADVANCE AUTO PARTS INC,4027,	
ABM,NYSE,ABM INDUSTRIES INC,4050,	
ABT,NYSE,ABBOTT LABORATORIES .,4065,	
ADC,NYSE,AGREE REALTY CORP,4151,	
...

Usage:

Download the CSV file
Parse it to create a symbol → IB_CONTRACT_ID mapping
Use the IB_CONTRACT_ID in your order requests

Note: Multiple records may exist for a single ticker on different exchanges. Filter by valid exchanges to ensure you get the correct contract ID.

Valid Exchanges: NYSE, NASDAQ, ARCA, AMEX, BATS

Example:

const fs = require('fs');
const csv = require('csv-parser');

const symbolToConid = {};
const validExchanges = new Set(["NYSE", "NASDAQ", "ARCA", "AMEX", "BATS"]);

fs.createReadStream('fracshare_stk.csv')
  .pipe(csv())
  .on('data', (row) => {
    if (validExchanges.has(row.MAIN_EXCHANGE)) {
      symbolToConid[row["#SYMBOL"]] = row.IB_CONTRACT_ID;
    }
  })
  .on('end', () => {
    console.log('ABT Contract ID:', symbolToConid['ABT']); // 4065
  });

Overview

IBKR provides three key trading endpoints:

Preview Order - Validate orders before execution
Submit Order - Place actual trading orders
Order Status - Check execution status of placed orders

Preview Order

Validate an order and see potential margin impact before execution.

IBKR Documentation

Endpoint

POST https://api.ibkr.com/v1/api/iserver/account/{accountId}/orders/whatif

Purpose

Simulate an order execution without actually placing it. Returns:

Order validation results
Margin requirements
Commission estimates
Price impact analysis

Request

{
  "orders": [
    {
      "conid": 265598,
      "orderType": "MKT",
      "side": "BUY",
      "tif": "DAY",
      "ticker": "AAPL",
      "acctId": "U25076105",
      "cashQty": 1978,
      "outsideRTH": false
    }
  ],
  "outsideRegularHours": false
}

Response

{
  "amount": {
    "amount": "1,977.60 USD (10 Shares)",
    "commission": "1 USD",
    "total": "1,978.60 USD"
  },
  "equity": {
    "current": "123,456",
    "change": "-1",
    "after": "123,455"
  },
  "initial": {
    "current": "1000",
    "change": "652",
    "after": "1652"
  },
  "maintenance": {
    "current": "900",
    "change": "590\"\"",
    "after": "1490"
  },
  "position": {
    "current": "20",
    "change": "10",
    "after": "30"
  },
  "warn": null,
  "error": null
}

Parameters

Parameter	Type	Required	Description
`conid`	integer	Yes	Contract ID of security
`orderType`	string	Yes	`MKT` (market) or `LMT` (limit)
`side`	string	Yes	`BUY` or `SELL`
`tif`	string	Yes	Time in force: `DAY`, `GTC`, etc.
`ticker`	string	Yes	Stock ticker symbol
`acctId`	string	Yes	Account ID
`cashQty`	number	Conditional	Amount in dollars (for BUY orders)
`quantity`	number	Conditional	Share quantity (for SELL or LMT orders)
`price`	number	Conditional	Limit price (for LMT orders)

Submit Order

Place an actual trading order.

IBKR Documentation

Endpoint

POST https://api.ibkr.com/v1/api/iserver/account/{accountId}/orders

Purpose

Execute a real order on the market. Requires valid session and sufficient margin.

Request

{
  "orders": [
    {
      "conid": 265598,
      "orderType": "MKT",
      "side": "BUY",
      "tif": "DAY",
      "ticker": "AAPL",
      "acctId": "U25076105",
      "cashQty": 1000,
      "outsideRTH": false
    }
  ],
  "outsideRegularHours": false
}

Response

[
  {
    "order_id": "1370093239",
    "order_status": "PreSubmitted",
    "encrypt_message": "1"
  }
]

Important Notes

Order must pass validation (use Preview Order first)
Session must be authenticated and connected
Sufficient margin required
Orders execute based on current market conditions

Order Status

Check the execution status and details of a placed order.

IBKR Documentation

Endpoint

GET https://api.ibkr.com/v1/api/iserver/account/order/status/{orderId}

Purpose

Retrieve current status, execution details, and any fills for an order.

Response

{
  "sub_type": null,
  "request_id": "209",
  "server_id": "0",
  "order_id": 1799796559,
  "conidex": "265598",
  "conid": 265598,
  "symbol": "AAPL",
  "side": "S",
  "contract_description_1": "AAPL",
  "listing_exchange": "NASDAQ.NMS",
  "option_acct": "c",
  "company_name": "APPLE INC",
  "size": "0.0",
  "total_size": "5.0",
  "currency": "USD",
  "account": "U1234567",
  "order_type": "MARKET",
  "cum_fill": "5.0",
  "order_status": "Filled",
  "order_ccp_status": "2",
  "order_status_description": "Order Filled",
  "tif": "DAY",
  "fg_color": "#FFFFFF",
  "bg_color": "#000000",
  "order_not_editable": true,
  "editable_fields": "",
  "cannot_cancel_order": true,
  "deactivate_order": false,
  "sec_type": "STK",
  "available_chart_periods": "#R|1",
  "order_description": "Sold 5 Market, Day",
  "order_description_with_contract": "Sold 5 AAPL Market, Day",
  "alert_active": 1,
  "child_order_type": "0",
  "order_clearing_account": "U1234567",
  "size_and_fills": "5",
  "exit_strategy_display_price": "193.12",
  "exit_strategy_chart_description": "Sold 5 @ 192.26",
  "average_price": "192.26",
  "exit_strategy_tool_availability": "1",
  "allowed_duplicate_opposite": true,
  "order_time": "231211180049"
}

Status Values

Status	Meaning
`Submitted`	Order accepted but not yet executed
`Filled`	Order completely filled
`Partially Filled`	Order partially filled, may fill more
`Cancelled`	Order cancelled
`Rejected`	Order rejected by exchange

Usage Example

const IBKR_BASE_PATH = "https://api.ibkr.com";

// 1. Preview order first
const previewResponse = await fetch(
  `${IBKR_BASE_PATH}/v1/api/iserver/account/U25076105/orders/whatif`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${bearerToken}`,
      "Content-Type": "application/json",
      "User-Agent": "Your Application/1.0",
    },
    body: JSON.stringify({
      orders: [
        {
          conid: 265598,
          orderType: "MKT",
          side: "BUY",
          tif: "DAY",
          ticker: "AAPL",
          acctId: "U25076105",
          cashQty: 1000,
        },
      ],
      outsideRegularHours: false,
    }),
  },
);

// 2. If preview successful, place order
const orderResponse = await fetch(
  `${IBKR_BASE_PATH}/v1/api/iserver/account/U25076105/orders`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${bearerToken}`,
      "Content-Type": "application/json",
      "User-Agent": "Your Application/1.0",
    },
    body: JSON.stringify({
      orders: [
        {
          conid: 265598,
          orderType: "MKT",
          side: "BUY",
          tif: "DAY",
          ticker: "AAPL",
          acctId: "U25076105",
          cashQty: 1000,
        },
      ],
      outsideRegularHours: false,
    }),
  },
);

const { order_id } = await orderResponse.json();

// 3. Check order status
const statusResponse = await fetch(
  `${IBKR_BASE_PATH}/v1/api/iserver/account/order/status/${order_id}`,
  {
    headers: {
      Authorization: `Bearer ${bearerToken}`,
      "User-Agent": "Your Application/1.0",
    },
  },
);

Next Steps

IBKR Session Management - Keep sessions alive
Complete IBKR Flow Example - Full working example