# 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](#categories)
- [Risk Levels](#risk-levels)
- [Detailed Scoring Rules](#detailed-scoring-rules)
  - [Authority Controls](#authority-controls)
  - [Holder Distribution](#holder-distribution)
  - [Liquidity Health](#liquidity-health)
  - [Metadata & Flags](#metadata--flags)
  - [Trust Signals](#trust-signals)
- [Hard Stops](#hard-stops)
  - [Severity Levels](#severity-levels)
  - [Platform Hard Stop](#platform-hard-stop)
  - [Liquidity Hard Stops](#liquidity-hard-stops)
- [Platform Detection](#platform-detection)
- [API Endpoints Used](#api-endpoints-used)
- [JSON Output Schema](#json-output-schema)
- [Example Output](#example-output)
- [Limitations](#limitations)

---

## 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

```json
{
  "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:

```json
{
  "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

- [Birdeye Security Data](https://docs.birdeye.so/docs/security-data)
- [Birdeye API: GET /defi/token_security](https://docs.birdeye.so/reference/get-defi-token_security)
- [Birdeye Security Docs](https://docs.birdeye.so/docs/security)