Building suspETHious — An AI Agent for Wallet Security

The Problem

Decentralized wallets today are powerful, but they lack built-in mechanisms to help users evaluate the trustworthiness of past transactions or counterparties. Many users fall victim to fraudulent transactions or scams without even realizing the red flags.

The Idea: suspETHious

suspETHious is a smart Ethereum-based crypto wallet enhanced with an AI-powered audit agent. Before executing any outgoing transaction, the agent scans and analyzes the historical transaction patterns of the target wallet.

The AI agent determines:

• If the wallet has a history of interacting with known scam addresses
• Transaction frequencies and amounts that look anomalous
• Gas fees or token behavior that deviates from norms

How It Works

Whenever you enter a recipient address, the wallet fetches all historical transactions for that address using the Etherscan API:

import requests
import os
BASE_URL = "https://api.etherscan.io/api"

def fetch_wallet_transactions(address):
    url = (
        f"{BASE_URL}?module=account&action=txlist"
        f"&address={address}&startblock=0&endblock=99999999"
        f"&sort=asc&apikey={os.environ['ETHERSCAN_API_KEY']}"
    )
    response = requests.get(url)
    data = response.json()
    if data["status"] != "1":
        if data["message"].lower().startswith("no transactions"):
            return []
        raise ValueError(f"Error from Etherscan: {data['message']}")
    return data["result"]

The transaction data is then transformed into features that capture behavioral patterns—like average time between transactions, unique counterparties, and value statistics. These features are fed into a machine learning model trained to spot scam-like activity:

import pandas as pd
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import PowerTransformer
from imblearn.over_sampling import RandomOverSampler
import xgboost as xgb
import pickle

def train_model():
    df = pd.read_csv('transaction_dataset.csv', index_col=0)
    # ...data cleaning and feature selection...
    y = df.iloc[:, 0]
    X = df.iloc[:, 1:]
    norm = PowerTransformer()
    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
    norm_train_f = norm.fit_transform(X_train)
    oversample = RandomOverSampler()
    x_tr_resample, y_tr_resample = oversample.fit_resample(norm_train_f, y_train)
    xgb_c = xgb.XGBClassifier()
    xgb_c.fit(x_tr_resample, y_tr_resample)
    with open('scam_model.pkl', 'wb') as f:
        pickle.dump(xgb_c, f)
    with open('scam_normalizer.pkl', 'wb') as f:
        pickle.dump(norm, f)

When a transaction is about to be sent, the model predicts whether the recipient is likely to be a scam address. If flagged, the system uses SHAP to explain which features contributed most to the verdict, and then passes this to a conversational AI agent for a human-friendly summary:

import shap
from langchain.agents import create_openai_functions_agent
from langchain_openai import ChatOpenAI

def explain_scam(features, model):
    explainer = shap.TreeExplainer(model)
    shap_values = explainer.shap_values(features)
    feature_contributions = dict(zip(features.columns, shap_values[0]))
    top_features = sorted(feature_contributions.items(), key=lambda x: abs(x[1]), reverse=True)[:3]
    return top_features

# LangChain agent setup
llm = ChatOpenAI(model="gpt-4o-mini")
agent = create_openai_functions_agent(llm, tools=[...], system_prompt="Explain why this address is suspicious.")

# Example usage:
explanation = agent.invoke({
    "input": "Explain why this address is flagged as a scam.",
    "features": top_features
})

The result? Before any ETH leaves your wallet, you get a clear, AI-generated warning if the recipient looks suspicious—plus a plain-English explanation of the red flags. This seamless blend of blockchain, machine learning, and LLMs helps users make safer decisions, without ever needing to understand the technical details under the hood.

The Tech Stack

• Machine Learning: I trained a fraud detection model (XGBoost Classifier) on a dataset of real Ethereum transactions containing scam flags.
• Explainability: I used SHAP (SHapley Additive exPlanations) to make the model decisions interpretable. Users can understand why a transaction was flagged.
• LLM Integration: The system integrates with OpenAI's GPT-4o-mini via LangChain, transforming ML insights into human-readable alerts.
• Frontend: Built with React.js, providing users with an intuitive interface and dynamic transaction alerts.
• Backend: A Flask server connects the React frontend, ML model, and Ethereum APIs.
• Blockchain: I used Ethereum testnets to simulate transactions and trigger wallet audits.

Project Repo

GitHub Repository