Web API v1.0 Documentation

As the Client Portal API Gateway was developed using Java, a working installation of the Java Runtime Environment (JRE) is required to run it. The minimum required version is Java 8 update 192.

In order to check if you have a working installation of Java, open a terminal and run the following command:

java -version

If Java is installed and correctly configured you should see information about the currently installed version, otherwise an error is raised.

If you do not have a working installation of Java, you can download it from the official website

Individual clients using Client Portal API will need to use a Java-based API gateway in order to access protected endpoints. The gateway is responsible for routing requests to the backend and ensuring that the brokerage session is authenticated. Interactive Brokers offers both a Standard and Beta release for our Client Portal API platforms. If you ever experience issues with the standard release, please try our Beta client in case your issue has already been resolved.

In order to launch the Client Portal Gateway, you must execute a set of commands through the Windows Command Prompt or Unix Terminal. This can not be done through the default file explorer. The API gateway is meant to be run on a local machine. As such, attempting to operate the gateway on a separate machine from where commands are generated may result in the issues and is not a supported practice by Interactive Brokers.

By default, the gateway will listen on port 5000. Clients can however change this to any available port on their device by modifying the listenPort field in the gateway configuration file ‘conf.yaml’, found in the ‘root’ directory of the gateway.

After successfully running the gateway, you may proceed through the Authentication steps before proceeding to calling your requested endpoints.

Using the terminal, Find and open the unzipped Client Portal Gateway directory.

For example, assume my Client Portal Gateway directory is in the Windows C:/Users/Example/Downloads/ , then I can run the following command to change to the directory:

cd C:/Users/Example/Downloads/clientportal.gw

After that, on Windows, launch the gateway using the following command:

bin\run.bat root\conf.yaml

And in the case of Unix systems:

bin/run.sh root/conf.yaml

The base url is: https://localhost:5000/v1/api

By default, the Client Portal Gateway is not bundled with a signed certificate. As such, customers should either look to independently have their certificate signed, or submit requests to their localhost as ‘insecure’.

Endpoint used to create a new alert, or modify an existing alert.

POST /iserver/account/{{ accountId }}/alert

Path Params

accountId: String.  Required
Identifier for the unique account to retrieve information from.
Value Format: “DU1234567”

Body Prams

alertName: String. Required
Used as a human-readable identifier for your created alert.
Format Structure: “Alert Name”

alertMessage: String. Required
The body content of what your alert will report once triggered
Value Format: “MESSAGE TEXT”

alertRepeatable: int. Required
Boolean number (0, 1) signifies if an alert can be triggered more than once.
A value of ‘1’ is required for MTA alerts
Value Format:

email: String. Required if ‘sendMessage’ == 1
Email address you want to send email alerts to
Value Format:

expireTime: String. Required if ‘tif’ == ‘GTD’
Used with a tif of “GTD” only. Signifies time when the alert should terminate if no alert is triggered.
Value Format: “YYYYMMDD-HH:mm:ss”

iTWSOrdersOnly: int. Optional
Boolean number (0, 1) to allow alerts to trigger alerts through the mobile app.
Value Format: 1

outsideRth: int. Required
Boolean number (0, 1) to allow the alert to trigger outside of regular trading hours.
Value Format: 1

sendMessage: int. Optional
Boolean number (0, 1) to allow alerts to trigger email messages
Value Format: 1

showPopup: int. Optional
Boolean number (0, 1) to allow alerts to trigger TWS Pop-up messages
Value Format: 1

tif: String.. Required
Time in Force duration of alert. Allowed: [“GTC”, “GTD”]
Value Format: “DAY”

conditions: List of Arrays. Required
Container for all conditions applied for an alert to trigger.
Required field.
Value Format:[ {…} ]

conidex: String. Required
Concatenation of conid and exchange. Formatted as “conid@exchange”
Value Format: “265598@SMART”

logicBind: String. Required
Describes how multiple conditions should behave together.
Allowed values are: {“a”: “AND”, “o”: “OR”, “n”: “END”}
Value Format: “a”

operator: String. Required
Indicates whether the trigger should be above or below the given value.
Value Format:”>=”

timeZone: String. Required for MTA alerts
Only needed for some MTA alert condition
Value Format: “US/Eastern”

triggerMethod: String. Required
Pass the string representation of zero, “0”
Value Format: “0”

type: int. Required
Designate what condition type to use.
Allowed values: {1: Price, 3: Time, 4: Margin, 5: Trade, 6: Volume, 7: MTA market, 8: MTA Position, 9: MTA Account Daily PnL}
Value Format: 1

value: String. Required
Trigger value based on Type. Allows a default value of “*”.
Value Format: “195.00”, “YYYYMMDD-HH:mm:ss”

}

]

Response Object:

Returns a single json object

request_id: integer. Always returns ‘null’

order_id: integer. Signifies tracking ID for given alert.

success: boolean. Displays result status of alert request

text: String. Response message to clarify success status reason.

order_status: String. Returns ‘null’

warning_message: String. Returns ‘null’
}

{
  "request_id": null,
  "order_id": 9876543210,
  "success": true,
  "text": "Submitted",
  "order_status": null,
  "warning_message": null
}

Retrieve a list of all alerts attached to the provided account.

GET /iserver/account/{{ accountId }}/alerts

Path Parameters

accountId: String. Required
Identifier for the unique account to retrieve information from.
Value Format: “DU1234567”

Response Object:

Returns an array of comma-separated json objects

order_id: int.
The searchable order ID

account: String.
The account the alert was attributed to.

alert_name: String.
The requested name for the alert.

alert_active: int.
Determines if the alert is active or not

order_time: String.
UTC-formatted time of the alert’s creation.

alert_triggered: bool.
Confirms if the order is is triggered or not.

alert_repeatable: int.
Confirms if the alert is enabled to repeat.

[
  {
    "order_id": 9876543210,
    "account": "U1234567",
    "alert_name": "AAPL Price",
    "alert_active": 1,
    "order_time": "20231211-18:55:35",
    "alert_triggered": false,
    "alert_repeatable": 0
  }
]

Request details of a specific alert by providing the assigned order ID.

GET /iserver/account/alert/{{ order_id }}

Path Parameters

order_id: int. Required
Alert ID returned from the original alert creation, or from the list of available alerts.

Query Parameters

type: String. Required
Must always pass ‘Q’.

Response Object

account: String.
Requestor’s account ID

order_id: int.
Alert’s tracking ID. Can be used for modifying or deleting alerts.

alertName: String.
Human readable name of the alert.

tif: String.
Time in Force effective for the Alert

expire_time: String.
Returns the UTC formatted date used in GTD orders.

alert_active: int.
Returns if the alert is active or disabled.

alert_repeatable: int.
Returns if the alert can be sent more than once.

alert_email: String.
Returns the designated email address for sendMessage functionality.

alert_send_message: int.
Returns whether or not the alert will send an email.

alert_message: String.
Returns the body content of what your alert will report once triggered

alert_show_popup: int.
Returns whether or not the alert will trigger TWS Pop-up messages

alert_play_audio: int.
Returns whether or not the alert will play audio

order_status: String.
Always returns “Presubmitted”.

alert_triggered: int.
Returns whether or not the alert was triggered yet.

fg_color: String.
Always returns “#FFFFFF”. Can be ignored.

bg_color: String.
Always returns “#000000”. Can be ignored.

order_not_editable: bool.
Returns if the order can be edited.

itws_orders_only: int.
Returns whether or not the alert will trigger mobile notifications.

alert_mta_currency: String.
Returns currency set for MTA alerts. Only valid for alert type 8 & 9.

alert_mta_defaults: String.
Returns current MTA default values.

tool_id: int.
Tracking ID for MTA alerts only. Returns ‘null’ for standard alerts.

time_zone: String.
Returned for time-specifc conditions.

alert_default_type: int.
Returns default type set for alerts. Configured in Client Portal.

condition_size: int.
Returns the total number of conditions in the alert.

condition_outside_rth: int.
Returns whether or not the alert will trigger outside of regular trading hours.

conditions: Array of json objects.
Returns all conditions, formatted as [ {Condition1}, {Condition2}, {…} ]

condition_type: int.
Returns the type of condition set.

conidex: String.
Returns full conidex in the format “conid@exchange”

contract_description_1: String.
Includes relevant descriptions (if applicable).

condition_operator: String.
Returns condition set for alert.

condition_trigger_method: int.
Returns triggerMethod value set.

condition_value: String.
Returns value set.

condition_logic_bind: String
Returns logic_bind value set.

condition_time_zone:
Returns timeZone value set.

{
  "account": "U1234567",
  "order_id": 9876543210,
  "alert_name": "AAPL Price",
  "tif": "GTD",
  "expire_time": "20231231-12:00:00",
  "alert_active": 1,
  "alert_repeatable": 0,
  "alert_email": null,
  "alert_send_message": 0,
  "alert_message": "MTA TEST!",
  "alert_show_popup": 0,
  "alert_play_audio": null,
  "order_status": "Submitted",
  "alert_triggered": false,
  "fg_color": "#FFFFFF",
  "bg_color": "#0000CC",
  "order_not_editable": false,
  "itws_orders_only": 0,
  "alert_mta_currency": null,
  "alert_mta_defaults": null,
  "tool_id": null,
  "time_zone": null,
  "alert_default_type": null,
  "condition_size": 1,
  "condition_outside_rth": 0,
  "conditions": [
    {
      "condition_type": 1,
      "conidex": "265598@SMART",
      "contract_description_1": "AAPL",
      "condition_operator": "<=",
      "condition_trigger_method": "0",
      "condition_value": "183.34",
      "condition_logic_bind": "n",
      "condition_time_zone": null
    }
  ]
}

Retrieve information about your MTA alert.

Each login user only has one mobile trading assistant (MTA) alert with it’s own unique tool id that cannot be changed.

MTA alerts can not be created or deleted, only modified. When modified a new order Id is generated.

See here for more information on MTA alerts.

GET /iserver/account/mta

Request Object

No additional parameters necessary.

Response Object

account: String.
Requestor’s account ID

order_id: int.
Alert’s tracking ID. Can be used for modifying or deleting alerts.

alertName: String.
Human readable name of the alert.

tif: String.
Time in Force effective for the Alert

expire_time: String.
Returns the UTC formatted date used in GTD orders.

alert_active: int.
Returns if the alert is active or disabled.

alert_repeatable: int.
Returns if the alert can be sent more than once.

alert_email: String.
Returns the designated email address for sendMessage functionality.

alert_send_message: int.
Returns whether or not the alert will send an email.

alert_message: String.
Returns the body content of what your alert will report once triggered

alert_show_popup: int.
Returns whether or not the alert will trigger TWS Pop-up messages

alert_play_audio: int.
Returns whether or not the alert will play audio

order_status: String.
Always returns “Presubmitted”.

alert_triggered: int.
Returns whether or not the alert was triggered yet.

fg_color: String.
Always returns “#FFFFFF”. Can be ignored.

bg_color: String.
Always returns “#000000”. Can be ignored.

order_not_editable: bool.
Returns if the order can be edited.

itws_orders_only: int.
Returns whether or not the alert will trigger mobile notifications.

alert_mta_currency: String.
Returns currency set for MTA alerts. Only valid for alert type 8 & 9.

alert_mta_defaults: String.
Returns current MTA default values.

tool_id: int.
Tracking ID for MTA alerts only. Returns ‘null’ for standard alerts.

time_zone: String.
Returned for time-specifc conditions.

alert_default_type: int.
Returns default type set for alerts. Configured in Client Portal.

condition_size: int.
Returns the total number of conditions in the alert.

condition_outside_rth: int.
Returns whether or not the alert will trigger outside of regular trading hours.

conditions: Array of json objects.
Returns all conditions, formatted as [ {Condition1}, {Condition2}, {…} ]

condition_type: int.
Returns the type of condition set.

conidex: String.
Returns full conidex in the format “conid@exchange”

contract_description_1: String.
Includes relevant descriptions (if applicable).

condition_operator: String.
Returns condition set for alert.

condition_trigger_method: int.
Returns triggerMethod value set.

condition_value: String.
Returns value set.

condition_logic_bind: String
Returns logic_bind value set.

condition_time_zone:
Returns timeZone value set.

{
  "account": "U1234567",
  "order_id": 9998887776,
  "alert_name": null,
  "tif": "GTC",
  "expire_time": null,
  "alert_active": 1,
  "alert_repeatable": 1,
  "alert_email": null,
  "alert_send_message": 1,
  "alert_message": null,
  "alert_show_popup": 0,
  "alert_play_audio": null,
  "order_status": "Inactive",
  "alert_triggered": false,
  "fg_color": "#000000",
  "bg_color": "#AFAFAF",
  "order_not_editable": false,
  "itws_orders_only": 0,
  "alert_mta_currency": "USD",
  "alert_mta_defaults": "9:STATE=1,MIN=-43115000,MAX=43115000,STEP=500,DEF_MIN=-4311500,DEF_MAX=4311500|{{...}}",
  "tool_id": 55834574848,
  "time_zone": "GMT (GMT),GMT (Africa/Abidjan),{{...}}",
  "alert_default_type": null,
  "condition_size": 0,
  "condition_outside_rth": 0,
  "conditions": []
}

Activate or Deactivate existing alerts created for this account. This does not delete alerts, but disables notifications until reactivated.

POST /iserver/account/{{ accountId }}/alert/activate

Request Details

Path Parameters

accountId: String. Required
Identifier for the unique account to retrieve information from.
Value Format: “DU1234567”

Request Body

alertId: int. Required
The alertId, or order_id, received from order creation or the list of alerts.

alertActive: int. Required
Set whether or not the alert should be active (1) or inactive (0)

Response Object

