PoB × Ethos - Enhanced Token Reputation Layer

A transparent, explainable reputation scoring system for Bags-launched tokens that helps users differentiate builders from extractors without censorship. Now enhanced with real creator reputation data from Ethos Network.

🎯 Why This Matters

The Bags ecosystem needs a way to evaluate token quality and creator behavior without relying on subjective judgments or black-box algorithms. PoB provides:

• Transparent Scoring: Every score is explainable with clear component breakdowns
• Behavioral Analysis: Focus on observable on-chain actions, not speculation
• Builder vs Extractor Detection: Identify patterns that indicate long-term commitment vs short-term extraction
• Creator Credibility: Real reputation data from Ethos Network enhances trust assessment
• No Censorship: Tokens aren't labeled as "scams" - users get data to make their own decisions

🤝 Ethos Network Integration

PoB now incorporates real creator reputation data from Ethos Network:

• Real Data Only: No mocked or placeholder Ethos data
• Optional but Weighted: Ethos enhances scoring when available, gracefully degrades when not
• Transparent Redistribution: When Ethos data is unavailable, points are redistributed proportionally
• Trust Enhancement: Improves safety without gating access
• Fully Documented: Complete transparency in how Ethos affects scoring

Ethos Unavailability Handling

Ethos Integration Philosophy:

• Ethos is Optional: Missing Ethos data does NOT penalize tokens
• No Creator Bias: Avoids bias against new creators or Solana-native projects
• Proportional Redistribution: When Ethos (30 points) is unavailable, the remaining 70 points are proportionally scaled to maintain a fair 0-100 scoring range
• Score Integrity: Total scores never exceed 100, ensuring consistent evaluation standards

Why This Approach:

1. Fairness: New creators aren't disadvantaged by lack of Ethos history
2. Inclusivity: Supports both Ethereum and Solana creator ecosystems
3. Transparency: Clear documentation of how redistribution works
4. Consistency: Maintains reliable 0-100 scoring across all tokens

Technical Implementation:

• When Ethos unavailable: Remaining components scaled by factor of 100/70 (≈1.43)
• Individual component caps respected (Creator History ≤20, Volume ≤20, etc.)
• Rounding adjustments ensure total equals exactly 100
• Status clearly marked as "unavailable" rather than "error"

How Ethos Enhances PoB

1. Creator Credibility: Ethos reputation scores provide community-validated creator trustworthiness
2. Enhanced Badge Logic: Ethos reputation influences Fresh/Growing/Extractive/Trusted categorization
3. Improved Discovery: Users can identify credible builders vs potential extractors more effectively
4. Economic Context: Reputation affects capital flows in live trading scenarios

🧮 How Scores Are Computed

Each token receives a 0-100 reputation score based on five weighted components:

Updated Scoring Model (Total: 100 points)

Component	Max Points	Description
Ethos Creator Reputation	30	Real credibility data from Ethos Network
Creator Launch History	20	Previous launches, token lifespans, extraction patterns
Volume Consistency	20	Daily variance, spike detection, sustained activity
Holder Distribution	15	Supply concentration, community adoption
Fee Claims Behavior	15	Claim frequency, timing, extraction patterns

1. Ethos Creator Reputation (0-30 points) 🆕

• Real Ethos Data: Fetches actual creator reputation from Ethos Network API
• Normalization: Ethos scores (~800-2500+) normalized to 0-30 PoB points
• Graceful Degradation: When unavailable, points redistributed proportionally
• Transparent Status: Clear indication of data availability

Normalization Logic:

• 800-1000 Ethos → 5-10 PoB points (basic credibility)
• 1000-1200 Ethos → 10-15 PoB points (decent credibility)
• 1200-1500 Ethos → 15-20 PoB points (good credibility)
• 1500-2000 Ethos → 20-25 PoB points (high credibility)
• 2000+ Ethos → 25-30 PoB points (exceptional credibility)

2. Creator Launch History (0-20 points)

• Previous Launches: Rewards creators with moderate, sustainable activity
• Average Lifespan: Higher scores for creators whose tokens survive longer
• Early Extraction: Penalizes creators who repeatedly extract fees early

3. Volume Consistency (0-20 points)

• Daily Variance: Rewards steady trading activity over volatile spikes
• Spike Detection: Identifies and penalizes pump-and-dump patterns
• Sustained Activity: Values consistent engagement over flash-in-the-pan volume

4. Holder Distribution (0-15 points)

