Hannibal Agent Accounting System

Design Document

Version 1.0 | January 2026

✅ IMPLEMENTATION STATUS: COMPLETE

This system has been fully implemented. Key implementation files:

• backend/src/accounting/ - Settlement periods, ledger, reports, agent settlement
• backend/src/routes/agents.ts - Agent management API
• backend/src/routes/agent.ts - Agent dashboard API
• backend/src/routes/allocations.ts - Point allocation API
• backend/src/routes/referrals.ts - Referral system API
• frontend/src/app/agent/ - Agent dashboard UI
• frontend/src/app/admin/ - Admin panel for agent management

---

Executive Summary

This document describes the agent-based accounting system for Hannibal. The platform operates on a hierarchical distribution model where users cannot join directly—they must be referred by an agent, and agents must be approved by the platform.

Points flow downward through the hierarchy: Platform allocates points to agents, agents allocate points to punters. Weekly settlement reconciles net positions between agents and the platform:

• Punters WIN → Platform pays Agent (platform received exchange winnings, passes to agent)
• Punters LOSE → Agent pays Platform (platform lost to exchange or netted, agent reimburses)

Agent Revenue Model: Agents make money through two streams:

1. Point Markup (Off-Platform): Configurable markup (0% to X%) when selling points to punters. Agent buys at face value, sells at markup.

2. Profit Sharing (On-Platform): Commission Share: 0% to 100% of commission collected from agent's punters

All settings are configurable per agent via sliders in the admin panel.

This model is standard across Indian betting skins (Lotus, Diamond, Sky Exchange) and provides clear accountability, credit control, and scalable distribution.

---

Table of Contents

1. The Distribution Model
2. Hierarchy and Roles
3. Point Allocation System
4. Risk and Profit Distribution
5. The Settlement Cycle
6. Referral and Onboarding
7. Admin Panels
8. Configuration Options
9. Edge Cases and Error Handling
10. Glossary

---

1. The Distribution Model

1.1 Why This Model Exists

Traditional betting platforms operate as direct-to-consumer (B2C) businesses. Users sign up, deposit money, and bet. The platform bears all risk and handles all customer relationships.

The agent model is different. It separates:

• Infrastructure (the platform that handles betting execution, odds, settlement)
• Distribution (agents who acquire and manage punters)

This separation provides several advantages:

For the Platform:

• Reduced customer acquisition cost—agents bring their own punters
• Reduced customer support burden—agents handle their punters
• Distributed risk—agents absorb their downline's volatility
• Simplified compliance—agents handle KYC/AML for their punters

For Agents:

• Access to professional betting infrastructure without building it
• Ability to earn through markup on points sold to punters
• Tools to manage their punter network
• Credit-based operation without handling actual money on-platform

For Punters:

• Access to competitive odds and markets
• Credit-based betting (no direct deposits required)
• Relationship with a local agent for support and settlement

1.2 How Points Replace Money

The platform operates on a points system rather than direct currency:

• Points are the internal unit of account
• 1 point = X currency (configurable, e.g., 1 INR, 1 USD, 1.02 USD)
• Points are purchased and redeemed off-platform
• The platform only tracks point balances—no payment processing

This structure provides regulatory benefits in many jurisdictions where "skill gaming with points" faces different regulation than "gambling with money."

The actual money movement happens outside the platform:

• Agent pays platform (via bank transfer, crypto, etc.) to receive points at face value
• Punter pays agent (cash, UPI, etc.) to receive points from the agent at a markup
• Settlement reconciles the net P&L between agent and platform

1.3 How Agents Make Money

Agents have two revenue streams:

Revenue Stream 1: Point Markup (Off-Platform)

Agents can mark up the price of points when selling to punters:

• Platform sells to agent at face value: 1 point = ₹1
• Agent sells to punter at markup: 1 point = ₹1.05 (5% markup)
• Markup percentage is configurable per agent (0% to X%)

This markup is the agent's off-platform revenue, collected directly from punters.

Revenue Stream 2: Profit Sharing (On-Platform)

Agents receive a share of the commission collected from their punters. This is configurable via sliders:

Profit Component	Calculation	Agent Share Setting
Commission	Sum of commission on winning bets	0% to 100% (slider)

Profit Share Calculation:

Agent's Profit Share = Commission × Commission Share %

Examples:

Agent A: Commission Share = 20%
├── Commission collected: ₹15,000
├── Profit share: ₹15,000 × 20% = ₹3,000

Agent B: Commission Share = 25%
├── Commission collected: ₹15,000
├── Profit share: ₹15,000 × 25% = ₹3,750

This profit share is netted into the weekly settlement (see Section 5).

---

2. Hierarchy and Roles

2.1 The Three-Tier Structure (Version 1)

For Version 1, the hierarchy is simple:

Platform (Hannibal)
    └── Agent
        └── Punter

Platform: The system owner. Has unlimited point-creation ability. Manages agents. Sees all accounting.

Agent: A user with agent privileges. Receives points from the platform. Distributes points to punters. Bears the profit/loss risk from their punters. Settles weekly with the platform.

Punter: An end user who bets. Receives points from their agent. Places bets. Settles with their agent (off-platform).

2.2 Future Hierarchy Support (Version 2+)

The system is designed to support deeper hierarchies in the future:

Platform (Hannibal)
    └── Super Master
        └── Master
            └── Agent
                └── Punter

Each intermediate level would:

• Receive points from their parent
• Allocate points to their children
• Bear a percentage of the risk (configurable share percentage)
• Settle with their parent on the defined cycle

