How to Code a Currency Conversion Order in the Web API

Articles From: Interactive Brokers
Website: Interactive Brokers

How to Code a Currency Conversion Order in the Web API

A Currency Conversion Order lets you convert cash from one currency to another. You would send a buy market order and either specify the amount of currency you want to convert from or the amount of currency you want to convert to. Please note Currency Conversion Orders express size using a monetary value (cash quantity) which are provided on a non-guaranteed basis. The system simulates the order by submitting a larger order size and cancelling it once the specified amount is spent (for buy orders) or collected (for sell orders). The system uses the maximum size that is calculated using the Cash Quantity Estimated Factor, which can be modified in Order Presets from Desktop TWS or IBKR Mobile.

The endpoint /portfolio/{accountId}/ledger can be used to determine the amount of settledcash available for each currency in your account. This is the maximum amount of cash to transfer from.

The endpoint /iserver/account/{accountId}/orders can be used to send a Currency Conversion Order by sending a BUY order using orderType: MKT, setting isCcyConv to true and either specifying the amount of currency transfer from or to. You do not specify the cash quantity for both.

  • To specify the amount of currency you want to transfer FROM use fxQty. The estimated amount of cash currency received will be automatically calculated.
  • To specify the amount of currency you want to transfer TO use quantity. The estimated amount of cash currency used will be automatically calculated.

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/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 /portal/iserver/contract/{conid}/info, to determine
                                              valid_exchange  
  • 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  
  • useAdaptive                     boolean
                                              If true, system will use Adaptive Algo to submit the order,
                                              ref: https://www.interactivebrokers.com/en/index.php?f=19091
  • 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 /portfolio/{accountId}/ledger to see how much settledCash is available.

Request:

POST
https://localhost:5000/v1/api/portfolio/DU***14/ledger

Response:
{
  "EUR": {
    "commoditymarketvalue": 0,
    "futuremarketvalue": 0,
    "settledcash": -51518.95,
    "exchangerate": 1.155175,
    "sessionid": 2,
    "cashbalance": -51518.95,
    "corporatebondsmarketvalue": 0,
    "warrantsmarketvalue": 0,
    "netliquidationvalue": 50828.85,
    "interest": 0,
    "unrealizedpnl": 7352.49,
    "stockmarketvalue": 102347.8,
    "moneyfunds": 0,
    "currency": "EUR",
    "realizedpnl": 0,
    "funds": 0,
    "acctcode": "DU***14",
    "issueroptionsmarketvalue": 0,
    "key": "LedgerList",
    "timestamp": 1633634484,
    "severity": 0,
    "stockoptionmarketvalue": 0,
    "tbondsmarketvalue": 0,
    "futureoptionmarketvalue": 0,
    "cashbalancefxsegment": 0,
    "secondkey": "EUR",
    "tbillsmarketvalue": 0,
    "dividends": 0
  },
  "USD": {
    "commoditymarketvalue": 0,
    "futuremarketvalue": 0,
    "settledcash": 8877099,
    "exchangerate": 1,
    "sessionid": 2,
    "cashbalance": 8877099,
    "corporatebondsmarketvalue": 1040.03,
    "warrantsmarketvalue": 0,
    "netliquidationvalue": 10503973,
    "interest": 0,
    "unrealizedpnl": 623677.25,
    "stockmarketvalue": 1622525.2,
    "moneyfunds": 0,
    "currency": "USD",
    "realizedpnl": 805.78,
    "funds": 0,
    "acctcode": "DU***14",
    "issueroptionsmarketvalue": 0,
    "key": "LedgerList",
    "timestamp": 1633634484,
    "severity": 0,
    "stockoptionmarketvalue": 0,
    "tbondsmarketvalue": 1181.9,
    "futureoptionmarketvalue": 0,
    "cashbalancefxsegment": 0,
    "secondkey": "USD",
    "tbillsmarketvalue": 0,
    "dividends": 0
  },
  "BASE": {
    "commoditymarketvalue": 0,
    "futuremarketvalue": 0,
    "settledcash": 8712214,
    "exchangerate": 1,
    "sessionid": 2,
    "cashbalance": 8712214,
    "corporatebondsmarketvalue": 1040.03,
    "warrantsmarketvalue": 0,
    "netliquidationvalue": 10458676,
    "interest": -182.53033,
    "unrealizedpnl": 629821.7,
    "stockmarketvalue": 1742298.2,
    "moneyfunds": 0,
    "currency": "BASE",
    "realizedpnl": 805.78,
    "funds": 0,
    "acctcode": "DU***14",
    "issueroptionsmarketvalue": 0,
    "key": "LedgerList",
    "timestamp": 1633634484,
    "severity": 0,
    "stockoptionmarketvalue": 0,
    "tbondsmarketvalue": 1181.9,
    "futureoptionmarketvalue": 0,
    "cashbalancefxsegment": 0,
    "secondkey": "BASE",
    "tbillsmarketvalue": 0,
    "dividends": 0
  }
}

Submitting a Currency Conversion Order to transfer USD to EUR by specifying fxQty = USD. The amount of EUR received will be calculated.

Request:

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

Request Body: 
{ 
  “orders”: [ 
  { 
     “acctId”: “DU***14”, 
     “cOID”: “66827401”, 
     “conid”: 12087792, 
     “fxQty”: 10000, 
     “isCcyConv”: true 
     “orderType”: “MKT”, 
     “side”: “BUY”, 
     “ticker”: “EUR.USD”, 
     “tif”: “DAY”, 
     “referrer”: “testCcy1” 
  } 
 ] 
} 
 
