Third-Party Web API v1

/oauth

OAuth example client (java)

OAuth Documentation

POST /oauth/request_token

Obtain a request token. See section 6.1 of the OAuth v1.0a specification for more information.

Note: We do not return an oauth_token_secret in the response as we are using RSA signatures rather than PLAINTEXT authentication.

Parameters

Parameter Value Description
oauth_consumer_key The 25-character hexadecimal string that was obtained from Interactive Brokers during the OAuth consumer registration process.
oauth_signature_method The signature method used to sign the request. Currently only 'RSA-SHA256' is supported.
oauth_signature The signature for the request generated using the method specified in the oauth_signature_method parameter. See section 9 of the OAuth v1.0a specification for more details on signing requests.
oauth_timestamp Timestamp expressed in seconds since 1/1/1970 00:00:00 GMT. Must be a positive integer and greater than or equal to any timestamp used in previous requests.
oauth_nonce A random string uniquely generated for each request.
oauth_callback An absolute URL to which IB will redirect the user. This URL is provided by the consumer during registration. This parameter must be set to 'oob'.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "object",
"properties": {
   "oauth_token": { "type" : "string" }
  }
}
Unsuccessful Response
Return codes 400, 401, 403, 408
POST /oauth/access_token

Obtain an access token using the request token and the verification code you received after the user provided authorization. See section 6.3 of the OAuth v1.0a specification for more details.

Parameters

Parameter Value Description
oauth_consumer_key The 25-character hexadecimal string that was obtained from Interactive Brokers during the OAuth consumer registration process.
oauth_token The request token obtained from IB via /request_token.
oauth_signature_method The signature method used to sign the request. Currently only 'RSA-SHA256' is supported.
oauth_signature The signature for the request generated using the method specified in the oauth_signature_method parameter. See section 9 of the OAuth v1.0a specification for more details on signing requests.
oauth_timestamp Timestamp expressed in seconds since 1/1/1970 00:00:00 GMT. Must be a positive integer and greater than or equal to any timestamp used in previous requests.
oauth_nonce A random string uniquely generated for each request.
oauth_verifier The verification code received from IB after the user has granted authorization.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "object",
"properties": {
   "oauth_token": { "type" : "string" },
   "oauth_token_secret": { "type" : "string" }
  }
}
Unsuccessful Response
Return codes 400, 401, 403, 408
POST /oauth/live_session_token

In order to access protected IB resources, a live session token is required. This endpoint allows consumers to obtain a live session token to access these resources using an OAuth access token and the Diffie-Hellman prime and generator supplied during the registration process.

Note: This is an additional IB-specific step, and not part of the OAuth v1.0a specification. Please refer to the "OAuth at Interactive Brokers" document for more details.

Parameters

Parameter Value Description
oauth_consumer_key The 25-character hexadecimal string that was obtained from Interactive Brokers during the OAuth consumer registration process.
oauth_token The access token obtained from IB in response to the /access_token request.
oauth_signature_method The signature method used to sign the request. Currently only 'RSA-SHA256' is supported.
oauth_signature The signature for the request generated using the method specified in the oauth_signature_method parameter. See section 9 of the OAuth v1.0a specification for more details on signing requests.
oauth_timestamp Timestamp expressed in seconds since 1/1/1970 00:00:00 GMT. Must be a positive integer and greater than or equal to any timestamp used in previous requests.
oauth_nonce A random string uniquely generated for each request.
diffie_hellman_challenge Challenge value calculated using the Diffie-Hellman prime and generated provided during the registration process. See the "OAuth at Interactive Brokers" document for more details.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "object",
"properties": {
   "diffie_hellman_response": { "type" : "string" },
   "live_session_token_signature": { "type" : "string" }
  }
}
Unsuccessful Response
Return codes 400, 401, 403, 408

/accounts

Important Info

Accounts that are authorized before 16:55 EST will be accessible via the API the following day (after the 'nightly refresh').
After the initial authorization by a given user and before the nightly refresh has occurred, all /accounts/ endpoints for that user will return HTTP status code 204 (204 is 'no content') .
Upon subsequent account authorizations, only previously authorized accounts will appear in /accounts before the nightly refresh.

Resources with the HTTP method tagged with '*' may return HTTP 423 (Resource Locked) when queried repeatedly.

GET /accounts

Allows the caller to request a list of accounts associated with the session.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "object",
"properties" : {
   "accounts" : { "type" : "array" },
   "items" : { "type" : "string" }
  }
}
Unsuccessful Response
Return codes 202, 204, 401, 403, 408
GET /accounts/{account}/positions

