How to Code a Fractional Shares Order in the Web API

Trading fractional shares (also known as a Cash Quantity Order) allows you to invest in companies which you may not be able to afford the full share price. You may buy a fraction of a share based on the amount of cash specified. For example, if you want to spend $500 but one share of the stock is $1000 you would end up with 0.5 shares. For more details review the following URL: https://www.interactivebrokers.com/en/index.php?f=45718  

The endpoint /iserver/account/rules can be used to confirm if the contract and side supports trading fractional shares. The object fraqTypes relays back the list of order types that support fractional shares. The endpoint /iserver/account/{accountId}/orders can be used to send a Fractional Share Order by specifying cashQTY as the monetary value of the order. When specifying cashQTY you do not specify quantity.  

Please be sure to authenticate first in order to resolve the below URLs. 
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login 

POST 
https://localhost:5000/v1/api/iserver/contract/rules 

Request Body: 

{  

  • conid                     string 
    required                 IBKR contract identifier 
  • isBuy                     boolean 
    required                 Side of the market, rules apply too.
                                   Enum: 
                                       • true = Buy Order 
                                       • false = Sell Order 

} 

Response: 

Array () [ 

  • algoEligible             boolean 
                                        Supports Algo orders, see how-to-code-an-ib-algo-order for details.   
  • canTradeAcctIds       Array of strings 
                                        List the accounts that support trading 
  • error                             string 
                                        Returns a description on any errors with order presets 
  • orderTypes                  Array of strings 
                                        List of order types the contract and side support 
  • ibalgoTypes                Array of strings 
                                        List of order types supported for IB Algo orders. 
  • fraqTypes                    Array of strings 
                                        List of order types supported for Fractional Share Orders. 
  • cqtTypes                    Array of strings 
                                        List of order types supported for Cash Quantity Orders 
  • orderDefaults             Array of objects 
                                        Will provide the defaults based on user settings 

    Array()[

    {

    • ORTH    boolean 
             Outside of regular trading hours 
    • SP    string 
                Stop price value 
    • LP    string 
             Limit price value 
    • PC    string 
             Price cap value 
    • TA    string 
             Trailing amount value 
    • TU    string 
             Trailing unit 
    • ROA    string 
             Relative offset amount 
    • ROP    string 
             Relative offset percent 
    • TT    string 
             Touch trigger price 
    • UNP    string 
             Use net price for Bonds 

    } 

  ] 

  • orderTypesOutside    Array of string 
                                         List of order types supported for outside of regular trading hours 
  • defaultSize                  integer 
                                         Default quantity 
  • cashSize                        integer 
                                         cash value 
  • sizeIncrement              integer 
                                         Increment quantity value 
  • tifTypes                   Array of strings 
                                         Time in Force values. Format may contain o or a value. 
                                         Enum: 
                                            • o = Supports outside regular trading hours 
                                            • a = Supports Algo orders 
  • tifDefaults          Array of objects 

    Array()[ 

    • TIF        string 
                  Default time in force 
    • SIZE    double 
                  Default quantity 

  • limitPrice          number 
                               Limit Price 
  • stopprice            number 
                               Stop Price 
  • orderOrigination number 
                               Order origin designation for US securities and Options Clearing Corporation 
  • preview            boolean 
                               Order preview required 
  • displaySize         number 
                               Display size 
  • fraqInt               number 
                               Decimal places for fractional order size 
  • cashCcy            string 
                               Cash currency for the contract 
  • cashQtyIncr            number 
                               Increment value for cash quantity 
  • priceMagnifier      number 
                               Price Magnifier 
  • negativeCapable boolean 
                               trading negative price support 
  • incrementType  number 
                               Market Data Price format for the contract 

                                      Enum: 
                                      • 1 = decimal 
                                      • 2 = fractional (reduced denominator) 
                                      • 3 = fractional (fix denominator) 
                                      • 4 = Garban price 

  • incrementRules  Array of objects
                                   Price increment value contract trades. 

Array()[ 
            {
                 • lowerEdge    number 
                                        minimum contract price on the market that supports the specified increment. 
                 • increment    double 
                                        minimum increment value for contract price  

             } 

  • hasSecondary    boolean 
                                   Whether it is a secondary order rule request 
  • increment          double 
                                   Price increment value 
  • incrementDigits   integer 
                                   Number of digits for decimal price 

Once you confirm fraqTypes is returned for given contract, send the endpoint /iserver/account/{accountId}/orders to submit an order. 

POST 
https://localhost:5000/v1/api/iserver/account/{accountId}/orders 

Request Body: 

Array () [ 

  • acctId string 
                  The specified Account order is placed for.
                  This should be one of the accounts returned by /iserver/accounts 
  • conid string 
                  contract identifier of the security you want to trade.
                  You can find the conid with /iserver/secdef/search 
  • secType string 
                  asset class formatted as conid:type, for example 265598:STK 
  • cOID string 
                  Customer Order Id. Arbitrary string that can be used to identify the order, e.g “my-fb-order”.
                  Value must be unique for 24h 
  • parentId string 
                  When placing brack orders, specify with the child order.
                  Must be equal to the cOID of the parent 
  • orderType string 
                  The type of order, example MKT (Market), LMT (Limit).
                  Use the endpoint /info-and-rules to determine available orderType(s) 
  • listingExchange string 
    required : false               By default we use “SMART” routing. Use the endpoint:
                  /portal/iserver/contract/{conid}/info, to determine valid_exchange 
  • outsideRTH               boolean 
                  Set to true if the order can be executed outside regular trading hours 
  • price              number 
                  For LMT this is the limit price. For STP this is the stop price 
  • auxPrice       number 
                  For STOP_LIMIT orders this is the Stop Price 
  • side                       string 
                  SELL or BUY 
  • ticker                          string 
                  Contract Symbol 
  • tif                          string 
                  The time-in-force of an order, example DAY. Use the endpoint /info-and-rules to determine tifTypes 
  • referrer                     string 
                  Order reference 
  • quantity               number 
                  the amount or shares of the order.
                  Usually integer, for some special cases can be float numbers 
  • cashQty                             number 
                  Cash Quantity – used to specify the monetary value of an order instead of the number of shares. 
  • fxQty                             number 
                  double number, this is the cash quantity field used for Currency conversion orders. 
  • isCcyConv boolean 
                  Set to true for a FX conversion order 
  • allocationMethod        string 
                  Set the allocation method when placing an order using an FA account for a group 
  • isClose                            boolean 
                  Set to true if order is closing an existing position 
  • isSingleGroup               boolean 
                  Set to true for each order assigned to the same OCA Group. 

Response: 

Array () [ 

  • id                                  string 
                  order_id = system generated order Id(s) for each order.
                   local_order_id = cOID. parent_order_id = order_Id of the parent order. 
  • message                                   Array of strings 
    if the message is a question, you must use the endpoint /iserver/reply/{replyid} to confirm the message and submit the order. 

Please be sure to authenticate first in order to resolve the below URLs. 
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login 

Example: 

Use the endpoint /iserver/account/rules for Apple Stock to see if limit order type is returned in fraqTypes

Request: 

POST 
https://localhost:5000/v1/api/iserver/contract/rules 

Request Body: 
{ 

  "conid": "265598", 

  "isBuy": true 

} 

 

Response: 

{ 

  "algoEligible": true, 

  "canTradeAcctIds": [ 

    "DU***14" 

  ], 

  "error": "The Allow pre-open: true is not supported on mobile.\n\nTo continue, adjust Order Type field.\n\nYou can modify your Presets in the desktop Trader Workstation.", 

  "orderTypes": [ 

    "limit", 

    "midprice", 

    "market", 

    "stop", 

    "stop_limit", 

    "mit", 

    "lit", 

    "trailing_stop", 

    "relative", 

    "marketonclose", 

    "limitonclose" 

  ], 

  "ibAlgoTypes": [ 

    "limit", 

    "stop_limit", 

    "lit", 

    "relative", 

    "marketonclose", 

    "limitonclose" 

  ], 

  "fraqTypes": [ 

    "limit", 

    "market", 

    "stop", 

    "stop_limit", 

    "mit", 

    "lit", 

    "trailing_stop" 

  ], 

  "cqtTypes": [ 

    "limit", 

    "market", 

    "stop", 

    "stop_limit", 

    "mit", 

    "lit", 

    "trailing_stop" 

  ], 

  "orderDefaults": { 

    "invalid": {} 

  }, 

  "orderTypesOutside": [ 

    "limit", 

    "stop_limit", 

    "lit", 

    "relative" 

  ], 

  "defaultSize": 50, 

  "cashSize": 0, 

  "sizeIncrement": 57, 

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

  }, 

  "limitPrice": null, 

  "stopprice": null, 

  "orderOrigination": null, 

  "preview": true, 

  "displaySize": null, 

  "fraqInt": 4, 

  "cashCcy": "USD", 

  "cashQtyIncr": 500, 

  "priceMagnifier": null, 

  "negativeCapable": false, 

  "incrementType": 1, 

  "incrementRules": [ 

    { 

      "lowerEdge": 0, 

      "increment": 0.01 

    } 

  ], 

  "hasSecondary": true, 

  "increment": 0.01, 

  "incrementDigits": 2 

} 

Confirmed fraqTypes returned “limit”. Now submit a Fractional Shares Limit Order for $500 of Apple Stock by specifying cashQty = 500.  

Request: 

POST 
https://localhost:5000/v1/api/iserver/account/DU***14/orders 

Request Body: 
{ 

  "orders": [ 

    { 

      "acctId": "DU***14", 

      "conidex": "265598", 

      "cOID": "54881719", 

      "orderType": "LMT", 

      "outsideRTH": true, 

      "listingExchange": "SMART", 

      "price": 150.25, 

      "side": "BUY", 

      "ticker": "AAPL", 

      "tif": "DAY", 

      "referrer": "testFractOrder", 

      "cashQty": 500, 

      "useAdaptive": false, 

      "isClose": false 

    } 

  ] 

} 

 
Response: 
[ 
  { 
    “order_id”: “1730952373”, 
    “order_status”: “Submitted”, 
    “local_order_id”: “54881719” 
  } 
] 

If you have any further questions or issues creating OCA orders, please reach out to the API Group, ref: https://www.interactivebrokers.com/en/index.php?f=47047

Visit the IBKR API Center for Downloads, Resources, and Technical Details: 
https://www.interactivebrokers.com/en/trading/ib-api.php

Disclosure: Interactive Brokers

The analysis in this material is provided for information only and is not and should not be construed as an offer to sell or the solicitation of an offer to buy any security. To the extent that this material discusses general market activity, industry or sector trends or other broad-based economic or political conditions, it should not be construed as research or investment advice. To the extent that it includes references to specific securities, commodities, currencies, or other instruments, those references do not constitute a recommendation by IBKR to buy, sell or hold such investments. This material does not and is not intended to take into account the particular financial conditions, investment objectives or requirements of individual customers. Before acting on this material, you should consider whether it is suitable for your particular circumstances and, as necessary, seek professional advice.

The views and opinions expressed herein are those of the author and do not necessarily reflect the views of Interactive Brokers LLC, its affiliates, or its employees.

Any trading symbols displayed are for illustrative purposes only and are not intended to portray recommendations.

In accordance with EU regulation: The statements in this document shall not be considered as an objective or independent explanation of the matters. Please note that this document (a) has not been prepared in accordance with legal requirements designed to promote the independence of investment research, and (b) is not subject to any prohibition on dealing ahead of the dissemination or publication of investment research.

Disclosure: API Examples Discussed

Throughout the lesson, please keep in mind that the examples discussed are purely for technical demonstration purposes, and do not constitute trading advice. Also, it is important to remember that placing trades in a paper account is recommended before any live trading.

Disclosure: Order Types / TWS

The order types available through Interactive Brokers LLC’s Trader Workstation are designed to help you limit your loss and/or lock in a profit. Market conditions and other factors may affect execution. In general, orders guarantee a fill or guarantee a price, but not both. In extreme market conditions, an order may either be executed at a different price than anticipated or may not be filled in the marketplace.