• Top Holder Concentration: Penalizes extreme concentration in few wallets
• Total Holders: Rewards broader community adoption
• Healthy Dispersion: Identifies tokens with genuine distribution

5. Fee Claims Behavior (0-15 points)

• Claim Frequency: Analyzes how often creators extract fees
• Claim Percentage: Compares fees claimed vs fees accrued
• Timing Patterns: Penalizes aggressive early extraction, rewards patience

🏷️ Enhanced Badge System

Every token gets exactly one badge based on rule-based logic that now incorporates Ethos reputation:

• 🆕 Fresh: New token with insufficient data (< 14 days or < 7 volume data points)
• 📈 Growing: Positive/neutral Ethos score, consistent volume, rising holders, reasonable fee behavior
• ⚠️ Extractive: Weak/negative Ethos signals, frequent fee claims, spiky volume, or concentrated holders
• ✅ Trusted: Strong Ethos reputation, proven creator with long-term consistency and healthy patterns

Badge Logic Updates

• Ethos Integration: Creator reputation from Ethos Network influences badge assignment
• Graceful Handling: Missing Ethos data doesn't penalize tokens
• Enhanced Trust: Strong Ethos scores boost Trusted badge eligibility
• Risk Detection: Poor Ethos reputation contributes to Extractive classification

🚀 Why This Helps Bags & Ethos

For Bags Ecosystem:

1. Enhanced User Protection: Ethos reputation helps identify risky tokens before investing
2. Creator Incentives: Rewards good behavior and established reputation with higher scores
3. Ecosystem Health: Promotes long-term thinking over short-term extraction
4. Improved Discovery: Better differentiation between builders and extractors

For Ethos Network:

1. Live Economic Context: Ethos reputation affects real capital flows and trading decisions
2. Identity → Influence → Markets: Demonstrates how on-chain reputation impacts economic outcomes
3. Expanded Utility: Ethos data gains new use case in DeFi token evaluation
4. Network Effects: Incentivizes creators to build Ethos reputation for better token reception

🔌 Ethos API Integration

Real Data Sources

• Ethos API v2: https://api.ethos.network/api/v2
• Score Endpoint: /score/address?address={wallet}
• Batch Endpoint: /score/addresses for multiple lookups
• No Authentication: Uses public read-only endpoints

Data Handling

• 1-Hour Caching: Ethos scores cached to prevent excessive API calls
• Graceful Degradation: System continues working if Ethos is unavailable
• Transparent Status: Clear indication of Ethos data availability
• Error Handling: Robust error handling with fallback behavior

Score Normalization

// Ethos scores typically range 800-2500+
// Normalized to 0-30 PoB points with documented logic
function normalizeEthosScore(ethosScore: number): number {
  if (ethosScore < 800) return Math.max(0, Math.min(5, ethosScore / 160))
  if (ethosScore < 1000) return 5 + Math.floor((ethosScore - 800) / 40)
  if (ethosScore < 1200) return 10 + Math.floor((ethosScore - 1000) / 40)
  if (ethosScore < 1500) return 15 + Math.floor((ethosScore - 1200) / 60)
  if (ethosScore < 2000) return 20 + Math.floor((ethosScore - 1500) / 100)
  return Math.min(30, 25 + Math.floor((ethosScore - 2000) / 200))
}

🛠️ Technical Architecture

• Frontend: Next.js 14 with App Router, TailwindCSS, Recharts for visualization
• Backend: API routes for scoring, Prisma with SQLite for caching
• Data Sources:
  • Bags public API for token data
  • Ethos Network API v2 for creator reputation (real data)
  • On-chain Solana reads for additional metrics
• Scoring: Deterministic algorithms, no ML or black-box components
• Caching: 1-hour cache for computed scores and Ethos data
• Error Handling: Graceful degradation when external APIs are unavailable

📊 100% Real Bags Tokens

PoB displays only real tokens launched via the Bags platform:

Authentic Token Discovery

• API-Driven Discovery: Automatically finds real Bags tokens through claimable positions API
• Verified Launches: All tokens confirmed as authentic Bags platform launches
• Creator Verification: Each token verified through Bags creator API endpoints
• No Mock Data: Zero simulated or demo tokens in the system

Real Data Sources

• Token Discovery: Real Bags-launched tokens discovered via Bags API exploration
• Creator Information: Verified creator addresses from Bags API
• Ethos Reputation: Live creator reputation scores from Ethos Network
• Token Metadata: Real token names, symbols, and launch dates
• Creator History: Actual creator launch patterns and behavior

