Quickstarts

This document shows you a number of typical use cases in a simplified form. For a full reference see the Reference guide. I use generic ticker names representing the underlying assets, coincidences with real tickers are unintentional.

Simple rebalance calculations

currencies usd account Broker default fee 0.05% STOK 700 price 30usd buy,sell BOND 1000 price 22usd buy,sell GOLD 500 price 110usd buy,sell USD allocation STOK ~ 33%(total) BOND ~ 33%(total) GOLD ~ 33%(total) USD ~ 0%(total)
So far, it's nothing you cannot easily do by hand, except that it respects the assets being traded in whole units.

Rebalance with deposit/withdrawal

currencies usd account Broker default fee 0.05% STOK 700 price 30usd buy,sell BOND 1000 price 22usd buy,sell GOLD 500 price 110usd buy,sell USD -5000 allocation STOK ~ 33%(total) BOND ~ 33%(total) GOLD ~ 33%(total) USD ~ 0%(total) min 0usd

For rebalance with deposit/withdrawal you may specify the amount of money to be deposited/withdrawn, with negative values for withdrawals.

When negative amounts are specified, consider adding additional restriction that the amounts after rebalance must not be negative (min 0usd). By default, the rebalancing algorithm does not increase negative positions (and thus doesn't make any positive position negative), but already negative positions might stay thus after rebalance.

Rebalance with restricted accounts

currencies usd account Broker default fee 0.05% STOK 700 price 30usd buy,sell BOND 1000 price 22usd buy,sell USD 0 transfers out usd -> bank account Pension default fee 0.2% STOK 200 buy,sell BOND 300 buy,sell USD transfers in usd limit 5000usd account Bank USD -2000 transfers out usd -> broker,pension allocation STOK ~ 50%(total) BOND ~ 50%(total) USD ~ 0%(total) usd@bank min 0usd pension min current+4950usd

Making a withdrawal (2000usd from Bank) along with mandatory contribution to the pension account (pension min current+4950usd), from which withdrawals are forbidden (no out transfers specified) and only USD deposits are possible no more than 5000usd in total (transfers in usd limit 5000usd).

The default prices, tags and lot sizes for assets are defined upon the first occurrence, or alternatively in the optional assets clause.

Note a quirk here: pension min current+4950usd. If this is set to min current+5000usd then, combined with incoming transfer limit of also 5000usd, no transactions in Pension account will be possible because of trading fees depleting the account below the restriction value. But so far, there is no other way to specify mandatory contributions other than current+{amount}.

Exposure-based rebalancing

currencies usd tags group geo: us, eu, em account Broker default fee 0.05% STOK 1500 tags us=0.65, eu=0.2, em=0.15 price 30usd buy,sell EUST 0 tags eu price 22usd buy,sell EMST 0 tags em price 110usd buy,sell USD allocation us ~ 40%(group) eu ~ 30%(group) em ~ 30%(group) usd ~ 0%(total)
Suppose you primarily invest in a total world fund, but want to tilt your allocation away from US assets. You use tags to define asset exposures to different geographies and define your allocation in terms of these exposures instead of concrete assets.

Multidimensional rebalance

currencies usd tags group class: stocks, bonds, cash, gold group geo: us, eu, em account Broker default fee 0.05% STOK 1200 tags us=0.65,eu=0.2,em=0.15,stocks=0.95,cash=0.05 price 30usd buy,sell EUST 50 tags eu,stocks=0.95,cash=0.05 price 22usd buy,sell EMST 50 tags em,stocks=0.95,cash=0.05 price 110usd buy,sell GOLD 100 tags gold price 70usd buy,sell BOND 200 tags us=0.4,eu=0.4,em=0.2,bonds price 28usd buy,sell USD tags cash allocation stocks ~ 50%(group) bonds ~ 30%(group) cash ~ 10%(group) gold ~ 10%(group) us ~ 40%(group) eu ~ 30%(group) em ~ 30%(group)

You can specify different exposure dimensions, for example asset classes and geographies.

Finding the cheapest currency conversion path

currencies usd, eur=1.1 account Bank USD 10000 price *eur EUR 0 price *usd buy,sell spread 3% transfers out usd -> broker,wise fee 5usd out eur -> wise fee 15usd account Broker default fee 0.05% spread 0.2% USD buy,sell 1000 via usd_eur EUR buy,sell 1000 via eur_usd transfers out eur -> bank fee 15usd account Wise USD EUR buy,sell fee 0.45% transfers in usd fee 4.14usd allocation eur@wise ~ 100%(total)

Note price *usd clauses: by default, actual asset prices are not defined, thus no trading is possible. '*' here means «calculate the actual price from available information», in this case — from conversion rates specified in the currencies clause.

Limiting leverage

currencies usd tags collateral, debt group class: stock, bond account Broker default fee 0.05% STOK 200 price 30usd tags collateral=0.5,stock buy,sell BOND 200 price 22usd tags collateral,bond buy,sell USD -3000 tags debt=-1 allocation stock ~ 50%(group) bond ~ 50%(group) debt@broker max 50%(collateral@broker) ~ 50%(collateral@broker) usd@broker min -5000usd

If you decided to leverage your portfolio using margin credit. The setup is a bit contrived so I think about implementing this case in the system core. But as of now it is like this:

  • collateral tag sets how much of an asset value your broker takes as the collateral.
  • debt tag indicates borrowed assets, note the "-1" coefficient.
  • debt@broker max 50%(collateral@broker) limits debt amount to 50% of collateral value.
  • debt@broker ~ 50%(collateral@broker) instructs the algorithm to make debt as close as possible to the 50% of the collateral.
  • usd@broker min -5000usd allows increasing debt up to 5000usd.