HANNIBAL

Design Document

Version 1.0 | January 2026

---

Executive Summary

Hannibal is a multi-tenant betting platform that operates as a Betfair skin (Version 1) with B-book capabilities (Version 2). The platform aggregates user betting activity through a single Betfair Exchange account, capturing commission savings through aggregation - Betfair charges commission on the account's net P&L while we charge commission on each user's individual winnings. Version 2 will add the ability to selectively internalise user bets through a configurable B-book mechanism.

The platform serves as infrastructure for white-label operators who bring their own user base while Hannibal handles execution, risk management, and settlement. Users interact with a Betfair-clone interface using points (with future USDC optionality), while the platform operator retains full control over the unified book position and risk exposure.

---

Table of Contents

1. The Problem
2. The Opportunity
3. Solution Architecture
4. Netting Benefit
5. B-Book Engine
6. Odds Engine
7. Multi-Tenant Model
8. User Experience
9. Settlement & Reconciliation
10. Risk Management
11. Revenue Model
12. Technical Architecture
13. Phase Roadmap
14. Open Questions

---

1. The Problem

1.1 The Betfair Commission Structure

Betfair Exchange charges commission only on net winnings per market. The formula is:

Commission = Net Winnings × Market Base Rate × (1 - Discount Rate)

The Market Base Rate is typically 5%. The Discount Rate varies by account based on Betfair Points earned through volume. For most accounts, effective commission ranges from 2% to 5% of net market winnings.

The critical insight: commission is calculated on net position, not gross activity. If an account backs £1,000 on Team A and lays £1,000 on Team A in the same market, the net position is zero, and the commission is zero—regardless of outcome.

1.2 The Fragmentation Problem

Individual bettors each maintain separate Betfair accounts. When User A backs Mumbai and User B lays Mumbai, these are independent transactions. Betfair matches them against the broader market, and each user pays commission on their individual net winnings.

There is no mechanism for User A and User B to benefit from the fact that their positions naturally offset. This value—the commission that would be saved if they operated through a single account—is captured by Betfair.

1.3 The B-Book Opportunity

Retail betting populations exhibit predictable loss patterns. Industry data consistently shows that 95%+ of recreational bettors lose money over time. When a platform intermediates between users and the exchange, it gains visibility into flow composition and can selectively take the opposite side of retail flow rather than passing it to the exchange.

This is standard practice in FX (retail brokers routinely B-book 70-90% of flow) and increasingly common in sports betting (soft books operate as full B-books). The opportunity exists to apply this selectively and dynamically based on user profiling and market conditions.

---

2. The Opportunity

2.1 Commission Arbitrage Through Netting

Netting is the core revenue mechanism for Hannibal. Here's how it works:

The Setup:

• Frontend: Multiple individual user accounts (User A, User B, User C, etc.)
• Backend: ONE single Betfair account that places all bets on behalf of all users

The Mechanism:

Betfair charges commission only on net winnings of an account. When multiple users bet through our single Betfair account, their individual wins and losses aggregate together:

User	Bet	Outcome	Individual P&L
User A	Back Mumbai ₹1000 @ 2.0	Mumbai wins	+₹1000
User B	Back Chennai ₹800 @ 2.0	Chennai loses	-₹800
User C	Back Mumbai ₹500 @ 2.0	Mumbai wins	+₹500
User D	Back Chennai ₹700 @ 2.0	Chennai loses	-₹700
Platform Betfair Account			Net: ₹0

What happens:

1. On Betfair: Our single account's net P&L = ₹0 (winners and losers balanced out)

   • Betfair commission on ₹0 net winnings = ₹0

2. On Our Platform: We settle with each user individually and charge 5% commission on their winnings

   • User A wins ₹1000 → We charge ₹50 commission
   • User C wins ₹500 → We charge ₹25 commission
   • Total commission collected: ₹75

3. Platform Profit: ₹75 (commission collected) - ₹0 (paid to Betfair) = ₹75

The Key Insight: By aggregating many users into one Betfair account:

• Individual wins and losses tend to offset each other
• Betfair sees a smaller net position (often near zero)
• We pay less or no commission to Betfair
• But we still charge each winning user our 5% commission

We're essentially running a commission arbitrage - Betfair charges on net account P&L, we charge on gross individual winnings.

