swagger: '2.0' info: title: IBKR 3rd Party Web API description: Interactive Brokers Web API for 3rd Party Companies version: 1.0.0 host: www.interactivebrokers.com schemes: - https basePath: /tradingapi/v1 produces: - application/json securityDefinitions: cookieAuth: type: apiKey name: portal in: header security: - cookieAuth: [] paths: /oauth/request_token: post: summary: Obtain a request token description: | Obtain a request token. See section 6.1 of the OAuth v1.0a specification for more information. http://oauth.net/core/1.0a/#auth_step1 Note we do not return an oauth_token_secret in the response as we are using RSA signatures rather than PLAINTEXT authentication. tags: - OAuth parameters: - in: body name: body description: OAuth Parameters required: true schema: type: object properties: oauth_consumer_key: type: string description: The 25-character hexadecimal string that was obtained from Interactive Brokers during the OAuth consumer registration process. oauth_signature_method: type: string description: The signature method used to sign the request. Currently only 'RSA-SHA256' is supported. oauth_signature: type: string description: >- 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: type: string description: >- 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: type: string description: >- A random string uniquely generated for each request. oauth_callback: type: string description: >- 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: '200': description: OAuth token schema: type: object properties: oauth_token: type: string '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response /oauth/access_token: post: summary: Obtain a access token description: | 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. tags: - OAuth parameters: - in: body name: body description: OAuth Parameters required: true schema: type: object properties: oauth_consumer_key: type: string description: The 25-character hexadecimal string that was obtained from Interactive Brokers during the OAuth consumer registration process. oauth_token: type: string description: The request token obtained from IB via /request_token. oauth_signature_method: type: string description: The signature method used to sign the request. Currently only 'RSA-SHA256' is supported. oauth_signature: type: string description: 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: type: string description: 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: type: string description: A random string uniquely generated for each request. oauth_verifier: type: string description: The verification code received from IB after the user has granted authorization. responses: '200': description: Access token and token secret schema: type: object properties: oauth_token: type: string oauth_token_secret: type: string '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response /oauth/live_session_token: post: summary: Obtain a live session token description: | 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. https://www.interactivebrokers.com/webtradingapi/oauth.pdf tags: - OAuth parameters: - in: body name: body description: OAuth Parameters required: true schema: type: object properties: oauth_consumer_key: type: string description: The 25-character hexadecimal string that was obtained from Interactive Brokers during the OAuth consumer registration process. oauth_token: type: string description: The request token obtained from IB via /request_token. oauth_signature_method: type: string description: The signature method used to sign the request. Currently only 'RSA-SHA256' is supported. oauth_signature: type: string description: 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: type: string description: 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: type: string description: A random string uniquely generated for each request. diffie_hellman_challenge: type: string description: | 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: '200': description: DH response schema: type: object properties: diffie_hellman_response: type: string live_session_token_signature: type: string '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response /accounts: get: summary: Brokerage Accounts description: >- Allows the caller to request a list of accounts associated with the session. tags: - Account & Portfolio parameters: - name: account in: path required: true type: string description: Account Number responses: '200': description: An array of accounts schema: type: object properties: accounts: type: array items: type: string description: Unique account id '202': description: Unsuccessfull response '204': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response '/accounts/{account}/positions': get: summary: Account Positions description: 'Returns a list of positions for the indicated account. ' tags: - Account & Portfolio parameters: - name: account in: path required: true type: string description: Account Number responses: '200': description: Returns a list of positions for the indicated account schema: type: array items: type: object properties: Position: type: number AverageCost: type: number ContractId: type: number '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response '/accounts/{account}/summary': get: summary: Account Values Summary description: >- Returns a list of account and margin balances associated with the account passed in the URL tags: - Account & Portfolio parameters: - name: account in: path required: true type: string description: Account Number responses: '200': description: > Returns object for account summary with multiple properties. A property is sufficed with -c if it provides commodity value, -s if it provides security value, and -c if its UKL segment value. "These values correspond to the TWS Account Window: https://www.interactivebrokers.com/en/software/tws/usersguidebook/realtimeactivitymonitoring/account_window.htm" schema: type: object properties: Ledger: type: array items: type: object properties: CashCumQty: type: number ExchangeRate: type: number NetInterest: type: number RealizedPNL: type: number FuturePNL: type: number UnrealizedPNL: type: number OptionMarketValue: type: number StockMarketValue: type: number CashBalance: type: number FutureOptionMarketValue: type: number NetDividend: type: number NetLiquidation: type: number TotalCashBalance: type: number CashBalanceFXSegment: type: number Info: type: object properties: AccountType: type: string AccountCode: type: string AccountReady: type: string Cushion: type: string DayTradesRemaining: type: string DayTradesRemainingT: type: string DayTradesRemainingT+2: type: string DayTradesRemainingT+3: type: string DayTradesRemainingT+4: type: string HighestSeverity: type: string Leverage-S: type: string LookAheadNextChange: type: string SegmentTitle-C: type: string SegmentTitle-S: type: string TradingType-S: type: string WhatIfPMEnabled: type: string Summary: type: object properties: AccruedCash: type: number AccruedCash-C: type: number AccruedCash-S: type: number AccruedDividend: type: number AccruedDividend-C: type: number AccruedDividend-S: type: number AvailableFunds: type: number AvailableFunds-C: type: number AvailableFunds-S: type: number Billable: type: number Billable-C: type: number Billable-S: type: number BuyingPower: type: number EquityWithLoanValue: type: number EquityWithLoanValue-C: type: number EquityWithLoanValue-S: type: number ExcessLiquidity: type: number ExcessLiquidity-C: type: number ExcessLiquidity-S: type: number FullAvailableFunds: type: number FullAvailableFunds-C: type: number FullAvailableFunds-S: type: number FullExcessLiquidity: type: number FullExcessLiquidity-C: type: number FullExcessLiquidity-S: type: number FullInitMarginReq: type: number FullInitMarginReq-C: type: number FullInitMarginReq-S: type: number FullMaintMarginReq: type: number FullMaintMarginReq-C: type: number FullMaintMarginReq-S: type: number GrossPositionValue: type: number GrossPositionValue-C: type: number GrossPositionValue-S: type: number IndianStockHaircut: type: number IndianStockHaircut-C: type: number IndianStockHaircut-S: type: number InitMarginReq: type: number InitMarginReq-C: type: number InitMarginReq-S: type: number InsuredDeposit: type: number InsuredDeposit-C: type: number InsuredDeposit-S: type: number LookAheadAvailableFunds: type: number LookAheadAvailableFunds-C: type: number LookAheadAvailableFunds-S: type: number LookAheadExcessLiquidity: type: number LookAheadExcessLiquidity-C: type: number LookAheadExcessLiquidity-S: type: number LookAheadInitMarginReq: type: number LookAheadInitMarginReq-C: type: number LookAheadInitMarginReq-S: type: number LookAheadMaintMarginReq: type: number LookAheadMaintMarginReq-C: type: number LookAheadMaintMarginReq-S: type: number MaintMarginReq: type: number MaintMarginReq-C: type: number MaintMarginReq-S: type: number NetLiquidation: type: number NetLiquidation-C: type: number NetLiquidation-S: type: number NetLiquidationUncertainty: type: number PASharesValue: type: number PASharesValue-C: type: number PASharesValue-S: type: number PostExpirationExcess: type: number PostExpirationExcess-C: type: number PostExpirationExcess-S: type: number PostExpirationMargin: type: number PostExpirationMargin-C: type: number PostExpirationMargin-S: type: number RegTEquity: type: number RegTEquity-S: type: number RegTMargin: type: number RegTMargin-S: type: number SMA: type: number SMA-S: type: number TotalCashValue: type: number TotalCashValue-C: type: number TotalCashValue-S: type: number '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response '/accounts/{account}/orders': parameters: - name: account in: path required: true type: string description: Account Number get: summary: Open Orders description: Returns a list of orders for the account passed in the URL tags: - Orders responses: '200': description: Returns a list of orders for the indicated account schema: type: array items: $ref: '#/definitions/orderState' '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response post: summary: Place Order description: Places order tags: - Orders parameters: - in: body name: body description: Order Parameters required: true schema: type: object properties: CustomerOrderId: type: string description: The order ID assigned by the customer. Ticker: type: string description: The symbol that identifies the trading product ListingExchange: type: string description: >- The exchange on which the trading product is listed (only for InstrumentType=STK) Currency: type: string description: >- The currency in which the FX pair trades (only for InstrumentType=CASH) InstrumentType: type: string description: The instrument type of the contract ContractId: type: number description: >- The internal IB identifier for the trading product specified as an integer (can be obtained in response to /secdef request) Quantity: type: number description: The number of units in the order; contracts or shares Price: type: number description: The order price Order Type: $ref: '#/definitions/orderType' Aux Price: type: number description: Required Price to support Stop and Stop Limit orders Time in Force: $ref: '#/definitions/timeInForce' Outside RTH: type: number description: >- Indicates if order is active outside regular trading hours, where defined. 0 = no (default), 1 = yes Side: type: number description: 'Buy = ''1'', Sell = ''2''' enum: [1, 2] OrderRestrictions: type: number description: | 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. '1' Program Trade '2' Index Arbitrage '3' Non-Index Arbitrage GermanHftAlgo: type: boolean description: >- 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. Mifid2DecisionMaker: type: string description: >- This field permits specification of the user's preregistered (via account management) MiFID II short code for decision makers. Mifid2Algo: type: string description: >- 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: type: string description: >- This field permits specification of the user's preregistered (via account management) MiFID II person responsible for handling/routing of the order Mifid2ExecutionAlgo: type: string description: >- 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. responses: '200': description: Returns order status information schema: type: array items: $ref: '#/definitions/orderState' '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response '/accounts/{account}/orders/{CustomerOrderId}': parameters: - name: account in: path required: true type: string description: Account Number - name: CustomerOrderId in: path required: true type: string description: Customer Order ID get: summary: Return specific order info tags: - Orders description: >- Returns the order with the referenced Customer Order ID for the account passed in the URL. responses: '200': description: Returns order status information schema: type: array items: $ref: '#/definitions/orderState' '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response delete: summary: Cancel Order tags: - Orders description: >- Cancels the order with the referenced Customer Order ID for the account passed in the URL. responses: '200': description: Returns result of cancellation attempt schema: type: array items: type: object properties: CustomerOrderId: type: string Symbol: type: number OrderQty: type: number Price: type: string Side: type: number enum: [1, 2] Status: $ref: '#/definitions/orderStatus' Warning: type: string OrderType: $ref: '#/definitions/orderType' '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response put: summary: Modify Order tags: - Orders description: >- 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: - in: body name: body description: Order Parameters required: true schema: type: object properties: OrigCustomerOrderId: type: string description: The order ID assigned by the customer CustomerOrderId: type: string description: >- The new order ID assigned by the customer for the modification. Quantity: type: number description: The number of units in the order; contracts or shares Price: type: number description: The order price Order Type: $ref: '#/definitions/orderType' Aux Price: type: number description: Required Price to support Stop and Stop Limit orders Time in Force: $ref: '#/definitions/timeInForce' Outside RTH: type: number description: >- Indicates if order is active outside regular trading hours, where defined. 0 = no (default), 1 = yes Side: type: number description: 'Buy = ''1'', Sell = ''2''' enum: [1, 2] GermanHftAlgo: type: boolean description: >- 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. Mifid2DecisionMaker: type: string description: >- This field permits specification of the user's preregistered (via account management) MiFID II short code for decision makers. Mifid2Algo: type: string description: >- 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: type: string description: >- This field permits specification of the user's preregistered (via account management) MiFID II person responsible for handling/routing of the order Mifid2ExecutionAlgo: type: string description: >- 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. responses: '200': description: Result of order modification attempt schema: type: array items: type: object properties: CustomerOrderId: type: string Symbol: type: number OrderQty: type: number Price: type: string Side: type: number enum: [1, 2] Status: $ref: '#/definitions/orderStatus' Warning: type: string OrderType: $ref: '#/definitions/orderType' '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response '/accounts/{account}/order_impact': parameters: - name: account in: path required: true type: string description: Account Number post: summary: Return margin impact info tags: - Order Margin Requirements description: > 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: - in: body name: body description: Order Parameters required: true schema: type: object properties: CustomerOrderId: type: string description: The order ID assigned by the customer. Ticker: type: string description: The symbol that identifies the trading product ListingExchange: type: string description: >- The exchange on which the trading product is listed (only for InstrumentType=STK) Currency: type: string description: >- The currency in which the FX pair trades (only for InstrumentType=CASH) InstrumentType: type: string description: The instrument type of the contract ContractId: type: number description: >- The internal IB identifier for the trading product specified as an integer (can be obtained in response to /secdef request) Quantity: type: number description: The number of units in the order; contracts or shares Price: type: number description: The order price Order Type: $ref: '#/definitions/orderType' Aux Price: type: number description: Required price to support Stop and Stop Limit orders Time in Force: $ref: '#/definitions/timeInForce' Side: type: number description: 'Buy = ''1'', Sell = ''2''' enum: [1, 2] responses: '200': description: Order impact info 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 '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response '/accounts/{account}/trades': parameters: - name: account in: path required: true type: string description: Account Number get: summary: Returns trades in account tags: - Trades description: > 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: - in: body name: since description: > Start time specified in UTC. Allowed formats are "yyyy-MM-dd" or "yyyy-MM-dd'T'HH:mm:ss". Time is optional and is set to midnight if omitted, e.g. "00:00:00 hh:mm:ss". required: false schema: type: string responses: '200': description: List of Trades 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 enum: [1, 2] OrderType: $ref: '#/definitions/orderType' 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 '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response /secdef: get: summary: Get security definition tags: - Financial Instrument Definitions description: | Fields that compose security definition. Allowed combinations, (1) type and symbol and currency, or (2) type, symbol, exchange, and currency, or (3) conid parameters: - in: body name: body description: Order Parameters required: true schema: type: object properties: type: type: string description: The instrument type of the contract (CASH). symbol: type: string description: The symbol that identifies the trading product. currency: type: string description: The currency in which the given pair trades. exchange: type: string description: >- The exchange on which the trading product is listed (required for type=STK). conid: type: number description: >- The internal IB identifier for the trading product specified as an integer. responses: '200': description: Financial Instrument Definition schema: type: array items: type: object properties: ContractId: type: number Ticker: type: string SecurityType: type: string Exchange: type: string CompanyName: type: string Currency: type: string '202': description: Unsuccessfull response '204': description: Unsuccessfull response '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response /marketdata/snapshot: get: summary: Market Data Snapshot tags: - Market Data description: > 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: - in: body name: body description: >- Contract. Allowed combinations are [type and symbol and currency], or [type, symbol, exchange, and currency], or [conid]. required: true schema: type: array items: type: object properties: type: type: string description: The instrument type of the contract (CASH). symbol: type: string description: The symbol that identifies the trading product. currency: type: string description: The currency in which the given pair trades. exchange: type: string description: >- The exchange on which the trading product is listed (required for type=STK). conid: type: number description: >- The internal IB identifier for the trading product specified as an integer. responses: '200': description: Financial Instrument Definition schema: type: array items: type: object properties: Conid: type: string Temporality: type: number description: | 0 = Real time data 1 = Delayed data enum: [0, 1] 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 '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response /marketdata/exchange_components: get: summary: Exchange Components tags: - Market Data description: >- This endpoint provides a bit mapping for the bid/ask/last 'market' values in the snapshot response. responses: '200': description: Exchange Components 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 '400': description: Unsuccessfull response '401': description: Unsuccessfull response '403': description: Unsuccessfull response '408': description: Unsuccessfull response definitions: timeInForce: type: number enum: [0, 1, 2, 3, 7] description: | Defines order's active lifetime. Day = '0' GTC (Good till Cancel) = '1' IOC (Immediate or Cancel) = '3' Open = '2' Close = '7' orderType: type: number enum: [1, 2, 3, 4] description: | Market = '1' Limit = '2' Stop = '3' StopLimit = '4' orderState: description: An object containing all the properties defining an order type: object properties: CustomerOrderId: type: number ContractId: type: number Ticker: type: string ListingExchange: type: string RemainingQuantity: type: number FilledQuantity: type: number OrderType: $ref: '#/definitions/orderType' TimeInForce: $ref: '#/definitions/timeInForce' OutsideRTH: type: string Side: type: string enum: [1, 2] Price: type: number Status: $ref: '#/definitions/orderStatus' Warning: type: string TransactionTime: type: string orderStatus: type: string enum: ['-1', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E'] description: | Status of the order 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'