Returns a list of positions held by the account passed in the URL.

Responses

Successful Response
Return code 200 OK
Schema 

{
"type": "array",
"items": {
   "type": "object",
   "properties": {
      "Position": { "type": "number" },
      "AverageCost": { "type": "number" },
      "ContractId": { "type": "number" }
   }
}
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408
GET /accounts/{account}/summary

Returns a list of account and margin balances associated with the account passed in the URL.

Responses

Successful Response
Return code 200 OK
Example see summary.json
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408
GET /accounts/{account}/orders

Returns a list of orders for the account passed in the URL.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "array",
"items": {
   "type": "object",
   "properties": {
      "CustomerOrderId": { "type": "number" },
      "ContractId": { "type": "number" },
      "Ticker": { "type": "string" },
      "ListingExchange": { "type": "string" },
      "RemainingQuantity": { "type": "number" },
      "FilledQuantity": { "type": "number" },
      "OrderType": { "type": "FIXOrderType"},
      "TimeInForce": { "type" : "FIXTIF" },
      "OutsideRTH": { "type" : "string" },
      "Side": { "type": "string", "type": "FIXSide"},
      "Price": { "type": "number"},
      "Status": {"type": "Order Status"},
      "Warning": {"type": "string"},
      "TransactionTime": { "type": "string"}
   }
}
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408
POST * /accounts/{account}/orders

To specify the contract, you provide a value for the ContractId field, OR Ticker/ListingExchange/InstrumentType=STK for stocks OR Ticker/Currency/InstrumentType=CASH for FX.

Required Fields For Security Resolution

Asset Class Instrument Type Required Fields Example
Stocks STK
  • ContractId
or
  • InstrumentType
  • Ticker
  • ListingExchange
  • 8314
or
  • STK
  • IBM
  • NYSE
FX CASH
  • ContractId
or
  • InstrumentType
  • Ticker
  • Currency
  • 12087792
or
  • CASH
  • EUR
  • USD

Transmits an order tagged with the specified CustomerOrderId for the account passed in the URL.

Parameters

Parameter Value Description
CustomerOrderId The order ID assigned by the customer.
Ticker The symbol that identifies the trading product.
ListingExchange The exchange on which the trading product is listed (only for InstrumentType=STK).
Currency The currency in which the FX pair trades (only for InstrumentType=CASH).
InstrumentType The instrument type of the contract.
ContractId The internal IB identifier for the trading product specified as an integer (can be obtained in response to /secdef request).
Quantity The number of units in the order; contracts or shares.
Price The order price.
Order Type The order type (limit, market, stop, etc). values as defined in FIX Order Type Model
Aux Price Required Price to support Stop and Stop Limit orders
Time In Force Defines the time over which the order will remain active. values as defined in FIX TIF (Time In Force) Model
Outside RTH Allow the order to be executed outside regular trading hours
Side Specifies whether the order is a buy or sell. values as defined in FIX Side Model
OrderRestrictions MultiValueString representing the restrictions associated with an order. If more than one restriction is applicable to an order, this field can contain multiple instructions separated by space. See OrderRestricions
GermanHftAlgo

By setting this bool to false the customer attests that the order is not subject to German HFT Act, was not generated using any automated algorithm, and no algorithm determined or changed financial instrument, side, quantity, order type, limit or other price, trading venue or timing of this order.

Currently we cannot accept orders where this flag is set to true. Such orders will be rejected.

See BaFin's description for more information.
Mifid2DecisionMaker This field permits specification of the user's preregistered (via account management) MiFID II short code for decision makers.
Mifid2Algo This field permits specification of the user's preregistered (via account management) MiFID II short code for algos that are responsible for investment decisions.
Mifid2ExecutionTrader This field permits specification of the user's preregistered (via account management) MiFID II person responsible for handling/routing of the order.
Mifid2ExecutionAlgo This field permits specification of the user's preregistered (via account management) MiFID II short code for algos that are responsible for handling/routing of the order.
UsePricemanagementAlgo

Setting this bool to true activates an algo which caps (limits) price of your order if the limit price of your order is no more than allowed distance from the current reference price.

Find out more

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "array",
"items": {
   "type": "object",
   "properties": {
      "CustomerOrderId": { "type": "number" },
      "ContractId": { "type": "number" },
      "Ticker": { "type": "string" },
      "ListingExchange": { "type": "string" },
      "RemainingQuantity": { "type": "number" },
      "FilledQuantity": { "type": "number" },
      "OrderType": { "type": "FIXOrderType"},
      "TimeInForce": { "type" : "FIXTIF" },
      "OutsideRTH": { "type" : "string" },
      "Side": { "type": "string", "type": "FIXSide"},
      "Price": { "type": "number"},
      "Status": {"type": "Order Status"},
      "Warning": {"type": "string"},
      "TransactionTime": { "type": "string"}
   }
}
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408, 423
GET /accounts/{account}/orders/CUST_ORDER_ID

Returns the order with the referenced Customer Order ID for the account passed in the URL.

Parameters

Parameter Value Description
CustomerOrderId The order ID assigned by the customer.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "array",
"items": {
   "type": "object",
   "properties": {
      "CustomerOrderId": { "type": "number" },
      "ContractId": { "type": "number" },
      "Ticker": { "type": "string" },
      "ListingExchange": { "type": "string" },
      "RemainingQuantity": { "type": "number" },
      "FilledQuantity": { "type": "number" },
      "OrderType": { "type": "FIXOrderType" },
      "TimeInForce": { "type" : "FIXTIF" },
      "OutsideRTH": { "type" : "string" },
      "Side": { "type": "string", "type": "FIXSide"},
      "Price": { "type": "number"},
      "Status": {"type": "Order Status"},
      "Warning": {"type": "string"},
      "TransactionTime": { "type": "string"}
   }
}
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408
DELETE * /accounts/{account}/orders/CUST_ORDER_ID

Cancels the order with the referenced Customer Order ID for the account passed in the URL.

Parameters

Parameter Value Description
CustomerOrderId The order ID assigned by the customer.

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "array",
"items": {
   "type": "object",
   "properties": {
    "CustomerOrderId": {"type" : "string" },
      "Symbol":  {"type" : "string" },
      "OrderQty":  {"type" : "number" },
      "Price":  {"type" : "number" },
      "Side": { "type": "string", "type": "FIXSide"},
      "Status": {"type": "Order Status"},
      "Warning": {"type": "string"},
      "OrderType": { "type": "FIXOrderType" }
    }
  }
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408, 423
PUT * /accounts/{account}/orders/CUST_ORDER_ID

Allows the caller to modify the order with the referenced Customer Order ID specified in the URL. A separate Customer Order ID must be provided in the request body for the modification.

Parameters

Parameter Value Description
OrigCustomerOrderId The order ID assigned by the customer.
CustomerOrderId The new order ID assigned by the customer for the modification.
Quantity The number of units in the order; contracts or shares.
Price The order price.
Order Type The order type (limit, market, stop, etc). IB only supports changing a Limit order to a Market order. values as defined in FIX Order Type Model
Aux Price Required Price to support Stop and Stop Limit orders. This can only be modified if the original order was a STP or STP LMT order.
Time In Force Defines the time over which the order will remain active. values as defined in FIX TIF (Time In Force) Model IB supports changing Day order to GTC and
Outside RTH Allow the order to be executed outside regular trading hours
Side Specifies whether the order is a buy or sell. Must match the original order. values as defined in FIX Side Model
GermanHftAlgo

By setting this bool to false the customer attests that the order is not subject to German HFT Act, was not generated using any automated algorithm, and no algorithm determined or changed financial instrument, side, quantity, order type, limit or other price, trading venue or timing of this order.

Currently we cannot accept orders where this flag is set to true. Such orders will be rejected.

See BaFin's description for more information.
Mifid2DecisionMaker This field permits specification of the user's preregistered (via account management) MiFID II short code for decision makers.
Mifid2Algo This field permits specification of the user's preregistered (via account management) MiFID II short code for algos that are responsible for investment decisions.
Mifid2ExecutionTrader This field permits specification of the user's preregistered (via account management) MiFID II person responsible for handling/routing of the order.
Mifid2ExecutionAlgo This field permits specification of the user's preregistered (via account management) MiFID II short code for algos that are responsible for handling/routing of the order.
UsePricemanagementAlgo

Setting this bool to true activates an algo which caps (limits) price of your order if the limit price of your order is no more than allowed distance from the current reference price.

Find out more

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "array",
"items": {
   "type": "object",
   "properties": {
      "OrigCustomerOrderId": {"type" : "string" },
      "CustomerOrderId": {"type" : "string" },
      "OrderQty":  {"type" : "number" },
      "Price":  {"type" : "number" },
      "Side": { "type": "string", "type": "FIXSide"},
      "Status": {"type": "Order Status"},
      "Warning": {"type": "string"},
      "OrderType": { "type": "FIXOrderType" }
    }
  }
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408, 423
POST /accounts/{account}/order_impact

This endpoint allows the consumer to check the impact that an order would have on the account, including margin, NLV and estimated commission costs.

To specify the contract, you provide a value for the ContractId field, OR Ticker/ListingExchange/InstrumentType=STK for stocks OR Ticker/Currency/InstrumentType=CASH for FX.

Parameters

Parameter Value Description
CustomerOrderId The order ID assigned by the customer.
Ticker The symbol that identifies the trading product.
ListingExchange The exchange on which the trading product is listed (only for InstrumentType=STK).
Currency The currency in which the FX pair trades (only for InstrumentType=CASH).
InstrumentType The instrument type of the contract.
ContractId The internal IB identifier for the trading product specified as an integer (can be obtained in response to /secdef request).
Quantity The number of units in the order; contracts or shares.
Price The order price.
Order Type The order type (limit, market, stop, etc). values as defined in FIX Order Type Model
Aux Price Required Price to support Stop and Stop Limit orders
Time In Force Defines the time over which the order will remain active. values as defined in FIX TIF (Time In Force) Model
Side Specifies whether the order is a buy or sell. values as defined in FIX Side Model

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "object",
"properties": {
   "EquityWithLoan": { "type": "number" },
   "InitMargin": { "type": "number" },
   "InitMarginBefore": { "type": "number" },
   "MaintMargin": { "type": "number" },
   "MaintMarginBefore": { "type": "number" },
   "MarginCurrency": { "type": "string" },
   "Commission": { "type": "number" },
   "MinCommissions": { "type": "number" },
   "MaxCommissions": { "type": "number" },
   "CommissionsCurrency": { "type": "string" }
}
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408
GET /accounts/{account}/trades

Returns a list of trades for the account starting at the given 'since' date to the current time (now()). Timezone is UTC.
Any request with a future since date or going further than one week will result in an HTTP 400 bad request response. Calling /trades without since will return all trades for the past 24 hours.

Parameters

Parameter Value Description
since (optional) or Start time specified in UTC.
Allowed formats:
yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss
Time is optional and is set to midnight if omitted:
(00:00:00 hh:mm:ss)

Responses

Successful Response
Return code 200 OK
Schema 
{
"type": "array",
"items": {
   "type": "object",
   "properties": {
      "CustomerOrderId": { "type": "number" },
      "ContractId": { "type": "number" },
      "OrderId": { "type": "string" },
      "Ticker": { "type": "string" },
      "ListingExchange": { "type": "string" },
      "Currency": { "type": "string" },
      "Side": { "type": "string", "type": "FIXSide"},
      "OrderType": { "type": "string", "type": "FIXOrderType"},
      "FilledQuantity": { "type": "number" },
      "RemainingQuantity": { "type": "number" },
      "Quantity": { "type": "number" },
      "TradePrice": { "type": "number"},
      "TradeSize": { "type": "number"},
      "AvgPrice": { "type": "number"},
      "ExecutionTime": { "type": "string"},
      "ExecId": { "type": "string"},
      "Commission": { "type": "number"},
      "CommissionCurrency": { "type": "string"}
      "LastMarket": { "type": "string"}
   }
}
}
Unsuccessful Response
Return codes 202, 204, 400, 401, 403, 408

/secdef

GET /secdef

Allows the consumer to request details regarding a trading product from the IB trading product database.

Parameters

Parameter Value Description
type The instrument type of the contract.
symbol The symbol that identifies the trading product.
currency The currency in which the given pair trades.
or
Parameter Value Description
type The instrument type of the contract.
symbol The symbol that identifies the trading product.
exchange The exchange on which the trading product is listed (required for type=STK).
currency The currency in which the given pair trades (required for type=CASH).
or
Parameter Value Description
conid The internal IB identifier for the trading product specified as an integer.

Responses

Successful Response
Return code 200 OK
Schema 

{
  "type": "object",
  "properties": {
     "ContractId": { "type": "number" },
     "Ticker": {"type": "string" },
     "SecurityType": {"type": "string" },
     "Exchange": { "type": "string" },
     "CompanyName": { "type": "string" },
     "Currency": { "type": "string" }
  }
}
Unsuccessful Response
Return codes 202, 400, 401, 403, 408

/marketdata

GET /marketdata/snapshot

This endpoint allows the consumer to request a market data snapshot for one or more trading products. Consumers need to provide unique identifiers (conids) for the products in the IB product database (retrievable using the /secdef endpoint).

The 'market' values are integers whose bits indicate the exchange(s) making up the quote. The mapping of bit to exchange is obtained from the marketdata/exchange_component endpoint.

For example, if a bid has a 'market' value of 5 and the exchange_component result has the map 

0 => NYSE
1 => ISLAND
2 => ARCA
then the exchanges contributing to the bid size are NYSE and ARCA. Similarly, if market=2, then only ISLAND is contributing.

Parameters

Parameter Value Description
type The instrument type of the contract.
symbol The symbol that identifies the trading product.
currency The currency in which the given pair trades.
or
Parameter Value Description
type The instrument type of the contract.
symbol The symbol that identifies the trading product.
exchange The exchange on which the trading product is listed.
or
Parameter Value Description
conids A comma-separated list of IB contract IDs.

Responses

Successful Response
Return code 200 OK
Schema 
{
   "type": "array",
   "items": {
      "type": "object",
      "properties": {
         "Conid": {"type": "number"},
         "Temporality" : { "type" : "number" },
         "Complete" : { "type" : "boolean" },
         "Trade": {
            "type": "object",
            "properties" : {
               "market" : {"type" : "number"},
               "price" : {"type" : "number"},
               "size" : {"type" : "number"},
               "time" : {"type" : "number"}
            }
         },
         "Closing": {
            "type": "object",
            "properties" : {
               "price" : {"type" : "number"},
            }
         },
         "Bid": {
            "type": "object",
            "properties" : {
               "market" : {"type" : "number"},
               "price" : {"type" : "number"},
               "size" : {"type" : "number"}
            }
         },
         "Offer": {
            "type": "object",
            "properties" : {
               "market" : {"type" : "number"},
               "price" : {"type" : "number"},
               "size" : {"type" : "number"}
            }
         }
      }
   }
}
Unsuccessful Response
Return codes 400, 401, 403, 408
GET /marketdata/exchange_components

This endpoint provides a bit mapping for the bid/ask/last 'market' values in the snapshot response.

Parameters

Parameter Value Description
conids A comma-separated list of IB contract IDs.

Responses

Successful Response
Return code 200 OK
Schema 
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "Conid": {"type": "number"},
      "Complete": { "type": "boolean" },
      "mapping": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "bit": {"type": "number"},
            "code": {"type": "string"},
            "exchange": {"type": "string"}
          }
        }
      }
    }
  }
}
Unsuccessful Response
Return codes 400, 401, 403, 408