request_id: int.
Returns ‘null’

order_id: int.
Returns requested alertId or order_id

success: bool.
Returns true if successful

text: String.
Adds additional information for “success” status.

failure_list: String.
If “success” returns false, will list failed order Ids

{
  "request_id": null,
  "order_id": 9876543210,
  "success": true,
  "text": "Request was submitted",
  "failure_list": null
}

Permanently delete an existing alert.

If alertId is 0, it will delete all alerts

If you call delete an MTA alert, it will reset to the default state.

DELETE /iserver/account/{{ accountId }}/alert/{{ alertId }}

Request Parameters

Path Parameters

accountId: String. Required
Identifier for the unique account to retrieve information from.
Value Format: “DU1234567”

alertId: int. Required
order_id returned from the original alert creation, or from the list of available alerts.

Response Object

request_id: int.
Returns ‘null’

order_id: int.
Returns requested alertId or order_id

success: bool.
Returns true if successful

text: String.
Adds additional information for “success” status.

failure_list: String.
If “success” returns false, will list failed order Ids

{
  "request_id": null,
  "order_id": 9876543210,
  "success": true,
  "text": "Request was submitted",
  "failure_list": null
}

Returns an object containing PnL for the selected account and its models (if any).

GET /iserver/account/pnl/partitioned

Request Object:

No additional parameters necessary.

Response Object:

upnl : JSON Object.

Refers to “updated PnL”. Holds a json object of key-value paired account pnl details.

{accountId}.Core: JSON Object.

An object based on your current account or group model.

rowType: int.
Returns the positional value of the returned account. Always returns 1 for individual accounts.

dpl: float.
Daily PnL for the specified account profile.

nl: float.
Net Liquidity for the specified account profile.

upl: float.
Unrealized PnL for the specified account profile.

el: float.
Excess Liquidity for the specified account profile.

mv: float.
Margin value for the specified account profile.

{
  "upnl": {
    "U1234567.Core": {
      "rowType": 1,
      "dpl": 15.7,
      "nl": 10000.0,
      "upl": 607.0,
      "el": 10000.0,
      "mv": 0.0
    }
  }
}

Broker accounts configured with the DYNACCT property will not receive account information at login. Instead, they must dynamically query then set their account number.

Customers without the DYNACCT property will receive the following message

{
    "error": "Details currently unavailable. Please try again later and contact client services if the issue persists.",
    "statusCode": 503
}

Returns a list of accounts matching a query pattern set in the request.

GET /iserver/account/search/{{ searchPattern }}

Request Object

Query Params

searchPattern: String. Required
The pattern used to describe credentials to search for.
Valid Format: “DU” in order to query all paper accounts.

Response Object

matchedAccounts: List of objects.
Contains a series of objects that pertain to the account information requested.
[{
accountId: String.
Returns a matching account ID that corresponds to the matching value.

alias: String.
Returns the corresponding alias or alternative name for the specific account ID. May be a duplicate of the accountId value in most cases.

allocationId: String.
Returns the allocation identifier used internally for the account.
}]
pattern: String.
Displays the searchPattern used for the request.

{
  "matchedAccounts": [
    {
      "accountId": "U1234567",
      "alias": "U1234567",
      "allocationId": "1"
    }
  ],
  "pattern":"U123"
}

Broker accounts configured with the DYNACCT property will not receive account information at login. Instead, they must dynamically query then set their account number.

Customers without the DYNACCT property will receive the following message

{
    "error": "Details currently unavailable. Please try again later and contact client services if the issue persists.",
    "statusCode": 503
}

Set the active dynamic account. Values retrieved from Search Dynamic Account

POST /iserver/dynaccount

Request Object

Body Params

acctId: String. Required
The account ID that should be set for future requests.

Response Object

set: bool.
Confirms if the account change was fully set.

acctId: String.
The account ID that was set for future use.

{
  "set": "true",
  "acctId": "U1234567",
}

Receive a list of all applicant names on the account and for which account and entity is represented.

GET /acesws/{{ accountID }}/signatures-and-owners

Request Object

Path Params

accountId: String. Required
Pass the account identifier to receive information for.
Valid Structure: “U1234567”

Response Object

accountId: String.
Specified account identifier in the request.

users: Array of Objects.
Returns all usernames and their information affiliated with the account.
[{
roleId: String.
Returns the role of the username as it relates to the account.

hasRightCodeInd: bool.
Internal use only.

username: String.
Returns the username for the particular user under the account.

entity: Object.
Provides information about the particular entity.
{
firstName: String.
Returns the first name of the user.

lastName: String.
Returns the last name of the user.

entityType: String.
Returns the type of entity assigned to the user.
Valid Value: “INDIVIDUAL”, “Joint”, “ORG”

entityName: String.
Returns the full entity’s name, concatenating the first and last name fields.
}}]

applicant: Object.
Provides information about the individual listed for the account.
{
signatures: Array of Strings.
Returns all names attached to the account.
}

{
  "accountId": "U1234567",
  "users": [
    {
      "roleId": "OWNER",
      "hasRightCodeInd": true,
      "userName": "user1234",
      "entity": {
        "firstName": "John",
        "lastName": "Smith",
        "entityType": "INDIVIDUAL",
        "entityName": "John Smith"
      }
    },
    {
      "roleId": "Trustee",
      "hasRightCodeInd": False,
      "userName": "user5678",
      "entity": {
        "firstName": "Jane",
        "lastName": "Doe",
        "entityType": "INDIVIDUAL",
        "entityName": "Jane Doe"
      }
    }
  ],
  "applicant": {
    "signatures": [
      "John Smith",
      "Jane Doe"
    ]
  }
}

Switch the active account for how you request data.

Only available for financial advisors and multi-account structures.

POST /iserver/account

Request Object:

Body Parameters

acctId: String. Required
Identifier for the unique account to retrieve information from.
Value Format: “DU1234567”

Response Object:

set: bool.
Confirms that the account change was set.

acctId: String.
Confirms the account switched to.

{
    "set": true,
    "acctId": "U1234567
}

Returns a list of accounts the user has trading access to, their respective aliases and the currently selected account. Note this endpoint must be called before modifying an order or querying open orders.

GET /iserver/accounts

Request Object:

No parameters necessary.

Response Object:

accounts: Array of Strings.
Returns an array of all accessible accountIds.

acctProps: Json Object.
Returns an json object for each accessible account’s properties.

hasChildAccounts: bool.
Returns whether or not child accounts exist for the account.

supportsCashQty: bool
Returns whether or not the account can use Cash Quantity for trading.

supportsFractions: bool.
Returns whether or not the account can submit fractional share orders.

aliases: JSON Object.
Returns any available aliases for the account.

allowFeatures: JSON object
JSON of allowed features for the account.

showGFIS: bool.
Returns if the account can access market data.

showEUCostReport: bool.
Returns if the account can view the EU Cost Report

allowFXConv: bool.
Returns if the account can convert currencies.

allowFinancialLens: bool.
Returns if the account can access the financial lens.

allowMTA: bool.
Returns if the account can use mobile trading alerts.

allowTypeAhead: bool.
Returns if the account can use Type-Ahead support for Client Portal.

allowEventTrading: bool.
Returns if the account can use Event Trader.

snapshotRefreshTimeout: int.
Returns the snapshot refresh timeout window for new data.

liteUser: bool.
Returns if the account is an IBKR Lite user.

showWebNews: bool.
Returns if the account can use News feeds via the web.
research: bool.

debugPnl: bool.
Returns if the account can use the debugPnl endpoint.

showTaxOpt: bool.
Returns if the account can use the Tax Optimizer tool

showImpactDashboard: bool.
Returns if the account can view the Impact Dashboard.

allowDynAccount: bool.
Returns if the account can use dynamic account changes.

allowCrypto: bool.
Returns if the account can trade crypto currencies.

allowedAssetTypes: bool.
Returns a list of asset types the account can trade.

chartPeriods: Json Object.
Returns available trading times for all available security types.

groups: Array.
Returns an array of affiliated groups.

profiles: Array.
Returns an array of affiliated profiles.

selectedAccount: String.
Returns currently selected account. See Switch Account for more details.

serverInfo: JSON Object.
Returns information about the IBKR session. Unrelated to Client Portal Gateway.

sessionId: String.
Returns current session ID.

isFT: bool.
Returns fractional trading access.

isPaper: bool.
Returns account type status.

{
  "accounts": [
    "U1234567"
  ],
  "acctProps": {
    "U1234567": {
      "hasChildAccounts": false,
      "supportsCashQty": true,
      "noFXConv": false,
      "isProp": false,
      "supportsFractions": true,
      "allowCustomerTime": false
    }
  },
  "aliases": {
    "U1234567": "U1234567"
  },
  "allowFeatures": {
    "showGFIS": true,
    "showEUCostReport": false,
    "allowEventContract": true,
    "allowFXConv": true,
    "allowFinancialLens": false,
    "allowMTA": true,
    "allowTypeAhead": true,
    "allowEventTrading": true,
    "snapshotRefreshTimeout": 30,
    "liteUser": false,
    "showWebNews": true,
    "research": true,
    "debugPnl": true,
    "showTaxOpt": true,
    "showImpactDashboard": true,
    "allowDynAccount": false,
    "allowCrypto": false,
    "allowedAssetTypes": "STK,CRYPTO"
  },
  "chartPeriods": {
    "STK": [
      "*"
    ],
    "CRYPTO": [
      "*"
    ]
  },
  "groups": [],
  "profiles": [],
  "selectedAccount": "U1234567",
  "serverInfo": {
    "serverName": "JifN17091",
    "serverVersion": "Build 10.25.0p, Dec 5, 2023 5:48:12 PM"
  },
  "sessionId": "1234a5b.12345678",
  "isFT": false,
  "isPaper": false
}

Returns a list of security definitions for the given conids

GET /trsrv/secdef

Request Object

Query Prams

conids: int*. Required
A comma separated series of contract IDs.
Value Format: 1234

Response Object

secdef: array.
Returns the contents of the request with the array.

conid: int.
Returns the conID

currency: String.
Returns the traded currency for the contract.

time: int.
Returns amount of time in ms to generate the data.

chineseName: String.
Returns the Chinese characters for the symbol.

allExchanges: String*.
Returns a series of exchanges the given symbol can trade on.

listingExchange: String.
Returns the primary or listing exchange the contract is hosted on.

countryCode: String.
Returns the country code the contract is traded on.

name: String.
Returns the comapny name.

assetClass: String.
Returns the asset class or security type of the contract.

expiry: String.
Returns the expiry of the contract. Returns null for non-expiry instruments.

lastTradingDay: String.
Returns the last trading day of the contract.

group: String.
Returns the group or industry the contract is affilated with.

putOrCall: String.
Returns if the contract is a Put or Call option.

sector: String.
Returns the contract’s sector.

sectorGroup: String.
Returns the sector’s group.

strike: int.
Returns the strike of the contract.

ticker: String.
Returns the ticker symbol of the traded contract.

undConid: int.
Returns the contract’s underlyer.

multiplier: float,
Returns the contract multiplier.

type: String.
Returns stock type.

hasOptions: bool.
Returns if contract has tradable options contracts.

fullName: String.
Returns symbol name for requested contract.

isUS: bool.
Returns if the contract is US based or not.

incrementRules & displayRule: Array.
Returns rules regarding incrementation for order placement. Not functional for all exchanges. Please see /iserver/contract/rules for more accurate rule details.

isEventContract: bool.
Returns if the contract is an event contract or not.

pageSize: int.
Returns the content size of the request.

{
  "secdef": [
    {
      "conid": 265598,
      "currency": "USD",
      "time": 43,
      "chineseName": "苹果公司",
      "allExchanges": "AMEX,NYSE,CBOE,PHLX,CHX,ARCA,ISLAND,ISE,IDEAL,NASDAQQ,NASDAQ,DRCTEDGE,BEX,BATS,NITEECN,EDGEA,CSFBALGO,JEFFALGO,NYSENASD,PSX,BYX,ITG,PDQ,IBKRATS,CITADEL,NYSEDARK,MIAX,IBDARK,CITADELDP,NASDDARK,IEX,WEDBUSH,SUMMER,WINSLOW,FINRA,LIQITG,UBSDARK,BTIG,VIRTU,JEFF,OPCO,COWEN,DBK,JPMC,EDGX,JANE,NEEDHAM,FRACSHARE,RBCALGO,VIRTUDP,BAYCREST,FOXRIVER,MND,NITEEXST,PEARL,GSDARK,NITERTL,NYSENAT,IEXMID,HRT,FLOWTRADE,HRTDP,JANELP,PEAK6,IMCDP,CTDLZERO,HRTMID,JANEZERO,HRTEXST,IMCLP,LTSE,SOCGENDP,MEMX,INTELCROS,VIRTUBYIN,JUMPTRADE,NITEZERO,TPLUS1,XTXEXST,XTXDP,XTXMID,COWENLP,BARCDP,JUMPLP,OLDMCLP,RBCCMALP,WALLBETH,IBEOS,JONES,GSLP,BLUEOCEAN,USIBSILP,OVERNIGHT,JANEMID,IBATSEOS,HRTZERO,VIRTUALGO",
      "listingExchange": "NASDAQ",
      "countryCode": "US",
      "name": "APPLE INC",
      "assetClass": "STK",
      "expiry": null,
      "lastTradingDay": null,
      "group": "Computers",
      "putOrCall": null,
      "sector": "Technology",
      "sectorGroup": "Computers",
      "strike": "0",
      "ticker": "AAPL",
      "undConid": 0,
      "multiplier": 0.0,
      "type": "COMMON",
      "hasOptions": true,
      "fullName": "AAPL",
      "isUS": true,
      "incrementRules": [
        {
          "lowerEdge": 0.0,
          "increment": 0.01
        }
      ],
      "displayRule": {
        "magnification": 0,
        "displayRuleStep": [
          {
            "decimalDigits": 2,
            "lowerEdge": 0.0,
            "wholeDigits": 4
          }
        ]
      },
      "isEventContract": false,
      "pageSize": 100
    }
  ]
}

