SYSTEM ARCHITECTURE
SCAN PIPELINE — 9 STEPS

How the Wallet
Scanner Works

Every scan runs through a deterministic 9-step pipeline. Steps 4, 5, and 6 run in parallel to minimise latency. Results are cached for 7 days to protect Arkham API credits.

Steps 4, 5 & 6 run in parallel

Arkham inbound transfers, Arkham outbound transfers, Hyperliquid volume, and Slice Analytics all fire simultaneously via Promise.allSettled(). Total wall-clock time is dominated by the slowest of these (~10–15s for Arkham), not their sum.

01

Wallet Submitted

User / CTO API call

A wallet address is submitted — either via the web UI or a direct API call to POST /api/scan/:address. Supports EVM (0x…), Solana, and Tron (T…) addresses.

  • Address format validated (EVM / Solana / Tron regex)
  • Invalid addresses rejected immediately — no API calls made
  • API key checked for programmatic access
< 1ms
02

Cache Check

Housebets DB (TiDB)

Before hitting any external API, the server checks the local database for a cached result. If the same wallet was scanned within the last 7 days, the stored result is returned instantly — zero Arkham credits consumed.

  • Lookup by normalised wallet address (lowercase)
  • Cache TTL: 7 days from scan time
  • Cache hit → return instantly (~50ms, 0 Arkham credits)
  • Cache miss → proceed to live scan
~50ms
Arkham: 0 credits (cache hit)
03

Address Intelligence

Arkham API — 1 credit

Arkham's intelligence endpoint resolves the wallet address to a known entity (e.g. 'Binance Hot Wallet 3', 'Vitalik Buterin'). This is used for two purposes: exchange wallet exclusion and display labelling.

  • Detects exchange/CEX wallets (Binance, Coinbase, Kraken, etc.)
  • Exchange wallets are excluded immediately — scan stops here
  • Returns entity name and type for display
  • Cost: 1 Arkham credit
~300ms
Arkham: 1 credit
04

Transfer Fetch (Parallel)

Arkham API — up to 1,000 credits

Two Arkham transfer fetches run in parallel — inbound and outbound — covering the last 3 years of on-chain activity. Each fetch retrieves up to 500 transfers at 2 credits per row.

  • Inbound transfers: used for Whale Score (peak balance calculation)
  • Outbound transfers: used for Casino, Perps, and DEX scoring
  • Max 500 transfers per direction (1,000 total)
  • Fetched in parallel — both run simultaneously
  • Cost: up to 1,000 Arkham credits (2 per transfer row)
8–15s (parallel)
Arkham: Up to 1,000 credits
05

Hyperliquid Volume

Hyperliquid API — free

Simultaneously with the Arkham fetch, the Hyperliquid native API is queried for the wallet's all-time trading volume (cumVlm). This is the only perps platform with a direct volume API — all others are measured via on-chain deposits.

  • Runs in parallel with Arkham transfer fetches
  • Returns cumulative trading volume (not deposits)
  • EVM addresses only — Solana/Tron wallets skip this step
  • Free — no API credits consumed
  • Timeout: 10s (graceful skip if unavailable)
~500ms (parallel)
Arkham: Free
06

Slice Analytics

Slice API — parallel

The Slice Analytics API is queried in parallel with Arkham. Slice provides an independent scoring signal — particularly for Polymarket prediction market activity. If Slice returns a higher volume for any category, it overrides the Arkham figure.

  • Runs in parallel with Arkham scan
  • Source of truth for Polymarket score
  • If Slice volume > Arkham volume for a category → Slice wins
  • Graceful degradation: if Slice is down, Arkham result is used
  • dataSource field in response: 'arkham' | 'slice' | 'both'
~2–5s (parallel)
Arkham: Slice plan
07

Category Scoring

In-memory — no API calls