Netting Efficiency: The more users we have, and the more balanced their betting preferences, the higher our netting efficiency. In markets where roughly equal numbers of users back different outcomes (e.g., India vs Australia cricket), the net platform position approaches zero, maximizing our commission capture.

2.2 B-Book Margin Capture

When the platform internalises a position rather than passing it to Betfair:

• No commission is paid to Betfair
• The platform takes the opposite side of the user's bet
• Platform profit/loss equals the inverse of user profit/loss
• Over a large sample of recreational users, expected value is positive

The key is selectivity. Sharp users (those with demonstrated positive expected value) should be passed to Betfair. Recreational users with negative expected value can be profitably B-booked.

2.3 Combined Revenue Streams

Revenue Source	Mechanism	Expected Contribution
Commission arbitrage	Charge users 5%, pay Betfair less due to netting	2-3% of volume
B-book profit	Internalise recreational flow	Variable, positive EV
Odds margin	Display slightly worse odds than Betfair	Configurable

---

3. Solution Architecture

3.1 Core Concept

Hannibal sits between end users and the Betfair Exchange. Users see a Betfair-like interface displaying markets, odds, and their bets. Behind the scenes, Hannibal:

1. Receives user orders
2. Validates against user balance and limits
3. Places the bet on Betfair via our single platform account
4. Tracks the user's individual orders
5. Settles with each user when the market closes, charging commission on winnings

The netting benefit is automatic - by routing all users through one Betfair account, their wins and losses aggregate, reducing the net commission we pay to Betfair.

3.2 Order Flow (Version 1)

In Version 1, the flow is straightforward:

Step 1: Order Intake User places an order through the platform interface. The order is validated against their balance and any applicable limits.

Step 2: Betfair Execution The order is immediately placed on Betfair via our platform account. We track which user placed the bet.

Step 3: Confirmation User receives confirmation of their bet with the matched odds.

Step 4: Settlement When the market settles on Betfair, we calculate each user's individual outcome and update their balance, charging 5% commission on winnings.

Note: Version 2 will add B-book capability, where we can choose to take the opposite side of some bets instead of passing them to Betfair.

3.3 Settlement Flow

When a market settles on Betfair:

1. Betfair settles the platform's account (credits winnings or debits losses)
2. Platform calculates each user's individual outcome
3. User balances are updated accordingly
4. B-book P&L is recorded (V2)
5. Tenant revenue shares are calculated

---

4. Netting Benefit

4.1 How Netting Works

Netting is not an internal orderbook matching system. It's the natural benefit that arises from aggregating multiple user accounts into a single Betfair account.

The Core Principle:

• Betfair charges commission on the net winnings of an account
• When many users bet through one account, their individual wins and losses aggregate
• The account's net P&L is typically much smaller than the sum of individual P&Ls
• We pay commission on the small net amount, but charge commission on each user's individual winnings

4.2 Why It Works

Consider a cricket match between India and Australia:

User	Bet	Stake	Outcome	User P&L
User A	Back India	₹10,000	India wins	+₹10,000
User B	Back India	₹5,000	India wins	+₹5,000
User C	Back Australia	₹8,000	Australia loses	-₹8,000
User D	Back Australia	₹7,000	Australia loses	-₹7,000

Platform Betfair Account Net P&L: +₹15,000 - ₹15,000 = ₹0

Commission Calculation:

• Betfair commission (5% of ₹0): ₹0
• Platform charges User A (5% of ₹10,000): ₹500
• Platform charges User B (5% of ₹5,000): ₹250
• Total platform revenue: ₹750

If each user had their own Betfair account, they would collectively pay ₹750 to Betfair. By aggregating, we capture that ₹750 instead.

4.3 Netting Efficiency

Netting efficiency depends on how balanced the user base's betting preferences are:

Scenario	Platform Net P&L	Betfair Commission	Our Commission	Profit
Perfect balance (50/50)	₹0	₹0	Full	Maximum
Slight imbalance	Small net win/loss	Small	Full	High
Heavy imbalance	Large net win/loss	Higher	Full	Lower

Factors that improve netting efficiency:

• Large, diverse user base
• Popular markets with balanced interest (e.g., India vs Pakistan)
• Multiple outcomes (spreads betting across selections)