Send out a request to retrieve all contracts made available on a requested exchange. This returns all contracts that are tradable on the exchange, even those that are not using the exchange as their primary listing.

Note: This is only available for Stock contracts.

GET /trsrv/all-conids

Request Object

Query Params

exchange: String. Required
Specify a single exchange to receive conids for.

Response Object

ticker: String.
Returns the ticker symbol of the contract

conid: int.
Returns the contract identifier of the returned contract.

exchange: String.
Returns the exchanger of the returned contract.

[
  {
    "ticker": "BMO",
    "conid": 5094,
    "exchange": "NYSE"
  },
  {...},
  {
    "ticker": "ZKH",
    "conid": 671347171,
    "exchange": "NYSE"
  }
]

Requests full contract details for the given conid

GET /iserver/contract/{conid}/info

Request Object

Path Params:

conid: String.
Contract ID for the desired contract information.

Response Object

conid: int.
Contract ID of the requested contract.

ticker: String.
Ticker symbol of the requested contract.

secType: String.
Security type of the requested contract.

listingExchange: String.
Primary exchange of the requested contract.

exchange: String.
Traded exchange of the requested contract set in the request.

companyName: String.
Company name of the requested contract.

currency: String.
National currency of the requested contract.

validExchanges: String.
All valid exchanges of the requested contract.

priceRendering: String.
Render price of the requested contract.

maturityDate: String.
Maturity, or expiration date, of the requested contract.

right: String.
Right, put or call, of the requested contract.

strike: int.
Strike price of the requested contract.

{
  "cfi_code": "",
  "symbol": "AAPL",
  "cusip": null,
  "expiry_full": null,
  "con_id": 265598,
  "maturity_date": null,
  "industry": "Computers",
  "instrument_type": "STK",
  "trading_class": "NMS",
  "valid_exchanges": "SMART,AMEX,NYSE,CBOE,PHLX,ISE,CHX,ARCA,ISLAND,DRCTEDGE,BEX,BATS,EDGEA,JEFFALGO,BYX,IEX,EDGX,FOXRIVER,PEARL,NYSENAT,LTSE,MEMX,TPLUS1,IBEOS,OVERNIGHT,PSX",
  "allow_sell_long": false,
  "is_zero_commission_security": false,
  "local_symbol": "AAPL",
  "contract_clarification_type": null,
  "classifier": null,
  "currency": "USD",
  "text": null,
  "underlying_con_id": 0,
  "r_t_h": true,
  "multiplier": null,
  "underlying_issuer": null,
  "contract_month": null,
  "company_name": "APPLE INC",
  "smart_available": true,
  "exchange": "SMART",
  "category": "Computers"
}

Obtains available currency pairs corresponding to the given target currency.

GET /iserver/currency/pairs

Request Object

Query Params

currency: String. Required
Specify the target currency you would like to receive official pairs of.
Valid Structure: “USD”

Response Object

{{currency}}: List of Objects.
[{
symbol: String.
The official symbol of the given currency pair.

conid: int.
The official contract identifier of the given currency pair.

ccyPair: String.
Returns the counterpart of
}]

{
  "USD": [
    {
      "symbol": "USD.SGD",
      "conid": 37928772,
      "ccyPair": "SGD"
    },
	{...},
    {
      "symbol": "USD.RUB",
      "conid": 28454968,
      "ccyPair": "RUB"
    }
  ]
}

Obtains the exchange rates of the currency pair.

GET /iserver/exchangerate

Request Object

Query Params

Source: String. Required
Specify the base currency to request data for.
Valid Structure: “AUD”

Target: String. Required
Specify the quote currency to request data for.
Valid Structure: “USD”

Response Object

rate: float.
Returns the exchange rate for the currency pair.

{
    "rate": 0.67005002
}

Returns both contract info and rules from a single endpoint.
For only contract rules, use the endpoint /iserver/contract/rules.
For only contract info, use the endpoint /iserver/contract/{conid}/info.

GET /iserver/contract/{{ conid }}/info-and-rules

Request Object

Path Parameters

coind: String. Required
Contract identifier for the given contract.

Query Parameters

isBuy: bool.
Indicates whether you are searching for Buy or Sell order rules.
Set to true for Buy Orders, set to false for Sell Orders

Response Object

cfi_code: String.
Classification of Financial Instrument codes

symbol: String.
Underlying symbol

cusip: String.
Returns the CUSIP for the given instrument.
Only used in BOND trading.

expiry_full: String.
Returns the expiration month of the contract.
Formatted as “YYYYMM”

con_id: int.
Indicates the contract identifier of the given contract.

maturity_date: String.
Indicates the final maturity date of the given contract.
Formatted as “YYYYMMDD”

industry: String.
Specific group of companies or businesses.

instrument_type: String.
Asset class of the instrument.

trading_class: String.
Designated trading class of the contract.

valid_exchanges: String.
Comma separated list of support exchanges or trading venues.

allow_sell_long: bool.
Allowed to sell shares you own.

is_zero_commission_security: bool.
Indicates if the contract supports zero commission trading.

local_symbol: String.
Contract’s symbol from primary exchange. For options it is the OCC symbol.

contract_clarification_type: null

classifier: null.

currency: String.
Base currency contract is traded in.

text: String.
Indicates the display name of the contract, as shown with Client Portal.

underlying_con_id: int.
Underlying contract identifier for the requested contract.

r_t_h: bool.
Indicates if the contract can be traded outside regular trading hours or not.

multiplier: String.
Indicates the multiplier of the contract.

underlying_issuer: String.
Indicates the issuer of the underlying.

contract_month: String.
Indicates the year and month the contract expires.
Value Format: “YYYYMM”

company_name: String.
Indicates the name of the company or index.

smart_available: bool.
Indicates if the contract can be smart routed or not.

exchange: String.
Indicates the primary exchange for which the contract can be traded.

category: String.
Indicates the industry category of the instrument.

rules: Object.
See the /iserver/contract/rules endpoint.

{
  "cfi_code": "",
  "symbol": "AAPL",
  "cusip": null,
  "expiry_full": null,
  "con_id": 265598,
  "maturity_date": null,
  "industry": "Computers",
  "instrument_type": "STK",
  "trading_class": "NMS",
  "valid_exchanges": "SMART,AMEX,NYSE,CBOE,PHLX,ISE,CHX,ARCA,ISLAND,DRCTEDGE,BEX,BATS,EDGEA,JEFFALGO,BYX,IEX,EDGX,FOXRIVER,PEARL,NYSENAT,LTSE,MEMX,TPLUS1,IBEOS,OVERNIGHT,PSX",
  "allow_sell_long": false,
  "is_zero_commission_security": false,
  "local_symbol": "AAPL",
  "contract_clarification_type": null,
  "classifier": null,
  "currency": "USD",
  "text": null,
  "underlying_con_id": 0,
  "r_t_h": true,
  "multiplier": null,
  "underlying_issuer": null,
  "contract_month": null,
  "company_name": "APPLE INC",
  "smart_available": true,
  "exchange": "SMART",
  "category": "Computers",
  "rules": {
    "algoEligible": true,
    "overnightEligible": true,
    "costReport": false,
    "canTradeAcctIds": [
      "U1234567"
    ],
    "error": null,
    "orderTypes": [
      "limit",
      "midprice",
      "market",
      "stop",
      "stop_limit",
      "mit",
      "lit",
      "trailing_stop",
      "trailing_stop_limit",
      "relative",
      "marketonclose",
      "limitonclose"
    ],
    "ibAlgoTypes": [
      "limit",
      "stop_limit",
      "lit",
      "trailing_stop_limit",
      "relative",
      "marketonclose",
      "limitonclose"
    ],
    "fraqTypes": [
      "limit",
      "market",
      "stop",
      "stop_limit",
      "mit",
      "lit",
      "trailing_stop",
      "trailing_stop_limit"
    ],
    "forceOrderPreview": false,
    "cqtTypes": [
      "limit",
      "market",
      "stop",
      "stop_limit",
      "mit",
      "lit",
      "trailing_stop",
      "trailing_stop_limit"
    ],
    "orderDefaults": {
      "LMT": {
        "LP": "197.93"
      }
    },
    "orderTypesOutside": [
      "limit",
      "stop_limit",
      "lit",
      "trailing_stop_limit",
      "relative"
    ],
    "defaultSize": 100,
    "cashSize": 0.0,
    "sizeIncrement": 100,
    "tifTypes": [
      "IOC/MARKET,LIMIT,RELATIVE,MARKETONCLOSE,MIDPRICE,LIMITONCLOSE,MKT_PROTECT,STPPRT,a",
      "GTC/o,a",
      "OPG/LIMIT,MARKET,a",
      "GTD/o,a",
      "DAY/o,a"
    ],
    "tifDefaults": {
      "TIF": "DAY",
      "SIZE": "100.00"
    },
    "limitPrice": 197.93,
    "stopprice": 197.93,
    "orderOrigination": null,
    "preview": true,
    "displaySize": null,
    "fraqInt": 4,
    "cashCcy": "USD",
    "cashQtyIncr": 500,
    "priceMagnifier": null,
    "negativeCapable": false,
    "incrementType": 1,
    "incrementRules": [
      {
        "lowerEdge": 0.0,
        "increment": 0.01
      }
    ],
    "hasSecondary": true,
    "increment": 0.01,
    "incrementDigits": 2
  }
}

Returns supported IB Algos for contract.

A pre-flight request must be submitted before retrieving information

GET /iserver/contract/{{ conid }}/algos

Request Object

Path Parameters

conid: String. Required
Contract identifier for the requested contract of interest.

Query Parameters

algos: String. Optional
List of algo ids delimited by “;” to filter by.
Max of 8 algos ids can be specified.
Case sensitive to algo id.

addDescription: String. Optional
Whether or not to add algo descriptions to response. Set to 1 for yes, 0 for no.

addParams: String. Optional
Whether or not to show algo parameters. Set to 1 for yes, 0 for no.

Response Object

algos: Array of objects.
Contains all relevant algos for the contract.

[{

name: String.
Common name of the algo.

id: String.
Algo identifier used for requests

parameters: Array of objects.
All parameters relevant to the given algo.
Only returned if addParams=1

[{

guiRank: int.
Positional ranking for the algo. Used for Client Portal.

defaultValue: int.
Default parameter value.

name: String.
Parameter name.

id: String.
Parameter identifier for the algo.

legalStrings: Array
Allowed values for the parameter.

required: String.
States whether the parameter is required for the given algo order to place.
Returns a string representation of a boolean.

valueClassName: String.
Returns the variable type of the parameter.
}]
}]

{
  "algos": [
    {
      "name": "Adaptive",
      "id": "Adaptive",
      "parameters": [
        {
          "guiRank": 1,
          "defaultValue": "Normal",
          "name": "Adaptive order priority/urgency",
          "id": "adaptivePriority",
          "legalStrings": [
            "Urgent",
            "Normal",
            "Patient"
          ],
          "required": "true",
          "valueClassName": "String"
        }
      ]
    },
    {
      "name": "VWAP",
      "id": "Vwap",
      "parameters": [
        {
          "guiRank": 5,
          "defaultValue": false,
          "name": "Attempt to never take liquidity",
          "id": "noTakeLiq",
          "valueClassName": "Boolean"
        },
        {
          "guiRank": 11,
          "defaultValue": false,
          "name": "Opt-out closing auction",
          "id": "optoutClosingAuction",
          "valueClassName": "Boolean"
        },
        {
          "guiRank": 4,
          "defaultValue": false,
          "name": "Allow trading past end time",
          "id": "allowPastEndTime",
          "valueClassName": "Boolean"
        },
        {
          "guiRank": 8,
          "defaultValue": false,
          "name": "Speed up when market approaches limit price",
          "description": "Compensate for decreased fill rate due to presence of limit price.",
          "id": "speedUp",
          "enabledConditions": [
            "MKT:speedUp:=:no"
          ],
          "valueClassName": "Boolean"
        },
        {
          "guiRank": 12,
          "name": "Trade when price is more aggressive than:",
          "description": "Evaluates with bid for buy order and ask for sell order",
          "id": "conditionalPrice",
          "valueClassName": "Double"
        },
        {
          "guiRank": 2,
          "name": "Start Time",
          "description": "Defaults to start of market trading",
          "id": "startTime",
          "valueClassName": "Time"
        },
        {
          "guiRank": 1,
          "minValue": 0.01,
          "maxValue": 50,
          "name": "Max Percentage",
          "description": "From 0.01 to 50.0",
          "id": "maxPctVol",
          "valueClassName": "Double"
        },
        {
          "guiRank": 3,
          "name": "End Time",
          "description": "Defaults to end of market trading",
          "id": "endTime",
          "valueClassName": "Time"
        }
      ]
    }
  ]
}

Request a list of filters relating to a given Bond issuerID. The issuerId is retrieved from /iserver/secdef/search and can be used in /iserver/secdef/info?issuerId={{ issuerId }} for retrieving conIds.

/iserver/secdef/bond-filters

Request Object

Query Params

symbol: String. Required
This should always be set to “BOND”

issuerId: String. Required
Specifies the issuerId value used to designate the bond issuer type.