All 500 outbound transfers are processed in a single pass. Each transfer is classified into Casino, Perps, or DEX using a priority chain: entity type first (most reliable), then keyword matching (fallback). Volume is accumulated per platform.

  • Casino: entityType 'gambling' or keyword match (50+ keywords)
  • Perps: entityType 'derivatives' first, then keyword fallback (20+ protocols)
  • DEX: entityType 'dex' / 'dex-aggregator' first, then keyword fallback
  • Hyperliquid volume added to Perps total post-classification
  • Whale: peak running balance computed from inbound transfers
  • Single-pass O(n) — no additional API calls
< 10ms
Arkham: 0 credits
08

Tier Lookup & Winner

In-memory — no API calls

Each category's total volume is looked up against its tier table (Casino: 25 tiers, Perps: 15, DEX: 15, Whale: 30). The highest reward across all categories becomes the winning offer. Turnover is calculated using an EV-optimised multiplier.

  • Casino tiers: 25 levels, $1 → $100M+ deposits
  • Perps tiers: 15 levels, $1 → $5M+ margin deposited
  • DEX tiers: 15 levels, $1K → $100M+ swap volume
  • Whale tiers: 30 levels, $500 → $2.1M+ peak balance
  • Winner = highest reward (ties broken by level)
  • Turnover = EV-optimised (2x–5x based on tier)
< 1ms
Arkham: 0 credits
09

Result Cached & Returned

Housebets DB + Response

The final merged result is stored in the database with a 24-hour expiry (fire-and-forget — doesn't delay the response). The full result is returned to the caller in a single JSON response.

  • Result stored in scan_cache table (fire-and-forget)
  • Next scan of same wallet within 24h → instant cache hit
  • Response includes: winning category, level, reward, turnover
  • Response includes: all 4 category scores + top platforms
  • fromCache: true/false flag in response
  • elapsedMs: total scan time in milliseconds
< 5ms
Arkham: 0 credits

Arkham Credit Cost by Scenario

ScenarioCreditsWall Time
Exchange wallet (rejected at step 3)1~400ms
Cache hit (same wallet, < 24h)0~50ms
Fresh scan — low-activity wallet (< 100 transfers)~202~5–8s
Fresh scan — typical wallet (500 transfers)~1,002~10–15s
Fresh scan — max depth (500 per direction)~1,002~12–18s

* Arkham charges 2 credits per transfer row returned. 1 credit for intelligence lookups. Current plan: 10,000 credits/month. Contact [email protected] for enterprise pricing.

Data Sources & Detection Logic

Casino Detection

  • entityType: 'gambling' (Arkham label) — primary
  • 50+ keyword matches (stake, rollbit, roobet, bc.game…)
  • Measures: gross outbound deposits to gambling platforms
  • Tiers: 25 levels ($1 → $100M+)

Perps Detection

  • entityType: 'derivatives' (Arkham label) — primary
  • 20+ keyword matches (gmx, synthetix, drift, aevo…)
  • Hyperliquid native API: cumVlm (EVM only)
  • Measures: margin/collateral deposited (not notional volume)
  • Tiers: 15 levels ($1 → $5M+)

DEX Detection

  • entityType: 'dex' / 'dex-aggregator' — primary
  • 20+ keyword matches (uniswap, curve, 1inch, cowswap…)
  • Measures: outbound token value in swaps
  • Tiers: 15 levels ($1K → $100M+)

Whale Score

  • Peak historical balance (running max of inbound − outbound)
  • Not total volume — measures maximum wealth held at one time
  • Tiers: 30 levels ($500 → $2.1M+ peak balance)
  • X Boost: 100%–750% extra when player shares on X

REST API Reference

GET/api/scan/:address

Full wallet scan. Returns winning category, level, reward, turnover, and all category scores. Cached for 24h.

POST/api/claim/:address

Mark a wallet as having claimed their reward. EVM addresses only. Calls Slice PUT /claim.

Authorization: Bearer <HOUSEBETS_API_KEY> — contact the team to obtain a key.