SENTINEL Documentation

AI-Powered Liquidation Defense & Whale Intelligence Platform for Pacifica traders. SENTINEL runs 6 AI agents that monitor liquidation cascades, track whale movements, and protect your positions — all in real time.

Frontend

Next.js 14, TypeScript, SCSS Modules, D3.js, Socket.io, Privy Auth

Backend

FastAPI, Python 3.11, Redis, PostgreSQL, scikit-learn, TensorFlow

Contracts

Solidity 0.8.20, Hardhat, OpenZeppelin, Arbitrum Mainnet

Quick Start

# Clone and setup
git clone https://github.com/YOUR_ORG/sentinel.git
cd sentinel
cp .env.example .env

# Start everything with Docker
docker compose up --build

# Or start individually
cd apps/web && npm install && npm run dev
cd apps/api && pip install -r requirements.txt && uvicorn app.main:app --reload

Frontendhttp://localhost:3000

APIhttp://localhost:8000

API Docshttp://localhost:8000/docs

Redislocalhost:6379

PostgreSQLlocalhost:5432

Modules

M1 — Liquidation Radar

D3.js heatmap visualizing liquidation clusters. Cascade probability gauge, market sidebar with risk scoring.

/dashboard

M2 — Whale Intelligence

Elfa AI-powered whale tracking with intent classification. Convergence alerts when 3+ whales align.

/whale-intelligence

M3 — SENTINEL Guard

Automated position protection. Polls every 10s, executes partial close / full close / add margin.

/guard

M4 — Africa FX Hedge

NGN/KES/GHS hedge calculator using BTC perpetuals. Purpose-built for African businesses.

/africa-hedge

M5 — Funding Rate Intel

ARIMA + LSTM ensemble forecast 4 epochs ahead with confidence bands.

/funding-rates

AI Agents

All agents run as parallel async tasks via the worker runner. Each has independent polling intervals and publishes to Redis channels.

Guard Agent

10s

Monitors margin ratios, executes protective orders

Cascade Predictor

30s

ML inference on liquidation probability, publishes >85% to Arbitrum

Whale Intel Agent

60s

Elfa AI polling, intent classification, convergence detection

Funding Forecast

8h

ARIMA + LSTM ensemble on full funding history

Africa FX Advisor

60s

CoinGecko FX polling, hedge recommendation engine

Alert Broadcaster

1s

Redis queue → Socket.io push + Fuul referral links

API Reference

Base URL: http://localhost:8000

MethodEndpointAuthDescription

GET/healthNoService health check

GET/health/agentsNoAll 6 agent statuses

GET/api/v1/marketsNoActive Pacifica markets

GET/api/v1/alerts/cascadeNoCurrent cascade predictions

GET/api/v1/whale/eventsNoRecent whale activity

GET/api/v1/whale/convergenceNoSmart money convergence

GET/api/v1/funding/ratesNoLive funding rates

GET/api/v1/funding/forecast/:symbolNo4-epoch ARIMA+LSTM forecast

GET/api/v1/positionsYesOpen Pacifica positions

GET/api/v1/guard/configYesGuard bot configuration

PUT/api/v1/guard/configYesUpdate guard config

GET/api/v1/hedge/ratesNoNGN/KES/GHS FX rates

POST/api/v1/hedge/calculateNoHedge recommendation

GET/api/v1/referral/codeNoGet/create referral code for wallet

GET/api/v1/referral/statsNoReferral stats and conversions

POST/api/v1/referral/convertNoTrack referral conversion

GET/api/v1/referral/leaderboardNoTop referrers by points

WebSocket Events

Connect via Socket.io to ws://localhost:8000

liquidationReal-time liquidation events across all markets

{ symbol, side, price, size, notionalValue }

whaleNew whale events from Elfa AI + Pacifica order flow

{ id, wallet_address, action_type, size_usd, market, intent, elfa_score }

guardPosition health updates and guard action notifications

{ symbol, margin_ratio, mark_price, health_score }

fundingFunding rate updates per epoch

{ symbol, rate, nextFundingTime, markPrice }

cascadeCascade prediction alerts when probability exceeds threshold

{ market, probability, severity, time_horizon }

Smart Contracts

SentinelAlertRegistry

Deployed to Ethereum Sepolia testnet. Stores high-confidence cascade alerts (probability > 85%) on-chain for verifiability and transparency.

NetworkEthereum Sepolia

Chain ID11155111

Contract Address0x486aFe3c1e3dE1253B31C82A30d5270e63403c27

EtherscanView on Sepolia Etherscan

Authorized Publisher0xE5A747FA09271C8d479Cf718b205F8aADd6E4C30

Interface

// Publish a cascade alert (only authorized publisher)
function publishAlert(
  string memory market,
  uint256 cascadeProbability, // basis points (8500 = 85%)
  uint8 severity // 1=WATCH 2=ALERT 3=CASCADE_IMMINENT
) external onlyAuthorizedPublisher

// Read alerts (public)
function getAlertCount() view returns (uint256)
function getAlert(uint256 alertId) view returns (Alert)

// Event emitted on every alert
event AlertPublished(
  uint256 indexed alertId,
  address indexed publisher,
  string market,
  uint256 probability,
  uint8 severity,
  uint256 timestamp
)

Custom Errors (Gas-Optimized)

error NotAuthorized();
error InvalidSeverity();
error InvalidProbability();

Tier System

FeatureFreePro ($29)Institutional ($499)

Real-time data30s delay<500ms<500ms

Whale alerts3/dayUnlimitedUnlimited

Guard botNoYesYes

Funding forecastsNoYesYes

API accessNoNoYes

WebhooksNoNoYes

Earn 1,000 Fuul referral points = 1 month Pro free