bondFilters: Array of Objects.
Contains all filters pertaining to the given issuerId.
[{
displayText: String.
An identifier used to document returned options/values. This can be thought of as a key value.

columnId: int.
Used for user interfaces. Internal use only.

options: Array of objects.
Contains all objects with values corresponding to the parent displayText key.
[{
text: String.
In some instances, a text value will be returned, which indicates the standardized value format such as plaintext dates, rather than solely numerical values.

value: String.
Returns value directly correlating to the displayText key. This may include exchange, maturity date, issue date, coupon, or currency.

}]

}]

{
  "bondFilters": [
    {
      "displayText": "Exchange",
      "columnId": 0,
      "options": [
      {
        "value": "SMART"
      }]
    },
    {
      "displayText": "Maturity Date",
      "columnId": 27,
      "options": [
        {
          "text": "Jan 2025",
          "value": "202501"
      }]
    },
    {
      "displayText": "Issue Date",
      "columnId": 28,
      "options": [{
        "text": "Sep 18 2014",
        "value": "20140918"
      }]
    },
    {
      "displayText": "Coupon",
      "columnId": 25,
      "options": [{
        "value": "1.301"
      }]
    },
    {
      "displayText": "Currency",
      "columnId": 5,
      "options": [{
        "value": "EUR"
      }]
    }
  ]
}

Search by underlying symbol or company name. Relays back what derivative contract(s) it has. This endpoint must be called before using /secdef/info.
If company name is specified will only receive limited response: conid, companyName, companyHeader and symbol.

For bonds, enter the family type in the symbol field to receive the issuerID used in the /iserver/secdef/info endpoint.

GET /iserver/secdef/search

Request Object

Query Params

symbol: String. Required
Underlying symbol of interest. May also pass company name if ‘name’ is set to true, or bond issuer type to retrieve bonds.

name: bool.
Determines if symbol reflects company name or ticker symbol.

secType: String.
Valid Values: “STK”, “IND”, “BOND”
Declares underlying security type.

Response Object

“conid”: String.
Conid of the given contract.

“companyHeader”: String.
Extended company name and primary exchange.

“companyName”: String.
Name of the company.

“symbol”: String.
Company ticker symbol.

“description”: String.
Primary exchange of the contract.

“restricted”: bool.
Returns if the contract is available for trading.

“fop”: String.
Returns a string of dates, separated by semicolons.
Value Format: “YYYYMMDD;YYYYMMDD;YYYYMMDD”

“opt”: String.
Returns a string of dates, separated by semicolons.
Value Format: “YYYYMMDD;YYYYMMDD;YYYYMMDD”

“war”: String.
Returns a string of dates, separated by semicolons.
Value Format: “YYYYMMDD;YYYYMMDD;YYYYMMDD”

“sections”: Array of objects

“secType”: String.
Given contracts security type.

“months”: String.
Returns a string of dates, separated by semicolons.
Value Format: “JANYY;FEBYY;MARYY”

“symbol”: String.
Symbol of the instrument.

“exchange”: String.
Returns a string of exchanges, separated by semicolons.
Value Format: “EXCH;EXCH;EXCH”

Unique for Bonds
“issuers”: Array of objects
Array of objects containing the id and name for each bond issuer.

“id”: String.
Issuer Id for the given contract.

“name”: String.
Name of the issuer.

“bondid”: int.
Bond type identifier.

“conid”: String.
Contract ID for the given bond.

“companyHeader”: String.
Name of the bond type
Value Format: “Corporate Fixed Income”

“companyName”: null
Returns ‘null’ for bond contracts.

“symbol”:null
Returns ‘null’ for bond contracts.

“description”:null
Returns ‘null’ for bond contracts.

“restricted”:null
Returns ‘null’ for bond contracts.

“fop”:null
Returns ‘null’ for bond contracts.

“opt”:null
Returns ‘null’ for bond contracts.

“war”:null
Returns ‘null’ for bond contracts.

“sections”: Array of objects
Only relays “secType”:”BOND” in the Bonds section.

[
  {
    "conid": "43645865",
    "companyHeader": "IBKR INTERACTIVE BROKERS GRO-CL A (NASDAQ) ",
    "companyName": "INTERACTIVE BROKERS GRO-CL A (NASDAQ)",
    "symbol": "IBKR",
    "description": null,
    "restricted": null,
    "fop": null,
    "opt": null,
    "war": null,
    "sections": [],
    "secType": "STK"
  }
]

Returns trading related rules for a specific contract and side.

POST /iserver/contract/rules

Request Object

Body Parameters

conid: Number. Required
Contract identifier for the interested contract.

exchange: String.
Designate the exchange you wish to receive information for in relation to the contract.

isBuy: bool.
Side of the market rules apply too. Set to true for Buy Orders, set to false for Sell Orders
Defaults to true or Buy side rules.

modifyOrder: bool.
Used to find trading rules related to an existing order.

orderId: Number. Required for modifyOrder:true
Specify the order identifier used for tracking a given order.

Response Object

algoEligible: bool.
Indicates if the contract can trade algos or not.

overnightEligible: bool.
Indicates if outsideRTH trading is permitted for the instrument

costReport: bool.
Indicates whether or not a cost report has been requested (Client Portal only).

canTradeAcctIds: Array of Strings.
Indicates permitted accountIDs that may trade the contract.

error: String.
If rules information can not be received for any reason, it will be expressed here.

orderTypes: Array of Strings
Indicates permitted order types for use with standard quantity trading.

ibAlgoTypes: Array of Strings.
Indicates permitted algo types for use with the given contract.

fraqTypes: Array of Strings.
Indicates permitted order types for use with fractional trading.

forceOrderPreview: bool.
Indicates if the order preview is forced upon the user before submission.

cqtTypes: Array of Strings.
Indicates accepted order types for use with cash quantity.

orderDefaults: Object of objects
Indicates default order type for the given security type.

orderTypesOutside: Array of Strings.
Indicates permitted order types for use outside of regular trading hours.

defaultSize: int.
Default total quantity value for orders.

cashSize: float.
Default cash value quantity.

sizeIncrement: int.
Indicates quantity increase for the contract.

tifTypes: Array of Strings.
Indicates allowed tif types supported for the contract.

tifDefaults: Object.
Object containing details about your TIF value defaults.
These defaults can be viewed and modified in TWS’s within the Global Configuration.

limitPrice: float.
Default limit price for the given contract.

stopprice: float.
Default stop price for the given contract.

orderOrigination: String.
Order origin designation for US securities options and Options Clearing Corporation

preview: bool.
Indicates if the order preview is required (for client portal only)

displaySize: int.

fraqInt: int.
Indicates decimal places for fractional order size

cashCcy: String.
Indicates base currency for the instrument.

cashQtyIncr: int.
Indicates cash quantity increment rules.

priceMagnifier: int.
Signifies the magnifier of a given contract.
This is separate from the price multiplier, and will typically return ‘null’

negativeCapable: bool.
Indicates if the value of the contract can be negative (true) or if it is always positive (false).

incrementType: int.
Indicates the type of increment style.

incrementRules: Array of objects.
Indicates increment rule values including lowerEdge and increment value.

hasSecondary: bool.

modTypes: Array of Strings.
Lists the available order types supported when modifying the order.

increment: float.
Minimum increment values for prices

incrementDigits: int.
Number of decimal places to indicate the increment value.

{
  "algoEligible": true,
  "overnightEligible": true,
  "costReport": false,
  "canTradeAcctIds": [
    "U1234567"
  ],
  "error": null,
  "orderTypes": [
    "limit",
    "midprice",
    "market",
    "stop",
    "stop_limit",
    "mit",
    "lit",
    "trailing_stop",
    "trailing_stop_limit",
    "relative",
    "marketonclose",
    "limitonclose"
  ],
  "ibAlgoTypes": [
    "limit",
    "stop_limit",
    "lit",
    "trailing_stop_limit",
    "relative",
    "marketonclose",
    "limitonclose"
  ],
  "fraqTypes": [],
  "forceOrderPreview": false,
  "cqtTypes": [
    "limit",
    "market",
    "stop",
    "stop_limit",
    "mit",
    "lit",
    "trailing_stop",
    "trailing_stop_limit"
  ],
  "orderDefaults": {
    "LMT": {
      "LP": "549000.00"
    }
  },
  "orderTypesOutside": [
    "limit",
    "stop_limit",
    "lit",
    "trailing_stop_limit",
    "relative"
  ],
  "defaultSize": 100,
  "cashSize": 0.0,
  "sizeIncrement": 1,
  "tifTypes": [
    "IOC/MARKET,LIMIT,RELATIVE,MARKETONCLOSE,MIDPRICE,LIMITONCLOSE,MKT_PROTECT,STPPRT,a",
    "GTC/o,a",
    "OPG/LIMIT,MARKET,a",
    "GTD/o,a",
    "DAY/o,a"
  ],
  "tifDefaults": {
    "TIF": "DAY",
    "SIZE": "100.00"
  },
  "limitPrice": 549000.0,
  "stopprice": 549000.0,
  "orderOrigination": null,
  "preview": true,
  "displaySize": null,
  "fraqInt": 0,
  "cashCcy": "USD",
  "cashQtyIncr": 500,
  "priceMagnifier": null,
  "negativeCapable": false,
  "incrementType": 1,
  "incrementRules": [
    {
      "lowerEdge": 0.0,
      "increment": 0.01
    }
  ],
  "hasSecondary": true,
  "increment": 0.01,
  "incrementDigits": 2
}

Provides Contract Details of Futures, Options, Warrants, Cash and CFDs based on conid.

For all instruments, /iserver/secdef/search must be called first.

For derivatives such as Options, Warrants, and Futures Options, you will need to query /iserver/secdef/strikes as well.

GET /iserver/secdef/info

Request Object

Query Parameters

conid: String. Required
Contract identifier of the underlying. May also pass the final derivative conid directly.

sectype: String. Required
Security type of the requested contract of interest.

month: String. Required for Derivatives
Expiration month for the given derivative.

exchange: String. Optional
Designate the exchange you wish to receive information for in relation to the contract.

strike: String. Required for Options and Futures Options
Set the strike price for the requested contract details

right: String. Required for Options
Set the right for the given contract.
Value Format: “C” for Call or “P” for Put.

issuerId: String. Required for Bonds
Set the issuerId for the given bond issuer type.
Example Format: “e1234567”

Response Object

conid: int.
Contract Identifier of the given contract

ticker: String
Ticker symbol for the given contract

secType: String.
Security type for the given contract.

listingExchange: String.
Primary listing exchange for the given contract.

exchange: String.
Exchange requesting data for.

companyName: String.
Name of the company for the given contract.

currency: String
Traded currency allowed for the given contract.

validExchanges: String*
Series of all valid exchanges the contract can be traded on in a single comma-separated string.
priceRendering: null.

maturityDate: String
Date of expiration for the given contract.

right: String.
Right (P or C) for the given contract.

strike: Float.
Returns the given strike value for the given contract.

[
  {
    "conid": 667629330,
    "symbol": "AAPL",
    "secType": "OPT",
    "exchange": "SMART",
    "listingExchange": null,
    "right": "P",
    "strike": 195.0,
    "currency": "USD",
    "cusip": null,
    "coupon": "No Coupon",
    "desc1": "AAPL",
    "desc2": "JAN 05 '24 195 Put",
    "maturityDate": "20240105",
    "multiplier": "100",
    "tradingClass": "AAPL",
    "validExchanges": "SMART,AMEX,CBOE,PHLX,PSE,ISE,BOX,BATS,NASDAQOM,CBOE2,NASDAQBX,MIAX,GEMINI,EDGX,MERCURY,PEARL,EMERALD,MEMX,IBUSOPT"
  }
]

Query to receive a list of potential strikes supported for a given underlying.

This endpoint will always return empty arrays unless  /iserver/secdef/search is called for the same underlying symbol beforehand.

GET /iserver/secdef/strikes

Request Object

Query Parameters

conid: String. Required
Contract Identifier number for the underlying

sectype: String. Required
Security type of the derivatives you are looking for.
Value Format: “OPT” or “WAR”

month: String. Required
Expiration month and year for the given underlying
Value Format: {3 character month}{2 character year}
Example: AUG23

exchange: String. Optional
Exchange from which derivatives should be retrieved from.
Default value is set to SMART

Response Object

call: Array of Floats
Array containing a series of comma separated float values representing potential call strikes for the instrument.

put: Array of Floats
Array containing a series of comma separated float values representing potential put strikes for the instrument.

{
  "call":[
    185.0,
    190.0,
    195.0,
    200.0
  ],
  "put":[
    185.0,
    190.0,
    195.0,
    200.0
  ]
}

Returns a list of non-expired future contracts for given symbol(s)

GET /trsrv/futures

Request Object

Query Params

symbols: String. Required
Indicate the symbol(s) of the underlier you are trying to retrieve futures on. Accepts comma delimited string of symbols.

Response Body

symbol: Array
Displayed as the string of your symbol
Contains a series of objects for each symbol that matches the requested.

symbol: String.
The requested symbol value.

conid: int.
Contract identifier for the specific symbol

underlyingConid: int.
Contract identifier for the future’s underlying contract.

expirationDate: int.
Expiration date of the specific future contract.

ltd: int.
Last trade date of the future contract.

shortFuturesCutOff: int.
Represents the final day for contract rollover for shorted futures.

longFuturesCutOff: int.
Represents the final day for contract rollover for long futures.

{
  "ES": [
    {
      "symbol": "ES",
      "conid": 495512552,
      "underlyingConid": 11004968,
      "expirationDate": 20231215,
      "ltd": 20231214,
      "shortFuturesCutOff": 20231214,
      "longFuturesCutOff": 20231214
    },
    {...}
  ],
  "MES": [
    {
      "symbol": "MES",
      "conid": 586139726,
      "underlyingConid": 362673777,
      "expirationDate": 20231215,
      "ltd": 20231215,
      "shortFuturesCutOff": 20231215,
      "longFuturesCutOff": 20231215
    },
    {...}
  ]
}