Response: 
[ 
  { 
    “order_id”: “194938080”, 
    “order_status”: “Filled”, 
    “local_order_id”: “66827401” 
    “warning_message”: “399” 
    “text”: “Order Message:SELL 10K USD EUR.USD ForexWarning: Your order size is below the EUR 20000 IdealPro minimum and will be routed as an odd lot order” 
    “encrypt_message":"1” 
  } 
] 

Submitting a Currency Conversion Order to transfer USD to EUR by specifying quantity = EUR. The amount of USD needed will be calculated.

Request: 

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

Request Body: 
{ 
  “orders”: [ 
  { 
     “acctId”: “DU***14”, 
     “cOID”: “66827402”, 
     “conid”: 12087792, 
     “isCcyConv”: true 
     “orderType”: “MKT”, 
     “quantity”: 10000, 
     “side”: “BUY”, 
     “ticker”: “EUR.USD”, 
     “tif”: “DAY”, 
     “referrer”: “testCcy2” 
  } 
 ] 
} 
 
Response: 
[ 
  { 
    “order_id”: “194938091”, 
    “order_status”: “Filled”, 
    “local_order_id”: “66827402” 
    “warning_message”: “399” 
    “text”: “Order Message:\nBUY 10K USD EUR.USD ForexWarning: Your order size is below the EUR 20000 IdealPro minimum and will be routed as an odd lot order” 
    “encrypt_message":"1” 
  } 
] 

 

Once order is filled use the endpoint /portfolio/{accountId}/ledger to see the updated settledCash for each corresponding currency. 

Request: 

POST 
https://localhost:5000/v1/api/portfolio/DU***14/ledger

Response: 

{ 

  "EUR": { 

    "commoditymarketvalue": 0, 

    "futuremarketvalue": 0, 

    "settledcash": -32863.95, 

    "exchangerate": 1.155135, 

    "sessionid": 24, 

    "cashbalance": -32863.95, 

    "corporatebondsmarketvalue": 0, 

    "warrantsmarketvalue": 0, 

    "netliquidationvalue": 69471.78, 

    "interest": 0, 

    "unrealizedpnl": 7340.42, 

    "stockmarketvalue": 102335.73, 

    "moneyfunds": 0, 

    "currency": "EUR", 

    "realizedpnl": 0, 

    "funds": 0, 

    "acctcode": "DU***14", 

    "issueroptionsmarketvalue": 0, 

    "key": "LedgerList", 

    "timestamp": 1633636630, 

    "severity": 0, 

    "stockoptionmarketvalue": 0, 

    "tbondsmarketvalue": 0, 

    "futureoptionmarketvalue": 0, 

    "cashbalancefxsegment": 0, 

    "secondkey": "EUR", 

    "tbillsmarketvalue": 0, 

    "dividends": 0 

  }, 

  "USD": { 

    "commoditymarketvalue": 0, 

    "futuremarketvalue": 0, 

    "settledcash": 8855543, 

    "exchangerate": 1, 

    "sessionid": 24, 

    "cashbalance": 8855543, 

    "corporatebondsmarketvalue": 1040.03, 

    "warrantsmarketvalue": 0, 

    "netliquidationvalue": 10478366, 

    "interest": 0, 

    "unrealizedpnl": 619627.5, 

    "stockmarketvalue": 1618474.2, 

    "moneyfunds": 0, 

    "currency": "USD", 

    "realizedpnl": 805.78, 

    "funds": 0, 

    "acctcode": "DU***14", 

    "issueroptionsmarketvalue": 0, 

    "key": "LedgerList", 

    "timestamp": 1633636630, 

    "severity": 0, 

    "stockoptionmarketvalue": 0, 

    "tbondsmarketvalue": 1183.05, 

    "futureoptionmarketvalue": 0, 

    "cashbalancefxsegment": 0, 

    "secondkey": "USD", 

    "tbillsmarketvalue": 0, 

    "dividends": 0 

  }, 

  "BASE": { 

    "commoditymarketvalue": 0, 

    "futuremarketvalue": 0, 

    "settledcash": 8712207, 

    "exchangerate": 1, 

    "sessionid": 24, 

    "cashbalance": 8712207, 

    "corporatebondsmarketvalue": 1040.03, 

    "warrantsmarketvalue": 0, 

    "netliquidationvalue": 10454584, 

    "interest": -182.44173, 

    "unrealizedpnl": 625750.2, 

    "stockmarketvalue": 1738211.8, 

    "moneyfunds": 0, 

    "currency": "BASE", 

    "realizedpnl": 805.78, 

    "funds": 0, 

    "acctcode": "DU***14", 

    "issueroptionsmarketvalue": 0, 

    "key": "LedgerList", 

    "timestamp": 1633636630, 

    "severity": 0, 

    "stockoptionmarketvalue": 0, 

    "tbondsmarketvalue": 1183.05, 

    "futureoptionmarketvalue": 0, 

    "cashbalancefxsegment": 0, 

    "secondkey": "BASE", 

    "tbillsmarketvalue": 0, 

    "dividends": 0 

  } 

} 

 

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, its affiliates, or its employees.

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.

Disclosure: Forex

There is a substantial risk of loss in foreign exchange trading. The settlement date of foreign exchange trades can vary due to time zone differences and bank holidays. When trading across foreign exchange markets, this may necessitate borrowing funds to settle foreign exchange trades. The interest rate on borrowed funds must be considered when computing the cost of trades across multiple markets.

Disclosure: Futures Trading

Futures are not suitable for all investors. The amount you may lose may be greater than your initial investment. Before trading futures, please read the CFTC Risk Disclosure. A copy and additional information are available at ibkr.com.