4.4 Version 1 Implementation

In Version 1, netting is automatic - it's simply a consequence of our architecture:

1. All user bets are placed through our single Betfair account
2. Betfair naturally aggregates all positions
3. Commission is charged on the account's net P&L
4. We settle with each user individually, charging our commission on their winnings

No special "netting engine" is required. The benefit comes from the aggregation itself.

4.5 Comparison to Internal Orderbook

Some platforms implement an "internal orderbook" that matches user back bets against user lay bets before going to the exchange. This is different from netting:

Approach	Description	Complexity
Netting (our approach)	All bets go to Betfair via one account; commission savings from aggregation	Simple
Internal Orderbook	Match users internally first, only send unmatched to exchange	Complex

We use the simpler netting approach in Version 1. An internal orderbook could be considered for future versions if there's sufficient back/lay liquidity within our user base.

---

5. B-Book Engine

5.1 Purpose

The B-Book Engine decides whether to internalise user bets or pass them to the exchange. When B-booking, the platform takes the opposite side of the user's bet, profiting if the user loses and losing if the user wins.

Note: B-Book is a Version 2 feature. In Version 1, all user bets are passed to the exchange.

5.2 Configuration

The B-Book Engine is controlled by a single primary parameter:

B-Book Percentage: A slider from 0% to 100% indicating what proportion of user bets to internalise.

At 0%, all user bets are passed to the exchange (Version 1 behaviour - pure A-book). At 100%, all user bets are internalised (pure B-book - platform takes all risk). At 50%, half of user bets are B-booked, half are passed to the exchange.

This is a platform-level setting, not per-tenant. All flow pools into a single book, and the platform operator decides the aggregate risk appetite.

5.3 Exposure Limits

Regardless of the B-Book Percentage, the platform enforces absolute exposure limits:

Limit Type	Description	Purpose
Max Market Exposure	Maximum B-book liability per market	Prevents catastrophic single-event loss
Max Daily Exposure	Maximum B-book liability across all markets	Daily stop-loss
Max Selection Exposure	Maximum B-book liability per selection	Diversification

When exposure limits are reached, additional flow is automatically passed to Betfair regardless of the B-Book Percentage setting.

5.4 Decision Logic

For each incoming user bet:

1. Apply B-Book Percentage to determine how much to internalise
2. Check against all exposure limits
3. Cap B-book amount to respect limits
4. B-book the capped amount (platform takes the opposite side)
5. Pass remainder (if any) to the exchange

5.5 User Profiling (Future Enhancement)

A more sophisticated approach segments users by expected profitability:

User Segment	Identification	B-Book Treatment
Sharp	CLV positive, high win rate	Never B-book, pass to Betfair
Recreational	CLV negative, pattern bettor	B-book within limits
Unknown	Insufficient history	Apply platform default

This allows the platform to B-book only negative-EV flow while avoiding taking the wrong side against sharp users.

---

6. Odds Engine

6.1 Purpose

The Odds Engine determines what prices users see and at what prices their bets are accepted. It sources prices from Betfair and applies configurable adjustments.

6.2 Price Sourcing

Betfair provides two data access methods:

Polling API: Request/response model, suitable for pre-match and low-frequency updates. Rate-limited but simple to implement.

Exchange Stream API: WebSocket-based real-time price streaming. Updates pushed within 50-150ms of market movements. Required for in-play markets and competitive user experience.

For MVP, the Polling API is sufficient for pre-match markets. The Stream API integration should be prioritised for Phase 2.

6.3 Odds Adjustment

The platform applies a configurable adjustment to Betfair prices:

Odds Adjustment Slider: Ranges from -2% to +2%

At 0%, users see Betfair prices exactly. At +1%, users see prices 1% worse than Betfair (platform margin). At -1%, users see prices 1% better than Betfair (promotional/acquisition).

Adjustment is applied to the implied probability, then converted back to decimal odds:

1. Convert decimal odds to implied probability: p = 1 / odds
2. Adjust probability: p' = p × (1 + adjustment)
3. Convert back to odds: odds' = 1 / p'

6.4 Price Display vs. Execution

Users always see adjusted prices. However, internal accounting tracks:

