accrue_interest!

Author: rbeeli

src/interest.jl

@@ -4,11 +4,40 @@ using Dates
     accrue_interest!(acc, dt; year_basis=365.0)
 
 Accrues interest on cash balances between the last accrual timestamp and `dt`.
-Positive balances earn broker lend rates, negative balances pay broker borrow
-rates. Rates are evaluated at the accrual window start (`last_interest_dt`).
+Negative balances pay broker borrow rates.
+
+For positive balances, short-sale proceeds on principal-exchange spot shorts are
+handled via `broker_short_proceeds_rates`:
+- excluded fraction of locked short proceeds is removed from regular lend base,
+- optional rebate rate is applied to locked short proceeds.
+
+Rates are evaluated at the accrual window start (`last_interest_dt`).
 Interest is applied to both balances and equities and recorded as
-`CashflowKind.LendInterest` or `CashflowKind.BorrowInterest`.
+`CashflowKind.LendInterest` or `CashflowKind.BorrowInterest` based on net sign.
 """
+@inline function _fill_short_proceeds_by_settle_cash!(
+    acc::Account,
+    proceeds::Vector{Price},
+)
+    fill!(proceeds, 0.0)
+
+    @inbounds for pos in acc.positions
+        qty = pos.quantity
+        qty < 0.0 || continue
+
+        inst = pos.inst
+        inst.contract_kind == ContractKind.Spot || continue
+        inst.settlement == SettlementStyle.PrincipalExchange || continue
+
+        settled_proceeds = -qty * pos.avg_entry_price_settle * inst.multiplier
+        settled_proceeds > 0.0 || continue
+
+        proceeds[inst.settle_cash_index] += settled_proceeds
+    end
+
+    nothing
+end
+
 function accrue_interest!(
     acc::Account{TTime,TBroker},
     dt::TTime;
@@ -29,12 +58,30 @@ function accrue_interest!(
     cfs = acc.cashflows
     rate_dt = acc.last_interest_dt
     ledger = acc.ledger
+    short_proceeds_by_cash = ledger.short_proceeds_by_cash_buffer
+    short_proceeds_ready = false
     @inbounds for i in eachindex(ledger.balances)
         bal = ledger.balances[i]
-        cash_symbol = ledger.cash[i].symbol
-        borrow_rate, lend_rate = broker_interest_rates(acc.broker, cash_symbol, rate_dt, bal)
-        rate = bal >= 0 ? lend_rate : borrow_rate
-        interest = bal * rate * yearfrac
+        cash = ledger.cash[i]
+        interest = if bal < 0.0
+            borrow_rate, _ = broker_interest_rates(acc.broker, cash, rate_dt, bal)
+            bal * borrow_rate * yearfrac
+        else
+            exclude_fraction, rebate_rate = broker_short_proceeds_rates(acc.broker, cash, rate_dt)
+
+            locked = 0.0
+            if exclude_fraction != 0.0 || rebate_rate != 0.0
+                if !short_proceeds_ready
+                    _fill_short_proceeds_by_settle_cash!(acc, short_proceeds_by_cash)
+                    short_proceeds_ready = true
+                end
+                locked = min(bal, short_proceeds_by_cash[i])
+            end
+
+            lend_base = max(0.0, bal - exclude_fraction * locked)
+            _, lend_rate = broker_interest_rates(acc.broker, cash, rate_dt, lend_base)
+            lend_base * lend_rate * yearfrac + locked * rebate_rate * yearfrac
+        end
         interest == 0.0 && continue
         ledger.balances[i] += interest
         ledger.equities[i] += interest

test/binance_broker.jl

@@ -5,6 +5,8 @@ using TestItemRunner
     using Test, Fastback, Dates
 
     @test BinanceBroker() isa BinanceBroker{DateTime}
+    @test BinanceBroker().short_proceeds_exclusion == 1.0
+    @test BinanceBroker().short_proceeds_rebate == 0.0
 
     borrow_by_cash = Dict(:USD=>StepSchedule([(DateTime(2025, 1, 1), 0.10)]))
     broker = BinanceBroker(; borrow_by_cash=borrow_by_cash)
@@ -31,3 +33,15 @@ end
 
     @test_throws MethodError BinanceBroker(; borrow_by_cash=borrow_by_cash)
 end
+
+@testitem "BinanceBroker short proceeds defaults to full exclusion without rebate" begin
+    using Test, Fastback, Dates
+
+    broker = BinanceBroker()
+    dt = DateTime(2025, 1, 1)
+    usd = Cash(1, :USD, 2)
+    exclude_frac, rebate_rate = broker_short_proceeds_rates(broker, usd, dt)
+
+    @test exclude_frac == 1.0
+    @test rebate_rate == 0.0
+end

test/events.jl

@@ -45,9 +45,9 @@ using TestItemRunner
     cf_count = length(acc.cashflows)
 
     yearfrac = 1 / 365
-    rate = bal_before >= 0 ? 0.05 : 0.10
-    expected_interest = bal_before * rate * yearfrac
     pos = get_position(acc, inst)
+    short_proceeds = abs(pos.quantity) * pos.avg_entry_price_settle * inst.multiplier
+    expected_interest = (bal_before - short_proceeds) * 0.05 * yearfrac
     expected_borrow = abs(pos.quantity) * pos.mark_price * inst.multiplier * 0.20 * yearfrac
     @test bal_after_first - bal_before ≈ (expected_interest - expected_borrow) atol=1e-8
 

test/fx_conversion_helpers.jl

@@ -165,8 +165,9 @@ end
     advance_time!(acc, dt1; accrue_interest=true, accrue_borrow_fees=true)
 
     yearfrac = Dates.value(Dates.Millisecond(dt1 - dt0)) / (1000 * 60 * 60 * 24 * 365.0)
-    expected_interest = bal_before * 0.02 * yearfrac
-    expected_fee_settle = abs(qty) * price * inst.multiplier * inst.short_borrow_rate * yearfrac * usd_to_chf
+    short_proceeds_settle = abs(qty) * price * inst.multiplier * usd_to_chf
+    expected_interest = (bal_before - short_proceeds_settle) * 0.02 * yearfrac
+    expected_fee_settle = short_proceeds_settle * inst.short_borrow_rate * yearfrac
     expected_net = expected_interest - expected_fee_settle
 
     @test acc.ledger.balances[chf_idx] ≈ bal_before + expected_net atol=1e-8

test/ibkr_pro_fixed_broker.jl

@@ -11,6 +11,8 @@ using TestItemRunner
     @test broker isa IBKRProFixedBroker{DateTime}
     @test broker.benchmark_by_cash == benchmark_by_cash
     @test broker.benchmark_by_cash isa Dict{Symbol,StepSchedule{DateTime,Price}}
+    @test broker.short_proceeds_exclusion == 1.0
+    @test broker.short_proceeds_rebate_spread == broker.lend_spread
 
     benchmark_by_cash_date = Dict(:USD=>StepSchedule([(Date(2025, 1, 1), 0.03)]))
     broker_date = IBKRProFixedBroker(; time_type=Date, benchmark_by_cash=benchmark_by_cash_date)
@@ -19,3 +21,25 @@ using TestItemRunner
 
     @test_throws MethodError IBKRProFixedBroker(; benchmark_by_cash=benchmark_by_cash_date)
 end
+
+@testitem "IBKRProFixedBroker short proceeds uses benchmark rebate spread" begin
+    using Test, Fastback, Dates
+
+    benchmark_by_cash = Dict(:USD=>StepSchedule([(DateTime(2025, 1, 1), 0.03)]))
+    broker = IBKRProFixedBroker(;
+        benchmark_by_cash=benchmark_by_cash,
+        short_proceeds_exclusion=1.0,
+        short_proceeds_rebate_spread=0.01,
+    )
+    dt = DateTime(2025, 1, 10)
+    usd = Cash(1, :USD, 2)
+    eur = Cash(2, :EUR, 2)
+    exclude_frac, rebate_rate = broker_short_proceeds_rates(broker, usd, dt)
+
+    @test exclude_frac == 1.0
+    @test rebate_rate ≈ 0.02 atol=1e-12
+
+    ex_unknown, rebate_unknown = broker_short_proceeds_rates(broker, eur, dt)
+    @test ex_unknown == 1.0
+    @test rebate_unknown == 0.0
+end

test/spot_margin.jl

@@ -147,7 +147,7 @@ end
     @test cf.amount ≈ -expected_fee atol=1e-6
 end
 
-@testitem "Margin spot short accrues borrow fee and interest" begin
+@testitem "Margin spot short accrues borrow fee and lend on free cash only" begin
     using Test, Fastback, Dates
 
     base_currency=CashSpec(:USD)
@@ -195,7 +195,8 @@ end
     advance_time!(acc, dt1; accrue_interest=true, accrue_borrow_fees=true)
 
     yearfrac = Dates.value(Dates.Millisecond(dt1 - dt0)) / (1000 * 60 * 60 * 24 * 365.0)
-    expected_interest = bal_before * 0.02 * yearfrac
+    short_proceeds = abs(qty) * price * inst.multiplier
+    expected_interest = (bal_before - short_proceeds) * 0.02 * yearfrac
     expected_fee = abs(qty) * price * inst.multiplier * inst.short_borrow_rate * yearfrac
     expected_delta = expected_interest - expected_fee
 
@@ -216,6 +217,124 @@ end
     @test fee_cf.amount ≈ -expected_fee atol=1e-8
 end
 
+@testitem "IBKR short excludes proceeds from lend base and applies rebate" begin
+    using Test, Fastback, Dates
+
+    benchmark_by_cash = Dict(:USD=>StepSchedule([(DateTime(2026, 1, 1), 0.03)]))
+    base_currency=CashSpec(:USD)
+    acc = Account(
+        ;
+        broker=IBKRProFixedBroker(
+            benchmark_by_cash=benchmark_by_cash,
+            borrow_spread=0.015,
+            lend_spread=0.005,
+            credit_no_interest_balance=0.0,
+            short_proceeds_exclusion=1.0,
+            short_proceeds_rebate_spread=0.01,
+        ),
+        funding=AccountFunding.Margined,
+        base_currency=base_currency,
+    )
+    deposit!(acc, :USD, 10_100.0)
+
+    inst = register_instrument!(acc, Instrument(
+        Symbol("SPOTIBKR/USD"),
+        :SPOTIBKR,
+        :USD;
+        contract_kind=ContractKind.Spot,
+        settlement=SettlementStyle.PrincipalExchange,
+        margin_requirement=MarginRequirement.PercentNotional,
+        margin_init_long=0.5,
+        margin_maint_long=0.25,
+        margin_init_short=0.5,
+        margin_maint_short=0.25,
+    ))
+
+    dt0 = DateTime(2026, 1, 1)
+    price = 100.0
+    qty = -200.0
+    trade = fill_order!(acc, Order(oid!(acc), inst, dt0, price, qty); dt=dt0, fill_price=price, bid=price, ask=price, last=price)
+    @test trade isa Trade
+
+    usd = cash_asset(acc, :USD)
+    bal_before = cash_balance(acc, usd)
+    eq_before = equity(acc, usd)
+    @test bal_before ≈ 30_099.0 atol=1e-8
+    @test eq_before ≈ 10_099.0 atol=1e-8
+
+    accrue_interest!(acc, dt0)
+    @test isempty(acc.cashflows)
+
+    dt1 = dt0 + Day(1)
+    accrue_interest!(acc, dt1)
+
+    yearfrac = Dates.value(Dates.Millisecond(dt1 - dt0)) / (1000 * 60 * 60 * 24 * 365.0)
+    short_proceeds = abs(qty) * price * inst.multiplier
+    free_cash = bal_before - short_proceeds
+    expected_lend = free_cash * (0.03 - 0.005) * yearfrac
+    expected_rebate = short_proceeds * (0.03 - 0.01) * yearfrac
+    expected_interest = expected_lend + expected_rebate
+
+    @test cash_balance(acc, usd) ≈ bal_before + expected_interest atol=1e-8
+    @test equity(acc, usd) ≈ eq_before + expected_interest atol=1e-8
+    @test length(acc.cashflows) == 1
+    cf = only(acc.cashflows)
+    @test cf.kind == CashflowKind.LendInterest
+    @test cf.cash_index == usd.index
+    @test cf.amount ≈ expected_interest atol=1e-8
+end
+
+@testitem "Flat fee broker can include short proceeds in lend base" begin
+    using Test, Fastback, Dates
+
+    base_currency=CashSpec(:USD)
+    acc = Account(
+        ;
+        broker=FlatFeeBroker(
+            lend_by_cash=Dict(:USD=>0.02),
+            short_proceeds_exclusion_by_cash=Dict(:USD=>0.0),
+        ),
+        funding=AccountFunding.Margined,
+        base_currency=base_currency,
+    )
+    deposit!(acc, :USD, 10_000.0)
+
+    inst = register_instrument!(acc, Instrument(
+        Symbol("SPOTINCL/USD"),
+        :SPOTINCL,
+        :USD;
+        contract_kind=ContractKind.Spot,
+        settlement=SettlementStyle.PrincipalExchange,
+        margin_requirement=MarginRequirement.PercentNotional,
+        margin_init_long=0.5,
+        margin_maint_long=0.25,
+        margin_init_short=0.5,
+        margin_maint_short=0.25,
+    ))
+
+    dt0 = DateTime(2026, 1, 1)
+    price = 100.0
+    qty = -200.0
+    trade = fill_order!(acc, Order(oid!(acc), inst, dt0, price, qty); dt=dt0, fill_price=price, bid=price, ask=price, last=price)
+    @test trade isa Trade
+
+    usd = cash_asset(acc, :USD)
+    bal_before = cash_balance(acc, usd)
+    @test bal_before ≈ 30_000.0 atol=1e-8
+
+    accrue_interest!(acc, dt0)
+    dt1 = dt0 + Day(1)
+    accrue_interest!(acc, dt1)
+
+    yearfrac = Dates.value(Dates.Millisecond(dt1 - dt0)) / (1000 * 60 * 60 * 24 * 365.0)
+    expected_interest = bal_before * 0.02 * yearfrac
+
+    @test cash_balance(acc, usd) ≈ bal_before + expected_interest atol=1e-8
+    @test equity(acc, usd) ≈ 10_000.0 + expected_interest atol=1e-8
+    @test length(acc.cashflows) == 1
+    @test only(acc.cashflows).amount ≈ expected_interest atol=1e-8
+end
+
 @testitem "Fully funded account applies margin checks to spot" begin
     using Test, Fastback, Dates