Obsqra.fi Docs
Demo

AI Service Architecture

The AI Risk Engine is a Python FastAPI service that analyzes DeFi protocols, generates allocation recommendations, and commits them on-chain for verification.

System Overview

Layer 1: API Layer (FastAPI)
/risk-score/*
Protocol risk scores
/generate-recommendation
New allocations
/simulate/*
Volatility scenarios
Layer 2: Core Logic
RiskModel
Multi-factor scoring
Allocator
Optimization engine
VolatilitySimulator
Demo scenarios
Layer 3: Data Layer
DataFetcher
External APIs
Cache
In-memory storage
Config
Mode settings

Data Sources

The AI service fetches real-time data from trusted DeFi data providers:

DefiLlama

Primary source for protocol TVL and historical data.

  • ‣Current TVL per protocol
  • ‣7-day TVL change percentage
  • ‣Protocol category and chain

CoinGecko

Token price data and volatility metrics.

  • ‣Current token prices
  • ‣7-day price change
  • ‣Market cap and volume

Risk Model

The risk model produces a score from 0 (lowest risk) to 100 (highest risk) based on multiple weighted factors:

Factor
TVL Size
Weight
25%
Low Risk
>$1B TVL
High Risk
<$100M TVL
Factor
TVL Stability
Weight
20%
Low Risk
<5% change/week
High Risk
>20% change/week
Factor
Volatility
Weight
25%
Low Risk
<10% 7d change
High Risk
>30% 7d change
Factor
Protocol Age
Weight
15%
Low Risk
>2 years
High Risk
<6 months
Factor
Audit Status
Weight
15%
Low Risk
Multiple audits
High Risk
No audits
ℹ️
Demo Mode Fluctuation
In demo mode, a small random fluctuation (±3 points) is added to risk scores to simulate real-time market changes. This is disabled in testnet and mainnet modes.

Allocation Engine

The allocator optimizes for risk-adjusted returns while respecting DAO constraints.

Get Scores

Fetch risk data

Calculate

APY / Risk ratio

Constrain

Apply DAO limits

Output

Allocation weights

The algorithm calculates: score = APY / (riskScore + 1) for each protocol, then normalizes to 100%.

Volatility Simulator

For demo purposes, the service can inject market scenarios that affect risk scores:

Scenario
stable
Effect
No changes
Duration
Indefinite
Use Case
Normal operation
Scenario
mild_stress
Effect
2x volatility, -5% TVL
Duration
5 min
Use Case
Minor market dip
Scenario
flash_crash
Effect
5x volatility, -20% TVL
Duration
3 min
Use Case
Major crash event
Scenario
exploit_scare
Effect
Single protocol spike
Duration
4 min
Use Case
Exploit news
Scenario
bull_run
Effect
1.5x volatility, +10% TVL
Duration
5 min
Use Case
Market rally
⚠️
Demo Mode Only
Volatility simulation is only available when OBSQRA_MODE=demo. In testnet and mainnet modes, only real data is used.

Configuration

The service supports three modes with different behaviors:

Setting
Volatility Injection
Demo
Enabled
Testnet
Disabled
Mainnet
Disabled
Setting
Rebalance Trigger
Demo
5% drift
Testnet
10% drift
Mainnet
15% drift
Setting
Min Rebalance Interval
Demo
1 minute
Testnet
5 minutes
Mainnet
1 hour
Setting
Audit Logging
Demo
Always On
Testnet
Always On
Mainnet
Always On
Setting
Data Refresh
Demo
5 minutes
Testnet
5 minutes
Mainnet
5 minutes

API Endpoints

GET/health

Health check endpoint. Returns service status and model state.

GET/risk-score/all

Get risk scores for all supported protocols. Returns scores 0-100.

POST/generate-recommendation

Generate a new allocation recommendation based on current pool state.

POST/simulate/scenario

Trigger a volatility scenario (demo mode only). Scenarios: stable, mild_stress, flash_crash, exploit_scare, bull_run.