Returns an object contains all stock contracts for given symbol(s)

GET /trsrv/stocks

Request Object

Query Params

symbols: String.
Comma-separated list of stock symbols. Symbols must contain only capitalized letters.

Response Object

symbol: Array of Json
Contains a series of Json for all contracts that match the symbol.

name: String.
Full company name for the given contract.

chineseName: String.
Chinese name for the given company.

assetClass: String.
Asset class for the given company.

contracts: Array.
A series of arrays pertaining to the same company listed by “name”.
Typically differentiated based on currency of the primary exchange.

conid: int.
Contract ID for the specific contract.

exchange: String.
Primary exchange for the given contract.

isUS: bool.
States whether the contract is hosted in the United States or not.

{
  "AAPL": [
    {
      "name": "APPLE INC",
      "chineseName": "苹果公司",
      "assetClass": "STK",
      "contracts": [
        {
          "conid": 265598,
          "exchange": "NASDAQ",
          "isUS": true
        },
        {
          "conid": 38708077,
          "exchange": "MEXI",
          "isUS": false
        },
        {
          "conid": 273982664,
          "exchange": "EBS",
          "isUS": false
        }
      ]
    },
    {
      "name": "LS 1X AAPL",
      "chineseName": null,
      "assetClass": "STK",
      "contracts": [
        {
          "conid": 493546048,
          "exchange": "LSEETF",
          "isUS": false
        }
      ]
    },
    {
      "name": "APPLE INC-CDR",
      "chineseName": "苹果公司",
      "assetClass": "STK",
      "contracts": [
        {
          "conid": 532640894,
          "exchange": "AEQLIT",
          "isUS": false
        }
      ]
    }
  ]
}

Returns the trading schedule up to a month for the requested contract

GET /trsrv/secdef/schedule

Request Object

Query Params

assetClass: String. Required
Specify the security type of the given contract.
Value Formats: Stock: STK, Option: OPT, Future: FUT, Contract For Difference: CFD, Warrant: WAR, Forex: SWP, Mutual Fund: FND, Bond: BND, Inter-Commodity Spreads: ICS

symbol: String. Required
Specify the symbol for your contract.

exchange: String.
Specify the primary exchange of your contract.

exchangeFilter: String.
Specify all exchanges you want to retrieve data from.

Response Object

id: String.
Exchange parameter id

tradeVenueId: String.
Reference on a trade venue of given exchange parameter

schedules: Array of Objets.
Always contains at least one ‘tradingTime’ and zero or more ‘sessionTime’ tags

clearingCycleEndTime: int.
End of clearing cycle.

tradingScheduleDate: int.
Date of the clearing schedule.
20000101 stands for any Sat, 20000102 stands for any Sun, … 20000107 stands for any Fri. Any other date stands for itself.

sessions: Object.
description: String.
If the LIQUID hours differs from the total trading day then a separate ‘session’ tag is returned.

openingTime: int.
Opening date time of the session.

closingTime: int.
Closing date time of the sesion.

prop: String.
If the whole trading day is considered LIQUID then the value ‘LIQUID’ is returned.

tradingTimes: Object.
Object containing trading times.

description: String
Returns tradingTime in exchange time zone.

openingTime: int.
Opening time of the trading day.

closingTime: int.
Closing time of the trading day.

cancelDayOrders: string.
Cancel time for day orders.

[
  {
    "id": "p102082",
    "tradeVenueId": "v13133",
    "timezone": "America/New_York",
    "schedules": [      
      {
        "clearingCycleEndTime": "2000",
        "tradingScheduleDate": "20000103",
        "sessions": [
          {
            "openingTime": "0930",
            "closingTime": "1600",
            "prop": "LIQUID"
          }
        ],
        "tradingtimes": [
          {
            "openingTime": "0400",
            "closingTime": "2000",
            "cancelDayOrders": "Y"
          }
        ]
      },
      {...}
    ]
  }
]

Retrieves a list of all sub-accounts and returns their net liquidity and available equity for advisors to make decisions on what accounts should be allocated and how.

GET /iserver/account/allocation/accounts

Request Object

No params or body content should be sent.

Response Object

accounts: Array of objects.
Array containing all sub-accounts held by the advisor.
[{
data: Array of objects.
Contains Net liquidation and available equity of the given account Id.
[{
value: String.
Contains the price value affiliated with the key.

key: String.
Defines the value of the object.
Expected values: “AvailableEquity”, “NetLiquidation”
}]
name: String.
Returns the account ID affiliated with the balance data.
}]

{
  "accounts": [
    {
      "data": [
        {
          "value": "2677.89",
          "key": "NetLiquidation"
        },
        {
          "value": "2134.76",
          "key": "AvailableEquity"
        }
      ],
      "name": "U123456"
    },
    {
      "data": [
        {
          "value": "1200.88",
          "key": "NetLiquidation"
        },
        {
          "value": "1000.56",
          "key": "AvailableEquity"
        }
      ],
      "name": "U456789"
    }
  ]
}

Retrieves a list of all of the advisor’s allocation groups. This describes the name of the allocation group, number of subaccounts within the group, and the method in use for the group.

GET /iserver/account/allocation/group

Request Object

No params or body content should be sent.

Response Object

data: Array of objects.
Contains object pairs for each allocation groups
[{
allocation_method: String.
Uses the Allocation Method Code to represent which method is implemented.

size: int.
Represents the total number of sub-accounts within the group.

name: String.
The name set for the given allocation group.
}]

{
  "data": [
    {
      "allocation_method": "N",
      "size": 10,
      "name": "Group_1_NetLiq"
    }
  ]
}

Retrieves the configuration of a single account group. This describes the name of the allocation group, the specific accounts contained in the group, and the allocation method in use along with any relevant quantities.

POST /iserver/account/allocation/group/single

Request Object

Body Params

name: String. Required.
Name of an existing allocation group.

Response Object

{
name: String. Required Required
Name used to refer to your allocation group. This will be used while placing orders.

accounts: Array of objects. Required
Contains a series of objects depicting which accounts are involved and, for user-defined allocation methods, the distribution value for each sub-account.
[
{
name: String. Required
The accountId of a given sub-account.
Value Format: “U1234567”

amount: Number.
The total distribution value for each sub-account for user-defined allocation methods.
}
]
default_method: String.
Specify the allocation method code for the allocation group.
See Allocation Method Codes for more details.
}

{
  "name": "Group_1_NetLiq",
  "accounts": [
    {
      "amount": 1,
      "name": "DU1234567"
    },
    {
      "amount": 5,
      "name": "DU9876543"
    }
  ],
  "default_method": "R"
}

Add a new allocation group. This group can be used to trade

POST /iserver/account/allocation/group

Request Object

Body Params

name: String. Required Required
Name used to refer to your allocation group. This will be used while placing orders.

accounts: Array of objects. Required
Contains a series of objects depicting which accounts are involved and, for user-defined allocation methods, the distribution value for each sub-account.
[{
name: String. Required
The accountId of a given sub-account.
Value Format: “U1234567”

amount: Number.
The total distribution value for each sub-account for user-defined allocation methods.
}]
default_method: String.
Specify the allocation method code for the allocation group.
See Allocation Method Codes for more details.

Response Object

success: bool.
Confirms that the allocation group was properly set.

{
  "success": true
}

Modify an existing allocation group.

PUT /iserver/account/allocation/group

Request Object

Body Params

name: String. Required Required
Name used to refer to your allocation group. If prev_name is specified, this will become the new name of the group.

prev_name: String.
Name used to refer to your existing allocation group.
Only use this when updating the group name.

accounts: Array of objects. Required
Contains a series of objects depicting which accounts are involved and, for user-defined allocation methods, the distribution value for each sub-account.
[{
name: String. Required
The accountId of a given sub-account.
Value Format: “U1234567”

amount: Number.
The total distribution value for each sub-account for user-defined allocation methods.
}]
default_method: String. Required
Specify the allocation method code for the allocation group.
See Allocation Method Codes for more details.

Response Object

success: bool.
Confirms that the allocation group was properly set.

{
  "success": true
}

Remove an existing allocation group. This group will no longer be accessible.

POST /iserver/account/allocation/group/delete

Request Object

Body Params

name: String. Required Required
Name used to refer to your allocation group.

Response Object

success: bool.
Confirms that the allocation group was properly set.

{
  "success": true
}

Retrieve the preset behavior for allocation groups for specific events.

GET /iserver/account/allocation/presets

Request Object

No params or body content should be sent.

Response Object

group_auto_close_positions: bool.

default_method_for_all: String.

profiles_auto_close_positions: bool.

strict_credit_check: bool.

group_proportional_allocation: bool.

{
  "group_auto_close_positions": false,
  "default_method_for_all": "N",
  "profiles_auto_close_positions": false,
  "strict_credit_check": false,
  "group_proportional_allocation": false
}

Set the preset behavior for allocation groups for specific events.

POST /iserver/account/allocation/presets

Request Object

Body Params

default_method_for_all: String. Required
Set the default allocation method to be used for all allocation groups without a set value.

group_auto_close_positions: bool. Required

profiles_auto_close_positions: bool. Required

strict_credit_check: bool. Required

group_proportional_allocation: bool. Required

Response Object

success: bool.
Confirms that the preset was properly set.

{
  "success": true
}

IB-computed allocation methods

User-specified allocation methods

Formerly known as Allocation Profiles

Returns the total number of unread fyis

GET /fyi/unreadnumber

Request Object

No params or body content should be sent.

Response Object

BN: int.
Returns the number of unread bulletins.

{
  "BN": 4
}

Return the current choices of subscriptions for notifications.

GET /fyi/settings

Request Object

No params or body content should be sent.

Response Object

A: int.
Returns if the subscription can be modified.
Only returned if the subscription can be modified.
See /fyi/settings/{typecode} for how to modify.

FC: String.
Fyi code for enabling or disabling the notification.

H: int.
Disclaimer if the notification was read.
Value Format: 0: Unread; 1: Read

FD: String.
Returns a detailed description of the topic.

FN: String.
Returns a human readable title for the notification.

[
  {
    "FC": "M8",
    "H": 0,
    "A": 1,
    "FD": "Notify me when I establish position subject to US dividend tax withholding 871(m) rules.",
    "FN": "871(m) Trades"
  },
  {
    "FC": "AA",
    "H": 0,
    "A": 1,
    "FD": "Notifications related to account activity such as funding, application, trading and market data permission status",
    "FN": "Account Activity"
  },
  {...}
]

Configure which typecode you would like to enable/disable.

POST /fyi/settings/{{ typecode }}

Request Object

Path Params

typecode: String. Required
Code used to signify a specific type of FYI template.
See Typecode section for more details.

Body Params

enabled: bool. Required
Enable or disable the subscription.
See available typecodes under FYI Typecodes
Value format: true: Enable; false: Disable

Response Object

V: int.
Returns 1 to state message was acknowledged.

T: int.
Returns the time in ms to complete the edit.

{
  "V": 1,
  "T": 10
}

Receive additional disclaimers based on the specified typecode.

GET /fyi/disclaimer/{typecode}

Request Object

Path Params

typecode: String. Required
Code used to signify a specific type of FYI template.
See FYI Typecodes section for more details.

Response Object

FC: String.
Returns the Typecode for the given disclaimer.

DT: String.
Returns the Disclaimer message

{
  "FC": "SM",
  "DT": "This communication is provided for information purposes only and is not intended as a recommendation or a solicitation to buy, sell or hold any investment product. Customers are solely responsible for their own trading decisions."
}

Mark disclaimer message read.

PUT /fyi/disclaimer/{typecode}

Request Object

Path Params

typecode: String. Required
Code used to signify a specific type of FYI template.
See Typecode section for more details.

Response Object

V: int.
Returns 1 to state message was acknowledged.

T: int.
Returns the time in ms to complete the edit.

{
  "V": 1,
  "T": 10
}

Options for sending fyis to email and other devices

GET /fyi/deliveryoptions

Request Object

No params or body content should be sent.

Response Object

M: int.
Email option is enabled or not.
Value Format: 0: Email Disabled; 1: Email Enabled.

E: Array.
Returns an array of device information.
[{
NM: String.
Returns the human readable device name.

I: String.
Returns the deice identifier.

UI: String.
Returns the unique device ID.

A: String.
Device is enabled or not.
Value Format: 0: Disabled; 1: Enabled.
}]

{
  "E": [
    {
      "NM": "iPhone",
      "I": "apn://mtws@1234E5E67D8A9012EC3E45D6E7D89A01F2345CDBBB678B9BE0FB12345AF6D789",
      "UI": "apn://mtws@1234E5E67D8A9012EC3E45D6E7D89A01F2345CDBBB678B9BE0FB12345AF6D789",
      "A": 1
    }
  ],
  "M": 1
}

Choose whether a particular device is enabled or disabled.

POST /fyi/deliveryoptions/device

Request Object

Body Params

devicename: String. Required
Human readable name of the device.

deviceId: String. Required
ID Code for the specific device.

uiName: String. Required
Title used for the interface system.

enabled: bool. Required
Specify if the device should be enabled or disabled.

Response Object

V: int.
Returns 1 to state message was acknowledged.

T: int.
Returns the time in ms to complete the edit.

{
  "V": 1,
  "T": 10
}

Delete a specific device from our saved list of notification devices.

DELETE /fyi/deliveryoptions/{{ deviceId }}

Request Object

Path Params

deviceId: String. Required
Display the device identifier to delete from IB’s saved list.
Can be retrieved from /fyi/deliveryoptions.

Enable or disable your account’s primary email to receive notifications.

PUT /fyi/deliveryoptions/email

