Groups and Profiles | Interactive Brokers

Introduction

Financial Advisors are able to manage their allocation groups from the TWS API.

Modifications made through the API will affect orders placed through TWS, the TWS API, Client Portal, and the Web API.

Request FA Groups and Profiles

EClient.requestFA(faDataType)

Requests the FA configuration as set in TWS for the given FA Data Type.

faDataType

integer

The configuration to retrieve. See FA Data Types table below.

Python

Java

C++

C#

VB.NET

self.requestFA(1)

requestFA FA Data Types

Type Code	Type Name	Description
1	Groups	Offer traders a way to create a group of accounts and apply a single allocation method to all accounts in the group.
3	Account Aliases	Let you easily identify the accounts by meaningful names rather than account numbers.

Receive FA Groups and Profiles

EWrapper.receiveFA(faDataType, faXmlData)

Receives the Financial Advisor’s configuration available in the TWS.

faDataType

integer

The faDataType value specified in the requestFA call.

faXmlData

string

The xml-formatted configuration.

Python

Java

C++

C#

VB.NET

def receiveFA(self, faData: FaDataType, cxml: str):
	print("Receiving FA: ", faData)
	open('log/fa.xml', 'w').write(cxml)

Replace FA Allocations

EClient.replaceFA(reqId, faDataType, xml)

Replaces the FA configuration for the given FA Group or Profile.

To confirm that FA changes were saved, wait for the EWrapper.replaceFAEnd callback which provides the corresponding reqId. After saving, it is advised to verify the new FA setup via EClient.requestFA. If called before changes are fully saved, you may receive an error such as error 10230.

reqId

integer

Request identifier used to track data.

faDataType

integer

The configuration structure to change. Set to 1 (Groups). Passing other values may trigger error 585.

xml

string

XML configuration for the allocation group. See the Allocation Method XML Format section below for details.

Python

Java

C++

C#

VB.NET

self.replaceFa(reqId, 1, xml)

replaceFA FA Data Types

Type Code	Type Name	Description
1	Groups	Offer traders a way to create a group of accounts and apply a single allocation method to all accounts in the group.
2	Account Aliases	Let you easily identify the accounts by meaningful names rather than account numbers.

EWrapper.replaceFAEnd

EWrapper.replaceFAEnd(reqId, text)

Marks the end of the replaceFA reception.

reqId

integer

Request identifier used to track data.

text

string

The message text.

Python

Java

C++

C#

VB.NET

def replaceFAEnd(self, reqId: int, text: str):
    super().replaceFAEnd(reqId, text)
    print("ReplaceFAEnd.", "ReqId:", reqId, "Text:", text)

Allocation Methods and Groups

A number of methods for account allocations are available with Financial Advisor and IBroker account structures to specify how trades should be distributed across multiple accounts.

Allocation Groups can be created or modified in the Trader Workstation directly as described in TWS: Allocations and Transfers.

Alternatively, allocation groups can be created or modified through the EClient.replaceFA method in the API.

Interactive Brokers supports two forms of allocation methods: allocation methods with calculations completed by Interactive Brokers, and a set of allocation methods calculated by the user and then specified.

IB-computed allocation methods

Available Equity
Equal Quantity
Net Liquidation Value

User-specified allocation methods (formerly known as Allocation Profiles)

Cash Quantity
Percentages
Ratios
Shares

Allocation methods for financial advisor allocation groups are defined using an XML format. The examples below show how each supported allocation method is structured.

Available Equity

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.

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
    <name>MyTestProfile2</name>
    <defaultMethod>AvailableEquity</defaultMethod>
    <ListOfAccts varName="list">
      <Account>
        <acct>DU6202167</acct>
      </Account>
      <Account>
        <acct>DU6202168</acct>
      </Account>
    </ListOfAccts>
  </Group>
</ListOfGroups>

Monetary Amount

The Monetary Amount method calculates the number of units to be allocated based on the monetary value assigned to each account.

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>MonetaryAmount</defaultMethod>
  
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>1000.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>2000.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>

Equal Quantity

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.

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
    <name>MyTestProfile2</name>
    <defaultMethod>Equal</defaultMethod>
    <ListOfAccts varName="list">
      <Account>
        <acct>DU6202167</acct>
      </Account>
      <Account>
        <acct>DU6202168</acct>
      </Account>
    </ListOfAccts>
  </Group>
</ListOfGroups>

Net Liquidation Value

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.

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
    <name>MyTestProfile2</name>
    <defaultMethod>NetLiq</defaultMethod>
    <ListOfAccts varName="list">
      <Account>
        <acct>DU6202167</acct>
      </Account>
      <Account>
        <acct>DU6202168</acct>
      </Account>
    </ListOfAccts>
  </Group>
</ListOfGroups>

Percentages

This method will split the total number of shares in the order between listed accounts based on the percentages you indicate.

Example: Assume an order for 300 shares of stock ABC is transmitted. Account A is set to have 60.0 percentage while Account B is set to have 40.0 percentage. Account A should receive 180 shares and Account B should receive 120 shares.

Note: 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 example, to fully close out a position, specify a percentage of -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

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>Percent</defaultMethod>
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>60.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>40.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>

Ratios

This method calculates the allocation of shares based on the ratios you enter.

Example: Assume an order for 300 shares of stock ABC is transmitted. A ratio of 1.0 and 2.0 is set to Account A and Account B. Account A should receive 100 shares and Account B should receive 200 shares.

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>Ratio</defaultMethod>
  
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>1.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>2.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>

Contracts or 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.

Example: Assume an order for 300 shares of stock ABC is transmitted. Account A is set to receive 100.0 shares while Account B is set to receive 200.0 shares. Account A should receive 100 shares and Account B should receive 200 shares.

<?xml version="1.0" encoding="UTF-8"?>
<ListOfGroups>
  <Group>
  <name>MyTestProfile2</name>
  <defaultMethod>ContractsOrShares</defaultMethod>
  
  <ListOfAccts varName="list">
  <Account>
    <acct>DU6202167</acct>
    <amount>100.0</amount>
  </Account>
  <Account>
    <acct>DU6202168</acct>
    <amount>200.0</amount>
  </Account>
  </ListOfAccts>
  </Group>
</ListOfGroups>