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
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.
Join The Conversation
If you have a general question, it may already be covered in our FAQs. If you have an account-specific question or concern, please reach out to Client Services.