• Display Price: What the user saw and agreed to
• Betfair Price: Current Betfair market price (if order is passed)
• Execution Price: Price at which the order was actually matched on Betfair

For B-booked orders, there is no Betfair execution—the user's bet is settled at the Display Price against the platform's internal book.

---

7. Agent Distribution Model

Note: This section describes the Agent system which is fully implemented. Earlier documentation referred to this as "Multi-Tenant" - Agents ARE the tenants/white-label operators in our system.

7.1 Agent Concept

An Agent is a distribution partner who brings users (punters) to the platform. The platform operates on a hierarchical model:

Platform → Agents → Punters

Key characteristics:

• Users cannot join directly—they must be referred by an approved Agent
• Agents manage their own punter network
• Agents receive revenue share from their punters' activity
• Agents have their own dashboard with visibility only into their own punters

The platform operator (Hannibal) maintains the unified book, exchange accounts, and risk management across all Agents.

7.2 Agent Isolation

Data Type	Agent Visibility	Platform Visibility
Punter accounts	Own punters only	All users
Punter balances	Own punters only	All users
Punter bets	Own punters only	All bets
Exchange account P&L	None	Full view
B-book exposure	None	Full exposure
Revenue share	Own share only	All shares

Agents cannot see other Agents' punters or activity. They cannot see the exchange account P&L or B-book decisions.

7.3 Agent Revenue Model

Agents earn through two streams:

1. Point Markup (Off-Platform)

• Agent buys points from platform at face value (1 point = ₹1)
• Agent sells points to punters at markup (e.g., 1 point = ₹1.05)
• Markup percentage is configurable per agent (0% to X%)

2. Profit Sharing (On-Platform) Each component is independently configurable via admin sliders:

Profit Component	Calculation	Agent Share
Commission Share	% of commission collected from agent's punters	0-100% (configurable)
NGR Share	% of Net Gaming Revenue (stakes - payouts)	0-100% (configurable)

Important: NGR Share is only paid when NGR > 0 (platform profitable). If punters beat the book, NGR Share = ₹0.

7.4 Agent Dashboard

Each Agent has access to a dashboard (/agent) showing:

• Active punters and betting volume
• Point allocations and balances
• Revenue generated (commission + NGR share)
• Punter-level betting history
• Settlement period reports
• Withdrawal requests

Agents do not have access to:

• Platform-level settings (B-book %, odds adjustment)
• Exchange account details and P&L
• Other Agents' data
• Betfair/Pinnacle account credentials

7.5 Weekly Settlement Cycle

The platform operates on weekly settlement periods:

1. Period runs Monday 00:00 to Sunday 23:59
2. Bets settle throughout the week as matches complete
3. Period closes automatically at week end
4. Settlement calculated:
   • If punters NET WIN → Platform pays Agent
   • If punters NET LOSE → Agent pays Platform
5. Reports generated for reconciliation

---

8. User Experience

8.1 Interface Design

The user interface is a Betfair clone, providing familiar functionality:

• Market browsing by sport, competition, event
• Market view with back/lay prices and available volume
• Bet slip for placing orders
• My Bets view showing open and settled bets
• Account balance and transaction history

8.2 Points System

Users transact in points rather than currency:

• 1 point = 1 INR (or configurable exchange rate)
• Points are purchased from the tenant (off-platform)
• Points are redeemed through the tenant (off-platform)
• The platform tracks point balances but does not handle fiat

This structure:

• Avoids direct gambling regulation in many jurisdictions
• Simplifies platform operations (no payment processing)
• Delegates KYC/AML to tenants
• Enables future USDC integration

8.3 USDC Integration (Future)

A future enhancement allows users to hold balances in USDC:

• Deposit USDC to platform wallet
• Bet using USDC balance
• Withdraw USDC to external wallet

This provides:

• Instant, borderless deposits and withdrawals
• Reduced counterparty risk for users
• Transparent, auditable balances

8.4 Order Types

Market Order: Execute immediately at best available price. For B-booked orders, this is the current displayed price. For Betfair orders, this is the current market price.

Limit Order: Place an order at a specified price. If the market moves to that price, the order is matched. Limit orders are held in the platform's internal order book until matched or cancelled.

For MVP, only market orders are supported. Limit orders add complexity around order management and partial fills.

---

9. Settlement & Reconciliation

