Roanuz Cricket API — Data Provider Integration

What is Roanuz?

Roanuz is a cricket data API providing live scores, ball-by-ball updates, scorecards, commentary, fixtures, and player/team data. Hannibal uses Roanuz as the primary data provider for cricket — it does NOT handle betting or odds. Betting goes through Bifrost/Betfair; Roanuz provides the match data layer.

Official docs: https://www.cricketapi.com/v5/docs/guides/first-step

API Architecture

Data delivery: REST API (pull-based) + Socket.IO WebSocket (push-based for live matches)
Authentication: API key → POST /v5/core/{project_key}/auth/ → receive rs-token
Base URL: https://api.sports.roanuz.com
WebSocket URL: http://socket.sports.roanuz.com/cricket (path: /v5/websocket)
All endpoints: GET /v5/cricket/{project_key}/{endpoint}/ with rs-token header

Directory Structure

roanuz/
├── README.md                                ← You are here
├── HANNIBAL_INTEGRATION.md                  ← How Hannibal uses Roanuz (existing code map)
├── api-inventory.md                         ← Live audit (2026-05-14): which endpoints return 200/403/404 + 5 adapter bugs
├── sample-responses/                        ← Captured prod responses backing the audit (8 endpoints)
└── api/                                     ← Roanuz API reference (from official docs)
    ├── 00-authentication.md                 ← Auth flow, token management
    ├── 01-guides.md                         ← Caching, error handling, resource keys, data structure
    ├── 02-featured-matches.md               ← Featured matches endpoint ★ USED
    ├── 03-fixtures.md                       ← Fixtures list endpoint ★ USED
    ├── 04-match-details.md                  ← Match details endpoint ★ USED
    ├── 05-ball-by-ball.md                   ← Ball-by-ball endpoint ★ USED
    ├── 06-match-commentary.md               ← Commentary endpoint ★ USED
    ├── 07-match-scorecard.md                ← Scorecard endpoint ★ USED (implied)
    ├── 08-match-websocket.md                ← WebSocket subscription ★ USED
    ├── 09-overs-summary.md                  ← Overs summary endpoint
    ├── 10-associations.md                   ← Associations list endpoint
    ├── 11-tournaments.md                    ← Tournament endpoints (featured, fixtures, details, points, teams)
    ├── 12-odds.md                           ← Live & pre-match odds endpoints
    ├── 13-stats.md                          ← Tournament stats & player stats
    ├── 14-visualizations.md                 ← Worm, Manhattan, Run Rate, Wagon Zone
    ├── 15-misc.md                           ← Country list, flags, venue list, news, fantasy
    └── 16-refresh-intervals.md              ← API endpoint refresh intervals

★ = Currently used in Hannibal's RoanuzDataAdapter

Hannibal Integration Summary

What We Use Today

Roanuz API Endpoint	Hannibal Code	Purpose
`POST /v5/core/{key}/auth/`	`RoanuzDataAdapter.refreshToken()`	Token management
`GET /featured-matches-2/`	`RoanuzDataAdapter.getMatches()`	Live/curated match list
`GET /fixtures/`	`RoanuzDataAdapter.getMatches()`	Scheduled/upcoming matches
`GET /match/{matchId}/`	`RoanuzDataAdapter.getMatchState()`, `getRelatedBalls()`, `getVenueStatistics()`	Match details, live state, related balls
`GET /match/{matchId}/ball-by-ball/`	`RoanuzDataAdapter.getBallByBall()`	Ball-by-ball data
`GET /match/{matchId}/commentary/`	`RoanuzDataAdapter.getCommentary()`	Commentary entries
`GET /match/{matchId}/scorecard/`	`RoanuzDataAdapter.getScorecard()`	Full scorecard
WebSocket (Socket.IO)	`RoanuzWebSocketManager`	Real-time match updates

What We DON'T Use Yet (Available)

Roanuz API	Potential Use
Tournament endpoints	Tournament-level navigation, points tables
Live/Pre-match odds	Cross-reference with Bifrost/Betfair odds
Tournament stats	Player/team stats for AI analysis
Worm/Manhattan/Run Rate	Visualization data for UI
Wagon Zone	Batting zone analysis
Match Insights	AI-ready match insights
News Aggregator	Cricket news feed

Key Files

backend/src/
├── config/index.ts                          — ROANUZ_* env vars
├── exchanges/adapters/roanuz/
│   ├── index.ts                             — Module exports
│   ├── RoanuzDataAdapter.ts                 — IDataProvider implementation (REST)
│   └── RoanuzWebSocketManager.ts            — Socket.IO real-time manager
├── services/cricket/
│   ├── ballByBallService.ts                 — AI commentary on ball events
│   ├── cricketAnalysisService.ts            — Match analysis with Roanuz data
│   ├── cricketIdResolver.ts                 — Betfair↔Roanuz match ID mapping
│   ├── tossAnalysisService.ts               — Toss decision analysis
│   └── sessionBettingService.ts             — Session betting analysis
├── services/clientWs.ts                     — WebSocket relay to frontend
└── routes/cricket.ts                        — Cricket API routes

Environment Variables

ROANUZ_ENABLED=true
ROANUZ_PROJECT_KEY=<project_key>
ROANUZ_API_KEY=<api_key>
ROANUZ_BASE_URL=https://api.sports.roanuz.com    # default
ROANUZ_WS_URL=wss://api.sports.roanuz.com        # default
ROANUZ_TIMEOUT=10000                              # default ms
ROANUZ_RATE_LIMIT=100                             # default req/s

What is Roanuz?​

API Architecture​

Directory Structure​

Hannibal Integration Summary​

What We Use Today​

What We DON'T Use Yet (Available)​

Key Files​

Environment Variables​