API

Reference Documentation

OatsEngine

Main analysis engine class

class OatsEngine:
    """Token risk analysis engine."""
    
    WEIGHTS = {
        "concentration": 0.30,
        "liquidity_health": 0.25,
        "contract_maturity": 0.20,
        "transfer_quality": 0.15,
        "dev_exposure": 0.10,
    }
    
    def __init__(self, weights: dict = None):
        """Initialize engine with optional custom weights."""
        
    def analyze(self, snapshot: TokenRiskSnapshot) -> OatsAnalysis:
        """Run analysis on token risk snapshot."""

TokenRiskSnapshot

Input data model for on-chain risk metrics

Field	Type	Description
timestamp	float	Unix timestamp
top10_holder_pct	float	Top 10 holder percentage (0-100)
liquidity_to_mcap	float	Liquidity to market cap ratio
contract_age_days	float	Days since contract deployment
transfer_pattern_score	float	Organic transfer score (0-100)
dev_wallet_pct	float	Dev wallet holdings percentage

OatsAnalysis

Output data model from engine analysis

Field	Type	Description
oats_index	float	Composite risk index 0-100
grade	OatsGrade	CRITICAL \| RISKY \| MODERATE \| SAFE \| PRISTINE
signals	list[SignalResult]	Individual signal scores
dominant_signal	str	Signal with highest impact
risk_confidence	float	Confidence level of analysis

OatsGrade

Enum for risk grades

Field	Type	Description
CRITICAL	0-19	High probability of malicious design
RISKY	20-39	Multiple red flags present
MODERATE	40-59	Mixed signals, verify before entering
SAFE	60-79	Low risk overall, minor cautions
PRISTINE	80-100	All metrics healthy

usage.py

from oats import OatsEngine, TokenRiskSnapshot

# Initialize with default weights
engine = OatsEngine()

# Or with custom weights
engine = OatsEngine(weights={
    "concentration": 0.35,
    "liquidity_health": 0.25,
    "contract_maturity": 0.15,
    "transfer_quality": 0.15,
    "dev_exposure": 0.10,
})

# Create snapshot
snap = TokenRiskSnapshot(
    timestamp=1700000000.0,
    top10_holder_pct=25.0,
    liquidity_to_mcap=0.08,
    contract_age_days=150.0,
    transfer_pattern_score=70.0,
    dev_wallet_pct=4.0,
)

# Run analysis
result = engine.analyze(snap)

# Access results
print(result.oats_index)     # 74.5
print(result.grade)          # OatsGrade.SAFE
print(result.signals)        # [SignalResult(...), ...]
print(result.dominant_signal) # "concentration"