9.1 Settlement Trigger

Settlement occurs when a Betfair market is marked as settled. The platform:

1. Receives settlement notification via Betfair API
2. Retrieves the winning selection(s)
3. Calculates outcomes for all user orders in that market
4. Updates user balances (crediting winners, charging commission)
5. Records B-book P&L (V2)
6. Calculates tenant revenue shares

9.2 User Settlement

For each user bet in the settled market:

• Winning back bet: Credit stake × (odds - 1)
• Losing back bet: No action (stake already deducted)
• Winning lay bet: Credit liability (already held)
• Losing lay bet: Debit stake × (odds - 1) from liability

9.3 Platform Settlement

The platform's exchange account is settled based on the aggregate outcome of all bets placed:

• If the account has net winnings: Exchange credits the account (minus commission)
• If the account has net losses: Exchange debits the account
• Commission is deducted only from net winnings

9.4 B-Book Settlement

For B-booked positions:

• If users collectively won: Platform debits B-book P&L
• If users collectively lost: Platform credits B-book P&L

The B-book P&L is the inverse of user outcomes for the B-booked portion of positions.

9.5 Reconciliation

Daily reconciliation ensures consistency:

1. Sum of user balances = Platform liability to users
2. Betfair account balance + B-book P&L = Platform assets
3. Platform assets ≥ Platform liability (solvency check)

Any discrepancy triggers an alert for manual investigation.

---

10. Risk Management

10.1 Platform-Level Risks

Risk	Mitigation
B-book loss exceeds reserves	Exposure limits, daily stop-loss
Betfair account suspension	Maintain compliance, backup accounts
Sharp user exploitation	User profiling, selective B-booking
Liquidity mismatch	Only accept orders with Betfair liquidity
Settlement failure	Automated reconciliation, alerts

10.2 Exposure Monitoring

Real-time monitoring of:

• Total B-book exposure by market
• Total B-book exposure aggregate
• Largest single-market exposure
• User concentration (single user % of volume)

Dashboard displays current exposure against limits with visual alerts when approaching thresholds.

10.3 Circuit Breakers

Automatic protective actions:

Trigger	Action
Daily B-book loss > limit	Reduce B-book % to 0%
Single market exposure > limit	Pass all new flow to Betfair
Betfair API errors	Queue orders, alert operator
Reconciliation mismatch	Pause new bets, alert operator

10.4 User-Level Controls

Control	Purpose
Maximum stake per bet	Limit single-bet exposure
Maximum daily volume	Limit user-level risk
Maximum liability	Limit lay bet exposure
Account suspension	Manual intervention capability

---

11. Revenue Model

11.1 Revenue Streams

1. Commission Arbitrage

Users pay 5% commission on their individual net winnings. Platform pays Betfair commission only on the account's aggregate P&L. The difference is retained.

Example:

• User A wins £100, pays £5 commission to platform
• User B loses £100, pays £0 commission
• Account's aggregate P&L = £0, platform pays £0 to Betfair
• Platform retains £5

2. B-Book Profit

When B-booking, the platform profits from user losses and loses from user wins. Over a large sample of recreational users, expected value is positive.

Example:

• B-book £10,000 of recreational flow
• Expected user loss rate: 5% (industry average)
• Expected B-book profit: £500

3. Odds Margin

When odds adjustment is positive, users receive slightly worse prices than Betfair. This margin is captured regardless of outcome.

Example:

• Betfair price: 2.00
• Displayed price: 1.98 (1% margin)
• User backs £100, wins
• User receives £98 profit instead of £100
• Platform captures £2 margin

11.2 Revenue Projections

Monthly Volume	Netting Efficiency	B-Book %	Est. Monthly Revenue
£100,000	50%	50%	£3,000 - £5,000
£1,000,000	50%	50%	£30,000 - £50,000
£10,000,000	50%	50%	£300,000 - £500,000

Revenue scales linearly with volume. Higher netting efficiency and B-book percentage increase revenue but also increase risk.

---

12. Technical Architecture

12.1 Technology Stack

Component	Technology	Rationale
Frontend	Next.js + React	Modern, performant, SSR capable
Backend	Node.js + TypeScript	Type safety, async handling
Database	PostgreSQL (local)	Full control, local development
Cache	Redis	Fast caching for odds data
Authentication	Privy	Social login with automatic crypto wallet
Hosting	Vercel	Seamless Next.js deployment
Betfair Integration	REST API + Stream API	Official supported methods

