Ξ
ETHOS_ANALYTICS
BACK

Documentation

How Ethos Analytics Works

Overview

AI-Powered reputation analytics from Ethos Network

Ethos Analytics is an AI-powered reputation analysis tool that aggregates and analyzes reviews from the Ethos Network. It provides comprehensive insights into user reputation through sentiment analysis, thematic extraction, and temporal trends.

AI
GPT-5 Nano
24h
Cache
Live
Data
Fast
Analysis

Data Sources

  • ▹Ethos Network API: Live review data
  • ▹User Profiles: Twitter & wallet addresses
  • ▹Sentiment Scores: Positive, negative, neutral
  • ▹Temporal Data: Monthly review trends

AI Analysis

  • ▹GPT-5 Nano: Cost-effective LLM
  • ▹Theme Extraction: Auto-detect patterns
  • ▹Summarization: Comprehensive insights
  • ▹Context-Aware: Personalized to user

How It Works

1

User Input

Enter a Twitter handle or Ethereum wallet address. The system resolves this to an Ethos userkey using the Ethos Network API.

2

Data Fetching

Retrieves all reviews for the user from Ethos Network, categorized by sentiment (positive, negative, neutral).

3

AI Processing

GPT-5 Nano analyzes all reviews to generate summaries, extract themes, and identify key patterns in the reputation data.

4

Aggregation & Spike Detection

Computes statistics (sentiment counts, percentages), builds timeline trends, calculates the historical Ethos score trajectory, and detects anomaly months with unusual review activity (2x+ average or 150%+ increase).

5

Spike Analysis

For each detected spike, AI analyzes the reviews from that month to determine what triggered the anomaly, extracting key themes and generating concise explanations.

6

Caching

Results are cached for 24 hours to minimize AI costs. Subsequent visits load instantly from cache until expiration.

7

Visualization

Displays comprehensive analytics: reputation summary, theme badges, sentiment timeline chart, Ethos badge, Timeline Insights (spike analysis), and filterable reviews list.

Smart Themes

AI automatically identifies common themes in positive and negative reviews, presenting them as keyword badges.

Trustworthy
Helpful
Unreliable
Scammer

Timeline View

Interactive chart showing monthly sentiment trends alongside the Ethos score evolution over time.

Timeline Insights

AI-powered spike detection automatically identifies unusual activity months and explains what caused reputation changes.

API Endpoints

Internal API Reference

GET
/api/resolve

Resolves a Twitter handle or wallet address to an Ethos userkey.

Query Parameters:
twitter: Twitter handle (e.g., @elonmusk)
wallet: Ethereum address (e.g., 0x...)
Response:
{ "userkey": "service:x.com:elonmusk", "profile": {...} }
GET
/api/summary

Fetches comprehensive reputation summary with AI-generated insights.

Query Parameters:
userkey: Ethos userkey (required)
refresh: Force refresh cache (optional, boolean)
Response:
{ "summary": "...", "counts": {...}, "timeline": [...], "themes": [...] }
Cache:
24 hours (in-memory)
GET
/api/reviews

Retrieves paginated, filterable list of individual reviews.

Query Parameters:
userkey: Ethos userkey (required)
sentiment: Filter by POSITIVE | NEGATIVE | NEUTRAL
limit: Results per page (default: 50)
offset: Pagination offset (default: 0)
Response:
{ "reviews": [...], "total": 42, "limit": 50, "offset": 0 }

Ethos Badge Tiers

Reputation Score Ranges

Untrusted
0 - 799
Questionable
800 - 1199
Neutral
1200 - 1399
Known
1400 - 1599
Established
1600 - 1799
Reputable
1800 - 1999
Exemplary
2000 - 2199
Distinguished
2200 - 2399
Revered
2400 - 2599
Renowned
2600 - 2800

Getting Started

Quick Setup Guide

1. Clone the Repository

git clone https://github.com/nocliffcapital/ethos_analytics.git
cd ethos_analytics

2. Install Dependencies

npm install

3. Set Up Environment

echo "OPENAI_API_KEY=your_openai_api_key" > .env.local

Get your OpenAI API key from platform.openai.com

4. Start Development Server

npm run dev

Visit http://localhost:3000 to view the app.