Skip to content

SCORING.md

Latest commit

 

History

History
283 lines (210 loc) · 9.25 KB

SCORING.md

File metadata and controls

283 lines (210 loc) · 9.25 KB
Raw

Scoring Methodology

Comprehensive reference for the aignt-mint-scoring scoring system: categories, hard stops, platform detection, and the JSON output schema.

Table of Contents

Categories

100 points total across five categories:

Category Max Key Checks
Authority Controls 25 Mint revoked (+15), Freeze revoked (+10)
Holder Distribution 20 Top 10 concentration (+12), Creator holdings (+8)
Liquidity 25 LP lock % (+15), Rugcheck risk score (+7), No DANGER risks (+3)
Metadata & Flags 15 Immutable metadata (+8), No transfer fees (+5), Token type (+2)
Trust Signals 15 Jupiter strict list (+10), Not fake (+3), Validated (+2)

Risk Levels

Score Level Meaning
93–100 Excellent Very safe, all best practices met
81–92 Good Generally safe with minor concerns
70–80 Moderate Acceptable but exercise caution
55–69 Poor High risk, investigate thoroughly
0–54 Critical Very high risk / likely scam

Detailed Scoring Rules

Authority Controls

  • Mint authority (ownerAddress): null/empty = revoked → +15 pts. Active = 0 pts + CRITICAL warning.
  • Freeze authority (freezeAuthority): null/empty = revoked → +10 pts. Active = 0 pts + warning.
  • Non-transferable: If true, Authority Controls score forced to 0 (token cannot be traded).

Holder Distribution

  • Top 10 holders <20% → +12 pts; 20–30% → +10; 30–50% → +6; 50–70% → +3; ≥70% → 0.
  • Creator <1% → +8 pts; 1–5% → +6; 5–10% → +4; 10–25% → +2; ≥25% → 0.
  • On known bonding curve platforms (Pump.fun etc.) the protocol contract holds unsold supply — this looks like extreme concentration but is not a rug risk. A neutral override score of 10/20 is applied instead of falsely penalising the token.

Liquidity

Data source: rugcheck.xyz /v1/tokens/{id}/report/summary (public, no auth required).

LP lock % (15 pts)

LP Locked Points
0% 0 pts + Critical hard stop (score capped at 5)
>0% and <25% 3
25–49% 7
50–74% 10
75–94% 13
≥95% 15

Rugcheck risk score (7 pts) — lower raw score = safer

Rugcheck score Points
None (unavailable) 0 + warning
≥ 500 0
350–499 2
200–349 5
< 200 7

No DANGER-level risks (3 pts)

DANGER risks in risks[] Points
0 3
1 1
≥ 2 0

When rugcheck data is unavailable (fetch failed), the full 25 pts are granted.

Metadata & Flags

  • Immutable metadata → +8 pts. Mutable → 0 + warning.
  • No transfer fees → +5 pts. Transfer fee active → 0 + warning.
  • Standard SPL token → +2 pts. Token2022 → 0 (noted, not penalised beyond score).

Trust Signals

  • Jupiter strict list → +10 pts.
  • Not flagged as fake → +3 pts. Flagged as fake → Trust score forced to 0.
  • Birdeye isTrueToken validated → +2 pts.

Hard Stops

Hard stops are evaluated before normal scoring. When triggered, the final score is capped at the hard stop limit regardless of the category scores. When multiple hard stops trigger, the worst severity determines the cap.

Severity Levels

Severity Score Cap Conditions
🛑 Critical 5/100 Non-transferable token; Fake token flag; Mint authority NOT revoked
🔴 Severe 20/100 Creator holds >50%; Top 10 holders >90%
⚠️ Major 34/100 Creator holds 30–50%; Top 10 holders 70–90%; Freeze authority NOT revoked
ℹ️ Warning none Launch platform not identified (token flagged, score not capped)

Platform Hard Stop

Unknown launch origin is a Warning-level hard stop. Tokens that cannot be attributed to a known launchpad are flagged in the output — but since it is a Warning the score is not capped, allowing the rest of the checks to reflect the token's real quality.

Liquidity Hard Stops

Condition Severity Cap
lp_locked_pct = 0% (or missing) 🛑 Critical 5/100

