This website uses cookies to collect usage information in order to offer a better browsing experience. By browsing this site or by clicking on the "ACCEPT COOKIES" button you accept our Cookie Policy.

Duration: 5:30

Level: Intermediate

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:

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.

Supporting documentation for any claims and statistical information will be provided upon request.

Any stock, options or futures symbols displayed are for illustrative purposes only and are not intended to portray recommendations.

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.

trading top
Translate »