feat: Helius real on-chain wallet analysis

- Add helius.ts client: fetches 50 txs, computes daysInactive/protocols/streak/volumeDropPct/hasLiquidation
- Add /api/helius/analyze POST endpoint with optional autoFire Torque event integration
- Wire LiveAnalyzer component into WalletsPage JSX

src/app/(dashboard)/wallets/page.tsx

@@ -4,11 +4,138 @@ import { wallets } from '@/lib/mock-data'
 import { RiskBadge } from '@/components/ui/RiskBadge'
 import { RecoveryCard } from '@/components/ui/RecoveryCard'
 import { useToast } from '@/components/ui/Toast'
-import { Search, Flame, ExternalLink, ChevronRight, Zap, CheckCircle2, Loader2, Siren, Share2, AlertTriangle } from 'lucide-react'
+import { Search, Flame, ExternalLink, ChevronRight, Zap, CheckCircle2, Loader2, Siren, Share2, AlertTriangle, Radio } from 'lucide-react'
 import { useState, useCallback, useMemo } from 'react'
 import type { ChurnRisk, Wallet } from '@/lib/types'
 import { classifyWalletType } from '@/lib/agent-engine'
 
+// --- Live Wallet Analyzer (Helius) ---
+interface LiveResult {
+  address: string; score: number; risk: string; detectedSignals: string[]
+  signals: { daysInactive: number; protocols: string[]; currentStreak: number; volumeDropPct: number; totalTxLast30d: number; lastActiveDaysAgo: string }
+  torque: { fired: boolean; eventId?: string; eventName?: string }
+}
+
+function LiveAnalyzer() {
+  const [addr, setAddr] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [result, setResult] = useState<LiveResult | null>(null)
+  const [err, setErr] = useState<string | null>(null)
+  const [autoFire, setAutoFire] = useState(false)
+  const { fire: toast } = useToast()
+
+  const analyze = useCallback(async () => {
+    if (!addr.trim() || loading) return
+    setLoading(true); setErr(null); setResult(null)
+    try {
+      const res = await fetch('/api/helius/analyze', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ address: addr.trim(), autoFire }),
+      })
+      const data = await res.json()
+      if (!res.ok) { setErr(data.error); return }
+      setResult(data)
+      if (data.torque?.fired) {
+        toast({ type: 'event', title: `${data.torque.eventName} → ${addr.slice(0,8)}...`, body: data.torque.eventId?.slice(0,10) })
+      }
+    } catch (e: any) {
+      setErr(e.message)
+    } finally {
+      setLoading(false)
+    }
+  }, [addr, autoFire, loading, toast])
+
+  const RISK_CLR: Record<string, string> = { critical:'text-trading-down', high:'text-[#ff9500]', medium:'text-brand-yellow', low:'text-trading-up', safe:'text-muted' }
+  const RISK_BG: Record<string, string> = { critical:'border-trading-down/30 bg-trading-down/5', high:'border-[#ff9500]/30 bg-[#ff9500]/5', medium:'border-brand-yellow/30 bg-brand-yellow/5', low:'border-trading-up/30 bg-trading-up/5', safe:'border-hairline-dark bg-surface-elevated' }
+
+  return (
+    <div className="rounded-xl bg-surface-card border border-hairline-dark overflow-hidden">
+      <div className="px-5 py-4 border-b border-hairline-dark flex items-center gap-2">
+        <Radio className="w-4 h-4 text-trading-up" />
+        <h3 className="text-title-sm">Live Wallet Analyzer</h3>
+        <span className="text-[10px] px-2 py-0.5 rounded-pill bg-trading-up/10 text-trading-up font-semibold border border-trading-up/20">HELIUS</span>
+        <p className="text-caption text-muted ml-1">Enter any Solana address — real on-chain churn score</p>
+      </div>
+      <div className="p-5 space-y-4">
+        <div className="flex gap-2">
+          <input
+            value={addr} onChange={e => setAddr(e.target.value)}
+            onKeyDown={e => e.key === 'Enter' && analyze()}
+            placeholder="Enter Solana wallet address..."
+            className="flex-1 h-10 px-4 rounded-lg bg-surface-elevated border border-hairline-dark text-body-sm text-[#eaecef] placeholder:text-muted focus:outline-none focus:ring-1 focus:ring-brand-yellow/50 font-mono"
+          />
+          <label className="flex items-center gap-2 px-3 rounded-lg border border-hairline-dark bg-surface-elevated cursor-pointer select-none">
+            <input type="checkbox" checked={autoFire} onChange={e => setAutoFire(e.target.checked)} className="accent-brand-yellow" />
+            <span className="text-caption text-muted whitespace-nowrap">Auto-fire Torque</span>
+          </label>
+          <button onClick={analyze} disabled={loading || !addr.trim()}
+            className="flex items-center gap-2 px-4 py-2 rounded-lg bg-brand-yellow text-ink text-button font-semibold hover:bg-brand-yellow-active transition disabled:opacity-50">
+            {loading ? <Loader2 className="w-4 h-4 animate-spin" /> : <Zap className="w-4 h-4" />}
+            {loading ? 'Scanning...' : 'Analyze'}
+          </button>
+        </div>
+
+        {err && <p className="text-body-sm text-trading-down px-1">Error: {err}</p>}
+
+        {result && (
+          <div className={cn('rounded-xl border p-4 space-y-3', RISK_BG[result.risk] || 'border-hairline-dark')}>
+            <div className="flex items-center justify-between">
+              <div>
+                <p className="font-mono text-body-sm text-[#eaecef]">{result.address.slice(0,8)}...{result.address.slice(-6)}</p>
+                <a href={`https://solscan.io/account/${result.address}`} target="_blank" rel="noreferrer" className="text-caption text-muted hover:text-brand-yellow transition flex items-center gap-1 mt-0.5">
+                  <ExternalLink className="w-3 h-3" />View on Solscan
+                </a>
+              </div>
+              <div className="text-right">
+                <p className={cn('font-mono text-display-sm font-bold tabular-nums', RISK_CLR[result.risk])}>{result.score}</p>
+                <p className={cn('text-caption font-bold uppercase', RISK_CLR[result.risk])}>{result.risk}</p>
+              </div>
+            </div>
+            <div className="grid grid-cols-4 gap-3">
+              <div className="rounded-lg bg-surface-elevated p-2.5 text-center">
+                <p className="text-[10px] text-muted">Inactive</p>
+                <p className="font-mono text-body-sm text-[#eaecef] mt-0.5">{result.signals.lastActiveDaysAgo}</p>
+              </div>
+              <div className="rounded-lg bg-surface-elevated p-2.5 text-center">
+                <p className="text-[10px] text-muted">Streak</p>
+                <p className="font-mono text-body-sm text-[#eaecef] mt-0.5">{result.signals.currentStreak}d</p>
+              </div>
+              <div className="rounded-lg bg-surface-elevated p-2.5 text-center">
+                <p className="text-[10px] text-muted">Vol drop</p>
+                <p className="font-mono text-body-sm text-[#eaecef] mt-0.5">{result.signals.volumeDropPct}%</p>
+              </div>
+              <div className="rounded-lg bg-surface-elevated p-2.5 text-center">
+                <p className="text-[10px] text-muted">30d txs</p>
+                <p className="font-mono text-body-sm text-[#eaecef] mt-0.5">{result.signals.totalTxLast30d}</p>
+              </div>
+            </div>
+            {result.signals.protocols.length > 0 && (
+              <div className="flex flex-wrap gap-1">
+                {result.signals.protocols.map(p => <span key={p} className="text-[10px] px-1.5 py-0.5 rounded bg-surface-elevated text-muted">{p}</span>)}
+              </div>
+            )}
+            {result.detectedSignals.length > 0 && (
+              <div className="space-y-1">
+                {result.detectedSignals.map((s, i) => <p key={i} className="text-caption text-muted flex items-center gap-1.5"><span className="text-trading-down">↑</span>{s}</p>)}
+              </div>
+            )}
+            {result.torque.fired && (
+              <div className="flex items-center gap-2 p-2.5 rounded-lg bg-trading-up/10 border border-trading-up/30">
+                <CheckCircle2 className="w-4 h-4 text-trading-up flex-shrink-0" />
+                <div>
+                  <p className="text-caption text-trading-up font-semibold">{result.torque.eventName} fired via Torque</p>
+                  <p className="font-mono text-[10px] text-muted">{result.torque.eventId}</p>
+                </div>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
 type Filter = ChurnRisk | 'all'
 const filters: Filter[] = ['all', 'critical', 'high', 'medium', 'low', 'safe']
 
@@ -174,6 +301,8 @@ export default function WalletsPage() {
         </div>
       </div>
 
+      <LiveAnalyzer />
+
       <div className="grid grid-cols-2 lg:grid-cols-6 gap-3">
         {filters.map(r => (
           <button key={r} onClick={() => setF(r)} className={cn('rounded-xl border p-3 text-center transition-all', f === r ? 'border-brand-yellow/40 bg-brand-yellow/5' : 'border-hairline-dark bg-surface-card hover:border-brand-yellow/20')}>

src/app/api/helius/analyze/route.ts

@@ -0,0 +1,65 @@
+import { NextResponse } from 'next/server'
+import { fetchWalletSignals, isHeliusConfigured } from '@/lib/helius'
+import { calculateChurnScore } from '@/lib/agent-engine'
+import { sendCustomEvent, isTorqueConfigured } from '@/lib/torque-mcp'
+import { pushEvent } from '@/lib/event-store'
+import { recordIntervention } from '@/lib/attribution-store'
+
+export async function POST(req: Request) {
+  const { address, autoFire = false } = await req.json()
+
+  if (!address || typeof address !== 'string') {
+    return NextResponse.json({ error: 'address required' }, { status: 400 })
+  }
+  if (!isHeliusConfigured()) {
+    return NextResponse.json({ error: 'HELIUS_API_KEY not configured' }, { status: 503 })
+  }
+
+  const signals = await fetchWalletSignals(address)
+  if (!signals) {
+    return NextResponse.json({ error: 'Failed to fetch wallet data from Helius' }, { status: 502 })
+  }
+
+  const { score, risk, signals: detectedSignals } = calculateChurnScore({
+    daysInactive: signals.daysInactive,
+    volumeDropPct: signals.volumeDropPct,
+    uniqueProtocols: signals.uniqueProtocols,
+    currentStreak: signals.currentStreak,
+    hasLiquidation: signals.hasLiquidation,
+  })
+
+  let torqueResult: { fired: boolean; eventId?: string; eventName?: string } = { fired: false }
+
+  if (autoFire && isTorqueConfigured() && (risk === 'critical' || risk === 'high' || risk === 'medium')) {
+    const eventName = risk === 'critical' || risk === 'high' ? 'churn_risk_high' : 'churn_risk_medium'
+    const result = await sendCustomEvent(address, eventName, {
+      risk, score,
+      daysInactive: signals.daysInactive,
+      protocols: signals.protocols,
+      source: 'helius_live',
+      detectedBy: 'flowstate-helius-scan',
+    })
+    if (result.success && result.eventId) {
+      pushEvent({
+        ingestionId: result.eventId,
+        wallet: address,
+        eventName,
+        risk,
+        score,
+        firedAt: new Date().toISOString(),
+        source: 'scan',
+      })
+      recordIntervention(address, eventName, score)
+      torqueResult = { fired: true, eventId: result.eventId, eventName }
+    }
+  }
+
+  return NextResponse.json({
+    address,
+    signals,
+    score,
+    risk,
+    detectedSignals,
+    torque: torqueResult,
+  })
+}

src/lib/helius.ts

@@ -0,0 +1,118 @@
+/**
+ * Helius RPC client — fetches real Solana wallet activity for churn scoring.
+ * Uses the enhanced transactions API to derive wallet signals without an indexer.
+ */
+
+const HELIUS_BASE = 'https://api.helius.xyz/v0'
+const KEY = process.env.HELIUS_API_KEY || ''
+
+export function isHeliusConfigured() {
+  return KEY !== '' && !KEY.startsWith('your')
+}
+
+// Helius source → display protocol name
+const SOURCE_MAP: Record<string, string> = {
+  JUPITER: 'Jupiter',
+  RAYDIUM: 'Raydium',
+  DRIFT: 'Drift',
+  KAMINO: 'Kamino',
+  KAMINO_FINANCE: 'Kamino',
+  MARGINFI: 'Marginfi',
+  TENSOR: 'Tensor',
+  ORCA: 'Orca',
+  METEORA: 'Meteora',
+  PHOENIX: 'Phoenix',
+  LIFINITY: 'Lifinity',
+  MARINADE: 'Marinade',
+}
+
+interface HeliusTx {
+  timestamp: number
+  source: string
+  type: string
+  nativeTransfers?: Array<{ amount: number }>
+  tokenTransfers?: Array<{ tokenAmount: number }>
+}
+
+export interface WalletSignals {
+  address: string
+  daysInactive: number
+  protocols: string[]
+  uniqueProtocols: number
+  currentStreak: number
+  volumeDropPct: number
+  hasLiquidation: boolean
+  totalTxLast30d: number
+  lastActiveDaysAgo: string
+  source: 'helius' | 'mock'
+}
+
+export async function fetchWalletSignals(address: string): Promise<WalletSignals | null> {
+  if (!isHeliusConfigured()) return null
+  try {
+    const res = await fetch(
+      `${HELIUS_BASE}/addresses/${address}/transactions?api-key=${KEY}&limit=50`,
+      { next: { revalidate: 60 } }
+    )
+    if (!res.ok) return null
+    const txs: HeliusTx[] = await res.json()
+    if (!txs.length) return null
+
+    const nowSec = Date.now() / 1000
+    const sorted = txs.sort((a, b) => b.timestamp - a.timestamp)
+
+    // Days since last tx
+    const daysInactive = Math.round((nowSec - sorted[0].timestamp) / 86400)
+
+    // Protocols used
+    const protocolSet = new Set<string>()
+    for (const tx of sorted) {
+      const mapped = SOURCE_MAP[tx.source]
+      if (mapped) protocolSet.add(mapped)
+    }
+    const protocols = Array.from(protocolSet)
+
+    // Streak: count distinct calendar days active in last 7d
+    const sevenDaysAgo = nowSec - 7 * 86400
+    const activeDays = new Set(
+      sorted
+        .filter(tx => tx.timestamp >= sevenDaysAgo)
+        .map(tx => new Date(tx.timestamp * 1000).toDateString())
+    )
+    const currentStreak = activeDays.size
+
+    // Volume drop: tx count in last 7d vs prior 7d (proxy for volume)
+    const fourteenDaysAgo = nowSec - 14 * 86400
+    const recentCount = sorted.filter(tx => tx.timestamp >= sevenDaysAgo).length
+    const priorCount = sorted.filter(tx => tx.timestamp >= fourteenDaysAgo && tx.timestamp < sevenDaysAgo).length
+    const volumeDropPct = priorCount > 0
+      ? Math.round(Math.max(0, (priorCount - recentCount) / priorCount * 100))
+      : 0
+
+    // Liquidation check
+    const hasLiquidation = sorted.some(tx => tx.type?.includes('LIQUIDAT'))
+
+    // tx count last 30d
+    const thirtyDaysAgo = nowSec - 30 * 86400
+    const totalTxLast30d = sorted.filter(tx => tx.timestamp >= thirtyDaysAgo).length
+
+    const lastActiveDaysAgo = daysInactive === 0 ? 'today'
+      : daysInactive === 1 ? '1d ago'
+      : `${daysInactive}d ago`
+
+    return {
+      address,
+      daysInactive,
+      protocols,
+      uniqueProtocols: protocols.length,
+      currentStreak,
+      volumeDropPct,
+      hasLiquidation,
+      totalTxLast30d,
+      lastActiveDaysAgo,
+      source: 'helius',
+    }
+  } catch {
+    return null
+  }
+}