Request Object

Query Params

enabled: String. Required
Enable or disable your email.
Value format: true: Enable; false: Disable

Response Object

V: int.
Returns 1 to state message was acknowledged.

T: int.
Returns the time in ms to complete the edit.

{
  "V": 1,
  "T": 10
}

Get a list of available notifications.

GET /fyi/notifications

Request Object

Query Params

max: String.
Specify the maximum number of notifications to receive.
Can request a maximum of 10 notifications.

Response Object

D: String.
Notification date

ID: String.
Unique way to reference the notification.

FC: String.
FYI code, we can use it to find whether the disclaimer is accepted or not in settings

MD: String.
Content of notification.

MS: String.
Title of notification.

R: string.
Return if the notification was read or not.
Value Format: 0: Disabled; 1: Enabled.

[{
  "R": 0,
  "D": "1702469440.0",
  "MS": "IBKR FYI: Option Expiration Notification",
  "MD": "One or more option contracts in your portfolio are set to expire shortly.  
 - QQQ 15DEC2023 385 P in Account(Qty): U****7890(6) 
 - QQQ 15DEC2023 387 P in Account(Qty): D****0685(-6) 
  
Please use the Option Rollover tool to roll existing contracts into contracts with an expiration, strike and price condition of your preference.",
  "ID": "2023121370119463",
  "HT": 0,
  "FC": "OE"
}]

Mark a particular notification message as read or unread.

PUT /fyi/notifications/{notificationID}

Request Object

Path Params

notificationId: String. Required
Code used to signify a specific notification to mark.

Response Object

V: int.
Returns 1 to state message was acknowledged.

T: int.
Returns the time in ms to complete the edit.

P: Object.
Returns details about the notification read status.

R: int.
Returns if the message was read (1) or unread (0).

ID: String.
Returns the ID for the notification..

{
  "V": 1,
  "T": 5,
  "P": {
    "R": 1,
    "ID": "12345678901234567"
  }
}

Get Market Data for the given conid(s).

A pre-flight request must be made prior to ever receiving data. For some fields, it may take more than a few moments to receive information.

See response fields for a list of available fields that can be request via fields argument.

The endpoint /iserver/accounts must be called prior to /iserver/marketdata/snapshot.

For derivative contracts the endpoint /iserver/secdef/search must be called first.

GET /iserver/marketdata/snapshot

Request Object

Query Parameters

conids: String. Required
Contract identifier for the contract of interest.
May provide a comma-separated series of contract identifiers.

fields: String. Required
Specify a series of tick values to be returned.
May provide a comma-separated series of field ids.
See Market Data Fields for more information.

Response Object

server_id: String.
Returns the request’s identifier.

conidEx: String.
Returns the passed conid field. May include exchange if specified in request.

conid: int.
Returns the contract id of the request

_updated: int*.
Returns the epoch time of the update in a 13 character integer .

6119: String.
Field value of the server_id. Returns the request’s identifier.

fields*: String.
Returns a response for each request. Some fields not be as readily available as others. See the Market Data section for more details.

6509: String.
Returns a multi-character value representing the Market Data Availability.

[
  {
    "_updated": 1702334859712,
    "conidEx": "265598",
    "conid": 265598,
    "server_id": "q1",
    "6119": "serverId",
    "31": "193.18",
    "84": "193.06",
    "86":"193.14", 
    "6509": "RpB"
  }
]

Send a request for a regulatory snapshot.
This will cost $0.01 USD per request unless you are subscribed to the direct exchange market data already.

GET /md/regsnapshot

Request Object

Query Params

conid: String. Required
Provide the contract identifier to retrieve market data for.

Response Object

Note: The integer fields returned below also correspond to the Market Data Field values used for the standard /iserver/marketdata/snapshot endpoint.

conid: int.
Returns the contract ID of the request.

conidEx: String.
Returns the contract ID of the request type.

BboExchange: String.
Color for Best Bid/Offer Exchange in hex code

HasDelayed: false,
Returns if the data is live (false) or delayed (true).

84: float.
Returns the Bid value.

86: float.
Returns the Ask value.

88: int.
Returns the Bid size.

85: int.
Returns the Ask size.

BestBidExch: int.
Returns the exchange identifier of the current best bid value.
Internal use only.

BestAskExch: int.
Returns the exchange identifier of the current best Ask value.
Internal use only.

31: float.
Returns the exchange identifier of the most recent Last value.
Internal use only.

7059: int.
Returns the last traded size.

LastExch: int.
Returns the exchange of the last exchange as a binary integer*
Internal use only.

7057: String.
Returns the series of character codes for the Ask exchange.

7068: String.
Returns the series of character codes for the Bid exchange.

7058: String.
Returns the series of character codes for the Last exchange.

{
  "conid": conid,
  "conidEx": "conidEx",
  "BboExchange": "BboExchange",
  "HasDelayed": HasDelayed,
  "84": "Bid",
  "86": "Ask",
  "88": Bid_Size,
  "85": Ask_Size,
  "BestBidExch": BestBidExch,
  "BestAskExch": BestAskExch,
  "31": "Last",
  "7059": Last_Size,
  "LastExch": LastExch,
  "7057": "Ask Exch",
  "7068": "Bid Exch",
  "7058": "Last_Exch"
}

Get historical market Data for given conid, length of data is controlled by ‘period’ and ‘bar’.

Formatted as: min=minute, h=hour, d=day, w=week, m=month, y=year

Note:

• There’s a limit of 5 concurrent requests. Excessive requests will return a ‘Too many requests’ status 429 response.
• This /iserver/marketdata/history only provides up to 1000 data points.

GET /iserver/marketdata/history

Request Object

Query Params

conid: String. Required
Contract identifier for the ticker symbol of interest.

exchange: String.
Returns the exchange you want to receive data from.

period: String.
Overall duration for which data should be returned.
Default to 1w
Available time period– {1-30}min, {1-8}h, {1-1000}d, {1-792}w, {1-182}m, {1-15}y

bar: String. Required
Individual bars of data to be returned.
Possible value– 1min, 2min, 3min, 5min, 10min, 15min, 30min, 1h, 2h, 3h, 4h, 8h, 1d, 1w, 1m

startTime: String
Starting date of the request duration.

outsideRth: bool.
Determine if you want data after regular trading hours.

Response Object

serverId: String.
Internal request identifier.

symbol: String.
Returns the ticker symbol of the contract.

text: String.
Returns the long name of the ticker symbol.

priceFactor: String.
Returns the price increment obtained from the display rules.

startTime: String.
Returns the initial time of the historical data request.
Returned in UTC formatted as YYYYMMDD-HH:mm:ss

high: String.
Returns the High values during this time series with format %h/%v/%t.
%h is the high price (scaled by priceFactor),
%v is volume (volume factor will always be 100 (reported volume = actual volume/100))
%t is minutes from start time of the chart

low: String.
Returns the low value during this time series with format %l/%v/%t.
%l is the low price (scaled by priceFactor),
%v is volume (volume factor will always be 100 (reported volume = actual volume/100))
%t is minutes from start time of the chart

timePeriod: String.
Returns the duration for the historical data request

barLength: int.
Returns the number of seconds in a bar.

mdAvailability: String.
Returns the Market Data Availability.
See the Market Data Availability section for more details.

mktDataDelay: int.
Returns the amount of delay, in milliseconds, to process the historical data request.

outsideRth: bool.
Defines if the market data returned was inside regular trading hours or not.

volumeFactor: int.
Returns the factor the volume is multiplied by.

priceDisplayRule: int.
Presents the price display rule used.
For internal use only.

priceDisplayValue: String.
Presents the price display rule used.
For internal use only.

negativeCapable: bool.
Returns whether or not the data can return negative values.

messageVersion: int.
Internal use only.

data: Array of objects.
Returns all historical bars for the requested period.
[{
o: float.
Returns the Open value of the bar.

c: float.
Returns the Close value of the bar.

h: float.
Returns the High value of the bar.

l: float.
Returns the Low value of the bar.

v: float.
Returns the Volume of the bar.

t: int.
Returns the Operator Timezone Epoch Unix Timestamp of the bar.
}],

points: int.
Returns the total number of data points in the bar.

travelTime: int.
Returns the amount of time to return the details.

{
  "serverId": "20477",
  "symbol": "AAPL",
  "text": "APPLE INC",
  "priceFactor": 100,
  "startTime": "20230818-08:00:00",
  "high": "17510/472117.45/0",
  "low": "17170/472117.45/0",
  "timePeriod": "1d",
  "barLength": 86400,
  "mdAvailability": "S",
  "mktDataDelay": 0,
  "outsideRth": true,
  "tradingDayDuration": 1440,
  "volumeFactor": 1,
  "priceDisplayRule": 1,
  "priceDisplayValue": "2",
  "chartPanStartTime": "20230821-13:30:00",
  "direction": -1,
  "negativeCapable": false,
  "messageVersion": 2,
  "data": [
    {
      "o": 173.4,
      "c": 174.7,
      "h": 175.1,
      "l": 171.7,
      "v": 472117.45,
      "t": 16923456000
    }
  ],
  "points": 0,
  "travelTime": 48
}

500 System Error

error: String.

{
  'error': 'description'
}

429 Too many requests

error: String.

{
  'error': 'description'
}

Using a direct connection to the market data farm, will provide a list of historical market data for given conid.

GET /hmds/history

Request Object

Query Params

conid: String. Required
The contract identifier for which data should be requested.

period: String. Required
The duration for which data should be requested.
Available Values: See HMDS Period Units

bar: String. Required
The bar size for which bars should be returned.
Available Values: See HMDS Bar Sizes

outsideRth: bool.
Define if data should be returned for trades outside regular trading hours.

startTime: String.
Specify the value from where historical data should be taken.
Value Format: UTC; YYYYMMDD-HH:mm:dd
Defaults to the current date and time

direction: String.
Specify the direction from which market data should be returned
Available Values: -1: time from the startTime to now; 1: time from now to the end of the period.
Defaults to 1

barType: String.
Returns valid bar types for which data may be requested.
Available Values: Last, Bid, Ask, Midpoint, FeeRate, Inventory
Defaults to Last for Stocks, Options, Futures, and Futures Options.

Initial Response Object

The first time a user makes a request to the /hmds/history endpoints will result in a 404 error. This initial request instantiates the historical market data services allowing future requests to return data. Subsequent requests will return data as expected.

<html><body><h1>Resource not found</h1></body></html>

Response Object

startTime: String.
Returns the initial time of the historical data request.
Returned in UTC formatted as YYYYMMDD-HH:mm:ss

startTimeVal: int.
Returns the initial time of the historical data request.
Returned in epoch time.

endTime: String.
Returns the end time of the historical data request.
Returned in UTC formatted as YYYYMMDD-HH:mm:ss

endTimeVal: int.
Returns the end time of the historical data request.
Returned in epoch time.

data: Array of objects.
Returns all historical bars for the requested period.
[{
t: int.
Returns the epoch timestamp of the bar.

o: float.
Returns the Open value of the bar.

c: float.
Returns the Close value of the bar.

h: float.
Returns the High value of the bar.

l: float.
Returns the Low value of the bar.

v: float.
Returns the Volume of the bar.
}],

points: int.
Returns the total number of data points in the bar.

mktDataDelay: int.
Returns the amount of delay, in milliseconds, to process the historical data request.

{
  "startTime": "20231211-04:00:00",
  "startTimeVal": 1702285200000,
  "endTime": "20231211-17:51:20",
  "endTimeVal": 1702335080000,
  "data": [
    {
      "t": 1702285200000,
      "o": 195.01,
      "c": 194.8,
      "h": 195.01,
      "l": 194.8,
      "v": 1723.0
    },
    {...}
  ],
  "points": 14,
  "mktDataDelay": 0
}

Valid Period Units:

Note: These units are case sensitive.

Valid Bar Units:

Note: These units are case sensitive.

Cancel market data for given conid.

POST /iserver/marketdata/unsubscribe

Request Object

Body Params

conid: String. Required
Enter the contract identifier to cancel the market data feed.
This can clear all standing market data feeds to invalidate your cache and start fresh.

Response Object

success: bool.
Returns a confirmation status of your unsubscribe request. A true response indicates that the market data feed has been successfully cancelled.

{
  "success": true
}

Eror Response Object

A status 500 response will be sent when attempting to unsubscribe from a market data feed that is not currently open.

error: String.
Returns an error response with message unknown indicating that the user does not have an existing data feed for the given conid.

{
  "error": "unknown"
}

Cancel all market data request(s). To cancel market data for a specific conid, see /iserver/marketdata/{conid}/unsubscribe.

GET /iserver/marketdata/unsubscribeall

Request Object

No params or arguments should be passed.

Response Object

confirmed: String.
Returns a confirmation status of your unsubscribe request.

{
  "unsubscribed": true
}

To begin, users must first make a call to the /iserver/secdef/search endpoint for the underlying symbol. This is required for all future steps every time the user does not know the final derivative’s conId.

This must always be called before proceeding, even if you are aware of the conId and expiration dates.

In the response, we are able to see two important values returned. The first, we can find our ConID for the underlying, 416904. We will need this for our future requests.

We can also see under “sections”::”secType”:”OPT, “months” we will see all of the contract expirations months. This will be required to build our option chain in the next request.

[
  {
    "conid": "416904",
    "companyHeader": "S&P 500 Stock Index - CBOE",
    "companyName": "S&P 500 Stock Index",
    "symbol": "SPX",
    "description": "CBOE",
    "restricted": "IND",
    "fop": null,
    "opt": "20240102;{..};20291220",
    "war": "20231130;{..};20271216",
    "sections": [
      {...},
      {
        "secType": "OPT",
        "months": "JAN24;FEB24;MAR24;APR24;MAY24;JUN24;JUL24;AUG24;SEP24;OCT24;NOV24;DEC24;JAN25;MAR25;JUN25;DEC25;DEC26;DEC27;DEC28;DEC29",
        "exchange": "SMART;CBOE;IBUSOPT"
      },
      {...}
    ]
  }
]

