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.
