Skip to main content

New Take Settlement System

Version: 2.0 Date: April 2026 Replaces: take_settlement_deprecated.md

Overview​

Fluid settlement with no time periods. Upline settles downline anytime. Live takes. Simple history.

Take Formula​

Live Take (Read-Time)​

Player Live Take = balancePoints + exposure - creditLimit
Agent Live Take  = AC(self) + Σ (AC + exposure)(recursive downline) - creditLimit

Where:

  • exposure = SUM(stake) for open back bets + SUM(stake × (odds-1)) for open lay bets
  • Computed at read-time from batchGetExposurePnl
  • NOT stored — avoids write amplification on every bet placement

Stored Take (Write-Time, unchanged triggers)​

Player Stored Take = balancePoints - creditLimit
Agent Stored Take  = AC(self) + Σ AC(recursive downline) - creditLimit

Updated only on: market settlement, transfer & settle.

Why Exposure is Excluded from Stored Take​

When a bet is placed, balancePoints drops by stake but the bet hasn't settled. Without exposure adjustment, Take drops immediately as if the user lost. Adding exposure at read-time cancels this out:

Initial:     BP=100, CL=100, E=0   → Live Take = 100+0-100   = 0
Bet placed:  BP=90,  CL=100, E=10  → Live Take = 90+10-100   = 0   (correct)
Bet loses:   BP=90,  CL=100, E=0   → Live Take = 90+0-100    = -10 (correct)
Bet wins:    BP=110, CL=100, E=0   → Live Take = 110+0-100   = +10 (correct)

Sign Convention​

  • Entity perspective (stored in takeBalance.currentTake): positive = entity profited, negative = entity owes
  • Viewer/upline perspective (returned by API): negated — positive = "entity owes me" (collect), negative = "I owe entity" (pay)

Transfer & Settle​

Who Can Settle​

Only upline can initiate settlement. Available anytime (no grace period).

Direction-Dependent Balance Adjustment​

When entity owes upline (liveTake < 0 entity perspective):

entity.creditLimit -= amount
upline: no change

This shrinks the credit line. Entity's available balance stays the same (already zero or near-zero from losses), but their credit capacity is reduced. They cannot bet again until the agent explicitly re-allocates credit via "Edit Credit Limit" — which deducts from the agent's own balance. Upline state is unchanged — the CL reduction already fixes the take chain.

When upline owes entity (liveTake > 0 entity perspective):

entity.balancePoints -= amount
upline.balancePoints += amount

Entity received cash off-platform — on-platform balance decreases. Upline paid cash — balance increases to maintain correct take toward their own upline in the hierarchy.

Why CL Decrease Instead of BP Increase (Anti-Recycling)​

Problem with old approach (BP += amount when entity owes):

Master Agent → Agent → Player

Cycle 1: Player loses 1000, BP drops to 0
Agent settles: BP += 1000 → Player back to BP=1000, CL=1000
Player can lose another 1000 immediately.
Agent never settles with Master Agent.
Infinite loop — Master Agent never receives settlement.

New approach (CL -= amount when entity owes):

Cycle 1: Player loses 1000, BP drops to 0
Agent settles: CL -= 1000 → Player at BP=0, CL=0
Player CANNOT bet — zero credit limit.
Agent must "Edit Credit Limit" to give player more credit.
Edit Credit Limit deducts from Agent's own BP.
Agent's BP runs out if they don't settle with Master Agent.
The chain is enforced.

Settlement Transaction (Atomic)​

1. Read liveTake for downline entity (stored take + exposure)
2. Validate: amount > 0, amount <= |liveTake|
3. Determine direction from liveTake sign (entity perspective)
4. Atomic transaction:
   a. CREATE TransferSettlement record (amount, takeBefore, takeAfter, notes, settledByUserId)
   b. If entity owes:  UPDATE user SET creditLimit = creditLimit - amount
      If upline owes:  UPDATE user SET balancePoints = balancePoints - amount
   c. UPDATE takeBalance SET currentTake = recalculated live take
5. Invalidate balance cache

What Does NOT Change​

  • Upline's balancePoints — settlement is off-platform cash reconciliation
  • Exposure — not affected by settlement

Settlement History​

Simple record of all settlements performed by the agent on their downline.

Fields​

  • Entity name and type (Agent/Player)
  • Date and time
  • Expected payment (take at time of settlement)
  • Received/paid amount
  • Settlement notes
  • Direction (received from downline / paid to downline)

Filters​

  • Entity type: All, Agent, Player
  • Search by name
  • Date range selector
  • Pagination

UI Design​

Main Settlement View​

  • Summary cards: "Upline — TO PAY [amount]" + "Downline — TO RECEIVE [amount]"
  • Two tabs: "Downline [count]" / "Upline [count]"
  • Downline tab: Entity list with live take, AGENT/PLAYER badge, settle icon
  • Upline tab: Agent's own take towards their upline
  • Header: "Settlement History" button

Confirm Settlement (Bottom Sheet)​

  • Entity name + status badge
  • "To Receive" or "To Pay" with amount
  • Settlement Amount input (default 0, max = |take|)
  • Note (Optional)
  • "Swipe to Confirm [amount]"
  • Success toast

Settlement History​

  • Filter tabs: All, Agent, Player (with counts)
  • Search by name
  • Date range selector
  • Each record: name, type, date, expected payment, received amount, notes

What Was Removed​

Removed ConceptReason
Settlement periods (open/grace/finalized)Over-engineered — agents settle whenever they want
Frozen take snapshotsNo periods = no freeze point needed
Carryover systemNo periods = nothing to carry over
Settlement statuses (Pending/Settled/CarriedOver/Defaulted)No frozen snapshots = no status tracking
Grace period gatingSettlement available anytime
Agent settlement jobNo automated period transitions
Settlement configuration (duration, grace, poll interval)No periods to configure