Latest Features

This release adds a more enterprise-ready front page, richer live crypto mapping, stronger administration controls, and a clearer workflow for using Blue River as an on-chain intelligence application.

Quick Start

Get up and running with Blue River in under 5 minutes.

1. Create an account at the home page or log in with Google OAuth.
2. Navigate to the Explorer from the top menu to start analyzing wallets.
3. Enter a wallet address and select the blockchain (BTC, ETH, SOL, etc.).
4. View the analysis including risk score, IP traces, geolocation, and wallet attribution.
5. Open Live Map to switch between the dark 2D map and 3D globe view for global wallet activity.
6. Review Dashboard trends for major cryptocurrency movement across 1D, 1W, 1M, 3M, 6M, and 1Y windows.
7. Add to watchlist to receive alerts for future activity.

Account Setup

Registration

You can register with an email and password (minimum 8 characters) or use Google OAuth for instant access. Passwords are hashed using PBKDF2-SHA256 with 75,000 iterations.

Access and Subscription

• Trial access: New users receive a short trial window to explore the platform before subscription is required.
• Enterprise subscription: The paid plan is positioned at 199 USD monthly for continued access to the application.
• Admin access: Hardcoded administrator emails receive immediate admin privileges and bypass normal trial gating.
• Role-aware experience: Admin users see the Admin Panel quick link; standard users see the operational dashboard, explorer, live map, watchlists, AI, and settings areas based on access.

Using the Explorer

The Explorer is your primary interface for wallet analysis. Enter any supported address to receive:

• Basic Info: Label attribution, exchange identification, last known IP
• Risk Score: 0-100 score with explainable breakdown
• IP Trace: Last known IP, ISP/exchange, approximate geolocation
• Transactions: Recent transaction history with counterparties
• Map: Visual location on the interactive map

IP Tracing Guide

How It Works

Blue River uses multiple data sources to attribute IP addresses to wallets:

1. Exchange IP Database: Curated mappings of known exchange IP ranges to their operational entities
2. Transaction Metadata: Analysis of transaction relay patterns and node behavior
3. Public GeoIP: ip-api.com integration for city-level geolocation of IP addresses
4. Historical Traces: Time-series tracking of IP changes per wallet

Interpreting Results

When viewing IP traces, consider these confidence levels:

• High confidence: Wallet is an exchange hot/cold wallet with direct IP mapping
• Medium confidence: IP traced to known exchange infrastructure but not directly confirmed
• Low confidence: IP resolved via GeoIP only; could be VPN, proxy, or relay node

API Example

POST /api/wallet/ip-trace
Content-Type: application/json

{
  "chain": "btc",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
}

Response:
{
  "chain": "btc",
  "address": "bc1q...",
  "traces": [{
    "ip": "52.84.129.47",
    "source": "exchange",
    "txHash": "0x...",
    "exchange": "Binance",
    "location": "Tokyo, JP",
    "lat": 35.6895,
    "lon": 139.6917,
    "asn": "AS16509",
    "lastSeen": "2025-04-28T14:23:11Z"
  }]
}

Geo Mapping and Global Crypto Traffic

Blue River provides multiple map experiences for demonstrations, investigations, and executive-level situational awareness.

Landing Page 3D Globe

The front page now includes an interactive dark 3D globe with dense global crypto traffic arcs, wallet cluster points, and exchange hub activity. It is designed to be visually impressive for stakeholder demos while still representing the application's global wallet intelligence theme.

• Drag to rotate: Click and hold on the globe, then move left or right to inspect different regions.
• Scroll to zoom: Use the mouse wheel or trackpad scroll to zoom in and out of the globe.
• Dense traffic mode: More routes and animated arcs are shown across major hubs in Asia, Europe, the Middle East, and North America.
• No frame effect: The globe is visually blended into the landing page rather than shown as a boxed widget.

Live 2D Map

The 2D map uses dark-themed mapping with color-coded markers per cryptocurrency. Click any marker to see wallet details, balance, IP attribution, exchange name, and location context.

• Filter by cryptocurrency, exchange, wallet type, or node activity.
• Use Select All and Clear All controls to quickly adjust visible chains.
• Zoom into dense clusters for country, exchange, and wallet-level review.
• Open the detail panel to review address, balance, recent transaction value, IP, ASN, and country context.

Live 3D Globe View

The Live Map also includes a 3D globe mode for rotating global wallet infrastructure and high-value wallet locations. Use this when explaining cross-border flows, exchange concentration, or global crypto exposure.

Risk Scoring

The risk engine evaluates 100+ dimensions across these categories:

• Volume: Total USD value, large transaction count, velocity
• Frequency: Transaction count, burst patterns, time-of-day clustering
• Counterparties: Diversity, known entities, mixer interactions
• Exchange: Exchange diversity, hot wallet patterns, jurisdiction spread
• Temporal: Sudden activity spikes, dormant-then-active patterns