12.2 Database Schema (Core Tables)

tenants

• id, name, api_key, revenue_share_config, created_at

users

• id, tenant_id, email, balance_points, created_at

orders

• id, user_id, market_id, selection_id, side, stake, odds, status, created_at

settlements

• id, market_id, winning_selection_id, settled_at

bbook_ledger

• id, market_id, exposure, pnl, settled_at

12.3 API Design

User-Facing API

• POST /api/orders - Place an order
• GET /api/orders - List user's orders
• GET /api/markets - List available markets
• GET /api/markets/:id - Get market details with prices
• GET /api/account - Get user balance and info

Tenant API

• GET /api/tenant/users - List tenant's users
• GET /api/tenant/revenue - Get revenue summary
• GET /api/tenant/dashboard - Get dashboard data

Admin API

• GET /api/admin/orders - View all orders
• POST /api/admin/settings - Update platform settings
• GET /api/admin/bbook - View B-book exposure and P&L (V2)

12.4 Betfair Integration

Authentication: Betfair uses a session-based auth with certificates. The platform maintains a persistent session, refreshing as needed.

Market Data: Polling API for market catalogue and prices. Rate limit: 5 requests/second for free tier, higher for paid.

Order Placement: Betting API for placing, updating, and cancelling orders. Orders are placed as the platform's single account.

Settlement: Settled markets are retrieved via the Betting API. The platform polls for newly settled markets and processes them.

---

13. Version Roadmap & Implementation Status

Last Updated: January 2026

Version 1: Foundation ✅ COMPLETE

Objective: Core platform with netting, pre-match and in-play betting

Deliverable	Status	Notes
User authentication	✅	Reown AppKit (social login + embedded wallets)
Market display	✅	OddsPAPI integration with Redis caching
Order placement	✅	BETS API integration (Betfair + Pinnacle)
Back & Lay betting	✅	Full Betfair-style UI
Settlement	✅	Automated with commission charging
Admin UI	✅	Full dashboard with user/order management
In-play betting	✅	WebSocket real-time odds

Version 2: B-Book & Risk ✅ COMPLETE

Objective: B-book capability with risk controls

Deliverable	Status	Notes
B-book engine	✅	Configurable B-book percentage (0-100%)
Filter engine	✅	Routes orders based on rules
Exposure limits	✅	Global, per-market, per-selection, per-user limits
Sharp user management	✅	Exclude sharp users from B-book
B-book P&L tracking	✅	Separate accounting for B-book positions
B-book settlement	✅	Automatic settlement with exchange positions

Version 3: Agent Distribution System ✅ COMPLETE

Note: Originally called "Multi-Tenant" - implemented as the Agent hierarchy system.

Deliverable	Status	Notes
Agent management	✅	Create, approve, configure agents
Agent isolation	✅	Agents see only their own punters
Revenue sharing	✅	Configurable commission % and NGR % per agent
Agent dashboard	✅	Full self-service analytics at /agent
Point allocation	✅	Platform → Agent → Punter flow
Weekly settlement	✅	Automated settlement periods with reports
Referral system	✅	Punters join via agent referral codes

Version 4: AI Integration 🟡 FOUNDATION ONLY

See docs/HANNIBAL_AI_FEATURES_2026.md for the full vision document with 12 feature categories.

Only Phase 1 foundation features are implemented. The majority of the AI vision is NOT yet built.

What's Implemented (Foundation):

Deliverable	Status	Notes
AI fixture analysis button	✅	Click to get AI-generated analysis
AI chat assistant service	✅	FastAPI service with multi-provider LLM support
Tournament analysis	✅	AI-powered tournament overviews
Search analysis	✅	AI analysis for search queries
Basic watchlist CRUD	✅	Create/read/update/delete watchlists
Basic user agent CRUD	✅	Create/read/update/delete agents (Cricket only)
Agent monitoring service	✅	Polls live cricket matches for event triggers

What's NOT Implemented (From AI Features Vision):