For Version 1, we implement the simpler three-tier model but build the data structures to support recursive hierarchy expansion.

2.3 Role Characteristics

Attribute	Platform	Agent	Punter
Can create points	Yes	No	No
Can allocate points	Yes (to agents)	Yes (to punters)	No
Can place bets	No	Yes (with own unallocated points)	Yes
Bears risk from	Agents	Punters	Own bets
Settles with	N/A	Platform	Agent (off-platform)
Has admin panel	Yes	Yes (limited)	No

2.4 Agents Can Also Bet

Agents have a pool of unallocated points. They can use these points to place bets themselves, just like any punter. When an agent bets:

• The stake comes from their unallocated point balance
• Wins are credited to their unallocated balance
• Losses are deducted from their unallocated balance
• Commission is charged on winnings (same as punters)

Agent's own betting is separate from their punters' activity. In settlement:

• Agent's own P&L is tracked separately
• Agent's punters' P&L is tracked separately
• Both are visible in the agent's admin panel

This allows agents to participate in the platform as both distributors AND bettors.

---

3. Point Allocation System

3.1 The Flow of Points

Points flow strictly downward through the hierarchy:

Step 1: Platform → Agent Platform admin allocates points to an agent. This is recorded as:

• Increase in agent's available points
• This allocation is typically backed by an off-platform payment from agent to platform

Step 2: Agent → Punter Agent allocates points to their punter. This is recorded as:

• Decrease in agent's available points
• Increase in punter's available points
• This allocation is typically backed by an off-platform payment from punter to agent

3.2 Point Allocation is Real Transfer

Unlike credit-limit systems where no points move until settlement, our model uses real point transfer:

• When agent gives punter 10,000 points, agent's balance decreases by 10,000
• The punter now "owns" those 10,000 points
• This is simpler to understand and audit

3.3 Withdrawal (Points Moving Back Up)

Punters can request withdrawal of points back to their agent:

• Punter initiates withdrawal request
• Agent approves the withdrawal
• Points move from punter's balance to agent's balance
• Agent settles with punter off-platform (pays them cash)

Agents can similarly withdraw points back to the platform:

• Agent initiates withdrawal request
• Platform admin approves
• Points move from agent's balance to platform pool
• Platform settles with agent off-platform

3.4 Agent Cannot Over-Allocate

An agent can only allocate points they currently have:

• If agent has 100,000 points and 80,000 are already allocated to punters
• Agent can only allocate 20,000 more
• The system enforces this constraint at allocation time

This automatic limit answers the exposure concern—agents cannot expose themselves beyond their point balance because they cannot allocate points they don't have.

3.5 Example: Point Flow

Initial State:
├── Platform Pool: Unlimited (conceptual)
├── Agent A: 0 points
└── Punter P: 0 points

Platform allocates 100,000 to Agent A:
├── Platform Pool: -100,000 (tracked as liability to Agent A)
├── Agent A: 100,000 points
└── Punter P: 0 points

Agent A allocates 30,000 to Punter P:
├── Platform Pool: -100,000
├── Agent A: 70,000 points
└── Punter P: 30,000 points

Punter P places bet: 10,000 stake, loses:
├── Platform Pool: -100,000
├── Agent A: 70,000 points
└── Punter P: 20,000 points

Punter P places bet: 10,000 stake at 2.0 odds, wins:
├── Platform Pool: -100,000
├── Agent A: 70,000 points
└── Punter P: 30,000 points (20,000 + 10,000 winnings)

Where did the 10,000 winnings come from? This leads us to the next section.

---

4. Risk and Profit Distribution

4.1 The Core Principle: Settlement Reconciles Point Movement

The settlement is NOT about agent profit or loss from betting. The settlement reconciles the difference between what punters started with and what they now hold.

• Punters win: Platform received winnings from exchange → Platform passes to agent
• Punters lose: Platform lost to exchange (or netted) → Agent reimburses platform

Important: Agent profit comes from the markup on point sales (Section 1.3), NOT from settlement. The settlement merely ensures agents can cover their punters' cashouts.

4.2 How Punter Wins Are Funded

When a punter wins a bet, the points are credited to the punter immediately. Where do these points come from?

At the platform level:

• The bet was placed on Betfair/Pinnacle through the platform's single account
• Betfair/Pinnacle pays out to the platform account
• Platform credits the punter's balance

At the agent level:

• The agent's weekly settlement tracks: "Your punters net won X points"
• Platform pays agent X points (to cover the additional punter balances)
• This is settled during the weekly settlement cycle

4.3 The Settlement Accounting

The platform tracks each agent's position separately:

Agent A Weekly Summary:
├── Total punter stakes: 500,000 points
├── Total punter losses: 300,000 points (punters lost these bets)
├── Total punter wins: 250,000 points (punters won these bets)
├── Punters Net P&L: 250,000 - 300,000 = -50,000 points (punters lost net)
└── Settlement: Agent pays platform 50,000 points

Agent B Weekly Summary:
├── Total punter stakes: 400,000 points
├── Total punter losses: 150,000 points
├── Total punter wins: 200,000 points
├── Punters Net P&L: 200,000 - 150,000 = +50,000 points (punters won net)
└── Settlement: Platform pays agent 50,000 points

The rule is simple:

• Punters WIN → Platform pays Agent
• Punters LOSE → Agent pays Platform

4.4 Real-Time vs Settlement Accounting

Real-Time (during the week):

• Punter balances update immediately on bet placement and settlement
• Agent's "available points" shows their current unallocated balance
• No money moves between agent and platform

Weekly Settlement:

• Platform calculates each agent's punters' net P&L
• If punters won: Platform pays agent (agent needs funds to cover cashouts)
• If punters lost: Agent pays platform (platform covered exchange losses)
• Agent's credit with platform is adjusted accordingly

4.5 Example: Full Week Cycle

Monday: Week begins
├── Agent A's punters total balance: 100,000 points

During the week:
├── Punters bet total: 200,000 stakes
├── Punters lose: 60,000 points (lost bets)
├── Punters win: 40,000 points (won bets)
└── Punters net lost: 20,000 points

End of week:
├── Agent A's punters total balance: 80,000 points (100k - 20k net loss)

Settlement:
├── Punters net lost 20,000
├── Agent pays platform 20,000
└── (Platform either kept via netting or lost to exchange)

Off-platform:
├── Agent collected 100,000 from punters initially (with markup)
├── When punters cash out 80,000, agent pays 80,000
└── Plus agent paid platform 20,000 in settlement
└── Agent's gross margin = 100,000 × markup percentage

---

5. The Settlement Cycle

5.1 What Settlement Means

Settlement is the periodic reconciliation between each agent and the platform. It answers the question: "Based on how your punters performed this week, who owes whom?"

Settlement does NOT involve:

• Moving points between punters and agents
• Changing punter balances
• Real-time balance updates

Settlement DOES involve:

• Calculating each agent's net P&L from their punters' betting outcomes
• Adjusting the agent's credit with the platform
• Recording the settlement for audit purposes

5.2 Settlement Timing

Default: Weekly, every Sunday at midnight (configurable timezone)

Configurable options:

• Weekly (Sunday midnight)
• Bi-weekly (every other Sunday)
• Monthly (last day of month)
• On-demand (manual trigger by platform admin)

The settlement frequency is set at the platform level with possible agent-level overrides.

5.3 Settlement Calculation

The weekly settlement has two components that are calculated separately and then combined:

Component 1: Base Settlement (Punter P&L Reconciliation)

This reconciles the net movement of points in the agent's downline:

• Total Punter Wins (after commission): Sum of net winnings credited to punters
• Total Punter Losses: Sum of losing bet amounts
• Punters Net P&L: Total Wins - Total Losses

Base Settlement Rule:

• Punters net WON → Platform pays Agent (base settlement is positive for agent)
• Punters net LOST → Agent pays Platform (base settlement is negative for agent)

Component 2: Profit Share

This is the agent's share of commission collected from their punters:

• Commission Collected: Sum of commission on all winning bets
• Agent's Commission Share: Commission × (Agent's Commission Share %)

Profit share is always ≥ 0 for the agent (platform pays agent).

Final Settlement = Base Settlement + Profit Share

5.4 Settlement Examples

Example 1: Punters lost (platform profitable)

Settlement Period: Week of Jan 12-18, 2026
Agent: Agent A
Agent's Commission Share: 20%

Punter Betting Activity:
├── Total Stakes: ₹100,000
├── Total Payouts: ₹85,000
├── Commission collected: ₹750

Component 1 - Base Settlement:
├── Punters Net P&L: -₹15,000 (punters lost)
└── Base Settlement: Agent pays platform ₹15,000

Component 2 - Profit Share:
├── Commission share: ₹750 × 20% = ₹150

Final Settlement:
├── Base: -₹15,000 (agent pays)
├── Profit share: +₹150 (agent receives)
└── Net: Agent pays platform ₹14,850

Example 2: Punters won (platform lost)

Settlement Period: Week of Jan 19-25, 2026
Agent: Agent B
Agent's Commission Share: 25%

Punter Betting Activity:
├── Total Stakes: ₹100,000
├── Total Payouts: ₹130,000  ← Punters won big
├── Commission collected: ₹1,500

Component 1 - Base Settlement:
├── Punters Net P&L: +₹30,000 (punters won)
└── Base Settlement: Platform pays agent ₹30,000

Component 2 - Profit Share:
├── Commission share: ₹1,500 × 25% = ₹375

Final Settlement:
├── Base: +₹30,000 (agent receives)
├── Profit share: +₹375 (agent receives)
└── Net: Platform pays agent ₹30,375

Example 3: No profit sharing configured

Agent: Agent C
Agent's Commission Share: 0%

Component 2 - Profit Share:
├── Commission share: ₹0

Final Settlement = Base Settlement only (no profit share offset)

5.5 Settlement Status

Each settlement record has a status:

• Pending: Calculation complete, awaiting confirmation
• Confirmed: Reviewed and confirmed by platform admin
• Disputed: Agent disputes the calculation (manual review required)
• Settled: Off-platform payment received, settlement complete

5.6 What Happens After Settlement

If punters net lost:

• Agent pays platform the net loss amount
• Agent's debt to platform increases (or credit decreases)
• Off-platform: Agent collects losses from punters in cash
• Agent's net position: markup profit only (punter payments to agent minus agent payment to platform)

If punters net won:

• Platform pays agent the net win amount
• Agent's credit with platform increases
• Off-platform: Agent pays winning punters when they cash out
• Agent's net position: markup profit only (punter payments to agent plus platform payment, minus cashout payments)

5.7 Two Separate Flows

There are two distinct flows that work together:

1. Punter ↔ Agent (OFF-PLATFORM CASH)

This happens outside the Hannibal platform:

• Punter buys points → Pays agent cash (with markup)
• Punter cashes out → Agent pays punter cash (at face value)
• Agent's profit = markup on initial point sales

2. Agent ↔ Platform (ON-PLATFORM SETTLEMENT)

