Hannibal Version 1 - Detailed Specification

Executive Summary

Version 1 of Hannibal is a mobile-first betting platform that connects users to multiple betting providers through an aggregation layer (BETS API). The platform features social login with automatic crypto wallet creation, real-time odds display with Redis caching, and automated settlement processing with commission charging.

Netting Benefit: By routing all users through a single exchange account, individual wins and losses aggregate, reducing the net commission we pay to the exchange while we charge commission on each user's individual winnings. This is automatic - no special "netting engine" is required.

Key Principles for Version 1:

Mobile-first design (responsive for desktop)
Dual provider strategy: Betfair Exchange for Cricket, Pinnacle for other sports
Back AND Lay betting with Betfair-style UI/UX for all sports
No B-book functionality (reserved for Version 2)
Single tenant operation
In-play AND pre-match betting supported
All market types that OddsPAPI can settle are supported

1. User Interface Design

1.1 Design Philosophy

The UI will be inspired by Betfair Exchange's proven design patterns but with a modern, sleeker aesthetic and improved mobile experience. We will use a distinct color scheme to differentiate from Betfair while maintaining familiar betting conventions.

1.2 Color Scheme

Element	Color	Purpose
Primary	Deep Purple (#6B21A8)	Brand identity, headers
Secondary	Emerald Green (#10B981)	Success states, positive odds movement
Back Bet	Blue (#3B82F6)	Back betting columns (user backing outcome)
Lay Bet	Pink/Rose (#F472B6)	Lay betting columns (user laying/betting against outcome)
Background	Slate (#0F172A dark, #F8FAFC light)	App background
Surface	Gray variations	Cards, panels
Warning	Amber (#F59E0B)	Alerts, odds changes
Error	Red (#EF4444)	Errors, declined bets

1.3 Mobile-First Layout

The interface prioritizes touch interactions and single-hand usage:

Bottom Navigation Bar (persistent)

Home/Featured
Sports
My Bets
Account

Main Screens:

Home Screen
- Featured matches carousel (including live matches)
- Quick sport category icons
- Popular markets section
- Live scores ticker with in-play betting access
Sport/Market Browser
- Collapsible league/tournament accordion
- Match cards with key odds visible
- Swipe gestures for quick bet slip access
- Pull-to-refresh for odds updates
Match Detail View
- Team/player names and scheduled time
- Market tabs (1X2, Over/Under, Both Teams to Score, etc.)
- Odds grid with price and available limit
- Quick stake buttons
- Bet slip integration
Bet Slip (Bottom Sheet)
- Slide-up panel from bottom
- Current selections with live odds
- Stake input with preset amounts
- Potential returns calculation
- Place bet button with confirmation
My Bets Screen
- Active bets with live status
- Pending bets awaiting placement
- Settled bets history
- Filter by date range, sport, status
Account/Profile
- Balance display
- Deposit/Withdraw actions
- Wallet address (connected via Reown AppKit)
- Settings and preferences
- Transaction history

1.4 Betfair-Style Exchange UI

Odds Grid Layout (Back/Lay Columns):

For each outcome, display both back and lay prices in the classic Betfair format:

┌─────────────────────────────────────────────────────────┐
│  Team A         │  BACK (Blue)  │  LAY (Pink)          │
│                 │  2.66  ₹8499  │  2.68  ₹13437        │
├─────────────────────────────────────────────────────────┤
│  Draw           │  3.40  ₹5200  │  3.45  ₹8900         │
├─────────────────────────────────────────────────────────┤
│  Team B         │  2.90  ₹6100  │  2.94  ₹9200         │
└─────────────────────────────────────────────────────────┘

Key UI Elements:

Back Column (Blue #3B82F6): Best available back price + liquidity
Lay Column (Pink #F472B6): Best available lay price + liquidity
Price prominently displayed (larger font)
Available liquidity shown below price (smaller font)
Tap back column to add BACK bet to slip
Tap lay column to add LAY bet to slip
For Cricket (Betfair): Show 3-level depth on tap/expand
For other sports (Pinnacle): Show single best price, lay = converted back

Odds Movement Indicators:

Fade animation on odds changes
↑ Green flash for price improvement (better for backer)
↓ Red flash for price deterioration
Liquidity changes shown with subtle highlight

Visual Feedback:

Haptic feedback on bet placement (mobile)
Toast notifications for bet status changes
Real-time odds flashing on updates
Loading skeletons during data fetch
Different visual treatment for Cricket (full depth) vs other sports (single price)

2. Authentication System

2.1 Reown AppKit Integration

Recommended: Reown AppKit (formerly WalletConnect Web3Modal) provides social login combined with automatic embedded wallet creation, enabling a seamless Web3-ready experience without requiring users to understand crypto.

Why Reown AppKit over Privy:

Native multichain support (EVM, Solana, Bitcoin in one SDK)
Built-in WalletConnect protocol for 600+ external wallets
Generous free tier with enterprise options
Open source with active development
Unified embedded wallet that works across chains

Note: Both Privy and Reown are viable options. Reown is recommended for its better multichain support and open-source nature. Either can be used.

Method	Priority	Notes
Google	Primary	Most common, lowest friction
Apple	Primary	Required for iOS App Store
Email (OTP)	Primary	Magic link/code based
Discord	Secondary	Popular in crypto communities
X (Twitter)	Secondary	Web3 user preference
GitHub	Secondary	Developer-friendly
Farcaster	Secondary	Web3 social
Facebook	Tertiary	Broad reach

2.3 Authentication Flow

User clicks "Sign In"
- Reown AppKit modal opens with login options
User selects login method (e.g., Google)
- OAuth flow completes
- Reown verifies identity
Automatic Wallet Creation
- Reown generates embedded wallets for each chain type:
  - EVM Wallet: For Ethereum, Polygon, BSC, etc.
  - Solana Wallet: For Solana transactions
  - Note: Tron wallet requires custom implementation or alternative provider
- All wallets are linked to user's single identity
- Private keys are secured by Reown's infrastructure
Session Established
- JWT token issued
- User redirected to home screen
- Balance shown (initially zero for new users)

2.4 Multi-Chain Wallet Architecture

Reown AppKit supports multiple embedded wallets per user:

Chain Type	Wallet Support	Status
EVM (Ethereum, Polygon, BSC, etc.)	✅ Native	Fully supported
Solana	✅ Native	Fully supported via SolanaWeb3JsAdapter
Bitcoin	✅ Native	Supported for viewing/signing
Tron	⚠️ Limited	Not natively supported - requires custom integration

Configuration Example:

import { createAppKit } from '@reown/appkit'
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
import { SolanaAdapter } from '@reown/appkit-adapter-solana'

const appKit = createAppKit({
  adapters: [wagmiAdapter, solanaAdapter],
  projectId: 'YOUR_PROJECT_ID',
  networks: [mainnet, polygon, solana, solanaDevnet],
  features: {
    email: true,
    socials: ['google', 'apple', 'x', 'discord', 'github', 'farcaster'],
    emailShowWallets: true
  }
})

2.5 Wallet Management

Embedded Wallets: Created automatically per chain, no seed phrase required
Export Option: Users can upgrade to self-custodial wallet if desired
Multi-chain: Separate addresses for EVM and Solana chains
Recovery: Via social login re-authentication
External Wallets: Users can also connect existing wallets (MetaMask, Phantom, etc.)

2.6 User Data Model

User {
  id: UUID
  reown_id: string (Reown's user identifier)
  evm_wallet_address: string (EVM address from Reown)
  solana_wallet_address: string (Solana address from Reown)
  tron_wallet_address: string (nullable, requires custom integration)
  email: string (optional, from social login)
  display_name: string
  created_at: timestamp
  last_login: timestamp
  balance_points: decimal (1 point = 1 INR)
  status: enum (active, suspended, blocked)
}

2.7 Tron Wallet Consideration

For Tron support (USDT on Tron is popular in India), options include:

Custom TronWeb integration: Build custom wallet creation/signing
Privy for Tron only: Privy supports Tron embedded wallets
Defer to Version 5: Focus on EVM/Solana for V1, add Tron with USDC payments

3. Market Display & Odds Data

3.1 Data Source Architecture

Odds data flows through a multi-layer caching system:

OddsPAPI API → BETS API → Backend Service → Redis Cache → Frontend

3.2 OddsPAPI Integration

OddsPAPI provides real-time odds from 300+ bookmakers across multiple sports.

Supported Sports: All sports available through Betfair and Pinnacle via the BETS API are supported. This includes but is not limited to:

Soccer, Cricket, Tennis, Basketball, American Football, Baseball, Ice Hockey, Golf, MMA/UFC, Boxing, Rugby, Volleyball, Table Tennis, Esports, Horse Racing, and more.

The platform dynamically displays all sports and markets returned by the BETS API. No hardcoded sport restrictions.

API Endpoints Used:

Endpoint	Purpose
`/v4/fixtures`	List upcoming and live matches with filters
`/v4/odds`	Get odds for specific fixtures (pre-match and in-play)
`/v4/scores`	Live scores for display
`/v4/settlements`	Match results for bet settlement

3.3 Real-Time Odds Updates

OddsPAPI provides two methods for real-time odds updates:

Option 1: WebSocket (Recommended for Production)

OddsPAPI offers WebSocket access for real-time streaming of odds changes. This eliminates the need for polling and caching.

To Enable:

Contact OddsPAPI at contact@55-tech.com for WebSocket access
Requires partnership agreement

Benefits:

No polling required - instant updates pushed to client
No caching needed for live odds
Lower latency for in-play betting
Reduced API call costs

Option 2: Polling with Delta Endpoints

If WebSocket is not available, use the delta endpoints that return only changed odds:

Endpoint	Purpose	Use Case
`/api/v2/{lang}/odds/3sec`	Odds changed in last 3 seconds	In-play betting
`/api/v2/{lang}/odds/10sec`	Odds changed in last 10 seconds	Active matches
`/api/v2/{lang}/odds/30sec`	Odds changed in last 30 seconds	Pre-match updates

Polling Strategy:

In-play matches: Poll /odds/3sec every 3 seconds
Pre-match: Poll /odds/30sec every 30 seconds
Only changed odds are returned (delta updates)

3.4 Caching Strategy

With WebSocket (Recommended):

No caching needed for odds - WebSocket provides real-time stream
Cache only static data (sports, tournaments, fixture metadata)

With Polling (Fallback):

Data Type	Cache Key Pattern	TTL	Notes
Sports catalog	`catalog:sports`	1 hour	Static data
Leagues	`catalog:leagues:{sport}`	1 hour	Static data
Fixtures list	`fixtures:{sport}:{date}`	60 seconds	Metadata only
Match odds	Not cached	N/A	Use delta endpoints
Live scores	`scores:{fixtureId}`	5 seconds	Short TTL

Architecture Decision:

Version 1 Launch: Start with WebSocket if partnership secured
Fallback: Use polling with delta endpoints if WebSocket not available
Redis used primarily for session data, user balances, and static catalog data

3.5 In-Play Betting Support

Version 1 supports both pre-match and in-play betting:

In-Play Considerations:

Odds update in real-time via WebSocket (or every 3 seconds via polling)
Price validation is critical - odds may change between display and placement
acceptBetterOdds: true is recommended for in-play bets
Market suspension handling required (markets may close temporarily)

3.5 Market Types for Version 1

All market types that OddsPAPI can settle are supported. Common markets include:

Market	OddsPAPI marketId	Description
1X2 (Full Time Result)	101	Home/Draw/Away winner
Over/Under	102	Total goals/points threshold
Both Teams to Score	103	Yes/No for both teams scoring
Double Chance	104	Two of three outcomes combined
Match Winner	101	For non-draw sports (Tennis, Cricket)
Asian Handicap	105	Handicap betting with half-goal lines
Correct Score	106	Exact final score prediction
First Half Result	107	1X2 for first half only
Player Props	Various	Player-specific markets (where available)

Note: The system dynamically supports any market type returned by OddsPAPI that has settlement data available. The above are examples of commonly used markets.

4. Order Placement System

4.1 Dual Provider Strategy

The platform uses a dual provider strategy based on sport type:

Sport	Primary Provider	Lay Bet Support	Notes
Cricket	Betfair Exchange	Native	Full exchange functionality with back/lay
All Other Sports	Pinnacle	Converted	Lay converted to back on opposite outcome

All sports available from both providers are supported. The routing is simple:

Cricket → Betfair Exchange
Everything else → Pinnacle

Why This Strategy:

Cricket has excellent liquidity on Betfair Exchange (especially IPL, international matches)
Betfair Exchange supports native lay betting with full market depth
Pinnacle offers sharp odds and high limits for all other sports
User experience remains consistent (Betfair-style UI) regardless of backend provider

4.2 BETS API Integration

All bet placement goes through the BETS API (https://abp.55-tech.com), which routes orders to the appropriate bookmaker.

API Authentication:

API Key: Query parameter apiKey
Bookmaker Auth: Base64-encoded header X-Auth containing credentials for all bookmakers:
```
pinnacle:username:password;betfair-ex:username:password
```

Supported Bookmakers in BETS API:

pinnacle - Pinnacle sportsbook
betfair-ex - Betfair Exchange

4.3 Order Placement Flow

User places bet → Hannibal Backend → Route by Sport → BETS API → Bookmaker → Response → User notification

Routing Logic:

if (sport === "Cricket") {
  bookmaker = "betfair-ex"
  // Use native back/lay
} else {
  bookmaker = "pinnacle"
  if (isLayBet) {
    // Convert lay to back on opposite outcome
    convertedOutcome = getOppositeOutcome(outcomeId)
    back = true
  }
}

4.4 Back vs Lay Betting

Back Bet (Betting FOR an outcome):

User wins if the outcome happens
Stake = Amount risked
Profit = Stake × (Odds - 1)

Lay Bet (Betting AGAINST an outcome):

User wins if the outcome does NOT happen
Liability = Stake × (Odds - 1) — Amount risked
Profit = Stake (the backer's stake)

Lay Bet Handling by Provider:

Provider	Lay Bet Handling
Betfair Exchange	Native support - send `back: false` to BETS API
Pinnacle	Convert to back bet on opposite outcome

Example: Lay Bet Conversion for Pinnacle

User wants to LAY "Team A wins" at odds 2.0 for ₹100 liability:

Identify opposite outcome (e.g., "Team B wins or Draw")
Calculate equivalent back stake
Place BACK bet on opposite outcome via Pinnacle

4.5 Betfair Exchange Market Depth

For Cricket (Betfair), the UI displays full market depth from the exchangeMeta field:

{
  "bookmaker": "betfair-ex",
  "exchangeMeta": {
    "availableToBack": [
      {"size": 84.99, "price": 2.66},
      {"size": 152.16, "price": 2.64},
      {"size": 172.81, "price": 2.62}
    ],
    "availableToLay": [
      {"size": 134.37, "price": 2.68},
      {"size": 103.61, "price": 2.70},
      {"size": 133.70, "price": 2.72}
    ]
  }
}

UI Display:

Show best 3 prices on each side (back and lay)
Blue columns for back prices (descending)
Pink columns for lay prices (ascending)
Display available liquidity at each price level

4.6 Order Placement Examples

Example 1: Back Bet on Cricket (Betfair)

POST /api/v1/place-orders
{
  "orders": [{
    "bookmaker": "betfair-ex",
    "fixtureId": "id1000004461512432",
    "outcomeId": 101,
    "playerId": 0,
    "orderPrice": 2.66,
    "orderStake": 100,
    "userRef": "user_123_order_456",
    "requestUuid": "uuid-here",
    "back": true,
    "currency": "USD"
  }]
}

Example 2: Lay Bet on Cricket (Betfair)

POST /api/v1/place-orders
{
  "orders": [{
    "bookmaker": "betfair-ex",
    "fixtureId": "id1000004461512432",
    "outcomeId": 101,
    "playerId": 0,
    "orderPrice": 2.68,
    "orderStake": 100,
    "userRef": "user_123_order_456",
    "requestUuid": "uuid-here",
    "back": false,
    "currency": "USD"
  }]
}

Example 3: Back Bet on Soccer (Pinnacle)

POST /api/v1/place-orders
{
  "orders": [{
    "bookmaker": "pinnacle",
    "fixtureId": "id1000004461512432",
    "outcomeId": 103,
    "playerId": 0,
    "orderPrice": 1.85,
    "orderStake": 100,
    "userRef": "user_123_order_456",
    "requestUuid": "uuid-here",
    "back": true,
    "currency": "USD"
  }]
}

4.7 Order States

State	Description
pending	Submitted to BETS API, awaiting confirmation
accepted	Bet placed successfully with bookmaker
partially_accepted	Only portion of stake was accepted
declined	Rejected by bookmaker
cancelled	Cancelled before placement
settled	Match complete, outcome determined

4.8 Order Data Model

Order {
  id: UUID
  user_id: UUID
  fixture_id: string
  outcome_id: integer
  market_id: integer
  bookmaker: string ("pinnacle" or "betfair-ex")
  bet_type: enum (back, lay)
  stake: decimal (for back) / liability: decimal (for lay)
  placed_stake: decimal (actual accepted amount)
  odds: decimal (requested)
  placed_odds: decimal (actual placed)
  potential_return: decimal
  status: enum
  bets_api_order_id: integer
  request_uuid: string
  user_ref: string
  created_at: timestamp
  updated_at: timestamp
  settled_at: timestamp (nullable)
  settlement_outcome: enum (win, lose, void, push)
  profit_loss: decimal (nullable)

  // For converted lay bets (Pinnacle)
  original_bet_type: enum (back, lay)
  original_outcome_id: integer (nullable)
  converted: boolean
}

5. Netting Benefit

5.1 How Netting Works

Netting is not a complex engine or internal orderbook. It's the natural benefit that arises from our architecture:

The Setup:

Frontend: Multiple individual user accounts
Backend: ONE single Betfair/Pinnacle account that places all bets

The Mechanism:

Betfair/Pinnacle charges commission on the net winnings of an account. When many users bet through our single account, their individual wins and losses aggregate:

User	Bet	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 Account Net P&L: +₹15,000 - ₹15,000 = ₹0

Commission Calculation:

Exchange 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

5.2 Why It's Automatic

In Version 1, netting requires no special code:

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

The benefit comes from the aggregation itself, not from any matching logic.

5.3 Version 1 Implementation

No Position model or netting engine is needed. We simply:

Track each user's orders in the orders table
Place all bets via our single exchange account
When markets settle, calculate each user's individual P&L
Charge 5% commission on each user's winnings
The exchange charges us commission only on our net account P&L

6. Settlement System

6.1 Settlement Flow

Match Completion Detection
- Poll OddsPAPI /v4/settlements endpoint
- Match status changes to "finished"
Result Retrieval
- Fetch final scores and market outcomes
- Map results to market/outcome IDs
Order Settlement
- For each order on the fixture:
  - Determine win/lose/void/push
  - Calculate profit/loss
  - Update user balance
User Notification
- Push notification (if enabled)
- In-app notification
- Balance update visible immediately

6.2 Settlement Outcomes

Outcome	Description	Balance Action
Win	Selection was correct	Credit: stake × odds
Lose	Selection was incorrect	No action (stake already deducted)
Void	Market cancelled/invalid	Refund full stake
Push	Outcome equals line (tie)	Refund stake
Half Win	Asian handicap half win	Credit: stake × (0.5 × (odds-1) + 1)
Half Lose	Asian handicap half lose	Refund half stake

6.3 Settlement Data Model

Settlement {
  id: UUID
  fixture_id: string
  market_id: integer
  winning_outcome_id: integer (nullable for voids)
  settlement_status: enum (pending, settled, disputed)
  settled_at: timestamp
  raw_data: jsonb (API response)
  orders_affected: integer
  total_payout: decimal
  created_at: timestamp
}

7. Admin Interface

7.1 Admin Dashboard Features

Overview Panel:

Total active users
Daily bet volume
Pending orders count
System health status

User Management:

Search users by email, wallet, ID
View user bet history
Adjust user balance (with audit log)
Suspend/block users

Order Management:

View all orders with filters
Manual order status override
Resend failed orders
Void bets (with reason)

Settlement Admin:

Manual settlement trigger
Settlement override for disputed results
Audit trail for all settlement actions

7.2 Admin Access Control

Role	Permissions
Viewer	Read-only access to all panels
Operator	Manage users, view orders
Admin	Full access including settlements
Super Admin	System configuration, role management

8. Technical Architecture

8.1 Technology Stack

Layer	Technology	Rationale
Frontend	Next.js 14 + React 18	SSR, App Router, excellent mobile performance
Styling	Tailwind CSS	Rapid mobile-first development
State Management	Zustand + React Query	Lightweight, excellent for caching
Backend	Node.js + Express	Familiar, async-capable
Database	PostgreSQL (local)	Full control, robust, ACID compliant
Cache	Redis	Fast in-memory caching for odds
Auth	Reown AppKit	Social login + embedded wallets
API Client	Axios	HTTP client for BETS API
ORM	Prisma	Type-safe database access

8.2 System Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                            FRONTEND                                  │
│                       (Next.js Mobile PWA)                          │
└─────────────────────────┬───────────────────────────────────────────┘
                          │ HTTPS
┌─────────────────────────▼───────────────────────────────────────────┐
│                         API GATEWAY                                  │
│                    (Express + Auth Middleware)                       │
└─────────────────────────┬───────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
   │   Market    │ │   Order     │ │  Settlement │
   │   Service   │ │   Service   │ │   Service   │
   └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
          │               │               │
          ▼               ▼               ▼
   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
   │    Redis    │ │  PostgreSQL │ │  Job Queue  │
   │   (Cache)   │ │  (Database) │ │   (Bull)    │
   └──────┬──────┘ └─────────────┘ └─────────────┘
          │
          ▼
   ┌─────────────────────────────────────────────────────────────────┐
   │                       EXTERNAL APIs                              │
   │           OddsPAPI (odds data) + BETS API (order placement)      │
   └─────────────────────────────────────────────────────────────────┘

8.3 Database Schema (Key Tables)

Core Tables:

users - User accounts linked to Reown AppKit
wallets - User wallet information (EVM and Solana addresses)
orders - All bet orders (netting benefit comes from aggregating these through one exchange account)
settlements - Settlement records
transactions - Balance changes audit log
fixtures_cache - Local cache of fixture data
admin_users - Admin accounts with roles

9. Development Phases

Phase 1: Foundation (Week 1-2)

Project setup (Next.js, PostgreSQL, Redis)
Reown AppKit authentication integration
Basic UI shell with navigation
Database schema and migrations

Phase 2: Market Display (Week 2-3)

OddsPAPI integration via BETS API
Redis caching layer
Sport/League/Match browsing UI
Odds display components
Real-time updates with polling

Phase 3: Order Placement (Week 3-4)

BETS API order integration
Bet slip UI component
Order validation logic
Order status tracking
User notifications

Phase 4: Settlement (Week 4-5)

Settlement polling job
Settlement processing logic
Balance updates with commission charging
Settlement history UI
Netting is automatic (no special code needed)

Phase 5: Admin & Polish (Week 5-6)

Admin dashboard
User management
Order management
Testing and bug fixes
Performance optimization
Documentation

10. API Credentials Required

Service	Credential Type	Storage
Reown AppKit	Project ID	Environment variables
OddsPAPI	API Key	Environment variables
BETS API	API Key + Pinnacle credentials + Betfair credentials	Environment variables (encrypted)
PostgreSQL	Connection string	Environment variables
Redis	Connection URL	Environment variables

BETS API X-Auth Header Format:

Base64(pinnacle:username:password;betfair-ex:username:password)

11. Implementation Status

Last Updated: January 2026

✅ Implemented (Beyond Original V1 Scope)

The following features were originally planned for later versions but have been implemented:

Feature	Original Plan	Status
B-book functionality	Version 2	✅ Complete - Full B-book with filter engine, exposure limits, sharp user exclusion
Agent distribution system	Version 3 (as "Multi-Tenant")	✅ Complete - Full agent hierarchy with revenue sharing, settlement periods
In-play betting	Version 4	✅ Complete - WebSocket real-time odds
AI integration (Foundation)	Future	🟡 Partial - Basic fixture analysis, chat, watchlist/agent CRUD only

🟡 Partially Implemented

Feature	Status	What's Missing
AI Features	Foundation only	See `HANNIBAL_AI_FEATURES_2026.md` - 11 of 12 feature categories not implemented

🔴 Not Yet Implemented

The following features remain for future development:

Feature	Priority	Notes
USDC payments	High	Deposit/withdrawal via crypto wallets
AI Agentic System	High	Natural language agents, learning conditions, marketplace
AI Smart Watchlists	High	AI alerts, daily briefings, concept watchlists
Cash out	Medium	Early settlement of open bets
Bet builder/accumulators	Medium	Multi-selection combination bets
AI Conversational Betting	Medium	Natural language bet placement
AI Portfolio Intelligence	Medium	Portfolio view, risk analysis, hedge suggestions
Native mobile apps	Low	PWA currently works well
Limit orders	Low	Order book for unmatched bets
AI Voice Interface	Low	Voice commands and multimodal features
AI Memory & Personalization	Low	Persistent memory, preference learning

12. Success Metrics

Metric	Target
Page load time (mobile)	< 2 seconds
Bet placement latency	< 3 seconds
Odds update frequency	Real-time via WebSocket
Settlement time after match	< 15 minutes
System uptime	99.5%
API error rate	< 1%

Executive Summary​

1. User Interface Design​

1.1 Design Philosophy​

1.2 Color Scheme​

1.3 Mobile-First Layout​

1.4 Betfair-Style Exchange UI​

2. Authentication System​

2.1 Reown AppKit Integration​

2.2 Supported Login Methods​

2.3 Authentication Flow​

2.4 Multi-Chain Wallet Architecture​

2.5 Wallet Management​

2.6 User Data Model​

2.7 Tron Wallet Consideration​

3. Market Display & Odds Data​

3.1 Data Source Architecture​

3.2 OddsPAPI Integration​

3.3 Real-Time Odds Updates​

Option 1: WebSocket (Recommended for Production)​

Option 2: Polling with Delta Endpoints​

3.4 Caching Strategy​

3.5 In-Play Betting Support​

3.5 Market Types for Version 1​

4. Order Placement System​

4.1 Dual Provider Strategy​

4.2 BETS API Integration​

4.3 Order Placement Flow​

4.4 Back vs Lay Betting​

4.5 Betfair Exchange Market Depth​

4.6 Order Placement Examples​

4.7 Order States​

4.8 Order Data Model​

5. Netting Benefit​

5.1 How Netting Works​

5.2 Why It's Automatic​

5.3 Version 1 Implementation​

6. Settlement System​

6.1 Settlement Flow​

6.2 Settlement Outcomes​

6.3 Settlement Data Model​

7. Admin Interface​

7.1 Admin Dashboard Features​

7.2 Admin Access Control​

8. Technical Architecture​

8.1 Technology Stack​

8.2 System Diagram​

8.3 Database Schema (Key Tables)​

9. Development Phases​

Phase 1: Foundation (Week 1-2)​

Phase 2: Market Display (Week 2-3)​

Phase 3: Order Placement (Week 3-4)​

Phase 4: Settlement (Week 4-5)​

Phase 5: Admin & Polish (Week 5-6)​

10. API Credentials Required​

11. Implementation Status​

✅ Implemented (Beyond Original V1 Scope)​

🟡 Partially Implemented​

🔴 Not Yet Implemented​

12. Success Metrics​