Zero locked liquidity means the creator can pull the entire LP at any moment — immediate disqualification regardless of other scores.

Platform Detection

The scorer detects the token's launch platform and adjusts scoring to avoid false positives from bonding curve mechanics:

Platform Detection Method Trust Level Holder Override
Pump.fun Mint ends with pump Audited 10/20 (neutral)
Bonk Launchpad creatorOwner matches program address Community 10/20 (neutral)
Moonshot creatorOwner matches program address Community 10/20 (neutral)
LetsBonk creatorOwner matches program address Community 10/20 (neutral)
Unknown Fallback Unknown Full checks applied

Detection priority: Pump.fun (mint suffix) → Bonk Launchpad → Moonshot → LetsBonk → Unknown.

The detected platform and trust level are included in the score struct (launch_platform, platform_trust_level) and in the JSON output.

API Endpoints Used

Birdeye (authenticated)

Both endpoints send x-api-key: YOUR_KEY and x-chain: solana headers. The base URL defaults to https://api.uniblock.dev/direct/v1/Birdeye and is configurable via BirdeyeClient::with_base_url or the BIRDEYE_BASE_URL environment variable.

  • Token Security: GET {base_url}/defi/token_security?address=<MINT>

Rugcheck.xyz (public, no auth)

  • Token Report Summary: GET https://api.rugcheck.xyz/v1/tokens/<MINT>/report/summary

Key fields used: lpLockedPct, score, risks[].level.

JSON Output Schema

{
  "overall_score": 92.0,
  "hard_stop_triggered": false,
  "launch_platform": "Unknown",
  "platform_trust_level": "Unknown",
  "authority_score": 25.0,
  "holder_distribution_score": 18.0,
  "liquidity_score": 25.0,
  "metadata_score": 15.0,
  "trust_score": 15.0,
  "risk_level": "Excellent",
  "warnings": [],
  "positive_signals": [
    "✓ Mint authority revoked (no inflation risk)",
    "✓ Freeze authority revoked (no account freeze risk)"
  ],
  "details": {
    "mint_authority_revoked": true,
    "freeze_authority_revoked": true,
    "mutable_metadata": false,
    "top10_holder_percent": 15.2,
    "creator_percentage": 0.1,
    "is_token2022": false,
    "has_transfer_fee": false,
    "non_transferable": false,
    "jup_strict_list": true,
    "is_fake_token": false,
    "launch_platform": "Unknown",
    "platform_trust_level": "Unknown"
  }
}

When hard stops are triggered a hard_stop_violations array is included:

{
  "overall_score": 5.0,
  "hard_stop_triggered": true,
  "hard_stop_violations": [
    {
      "severity": "Critical",
      "category": "Authority Control",
      "message": "🛑 HARD STOP: Mint authority is NOT revoked",
      "description": "The token creator retains mint authority..."
    }
  ]
}

Example Output

Token With Hard Stop Violation

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛑 HARD STOP VIOLATIONS DETECTED 🛑
This token has CRITICAL security issues that are deal-breakers:

🛑 HARD STOP: Mint authority is NOT revoked [CRITICAL]
The token creator retains mint authority, allowing them to create
unlimited new tokens at any time...

⚠️  Investment in this token is NOT RECOMMENDED ⚠️
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OVERALL SECURITY SCORE: 5.0/100
(Score capped due to hard stop violations)
LAUNCH PLATFORM: Pump.fun (Audited)
RISK LEVEL: CRITICAL

Token Without Hard Stops

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OVERALL SECURITY SCORE: 92.0/100
LAUNCH PLATFORM: Unknown (Unknown)
RISK LEVEL: EXCELLENT

Category Breakdown:
  Authority Controls:   25.0/25
  Holder Distribution:  18.0/20
  Metadata & Flags:     15.0/15
  Trust Signals:        15.0/15
  Liquidity:            25.0/25

Positive Signals:
  ✓ Mint authority revoked (no inflation risk)
  ✓ Freeze authority revoked (no account freeze risk)
  ✓ Excellent distribution: Top 10 holders own 15.2%
  ✓ Listed on Jupiter strict list (manually verified)

References