Models

Order Status 

InvalidOrderStatus = -1
New = '0'
PartiallyFilled = '1'
Filled = '2'
DoneForTheDay = '3'
Canceled = '4'
Replaced = '5'
PendingCancelReplace = '6'
Stopped = '7'
Rejected = '8'
Suspended = '9'
PendingNew = 'A'
Calculated = 'B'
Expired = 'C'
AcceptedForBidding = 'D'
PendingReplace = 'E'

FIX Order Type 

Market = '1'
Limit = '2'
Stop = '3'
StopLimit = '4'

FIX Side 

Buy = '1'
Sell = '2'

FIX TIF (Time In Force) Model 

Day = '0'
GTC (Good till Cancel) = '1'
IOC (Immediate or Cancel) = '3'
Open = '2'
Close = '7'

Execution Type 

Invalid = -1
New = '0'
PartialFill = '1'
Fill = '2'
DoneForDay = '3'
ETCanceled = '4'
Replace = '5'
PendingCancel = '6'
Stopped = '7'
Rejected = '8'
Suspended = '9'
PendingNew = 'A'
Calculated = 'B'
Expired ='C'
Restated = 'D'
PendingReplace = 'E'
Trade = 'F'
TradeCorrect = 'G'
TradeCancel = 'H'
OrderStatus = 'I

Exchanges 

US
American Stock Exchange = AMEX
Bulletin Board = ARCAEDGE
New York Stock Exchange = NYSE
NASDAQ = ISLAND
Pink Sheets = ARCAEDGE
OTCQB = ARCAEDGE
OTCQX = ARCAEDGE

Canada
Toronto Exchange = TSE
Venture Exchange = VENTURE
NEX = AEQNEO

OrderRestrictions 

'1' Program Trade
'2' Index Arbitrage
'3' Non-Index Arbitrage

Temporality 

0 = Real time data
1 = Delayed data