Category	Features	Status
Agentic AI System	Natural language agent creation, compound logic, learning conditions, agent marketplace	🔴
Smart Watchlists	AI-powered alerts, predictive notifications, daily briefings, concept watchlists	🔴
Conversational Betting	Natural language bet placement, voice commands, bet building via chat	🔴
AI Bet Builder	AI-suggested parlays, correlation detection, bet optimization	🔴
Portfolio Intelligence	Portfolio view, performance attribution, risk analysis, hedge suggestions	🔴
Real-Time Intelligence	News aggregation, social media monitoring, weather integration, line movement	🔴
Predictive Models	Match outcome predictions, Monte Carlo simulations, model marketplace	🔴
Social Intelligence	Community insights, expert tracking, social sentiment	🔴
Responsible Gambling AI	Behavioral detection, intervention levels, budget management	🔴
Multimodal AI	Voice interface, image analysis, video highlights	🔴
AI Memory	Persistent memory, preference learning, adaptive recommendations	🔴

Version 5: USDC & Advanced 🔴 NOT STARTED

Objective: Crypto integration and advanced features

Deliverable	Status	Notes
USDC deposits	🔴	Wallet integration pending
USDC withdrawals	🔴	Automated processing pending
Advanced user profiling	🔴	CLV calculation, segmentation
Limit orders	🔴	Order book management

Future Enhancements 🔴 NOT STARTED

Feature	Priority	Notes
Cash out	Medium	Early settlement of open bets
Bet builder/accumulators	Medium	Multi-selection bets
Native mobile apps	Low	React Native (PWA works well)
Circuit breaker UI	Low	Visual risk dashboard

---

14. Open Questions

14.1 Regulatory

1. Jurisdiction: Which jurisdiction(s) will the platform operate in? This affects licensing requirements.

2. Licensing: Does operating as a Betfair skin require a separate gambling license, or does Betfair's license cover downstream activity?

3. Points vs. Currency: Does the points model provide regulatory protection, or is it considered gambling regardless?

14.2 Commercial

4. Betfair Relationship: Is Betfair aware of and permissive toward skin operations? What are the terms of service implications?

5. Tenant Acquisition: How will tenants be acquired? What is the value proposition for a white-label operator?

6. Pricing: What commission rate should be charged to users? Should it match Betfair (5%) or differ?

14.3 Technical

7. Betfair Rate Limits: What are the actual rate limits for the Betfair API? How do they scale with volume?

8. Latency Requirements: What latency is acceptable for in-play betting? This affects architecture decisions.

9. Disaster Recovery: What happens if Betfair is unavailable? Should there be a backup exchange?

14.4 Operational

10. Capital Requirements: How much capital is needed to cover B-book exposure and user balances?

11. Staffing: What operational roles are needed? Risk management, customer support, compliance?

12. Monitoring: What metrics should be tracked? What alerting thresholds?

---

Appendix A: Glossary

Term	Definition
Back	Betting on a selection to win
Lay	Betting against a selection (acting as bookmaker)
Netting	Commission arbitrage achieved by aggregating multiple users into one exchange account - exchange charges on net P&L, platform charges on individual winnings
B-Book	Internalising user bets rather than passing to exchange (V2 feature)
A-Book	Passing user bets to exchange (opposite of B-book)
CLV	Closing Line Value - measure of bet quality
Sharp	Sophisticated bettor with positive expected value
Recreational	Casual bettor with negative expected value
Skin	White-label platform operating on another's infrastructure
Tenant	White-label operator using the platform

---

Appendix B: Betfair API Reference

Authentication

Betfair requires:

1. API key (obtained from Betfair developer portal)
2. Session token (obtained via login with username/password)
3. SSL certificate (for non-interactive login)

Session tokens expire after 20 minutes of inactivity. The platform should implement automatic refresh.

Key Endpoints

Endpoint	Purpose
listEventTypes	Get available sports
listCompetitions	Get competitions for a sport
listEvents	Get events for a competition
listMarketCatalogue	Get markets for an event
listMarketBook	Get prices for markets
placeOrders	Place bets
listCurrentOrders	Get open orders
listClearedOrders	Get settled orders

Rate Limits

• Free tier: 5 requests/second
• Paid tier: Higher limits available
• Streaming: Separate connection, no request limit

---

Document Version 1.0 - January 2026 Author: Hannibal Platform Team