Allocation Methods and Groups

A number of methods and profiles are available with Financial Advisor and IBroker account structures to specify how trades should be distributed across multiple accounts. This functionality allows for trades to be placed across multiple accounts. The API has the same functionality available as TWS.

Group and Profile order allocation methods for Financial Advisor Accounts can be created directly in TWS: Allocations and Transfers, or utilize the IBApi.EClient.replaceFA() method via the API directly.

As suggested from the method names below, a Group will distribute the order based on inherent properties such as the account's liquidation value or equity whereas a Profile will offer the possibility to assign the allocated proportion based on explicit ratios or percentages.
Note, however, in TWS v983+, there is an API setting which merges groups and profiles, where both allocation methods are considered groups. See Unification of Groups and Profiles

Allocation by Group

EqualQuantity

Requires you to specify an order size. This method distributes shares equally between all accounts in the group.

Example: You transmit an order for 400 shares of stock ABC. If your Account Group includes four accounts, each account receives 100 shares. If your Account Group includes six accounts, each account receives 66 shares, and then 1 share is allocated to each account until all are distributed.

NetLiq

Requires you to specify an order size. This method distributes shares based on the net liquidation value of each account. The system calculates ratios based on the Net Liquidation value in each account and allocates shares based on these ratios.

Example: You transmit an order for 700 shares of stock XYZ. The account group includes three accounts, A, B and C with Net Liquidation values of $25,000, $50,000 and $100,000 respectively. The system calculates a ratio of 1:2:4 and allocates 100 shares to Client A, 200 shares to Client B, and 400 shares to Client C.

AvailableEquity

Requires you to specify an order size. This method distributes shares based on the amount of available equity in each account. The system calculates ratios based on the Available Equity in each account and allocates shares based on these ratios.

Example: You transmit an order for 700 shares of stock XYZ. The account group includes three accounts, A, B and C with available equity in the amounts of $25,000, $50,000 and $100,000 respectively. The system calculates a ratio of 1:2:4 and allocates 100 shares to Client A, 200 shares to Client B, and 400 shares to Client C.

PctChange

Do not specify an order size. Since the quantity is calculated by the system, the order size is displayed in the Quantity field after the order is acknowledged. This method increases or decreases an already existing position. Positive percents will increase a position, negative percents will decrease a position. For exmaple, to fully close out a position, you just need to specify percentage to be -100.

BUY ORDER	Positive Percent	Negative Percent
Long Position	Increases position	No effect
Short Position	No effect	Decreases position

SELL ORDER	Positive Percent	Negative Percent
Long Position	No effect	Decreases position
Short Position	Increases position	No effect

Allocation by Profile

Percentages

This method will split the total number of shares in the order between listed accounts based on the percentages you indicate. For example, an order for 1000 shares using a profile with four accounts at 25% each would allocate 250 shares to each listed account in the profile.

Financial Ratios

This method calculates the allocation of shares based on the ratios you enter. For example, an order for 1000 shares using a profile with four accounts set to a ratio of 4, 2, 1, 1 would allocate 500, 250, 125 and 125 shares to the listed accounts, respectively.

Shares

This method allocates the absolute number of shares you enter to each account listed. If you use this method, the order size is calculated by adding together the number of shares allocated to each account in the profile.

Profile Methods Matching
Profile Methods	Type Number
Percentages	Type - 1
Financial Ratios	Type - 2
Shares	Type - 3

Groups and Profiles from the API

The IBApi.EClient.requestFA function allows Financial Advisor to manually request current allocation configuration data from TWS.

Request Account Aliases

client.requestFA(Constants.FaAliases);
client.requestFA(FADataType.ALIASES.ordinal());
client.requestFA(Constants.FaAliases)
m_pClient->requestFA(faDataType::ALIASES);
1 self.requestFA(FaDataTypeEnum.ALIASES)

Request FA Groups

client.requestFA(Constants.FaGroups);
client.requestFA(FADataType.GROUPS.ordinal());
client.requestFA(Constants.FaGroups)
m_pClient->requestFA(faDataType::GROUPS);
1 self.requestFA(FaDataTypeEnum.GROUPS)

Request FA Profiles

The resulting FA allocation configuration will be delivered via the IBApi.EWrapper.receiveFA. The event includes an XML string containing the requested information.

public class EWrapperImpl : EWrapper