Supplemental Data

Some detailed metrics are supplemented with realistic estimates because they're not available in the basic Bags API:

• Daily Volume Breakdowns: Distributed from real total volume data
• Holder Distribution Percentages: Estimated based on token characteristics
• Fee Claim Details: Calculated from real volume using standard fee rates

100% Authentic Experience

• No fake mint addresses - all tokens are real Solana mint addresses
• No hardcoded sample scores - all scores computed from live data
• No artificial token data - everything sourced from real APIs
• Only verified Bags-launched tokens are displayed

Real Token Discovery Process

The system automatically discovers and displays real Bags-launched tokens by:

1. Exploring creator claimable positions to find real Bags tokens
2. Verifying each token through Bags creator API endpoints
3. Computing live reputation scores using real creator and token data
4. Sorting by reputation score to showcase natural diversity
5. Refreshing data to reflect current token state

Transparent Scoring

All reputation scores reflect:

• Real creator behavior from Ethos Network (when available)
• Actual token launch patterns from Bags API
• Live on-chain state at time of computation
• No manipulation or curation of scores

🔧 Getting Started

1. Install dependencies:

   npm install

2. Set up environment:

   cp .env.example .env
   # Add your BAGS_API_KEY and configure Ethos settings

3. Initialize database:

   npx prisma generate
   npx prisma db push

4. Run development server:

   npm run dev

5. Visit: http://localhost:3000

🌐 API Endpoints

GET /api/token/[mint]/reputation

Returns reputation score, badge, component breakdown, and Ethos data.

Response:

{
  "score": 72,
  "badge": "Growing",
  "breakdown": {
    "ethos": 18,
    "creatorHistory": 16,
    "volumeConsistency": 18,
    "holderDistribution": 12,
    "feeBehavior": 8
  },
  "ethos": {
    "score": 18,
    "max": 30,
    "status": "available",
    "source": "Ethos"
  },
  "token": {
    "mint": "...",
    "name": "Token Name",
    "symbol": "TKN",
    "creatorAddress": "..."
  }
}

GET /api/token/[mint]/raw

Returns raw metrics including Ethos data for transparency and debugging.

Includes:

• All token metrics and computed values
• Raw Ethos data (score, level, status, last fetched)
• Normalized Ethos score used in PoB calculation

🚀 Deployment

Deploy to Vercel with one click:

1. Connect your GitHub repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

🔮 Extensibility

The system is designed for easy extension:

• New Metrics: Add components to ReputationCalculator
• Data Sources: Extend BagsAPI or EthosAPI classes for additional data
• Badge Logic: Modify determineBadge method for new categories
• UI Components: Add visualizations in TokenDetails component
• Caching Strategy: Adjust refresh intervals in API routes
• Ethos Integration: Easily modify normalization logic or add new Ethos endpoints

🏆 Dual Hackathon Positioning

For Bags Hackathon:

• Enhanced Discovery & Safety: Ethos reputation improves token evaluation
• Discourages Extractive Behavior: Poor reputation affects token reception
• Encourages Credible Builders: Rewards established creators with better scores
• Maintains Bags Focus: Core functionality remains Bags-centric

For Ethos Vibeathon:

• Live Economic Context: Ethos reputation affects real capital flows
• Identity → Influence → Markets: Demonstrates reputation's economic impact
• Real-World Utility: Practical use case for Ethos reputation data
• Network Effects: Incentivizes creators to build Ethos reputation

⚖️ Constraints & Philosophy

• ❌ No "scam" labels - provides data, not judgments
• ❌ No black-box AI - all scoring is deterministic and explainable
• ❌ No hidden methodology - complete transparency in calculations
• ❌ No wallet connection required - public data only
• ❌ No dummy Ethos data - real API integration only
• ❌ No creator bias - missing Ethos data doesn't penalize tokens
• ✅ Explainable scores with clear breakdowns
• ✅ Rule-based badge assignment
• ✅ Focus on observable behavior patterns
• ✅ Real Ethos reputation integration
• ✅ Proportional score redistribution when external data unavailable
• ✅ Scores reflect behavior, not financial advice or moral judgments
• ✅ Extensible architecture for future enhancements

---

Built for dual hackathon submission - enhancing Bags ecosystem safety while demonstrating Ethos reputation's real-world economic impact.

Important: Reputation scores reflect observable on-chain behavior and are not financial advice or moral judgments. Always conduct your own research before making investment decisions.