This is what the "Settlement Cycle" section describes:

• Punters win → Platform pays agent (to cover increased punter balances)
• Punters lose → Agent pays platform (to cover exchange/netting losses)
• This ensures agent can always cover punter cashouts

Example: Punters LOSE 20,000

Initial:
├── Agent sells 100,000 points to punters for ₹105,000 (5% markup)

During the week, punters bet and net lose 20,000:
├── Punters' total balance: 80,000 points

Settlement:
├── Agent pays platform ₹20,000 (punters lost, agent reimburses platform)

When punters cash out:
├── Punters cash out 80,000 points
├── Agent pays punters ₹80,000

Agent's P&L:
├── Received from punters: ₹105,000
├── Paid to platform (settlement): ₹20,000
├── Paid to punters (cashout): ₹80,000
└── Net profit: ₹105,000 - ₹20,000 - ₹80,000 = ₹5,000 (the markup)

Example: Punters WIN 20,000

Initial:
├── Agent sells 100,000 points to punters for ₹105,000 (5% markup)

During the week, punters bet and net win 20,000:
├── Punters' total balance: 120,000 points

Settlement:
├── Platform pays agent ₹20,000 (punters won, platform covers the winnings)

When punters cash out:
├── Punters cash out 120,000 points
├── Agent pays punters ₹120,000

Agent's P&L:
├── Received from punters: ₹105,000
├── Received from platform (settlement): ₹20,000
├── Paid to punters (cashout): ₹120,000
└── Net profit: ₹105,000 + ₹20,000 - ₹120,000 = ₹5,000 (the markup)

Key insight: The agent's profit is always the markup, regardless of whether punters win or lose. The settlement ensures the math works out.

---

6. Referral and Onboarding

6.1 The Referral Link System

No one can join Hannibal directly. Access is controlled through referral links:

Agent Referral Link:

https://hannibal.bet/join?ref=PLATFORM_CODE

• Generated by platform admin
• Contains a unique platform referral code
• When someone signs up through this link, they become an agent candidate

Punter Referral Link:

https://hannibal.bet/join?ref=AGENT_CODE

• Generated by each agent
• Contains the agent's unique referral code
• When someone signs up through this link, they become that agent's punter

6.2 Agent Onboarding Flow

1. Discovery: Prospective agent receives referral link from platform
2. Registration: Agent clicks link, creates account with social login (Reown AppKit)
3. Application: Agent provides required information (name, contact, etc.)
4. Review: Platform admin reviews the application
5. Approval: Admin approves and sets initial credit limit
6. Activation: Agent is notified, receives points, can start onboarding punters

6.3 Punter Onboarding Flow