{

...
public virtual void receiveFA(int faDataType, string faXmlData)

{

Console.WriteLine("Receing FA: "+faDataType+" - "+faXmlData);

}
public class EWrapperImpl implements EWrapper {

...
@Override

public void receiveFA(int faDataType, String xml) {

System.out.println("Receiving FA: " + faDataType + " - " + xml);

}
Public Class EWrapperImpl

Implements EWrapper

...
Public Sub receiveFA(faDataType As Integer, faXmlData As String) Implements IBApi.EWrapper.receiveFA

Console.WriteLine("Receing FA: " & faDataType & " - " & faXmlData)

End Sub
class TestCppClient : public EWrapper

{

...
void TestCppClient::receiveFA(faDataType pFaDataType, const std::string& cxml) {

std::cout << "Receiving FA: " << (int)pFaDataType << std::endl << cxml << std::endl;

}
1 class TestWrapper(wrapper.EWrapper):

...
1 def receiveFA(self, faData: FaDataType, cxml: str):

2 super().receiveFA(faData, cxml)

3 print("Receiving FA: ", faData)

4 open('log/fa.xml', 'w').write(cxml)

The IBApi.EClient.replaceFA function can be called to replace the previous FA configuration in TWS by passing in a FULL XML string that contains all allocation information.

Replace Account Groups Configuration

...
...
...
...
...

Note: The above command will replace any previous FA group configuration in TWS with one 'Group_Equal_Quantity' group allocation.

...
...
...
...
...

Note: The above command will add another 'Group_Pct_Change' group allocation to the previous FA configuration.

Replace Account Profiles Configuration

You can find the corresponding type number for profile allocation in the "Profile Methods Matching" table above.

...
...
...
...
...

Note: The above command will replace any previous FA profile configuration in TWS with one 'Percent_60_40' profile allocation

...
...
...
...
...

Note: The above command will add another 'Group_Pct_Change' group allocation to the previous FA configuration

Confirming replaceFA Configuration Updates

In order to confirm that your FA changes were saved, you may wait for the IBApi::EWrapper::replaceFAEnd callback shown below, which provides the corresponding reqId.

public class EWrapperImpl : EWrapper

{

...
public virtual void replaceFAEnd(int reqId, string text)

{

Console.WriteLine("Replace FA End. ReqId: " + reqId + ", Text: " + text + "\n");

}
public class EWrapperImpl implements EWrapper {

...
@Override

public void replaceFAEnd(int reqId, String text) {

System.out.println(EWrapperMsgGenerator.replaceFAEnd(reqId, text));

}
Public Class EWrapperImpl

Implements EWrapper

...
Public Sub replaceFAEnd(reqId As Integer, text As String) Implements IBApi.EWrapper.replaceFAEnd

Console.WriteLine("replaceFAEnd. ReqId: {0}, Text: {1}", reqId, text)

End Sub
class TestCppClient : public EWrapper

{

...
void TestCppClient::replaceFAEnd(int reqId, const std::string& text) {

printf("Replace FA End. Request: %d, Text:%s\n", reqId, text.c_str());

}
1 class TestWrapper(wrapper.EWrapper):

...
1 def replaceFAEnd(self, reqId: int, text: str):

2 super().replaceFAEnd(reqId, text)

3 print("ReplaceFAEnd.", "ReqId:", reqId, "Text:", text)

In addition, after saving changes, it is advised to verify the new FA setup via IBApi::EClient::requestFA. If it is called before changes are fully saved, you may receive an error. See Message Codes.

Unification of Groups and Profiles

With TWS/IBGW build 983+, the API settings will have a new flag/checkbox, "Use Account Groups with Allocation Methods" (enabled by default for new users). If not enabled, groups and profiles would behave the same as before. If it is checked, group and profile functionality will be merged, and API clients will see the following changes:

Both IBApi::EClient::replaceFA and IBApi::EClient::requestFA will send and receive unified groups/profiles list if the argument is Group.
- Both IBApi::EClient::replaceFA and IBApi::EClient::requestFA will receive error if the argument is Profile.
IBApi::EClient::placeOrder will support specifying profile name as the IBApi.Order.FaGroup name; IBApi::Order::FaMethod may be omitted.
- If specifying actual group name and the faMethod is blank/omitted the default method of that group will be used. Otherwise, the method in the request will be set on the order.
IBApi::EWrapper::openOrder callback will report Profile in place of Group if order was for profile.
The following calls from API, which take Group name, will also accept Profile name in its place:

Model Portfolios and the API

Placing Orders to a FA account