After querying the /iserver/secdef/search endpoint, developers should now call the /iserver/secdef/strikes endpoint. To receive the appropriate strikes, the conId, secType, and expiration month should be specified.

This must always be called before proceeding, even if you are aware of the strikes.

Note: For Futures Options, the conId of the Index should be specified, along with the explicit exchange being listed. As an example, CL futures options should specify “exchange=NYMEX” as an additional query parameter.

As a response, an object containing arrays of all Call and Put strikes will be returned. This will only return potential strike prices. This does not necessarily indicate. These strikes should be confirmed with our /info endpoint to confirm if the strike is valid.

{
  "call": [
    200.0,
  {...},
    7800.0
  ],
  "put": [
    200.0,
  {...},
    7800.0
  ]
}

After calling the /search and /strikes endpoints, users can use the /iserver/secdef/info endpoint to validate the derivative conId. This endpoint should be called for each strike and right combination of interest.

Note: For Futures Options, the conId of the Index should be specified, along with the explicit exchange being listed. As an example, CL futures options should specify “exchange=NYMEX” as an additional query parameter.

While all of the information is relevant, it is most important to save the conId in order to track the contract itself. For the lifespan of the Option, this conId will remain constant. This will also be used for all subsequent requests for market data or order placement.

[
  {
    "conid": 654371995,
    "symbol": "SPX",
    "secType": "OPT",
    "exchange": "SMART",
    "listingExchange": null,
    "right": "P",
    "strike": 3975.0,
    "currency": "USD",
    "cusip": null,
    "coupon": "No Coupon",
    "desc1": "SPX",
    "desc2": "JAN 16 '25 3975 Put (AM)",
    "maturityDate": "20250116",
    "multiplier": "100",
    "tradingClass": "SPX",
    "validExchanges": "SMART,CBOE,IBUSOPT"
  }
]

This endpoint requires a pre-flight request.
Orders is the list of live orders (cancelled, filled, submitted).

To retrieve order information for a specific account, clients must first query the /iserver/account endpoint to switch to the appropriate account.

GET /iserver/account/orders

Request Object

Query Params

filters: String.
Optionally filter your list of orders by a unique status value. More than one filter can be passed, separated by commas.
For available filters, see Order Status Values

force: bool.
Force the system to clear saved information and make a fresh request for orders. Submission will appear as a blank array.

Response Object

orders: Array of objects.
Contains all orders placed on the account for the day.
[{
acct: String.
Returns the accountID for the submitted order.

conidex: String.
Returns the contract identifier for the order.

conid: int.
Returns the contract identifier for the order.

orderId: int.
Returns the local order identifier of the order.

cashCcy: String.
Returns the currency used for the order.

sizeAndFills: String.
Returns the size of the order and how much of it has been filled.

orderDesc: String.
Returns the description of the order including the side, size, order type, price, and tif.

description1: String.
Returns the local symbol of the order.

ticker: String.
Returns the ticker symbol for the order.

secType: String.
Returns the security type for the order.

listingExchange: String.
Returns the primary listing exchange of the orer.

remainingQuantity: float.
Returns the remaining size for the order to fill.

filledQuantity: float.
Returns the size of the order already filled.

companyName: String.
Returns the company long name.

status: String.
Returns the current status of the order.

order_ccp_status: String.
Returns the current status of the order.

origOrderType: String.
Returns the original order type of the order, whether or not the type has been changed.

supportsTaxOpt: String.
Returns if the order is supported by the Tax Optimizer.

lastExecutionTime: String.
Returns the datetime of the order’s most recent execution.
Time returned is based on UTC timezone.
Value Format: YYMMDDHHmmss

orderType: String.
Returns the current order type, or the order at the time of execution.

bgColor: String.
Internal use only.

fgColor: String.
Internal use only.

order_ref: String.
User defined string used to identify the order. Value is set using “cOID” field while placing an order.

timeInForce: String.
Returns the time in force (tif) of the order.

lastExecutionTime_r: int.
Returns the epoch time of the most recent execution on the order.

side: String.
Returns the side of the order.

avgPrice: String.
Returns the average price of execution for the order.
}]

snapshot: bool.
Returns if the data is a snapshot of the account’s orders.

{
  "orders": [
    {
      "acct": "U1234567",
      "conidex": "265598",
      "conid": 265598,
      "account": "U1234567",
      "orderId": 1234568790,
      "cashCcy": "USD",
      "sizeAndFills": "5",
      "orderDesc": "Sold 5 Market, GTC",
      "description1": "AAPL",
      "ticker": "AAPL",
      "secType": "STK",
      "listingExchange": "NASDAQ.NMS",
      "remainingQuantity": 0.0,
      "filledQuantity": 5.0,
      "totalSize": 5.0,
      "companyName": "APPLE INC",
      "status": "Filled",
      "order_ccp_status": "Filled",
      "avgPrice": "192.26",
      "origOrderType": "MARKET",
      "supportsTaxOpt": "1",
      "lastExecutionTime": "231211180049",
      "orderType": "Market",
      "bgColor": "#FFFFFF",
      "fgColor": "#000000",
      "order_ref": "Order123",
      "timeInForce": "GTC",
      "lastExecutionTime_r": 1702317649000,
      "side": "SELL"
    }
  ],
  "snapshot": true
}

Retrieve the given status of an individual order using the orderId returned by the order placement response or the orderId available in the live order response.

GET /iserver/account/order/status/{{ orderId }}

Request Object

Query Params

orderId: String. Required
Order identifier for the placed order. Returned by the order placement response or the orderId available in the live order response.

Response Object

sub_type: null.
Internal use only.

request_id: String.
Returns the requestId of the order palced by the user.

order_id: int.
Returns the orderId of the requested order.

conidex: String.
Returns the contract identifier for the order.

conid: int.
Returns the contract identifier for the order.

symbol: String.
Returns the ticker symbol for the order.

side: String.
Returns the side of the order.

contract_description_1: String.
Returns the local symbol of the order.

listing_exchange: String.
Returns the primary listing exchange of the orer.

option_acct: String.
For Client Portal use (Internal use only).

company_name: String.
Returns the company long name.

size: String.
Returns the quantity of the order.

total_size: String.
Returns the maximum quantity of the order.

currency: String.
Returns the base currency of the order.

account: String.
Returns the account the order was placed for.

order_type: String.
Returns the order type for the given order.

cum_fill: String.
Returns the cumulative fill of the order.

order_status: String.
Returns the current status of the order.

order_ccp_status: String.
Returns the current status of the order as a code.

order_status_description: String.
Returns the human readable response of the order status.

tif: String.
Returns the time in force of the order.

fg_color: String.
For Client Portal use (Internal use only).

bg_color: String.
For Client Portal use (Internal use only).

order_not_editable: bool.
Returns whether or not the order can be modified.
This is relevant for orders that are currently or have already been executed.

editable_fields: null.
For Client Portal use (Internal use only).

cannot_cancel_order: bool.
Returns whether or not the order can be cancelled.
This is relevant for orders that are currently or have already been executed.

deactivate_order: bool.
Return whether or not the order has been marked inactive.

sec_type: String.
Returns the security type of the order’s contract.

available_chart_periods: String.
For Client Portal use (Internal use only).

order_description: String.
Returns the description of the order including the side, size, order type, price, and tif.

order_description_with_contract: String.
Returns the description of the order including the side, size, symbol, order type, price, and tif.

alert_active: int.
Returns wheteher or not there is an active alert available on the order.

child_order_type: String.
type of the child order
Value Format: A=attached, B=beta-hedge, 0=No Child

order_clearing_account: String.
Returns the accountID for the submitted order.

size_and_fills: String.
Returns the size of the order and how much of it has been filled.

exit_strategy_display_price: String.
Displays the price of the order as it resolved its execution.

exit_strategy_chart_description: String.
Returns the description of the order including the side, size, order type, price, and tif.

average_price: String.
Returns the average price of execution for the order.

exit_strategy_tool_availability: String.
Internal use only.

allowed_duplicate_opposite: bool.
Returns whether or not the opposing order can be placed on the market.

order_time: String.
Returns the datetime of the order placement.
Time returned is based on UTC timezone.
Value Format: YYMMDDHHmmss

{
  "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"
}

Returns a list of trades for the currently selected account for current day and six previous days. It is advised to call this endpoint once per session.

GET /iserver/account/trades

Request Object

Query Params

days: String.
Specify the number of days to receive executions for, up to a maximum of 7 days.
If unspecified, only the current day is returned.

Response Object.

execution_id: String.
Returns the execution ID for the trade.

symbol: String.
Returns the underlying symbol.

supports_tax_opt: String.
Returns whether or not tax optimizer is supported for the order.

side: String.
Returns the side of the order, Buy or Sell.

order_description: String.
Returns the description of the order including the side, size, symbol, order type, price, and tif.

order_ref: String.
User defined string used to identify the order. Value is set using “cOID” field while placing an order.

trade_time: String.
Returns the UTC format of the trade time.

trade_time_r: int.
Returns the epoch time of the trade.

size: float.
Returns the quantity of the order.

price: String.
Returns the price of trade execution.

submitter: String.
Returns the username that submitted the order.

exchange: String.
Returns the exchange the order was executed on.

commission: String.
Returns the cost of commission for the trade.

net_amount: float.
Returns the total net cost of the order.

account: String.
Returns the account identifier.

accountCode: String.
Returns the account identifier.

company_name: String.
Returns the long name of the contract’s company.

contract_description_1: String.
Returns the local symbol of the order.

sec_type: String.
Returns the security type of the contract.

listing_exchange: String.
Returns the primary listing exchange of the contract.

conid: int.
Returns the contract identifier of the order.

conidEx: String.
Returns the contract identifier of the order.

clearing_id: String.
Returns the clearing firm identifier.

clearing_name: String.
Returns the clearing firm identifier.

liquidation_trade: String.
Returns whether the order was part of an account liquidation or note.

is_event_trading: String.
Returns whether the order was part of event trading or not.

[
  {
    "execution_id": "0000e0d5.6576fd38.01.01",
    "symbol": "AAPL",
    "supports_tax_opt": "1",
    "side": "S",
    "order_description": "Sold 5 @ 192.26 on ISLAND",
    "trade_time": "20231211-18:00:49",
    "trade_time_r": 1702317649000,
    "size": 5.0,
    "price": "192.26",
    "order_ref": "Order123",
    "submitter": "user1234",
    "exchange": "ISLAND",
    "commission": "1.01",
    "net_amount": 961.3,
    "account": "U1234567",
    "accountCode": "U1234567",
    "account_allocation_name": "U1234567",
    "company_name": "APPLE INC",
    "contract_description_1": "AAPL",
    "sec_type": "STK",
    "listing_exchange": "NASDAQ.NMS",
    "conid": 265598,
    "conidEx": "265598",
    "clearing_id": "IB",
    "clearing_name": "IB",
    "liquidation_trade": "0",
    "is_event_trading": "0"
  }
]

When connected to an IServer Brokerage Session, this endpoint will allow you to submit orders.

CP WEB API supports various advanced orderTypes, for additional details and examples refer to the Order Types page.

Cash Quantity: Send orders using monetary value by specifying cashQty instead of quantity, e.g. cashQty: 200. The endpoint /iserver/contract/rules returns list of valid orderTypes in cqtTypes. Please note this will round the order down to the nearest whole share, which may be 0 depending on the value provided compared to the current share price.

Currency Conversion: Convert cash from one currency to another by including isCcyConv = true. To specify the cash quantity use fxQTY instead of quantity, e.g. fxQTY: 100.

IB Algos: Attached user-defined settings to your trades by using any of IBKR’s Algo Orders. Use the endpoint /iserver/contract/{conid}/algos to identify the available strategies for a contract.

Notes:

• With the exception of OCA groups and bracket orders, the orders endpoint does not currently support the placement of unrelated orders in bulk.
• Developers should not attempt to place another order until the previous order has been fully acknowledged, that is, when no further warnings are received deferring the client to the reply endpoint.

POST /iserver/account/{accountID}/orders

Request Object

Path Params

accountId: String.
The account ID for which account should place the order.
Financial Advisors should instead specify their allocation group.

Body Params