Each score comes with a detailed explanation listing the specific signals that contributed.

AI Assistant

The AI assistant supports natural language queries about on-chain data, wallet risk, market trends, and investigation workflows. It can use Workers AI first, with Kimi or OpenAI-compatible fallback providers when configured.

Example Queries

• "Why is this wallet flagged as high risk?"
• "Explain the transaction pattern for address 0x..."
• "What exchanges has this wallet interacted with?"
• "Compare the risk profiles of these two wallets"
• "Summarize the last 30 days of activity"

Watchlists & Alerts

Pro and Developer plans support unlimited watchlists and configurable alerts.

Creating a Watchlist

1. Go to Watchlists from the navigation menu
2. Click "New Watchlist" and enter a name
3. Add addresses by chain and optional labels
4. Set alert thresholds (transaction value, frequency)

Alert Channels

• In-app: Real-time notifications in the dashboard
• Telegram: Connect your Telegram bot for push notifications

Telegram Setup

Connect Telegram from Settings or Alerts page. You will receive a deep link to start the Blue River bot. Use /start [user_id] to link your account.

Portfolio Analytics

Track your personal crypto holdings with real-time valuation:

• Add holdings with symbol, amount, and average buy price
• View current value, profit/loss, and percentage returns
• Historical price charts from D1 database cache

Dashboard and Market Trends

The dashboard is the operational overview for authenticated users. It combines market movement, whale activity, watchlist signals, portfolio context, and AI-assisted workflows.

Market Trend Windows

Major cryptocurrencies can be viewed across standard time windows:

• Line trend view: Shows price movement for the selected symbol and time range.
• Bar comparison view: Compares major assets by 24-hour movement, volume, and market data.
• Fallback data: If the database has limited history, the dashboard generates synthetic trend points from the latest market snapshot so the page remains useful instead of empty.
• Supported major symbols: BTC, ETH, SOL, BNB, XRP, DOGE, ADA, TRX, TON, and AVAX.

Whale Tape and Activity

The whale tape now builds a multi-chain view from enriched top-wallet data first, then falls back to large transaction records and demo data where required. This prevents the dashboard from looking empty when transaction tables are sparse.

API Reference

All API endpoints accept and return JSON. Authentication via Bearer token or session cookie.

Authentication

Authorization: Bearer <session_token>

Core Endpoints

Export & Reports

Developer plan users can export comprehensive reports:

• CSV: Transaction data, wallet labels, price history
• PDF: Formatted investigation reports with maps and charts

Admin Panel

The Admin Panel is available to administrator users only. It is used to manage accounts, access, and user support without manually editing the database.

What admins can do

• List users: Review registered users, plan levels, roles, Stripe identifiers, and account creation dates.
• Create users: Add users with email, name, password, plan, and role.
• Update users: Change plan, role, display name, or reset password.
• Delete users: Remove standard users and related sessions, alerts, portfolio records, and AI conversations.
• Protect administrator accounts: Hardcoded administrator emails cannot be removed from the admin panel.

Instant administrator emails

The application grants administrator privileges automatically to configured trusted emails. These accounts are treated as admin even if their stored role is not manually updated.

Supported Chains

FAQ

Is IP tracing accurate?

IP traces show the last known relay node or exchange endpoint, not necessarily the wallet owner's physical location. Exchange wallets show the exchange's server location. Private wallets may show VPN, proxy, or ISP locations.

Can I export data?

CSV export is available on the Developer plan. PDF reports are generated server-side and also require Developer.

How fresh is the data?

Price data is fetched from CoinGecko when available and cached in D1. Wallet labels, IP traces, and top-wallet geo points are stored in D1, with fallback demo data used when live data is unavailable so the dashboard and maps remain presentable.

Is my data private?

All queries and watchlists are private to your account. We do not share or sell user data. Sessions and trial access follow the configured Worker policy; current builds use short trial gating and subscription checks for continued use.

Troubleshooting

"Database not configured" error

Ensure your wrangler.toml has the D1 database binding: [[d1_databases]] with binding = "DB".

IP traces return empty

New or rarely-used addresses may have no traceable IP history. Try known exchange hot wallets to verify the system is working. Also check that ip-api.com is accessible from your Worker region.

Landing globe does not drag or zoom

Hard refresh the page after deployment to clear cached HTML and JavaScript. On desktop, place the cursor directly over the globe, then drag to rotate and scroll to zoom. If interaction still fails, check that the globe container is not covered by another overlay and that pointer events are enabled for the globe layer.

Landing globe traffic looks too sparse

Refresh the deployed Worker and confirm the latest file is live. The updated landing page uses a denser route set and more wallet cluster points; older cached versions may still show a quieter globe.

Map shows no markers

Ensure the /api/all-crypto-geo endpoint returns data. If empty, seed the database via POST /api/seed-wallets.

AI assistant not responding

Verify that KIMI_API_KEY or OPENAI_API_KEY is set in your Worker environment variables.