1. Discovery: Prospective punter receives referral link from their agent
2. Registration: Punter clicks link, creates account with social login
3. Association: System automatically associates punter with the referring agent
4. Activation: Punter is active immediately (pending agent's point allocation)
5. Point Allocation: Agent allocates points to punter through their admin panel
6. Betting: Punter can now place bets

6.4 Referral Code Format

Referral codes should be:

• Unique per agent
• Human-readable (for sharing verbally)
• Case-insensitive
• Example formats: LOTUS123, AGT-7829, DIAMOND-A

Agents can request custom referral codes (subject to availability and platform approval).

6.5 Referral Link Expiry

Referral links do not expire by default. However, the platform can:

• Deactivate an agent's referral code (stops new signups)
• Set time-limited referral codes for campaigns
• Rate-limit signups per referral code

---

7. Admin Panels

7.1 Platform Admin Panel

The platform admin panel provides complete visibility into the system:

Dashboard:

• Total active agents count
• Total active punters count
• Total points in circulation
• Weekly settlement summary
• System health metrics

Agent Management:

• List all agents with status, credit limit, punter count
• View individual agent details
• Approve/reject pending agent applications
• Adjust agent credit limits
• Suspend/activate agents
• View agent's punter list
• View agent's betting history (aggregated)
• Generate settlement reports

Punter Management:

• Search punters across all agents
• View punter details and betting history
• Emergency suspension (bypassing agent)
• Balance adjustments (with audit trail)

Settlement Management:

• View pending settlements
• Confirm/dispute settlements
• Mark settlements as complete
• Generate settlement reports
• View settlement history

Configuration:

• Point-to-currency exchange rate
• Settlement frequency (default)
• Referral code settings
• System-wide limits

7.2 Agent Admin Panel

Each agent has access to a limited admin panel for their downline:

Dashboard:

• Total punter count
• Total points allocated to punters
• This week's P&L summary
• Pending settlement amount

Punter Management:

• List all punters with status and balance
• View individual punter details
• Allocate points to punter
• Withdraw points from punter
• View punter's betting history
• Suspend/activate punters

Settlement View:

• Current period's running P&L
• Historical settlements
• Settlement breakdown by punter

Profile:

• View own credit limit
• View own referral code and link
• Request credit limit increase
• Request withdrawal

7.3 Punter View

Punters do not have an admin panel. They have a standard user interface with:

• Balance display
• Betting interface
• Bet history
• Transaction history
• Profile settings

Punters cannot see:

• Other punters
• Their agent's details (beyond name/ID)
• Settlement information

---

8. Configuration Options

8.1 Platform-Level Configuration

Setting	Description	Default	UI
Point Currency Code	Display currency for points	INR	Dropdown
Point Exchange Rate	1 point = X currency units	1.0	Input
Settlement Frequency	Default settlement cycle	Weekly (Sunday)	Dropdown
Settlement Timezone	Timezone for settlement cutoff	Asia/Kolkata	Dropdown
Agent Application Required	Whether new agents need approval	Yes	Toggle
Punter Auto-Activation	Whether punters are active immediately	Yes	Toggle
Minimum Agent Credit	Minimum credit limit for agents	10,000	Input
Maximum Agent Credit	Maximum credit limit for agents	10,000,000	Input
Platform Commission Rate	Commission charged on winning bets	2%	Slider (0-20%)
Default Commission Share	Default agent share of commission	0%	Slider (0-100%)
Max Agent Markup	Maximum markup agents can charge	10%	Slider (0-50%)

8.2 Agent-Level Configuration

Setting	Description	Set By	UI
Credit Limit	Maximum points the agent can hold	Platform Admin	Input
Settlement Frequency	Override platform default (if allowed)	Platform Admin	Dropdown
Referral Code	Unique code for punter invites	System (custom on request)	Input
Status	active, suspended, blocked	Platform Admin	Dropdown
Commission Share %	Agent's share of commission collected from their punters	Platform Admin	Slider (0-100%)
Point Markup %	Markup agent charges punters for points	Agent (within limits)	Slider (0 to Max)

8.3 Punter-Level Configuration

Setting	Description	Set By
Daily Betting Limit	Maximum stake per day	Agent (within platform limits)
Single Bet Limit	Maximum stake per bet	Agent (within platform limits)
Status	active, suspended, blocked	Agent or Platform Admin

---

9. Edge Cases and Error Handling

9.1 Agent Runs Out of Points

Scenario: Agent has allocated all points to punters and cannot allocate more.

Handling:

• Agent cannot allocate more points until:
  • Points are withdrawn from punters back to agent
  • Settlement credits the agent (punters lost)
  • Agent deposits more (off-platform, admin credits)
• Punters can still bet with their existing balances
• New punters cannot receive point allocations

9.2 Punter Wins Big

Scenario: A punter wins a large bet, significantly increasing their balance.

Handling:

• Punter's balance is credited immediately (real-time)
• At settlement, this win is included in the agent's P&L calculation
• Agent may owe the platform a large amount
• If agent cannot pay: suspension, payment plan, or write-off

9.3 Agent Goes Negative at Settlement

Scenario: Agent's punters won more than they lost, and the settlement amount exceeds the agent's available credit.

Handling:

• Agent's status changes to "Settlement Due"
• Agent cannot onboard new punters
• Existing punters can continue betting (bets are risk to platform now)
• Platform admin can:
  • Extend credit (trust the agent to pay)
  • Suspend the agent (stop all activity)
  • Negotiate a payment plan
  • Write off the debt (rare, with penalties)

9.4 Punter Requests More Than Agent Has

Scenario: Punter requests a withdrawal, but agent doesn't have enough unallocated points.

Handling:

• Agent must first recover points from other punters
• Or wait for settlement to increase their pool
• Or deposit more with platform
• The withdrawal request remains pending until agent has sufficient balance

9.5 Agent Suspended Mid-Week

Scenario: Platform suspends an agent during an active settlement period.

Handling:

• Agent cannot allocate or withdraw points
• Agent's punters can continue betting (or can be suspended too, depending on reason)
• Settlement still runs at end of period
• Settlement amount is recorded but held until agent status is resolved

9.6 Bet Placed But Not Yet Settled

Scenario: Punter has an open bet at settlement cutoff time.

Handling:

• Open bets are NOT included in current settlement
• They will be included in the settlement period when they settle
• The punter's balance shows the stake as "locked" (not available)
• Settlement only considers fully settled bets

9.7 Disputed Settlement

Scenario: Agent disputes the settlement calculation.

Handling:

• Agent can mark settlement as "Disputed" with reason
• Platform admin reviews the calculation
• Admin can:
  • Confirm the original calculation (with explanation)
  • Adjust the calculation (with audit trail)
  • Void and recalculate
• Disputed settlements block automatic credit adjustments until resolved

9.8 System Failure During Settlement

Scenario: System crashes during settlement calculation.

Handling:

• Settlements are transactional—partial settlements are rolled back
• System resumes calculation on restart
• Manual trigger available for admin to re-run settlement
• All calculations are idempotent (re-running produces same result)

9.9 Multiple Punter Accounts

Scenario: Same person creates multiple punter accounts under different agents.

Handling:

• Wallet address linking can detect duplicates
• Platform admin can merge or block duplicate accounts
• Betting limits apply per-account (not per-person by default)
• Agents are responsible for knowing their punters (KYC is their domain)

9.10 Agent Transfer

Scenario: A punter wants to switch to a different agent.

Handling:

• Punter's current balance must be withdrawn to current agent first
• Current agent settles with punter off-platform
• Punter requests transfer (or creates new account under new agent)
• New agent allocates fresh points
• Historical betting data remains associated with original agent for settlement purposes

---

10. Glossary

Term	Definition
Agent	A user with distribution privileges who onboards and manages punters, allocates points, and bears the risk of punter betting activity
Punter	An end user who places bets. Must be associated with an agent
Point	The internal unit of account. Represents a configurable amount of real currency
Credit Limit	The maximum amount of points an agent can hold, set by platform admin
Allocation	The act of transferring points from agent to punter (or platform to agent)
Withdrawal	The act of transferring points from punter to agent (or agent to platform)
Settlement	The periodic reconciliation of net P&L between agent and platform
Net P&L	Total punter losses minus total punter wins for a period
Referral Code	Unique identifier used to associate new signups with their referrer
Downline	All users below a given user in the hierarchy (e.g., an agent's punters)
Upline	The parent user in the hierarchy (e.g., a punter's agent, an agent's platform)

---

Appendix A: Relationship to Existing Systems

A.1 Integration with Netting

The agent accounting system operates alongside the netting benefit described in the main design document:

Netting (Exchange Level):

• All bets from all punters go to Betfair/Pinnacle via one platform account
• The exchange sees aggregate positions, charges commission on net P&L
• Platform captures commission arbitrage

Agent Accounting (User Level):

• Punters are grouped under agents
• Agent bears the P&L risk for their punters
• Settlement determines who owes whom

These are complementary systems:

• Netting determines platform's cost (commission to exchange)
• Agent accounting determines agent's obligation (P&L to platform)
• Platform profit = Agent settlements + Netting benefit + Odds margin

A.2 Integration with B-Book (Version 2)

When B-book functionality is added:

• Some bets will be internalized by the platform (not sent to exchange)
• For agent accounting purposes, this is transparent
• Agent still bears punter P&L regardless of A-book/B-book routing
• Platform's B-book P&L is separate from agent settlements

A.3 No Changes to Existing Settlement

The existing settlement system (market settlement from exchanges) continues unchanged:

• Orders are settled when markets close
• Punter balances are updated in real-time
• Commission is charged on winnings

The agent settlement system is an additional layer that runs on a weekly cycle, independent of individual bet settlements.

---

Appendix B: Data Model Considerations

The implementation should use a recursive hierarchy model to support future expansion. Key entities:

User Model Extension:

• Role field (platform_admin, agent, punter)
• Parent reference (who is my upline?)
• Children relation (who is in my downline?)

Agent Profile:

• Credit limit
• Referral code
• Settlement preference
• Status

Point Allocation Records:

• From user, to user
• Amount
• Type (allocation, withdrawal)
• Timestamp

Settlement Records:

• Agent
• Period start/end
• Calculated totals
• Net P&L
• Status
• Confirmed by

This is described conceptually here. The actual database schema will be detailed in a separate technical specification.

---

Appendix C: Revenue Model and Commission

C.1 Platform Revenue Sources

The platform generates revenue through multiple channels:

1. Commission on Winnings: A configurable percentage (e.g., 2%) charged on each punter's individual winnings
2. Odds Margin: Displayed odds are slightly worse than raw exchange odds
3. Netting Benefit: The arbitrage between commission collected from users and commission paid to exchange
4. B-Book Profit (V2): Internalizing selected bets instead of passing to exchange

C.2 How Netting Benefit Works with Commission

The netting benefit specifically arises from the commission model:

What we charge punters:

• 2% commission on each individual punter's winnings
• Punter A wins ₹10,000 → We charge ₹200
• Punter B wins ₹5,000 → We charge ₹100
• Total collected: ₹300

What Betfair charges us:

• 5% commission on our account's NET P&L (Betfair's rate, not ours)
• If Punter A's win is offset by other punters' losses, net P&L may be ₹0
• Betfair charges: ₹0

Netting profit:

• Collected from punters: ₹300
• Paid to Betfair: ₹0
• Profit: ₹300

This is the "commission arbitrage" - we charge on gross individual winnings, Betfair charges on net account P&L.

C.3 Commission, Agent Settlements, and Profit Sharing

Three separate but related concepts:

1. Commission is charged by the platform on punter winnings:

• Deducted automatically when a punter wins
• Goes to the platform
• Part of platform's revenue from that agent

2. Base Settlement tracks the net P&L of the agent's punters:

• Calculated AFTER commission is deducted from punter winnings
• If punters net win: Platform pays agent
• If punters net lose: Agent pays platform

3. Profit Share is the agent's cut of platform revenue:

• Commission Share: Agent's % of commission collected (slider 0-100%)
• Always ≥ 0 for the agent

Example 1: Platform profitable

Week's activity for Agent A:
├── Commission Share: 25%
├── Total stakes: ₹100,000
├── Total payouts: ₹90,000
├── Commission collected: ₹500

Base Settlement:
├── Punters lost ₹10,000 → Agent pays platform ₹10,000

Profit Share:
├── Commission share: ₹500 × 25% = ₹125

Final Settlement:
├── Agent pays: ₹10,000 - ₹125 = ₹9,875 net to platform

Example 2: Platform lost

Week's activity for Agent B:
├── Commission Share: 25%
├── Total stakes: ₹100,000
├── Total payouts: ₹120,000  ← Sharp punters won
├── Commission collected: ₹1,000

Base Settlement:
├── Punters won ₹20,000 → Platform pays agent ₹20,000

Profit Share:
├── Commission share: ₹1,000 × 25% = ₹250

Final Settlement:
├── Platform pays: ₹20,000 + ₹250 = ₹20,250 to agent

C.4 Why This Works for Everyone

Platform benefits from:

• Commission on all winning bets
• Netting benefit (commission arbitrage)
• Profit when punters lose

Agent benefits from:

• Markup on point sales (off-platform, guaranteed)
• Commission share (on-platform, guaranteed when punters win bets)
• No infrastructure costs
• Tools to manage punter network

The incentive alignment:

• Platform wants volume (more bets = more commission)
• Agents want volume (more markup + more commission share)

---

Appendix D: How the Platform Makes Money (Complete Guide)

This section explains all the ways the platform generates revenue in simple, everyday language with real examples.

---

D.1 Overview: The Five Revenue Streams

The platform makes money through five main channels:

Revenue Stream	What It Means	When It Applies
1. Margin on Odds	We show slightly worse odds than the exchange	Sportsbook product only
2. Commission	We take a cut of user's net winnings per market	Both products
3. Slippage Capture	We keep the benefit when odds improve at placement	Both products
4. Netting Benefit	We charge users individually but pay exchange on net	Both products
5. Agent Booking System	Agents take a share of bet outcomes	Agent product

Important Note on Exchange Product: For the Exchange product, we show users the exact same odds as Betfair. There is zero margin on odds. Users see what the exchange sees. Revenue comes only from commission, slippage, and netting.

---

D.2 Margin on Odds (Sportsbook Product Only)

What is it? We take the odds from Betfair and make them slightly worse before showing them to users. The difference is our profit.

Simple Example:

Imagine a cricket match where India is playing Australia.

Betfair says: India to win pays 2.00 (bet ₹100, get ₹200 back)

We show user: India to win pays 1.96 (bet ₹100, get ₹196 back)

What happens when the user wins:

User bet ₹100 at 1.96 odds
India wins!

We collect from Betfair: ₹200 (at 2.00 odds)
We pay the user: ₹196 (at 1.96 odds)

Our profit: ₹200 - ₹196 = ₹4

Why does this work? The user doesn't know the Betfair odds. They see 1.96 and think it's a fair price. We pocket the difference.

How much margin? The margin is configurable per sport. Default is 2%. This means:

• If true odds are 2.00, we show approximately 1.96
• If true odds are 3.00, we show approximately 2.88
• If true odds are 1.50, we show approximately 1.47

Exchange Product: For the exchange product, margin is zero. Users see the exact Betfair odds. If Betfair shows 2.00, we show 2.00.

---

D.3 Commission on Net Winnings

What is it? When a user makes a net profit on a market (after all their bets on that match are settled), we take a percentage as commission.

Simple Example:

Ravi places two bets on the same cricket match:

Bet 1: ₹1,000 on India to win at 2.00 → India wins → Ravi gets ₹2,000 (profit ₹1,000)
Bet 2: ₹500 on Over 300 runs at 1.80 → Under 300 happens → Ravi loses ₹500

Ravi's net profit on this match: ₹1,000 - ₹500 = ₹500

Commission (2%): ₹500 × 2% = ₹10

Ravi's final profit: ₹500 - ₹10 = ₹490

Key Points:

• Commission is only charged when user has NET profit on a market
• If user loses overall on a market, commission is ₹0
• Commission rate is configurable (default 2%)
• This is the same model Betfair uses

Another Example (User Loses Overall):

Bet 1: ₹1,000 on India → India loses → Ravi loses ₹1,000
Bet 2: ₹500 on Australia → Australia wins → Ravi gets ₹900 (profit ₹400)

Ravi's net on this match: -₹1,000 + ₹400 = -₹600 (net loss)

Commission: ₹0 (no commission on losses)

---

D.4 Slippage Capture

What is it? Sometimes the odds improve between when we show them to the user and when we actually place the bet on Betfair. We keep this bonus.

Simple Example:

Step 1: User sees odds of 1.96 for India to win
Step 2: User clicks "Place Bet" for ₹1,000
Step 3: We go to Betfair to place the bet
Step 4: Betfair odds have improved to 2.05!
Step 5: We place at 2.05 but user is locked in at 1.96

What happens when user wins:

We collect from Betfair: ₹1,000 × 2.05 = ₹2,050
We pay the user: ₹1,000 × 1.96 = ₹1,960

Slippage profit: ₹2,050 - ₹1,960 = ₹90

This is called "positive slippage" - the odds moved in our favor.

What about negative slippage? Sometimes odds get worse. In that case:

• The user's locked price (1.96) becomes invalid
• We place at worse odds on Betfair (say 1.90)
• The user gets the worse odds (1.90), not their original price

The platform passes negative slippage to the user. This protects the platform from loss when odds move against us.

Simple Example of Negative Slippage:

User clicks bet at 1.96 odds
By the time we place on Betfair, odds have dropped to 1.90
User's bet is placed at 1.90 (not 1.96)
User's potential win is now lower, but they are protected from the bet being rejected

---

D.5 Netting Benefit (Commission Arbitrage)

What is it? We charge each user commission on their individual winnings. But Betfair only charges us commission on our account's NET position. When users' bets cancel each other out, we collect commission but pay nothing to Betfair.

Simple Example:

User A bets ₹10,000 on India to win
User B bets ₹10,000 on Australia to win

India wins!

User A wins ₹10,000 profit
User B loses ₹10,000

We charge User A: 2% of ₹10,000 = ₹200 commission
We charge User B: ₹0 (no commission on losses)

Our account at Betfair:
- User A's win: +₹10,000
- User B's loss: -₹10,000
- Net position: ₹0

Betfair charges us: 5% of ₹0 = ₹0 (Betfair's rate is 5%)

Our profit: ₹200 collected - ₹0 paid = ₹200

Why does this work? Betfair sees our account as one big pool. When our users bet against each other, the bets cancel out. We pay no commission to Betfair, but we still collect from each winning user.

Real-World Impact: With thousands of users betting on both sides of matches, a significant portion of bets net out. This "netting benefit" can be substantial.

---

D.6 The Agent Booking System (Point Ratio Model)

What is it? Agents can choose to "book" a percentage of their users' bets. This means they take a share of every bet's outcome - both wins AND losses.

The Key Concept: The odds stay exactly the same for users. The agent doesn't change the odds. Instead, the agent takes a percentage of the profit or loss from each bet.

Simple Example:

Agent has "1.25 points" which means they book 20% of the action

User bets ₹1,000 on India at 2.00 odds

Agent books: 20% = ₹200 of this bet
Platform books: 80% = ₹800 of this bet

Scenario 1: User LOSES

User loses ₹1,000

Agent keeps: ₹1,000 × 20% = ₹200
Platform keeps: ₹1,000 × 80% = ₹800

Scenario 2: User WINS

User wins ₹1,000 (at 2.00 odds, profit = ₹1,000)

Agent pays: ₹1,000 × 20% = ₹200
Platform pays: ₹1,000 × 80% = ₹800

The Point Ratio Mathematics:

The "points" determine what percentage the agent books:

Points	Formula	Agent Books
1.0	(1.0-1)/1.0 = 0%	0% (no risk, commission only)
1.1	(1.1-1)/1.1 = 9%	~9%
1.2	(1.2-1)/1.2 = 17%	~17%
1.25	(1.25-1)/1.25 = 20%	20%
1.5	(1.5-1)/1.5 = 33%	~33%
2.0	(2.0-1)/2.0 = 50%	50%

Formula:

Book Percentage = (Points - 1) / Points

Or the reverse:

Points = 1 / (1 - Book Percentage)

Example: For 20% booking → Points = 1 / (1 - 0.20) = 1 / 0.80 = 1.25

Why Would an Agent Book Action?

Model	Risk	Reward
No booking (1.0 points)	Zero risk	Small commission share only
20% booking (1.25 points)	Medium risk	20% of all user losses
50% booking (2.0 points)	High risk	50% of all user losses

Example Over a Week:

Agent with 1.25 points (20% booking) has 10 users who bet a total of ₹100,000

Total user bets: ₹100,000
Users who lost: ₹60,000
Users who won: ₹45,000
Net house profit: ₹15,000

Agent's share (20%):
├── Share of losses: ₹60,000 × 20% = ₹12,000 (agent receives)
├── Share of payouts: ₹45,000 × 20% = ₹9,000 (agent pays)
└── Agent's net profit: ₹12,000 - ₹9,000 = ₹3,000

Platform's share (80%):
├── Share of losses: ₹60,000 × 80% = ₹48,000
├── Share of payouts: ₹45,000 × 80% = ₹36,000
└── Platform's net profit: ₹48,000 - ₹36,000 = ₹12,000

Key Characteristics of the Booking System:

1. Odds Never Change - Users always see exchange odds (or margined odds for sportsbook)
2. Risk Sharing - Agent shares in both profits AND losses
3. Aligned Incentives - Agent wants users to lose (like a bookmaker)
4. Scalable - More users = more potential profit (or loss)
5. Settlement Based - Calculated at weekly settlement, not per bet

---

D.7 Putting It All Together: A Complete Example

Let's follow one bet through the entire system using the Exchange product (0% margin - user sees exact Betfair odds):

Setup:

• Product: Exchange (0% margin - exact Betfair odds shown)
• User: Ravi (under Agent Sharma)
• Agent Sharma: 1.25 points (books 20%), 25% commission share
• Bet: ₹10,000 on India to win

Step 1: Odds Display

Betfair true odds: 2.00
Margin: 0% (Exchange product)
Ravi sees: 2.00 (exact same as Betfair)

Step 2: Bet Placement

Ravi bets ₹10,000 at 2.00
We place on Betfair at 2.00 (no slippage in this example)

Step 3: India Wins! Settlement

Betfair pays us: ₹10,000 × 2.00 = ₹20,000
We pay Ravi: ₹10,000 × 2.00 = ₹20,000
Ravi's profit: ₹10,000

Platform captures from odds:
├── Margin profit: ₹0 (Exchange product has 0% margin)
├── Slippage profit: ₹0 (no slippage in this example)
└── Total odds profit: ₹0

Step 4: Commission

Ravi's net profit on market: ₹10,000
Commission (2%): ₹10,000 × 2% = ₹200

Ravi's final profit: ₹10,000 - ₹200 = ₹9,800

Step 5: Agent Booking (20%)

Ravi won ₹9,800 (after commission)

Agent Sharma pays: ₹9,800 × 20% = ₹1,960
Platform pays: ₹9,800 × 80% = ₹7,840

Step 6: Agent Profit Share

Commission collected: ₹200
Agent's commission share (25%): ₹200 × 25% = ₹50

Final Summary for This Bet:

Party	Amount	Notes
Ravi (User)	+₹9,800	Won bet minus commission
Agent Sharma	-₹1,910	Paid ₹1,960 (booking) + Received ₹50 (commission share)
Platform	-₹7,890	Paid ₹7,840 (booking) + Collected ₹200 (commission) - Paid ₹50 (agent share) - Paid to Ravi ₹200 shortfall

Note: This single bet was a loss for both platform and agent because the user won. Over many bets, the commission + netting benefit ensures profitability. With the Exchange product, there is no margin on odds - users see the exact same odds as Betfair.

---

D.8 Summary: Revenue by Product Type

Sportsbook Product:

Revenue Stream	Active?	Typical Rate
Margin on Odds	✅ Yes	2%
Commission	✅ Yes	2% on net profit
Slippage	✅ Yes	Variable
Netting Benefit	✅ Yes	Variable
Agent Booking	✅ Yes	0-50% configurable

Exchange Product:

Revenue Stream	Active?	Typical Rate
Margin on Odds	❌ No (0%)	Users see exact exchange odds
Commission	✅ Yes	2% on net profit
Slippage	✅ Yes	Variable
Netting Benefit	✅ Yes	Variable
Agent Booking	✅ Yes	0-50% configurable

---

End of Document