orders: Array of Objects. Required
Used to the order content.
[{
acctId: String.
It should be one of the accounts returned by /iserver/accounts.
If not passed, the first one in the list is selected.

conid: int. Required*
conid is the identifier of the security you want to trade
You can find the conid with /iserver/secdef/search.
*Can use conidex instead of conid.

conidex: String. Optional*
A mix of the contract identifier and exchange
*Can be used instead of conid when specifying the contract identifier of a security.
Value format: “conid@exchange”

secType: String.
The contract-identifier (conid) and security type (type) specified as a concatenated value
Value Format: “conid:type”

cOID: String.
Customer Order ID.
An arbitrary string that can be used to identify the order
The value must be unique for a 24h span.
Do not set this value for child orders when placing a bracket order.

parentId: String.
Only specify for child orders when placing bracket orders.
The parentId for the child order(s) must be equal to the cOId (customer order id) of the parent.

orderType: String. Required
The order-type determines what type of order you want to send.
Available Order Types: LMT, MKT, STP, STOP_LIMIT, MIDPRICE, TRAIL, TRAILLMT

listingExchange: String.
Primary routing exchange for the order.
By default we use “SMART” routing.
Possible values are available via the endpoint: /iserver/contract/{conid}/info

isSingleGroup: bool.
Set to true if you want to place a single group orders(OCA)

outsideRTH: bool.
Set to true if the order can be executed outside regular trading hours.

price: float. Required for LMT or STOP_LIMIT
This is typically the limit price.
For STP|TRAIL this is the stop price.
For MIDPRICE this is the option price cap.

auxPrice: float. Required for STOP_LIMIT and TRAILLMT orders.
Stop price for STOP_LIMIT and TRAILLMT orders.
You must specify both price and auxPrice for STOP_LIMIT|TRAILLMT orders.

side: String. Required
Valid Values: SELL or BUY

ticker: String.
This is the underlying symbol for the contract.

tif: String. Required
The Time-In-Force determines how long the order remains active on the market.
Valid Values: GTC, OPG, DAY, IOC, PAX (CRYPTO ONLY).

trailingAmt: float. Required for TRAIL and TRAILLMT order
optional if order is TRAIL, or TRAILLMT.
When trailingType is amt, this is the trailing amount
When trailingType is %, it means percentage.

trailingType: String. Required for TRAIL and TRAILLMT order
This is the trailing type for trailing amount.
You must specify both trailingType and trailingAmt for TRAIL and TRAILLMT order
Valid Values: “amt” or “%”

referrer: String.
Custom order reference

quantity: float. Required*
Used to designate the total number of shares traded for the order.

cashQty: float.
Used to specify the monetary value of an order instead of the number of shares.
When using ‘cashQty’ don’t specify ‘quantity’
Cash quantity orders are provided on a non-guaranteed basis.
In addition to the monetary value, the order uses a maximum size that is calculated using the Cash Quantity Estimated Factor, which can be modified in TWS Order Presets.
Please note this will round the order down to the nearest whole share, which may be 0 depending on the value provided compared to the current share price.

fxQty: float.
This is the cash quantity field which can only be used for Currency Conversion Orders.
When using ‘fxQty’ don’t specify ‘quantity’.

useAdaptive: boolean
If true, the system will use the Price Management Algo to submit the order.
Read more on our Price Management Algo page. https://www.interactivebrokers.com/en/index.php?f=43423

isCcyConv: boolean
set to true if the order is a FX conversion order

allocationMethod: String.
Set the allocation method when placing an order using an FA account for a group.
Based on value set in Trader Workstation.

manualOrderTime: int.
Only used for Brokers and Advisors. Mark the time to manually record initial order entry.
Must be sent as epoch time integer.

deactivated: bool.
Functions the same as Saving an Order in Trader Workstation.

strategy: String.
Specify which IB Algo algorithm to use for this order.

strategyParameters: Array.
The IB Algo parameters for the specified algorithm.
}]

Response Object

orderId: String.
Returns the orders identifier which can be used for order tracking, modification, and cancellation.

order_status: String.
Returns the order status of the current market order.
See Order Status Value for more information.

encrypt_message: String.
Returns a “1” to display that the message sent was encrypted.

[
  {
    "order_id": "1234567890",
    "order_status": "Submitted",
    "encrypt_message": "1"
  }
]

Alternate Response Object

In some instances, you will receive an ID along with a message about your order.

See the Place Order Reply section for more details on resolving the confirmation.

Important: The reply must be confirmed before sending any further orders. Otherwise, the order will be invalidated and attempts to confirm invalid replies will result in a timeout (503).

id: String.
Returns a message ID relating to the particular order’s warning confirmation.

message: Array of Strings.
Returns the message warning about why the order wasn’t initially transmitted.

isSuppressed: bool.
Returns if a particular warning was suppressed before sending.
Always returns false.

messageIds: Array of Strings.
Returns an internal message identifier (Internal use only).

[
  {
    "id": "07a13a5a-4a48-44a5-bb25-5ab37b79186c",
    "message": [
      "The following order \"BUY 5 AAPL NASDAQ.NMS @ 150.0\" price exceeds \nthe Percentage constraint of 3%.\nAre you sure you want to submit this order?"
    ],
    "isSuppressed": false,
    "messageIds": [
      "o163"
    ]
  }
]

Order Reject Object

In the event an order is placed that can not be completed based on account details such as trading permissions or funds, customers will receive a 200 OK response along with an error message explaining the issue.

This is unique from the 200 response used in the Alternate Response Object, or a potential 500 error resulting from invalid request content.

{
  "error":"We cannot accept an order at the limit price you selected. Please submit your order using a limit price that is closer to the current market price of 197.79.  Alternatively, you can convert your order to an Algorithmic Order (IBALGO)."
}

Confirm order precautions and warnings presented from placing orders.

POST /iserver/reply/{{ replyId }}

Request Object

Path Params

replyId: String. Required
Include the id value from the prior order request relating to the particular order’s warning confirmation.

Body Params

confirmed: bool. Required
Pass your confirmation to the reply to allow or cancel the order to go through.
true will agree to the message transmit the order.
false will decline the message and discard the order.

Response Object

orderId: String.
Returns the orders identifier which can be used for order tracking, modification, and cancellation.

order_status: String.
Returns the order status of the current market order.
See Order Status Value for more information.

encrypt_message: String.
Returns a “1” to display that the message sent was encrypted.

[
  {
    "order_id": "1234567890",
    "order_status": "Submitted",
    "encrypt_message": "1"
  }
]

Respond to a server prompt received via ntf webscoket message.

POST /iserver/notification

Request Object

Body Params

orderId int. Required
IB-assigned order identifier obtained from the ntf websocket message that delivered the server prompt.

reqId string. Required
IB-assigned request identifier obtained from the ntf websocket message that delivered the server prompt.

text string. Required
The selected value from the “options” array delivered in the server prompt ntf websocket message.
 

Response Object

{Status text}: string
Returns the status of the confirmation message.

Success

This endpoint allows you to preview order without actually submitting the order and you can get commission information in the response. Also supports bracket orders.

Note: Please be aware that /whatif orders are also effected by our message suppression endpoint.

Clients must query /iserver/marketdata/snapshot for the instrument prior to requesting the /whatif endpoint.

POST /iserver/account/{accountId}/orders/whatif

Request Object

The body content of the /whatif endpoint will follow the same structure as the standard /iserver/account/{accountId}/orders endpoint.

See the Place Order section for more details.

Response Object

amount: Object.
Contains the details about the order cost.
{
amount: String.
Returns the cost of the base order.

commission: String.
Returns the commission cost of the base order.

total: String.
Returns the total cost of the order.
},

equity: Object.
Contains the details about the order’s impact on your equity.
{
current: String.
Returns the current equity of the account.

change: String.
Returns the equity impact from the order.

after: String.
Returns the equity after the order is traded.
},

initial: Object.
Contains the details about the order’s impact on your initial margin.
{
current: String.
Returns the current initial margin value.

change: String.
Returns the amount the initial margin will change by.

after: String.
Returns the initial margin value after the order.
},

maintenance: Object.
Contains the details about the order’s impact on your maintenance margin.
{
current: String.
Returns the current maintenance margin value.

change: String.
Returns the amount the maintenance margin will change by.

after: String.
Returns the maintenance margin value after the transaction.
},

position: Object.
Contains the details about the order’s impact on your current position.
{
current: String.
Returns the cost of the base order.

change: String.
Returns the cost of the base order.

after: String.
Returns the cost of the base order.
},

warn: String.
Returns any potential warning message from placing this order.
Returns null if no warning is possible.

error: String.
Returns any potential error message from placing this order.
Returns null if no error is possible.

{
  "amount": {
    "amount": "1,977.60 USD (10 Shares)",
    "commission": "1 USD",
    "total": "1,978.60 USD"
  },
  "equity": {
    "current": "215,415,594",
    "change": "-1",
    "after": "215,415,593"
  },
  "initial": {
    "current": "116,965",
    "change": "652",
    "after": "117,617"
  },
  "maintenance": {
    "current": "106,332",
    "change": "592",
    "after": "106,924"
  },
  "position": {
    "current": "0",
    "change": "10",
    "after": "10"
  },
  "warn": "21/You are trying to submit an order without having market data for this instrument. \nIB strongly recommends against this kind of blind trading which may result in \nerroneous or unexpected trades.",
  "error": null
}

The body content on the right represents a standard bracket order which contains a parent order, a profit taker, and a stop loss. As you can see, the only addition to this order is the inclusion of cOID in the parent order, and the parentId field in the two children.

{
  "orders": [
    {
      "acctId": "U1234567",
      "conid": 265598,
      "cOID": "Parent",
      "orderType": "MKT",
      "listingExchange": "SMART",
      "outsideRTH": true,
      "side": "Buy",
      "referrer": "QuickTrade",
      "tif": "GTC",
      "quantity": 50
    },
    {
      "acctId": "U1234567",
      "conid": 265598,
      "orderType": "STP",
      "listingExchange": "SMART",
      "outsideRTH": false,
      "price": 157.30,
      "side": "Sell",
      "tif": "GTC",
      "quantity": 50,
      "parentId": "Parent"
    },
    {
      "acctId": "U1234567",
      "conid": 265598,
      "orderType": "LMT",
      "listingExchange": "SMART",
      "outsideRTH": false,
      "price": 157.00,
      "side": "Sell",
      "tif": "GTC",
      "quantity": 50,
      "parentId": "Parent"
    }
  ]
}

An OCA group will follow this same structure. However, in addition to the standard bracket, each order will include "isSingleGroup": true. Otherwise, no additional modifications need to be made.

{
  "orders": [
    {
      "acctId": "U1234567",
      "conid": 265598,
      "cOID": "Parent",
      "orderType": "MKT",
      "listingExchange": "SMART",
      "isSingleGroup": true,
      "outsideRTH": true,
      "side": "Buy",
      "referrer": "QuickTrade",
      "tif": "GTC",
      "quantity": 50
    },
    {
      "acctId": "U1234567",
      "conid": 265598,
      "orderType": "STP",
      "listingExchange": "SMART",
      "isSingleGroup": true,
      "outsideRTH": false,
      "price": 157.30,
      "side": "Sell",
      "tif": "GTC",
      "quantity": 50,
      "parentId": "Parent"
    },
    {
      "acctId": "U1234567",
      "conid": 265598,
      "orderType": "LMT",
      "listingExchange": "SMART",
      "outsideRTH": false,
      "isSingleGroup": true,
      "price": 157.00,
      "side": "Sell",
      "tif": "GTC",
      "quantity": 50,
      "parentId": "Parent"
    }
  ]
}

Cancels an open order.

Must call /iserver/accounts endpoint prior to cancelling an order.

Use /iservers/account/orders endpoint to review open-order(s) and get latest order status.

DELETE /iserver/account/{{ accountId }}/order/{{ orderId }}

Request Object

Path Param

accountId: String.
The account ID for which account should place the order.

orderId: String.
The orderID for that should be modified.
Can be retrieved from /iserver/account/orders
Submitting ‘-1’ will cancel all open orders

Response Object

msg: String.
Returns the confirmation of the request being submitted.

order_id: int.
Returns the orderID of the cancelled order.

conid: int.
Returns the conid for the requested order to be cancelled.
Returns -1 for orders that were immediately cancelled on request.

account: String.
Returns the accountId for the requested order to be cancelled.
Returns null for orders that were immediately cancelled on request.

{
    "msg": "Request was submitted",
    "order_id": 123456789,
    "conid": 265598,
    "account": "U1234567"
}

Error Object

error: String.
Returns the error message.

{
    "error": "OrderID 1 doesn't exist"
}

Modifies an open order.

Must call /iserver/accounts endpoint prior to modifying an order.

Use /iservers/account/orders endpoint to review open-order(s).

POST /iserver/account/{accountId}/order/{orderId}

Request Object

Path Param

accountId: String.
The account ID for which account should place the order.

orderId: String.
The orderID for that should be modified.
Can be retrieved from /iserver/account/orders

Body Params

The body content of the modify order endpoint will follow the same structure as the standard /iserver/account/{accountId}/orders endpoint.

The content should mirror the content of the original order.

See the Place Order section for more details.

Response Object

orderId: String.
Returns the orders identifier which can be used for order tracking, modification, and cancellation.

order_status: String.
Returns the order status of the current market order.
See Order Status Value for more information.

encrypt_message: String.
Returns a “1” to display that the message sent was encrypted.

[
    {
        "order_id": "1234567890",
        "order_status": "Submitted",
        "encrypt_message": "1"
    }
]

Alternate Response Object

In some instances, you will receive an ID along with a message about your order.

See the Place Order Reply section for more details on resolving the confirmation.

id: String.
Returns a message ID relating to the particular order’s warning confirmation.

message: Array of Strings.
Returns the message warning about why the order wasn’t initially transmitted.

isSuppressed: bool.
Returns if a particular warning was suppressed before sending.
Always returns false.

messageIds: Array of Strings.
Returns an internal message identifier (Internal use only).

[
  {
    "id": "a12b34c5-d678-9e012f-3456-7a890b12cd3e",
    "message": [
      "You are about to submit a stop order. Please be aware of the various stop order types available and the risks associated with each one.\nAre you sure you want to submit this order?"
    ],
    "isSuppressed": false,
    "messageIds": [
      "o0"
    ]
  }
]

Disables a messageId, or series of messageIds, that will no longer prompt the user.

POST /iserver/questions/suppress

Request Object

Body Param

messageIds: Array of Strings.
The identifier for each warning message to suppress.
The array supports up to 51 messages sent in a single request. Any additional values will result in a system error.
The only supported message IDs are listed in our Suppressible Message IDs list. However, users should look to suppress messages on an as-needed basis to avoid unexpected order submissions.

Response Object

status: String.
Verifies that the request has been sent.

{
  "status": "submitted"
}

Resets all messages disabled by the Suppress Messages endpoint.