| name | token-scoring |
| description | 4-category composite token scoring engine (11 factors, max 100) for exchange listing intelligence — evaluates market metrics, safety audits, social signals, and quality indicators with dual-gate verification. Supports Solana, Base, BSC, and Stacks (SIP-010). |
| author | buzzbysolcex |
| author_agent | Ionic Nova (Buzz BD Agent) |
| user-invocable | true |
| arguments | doctor | run | run --address <contract> --chain <chain> |
| entry | token-scoring/token-scoring.ts |
| requires | ["wallet","settings"] |
| tags | ["read-only","infrastructure","l2"] |
Token Scoring
What it does
Scores any token across Solana, Base, BSC, or Stacks on a 0-100 composite scale using 4 scoring categories with 11 weighted factors. Data sources: DexScreener (market data, pairs), CoinGecko (project metadata, supply data), RugCheck (contract safety audits), and Hiro API (Stacks SIP-010 tokens). Applies dual-gate verification where fundamentals (safety + holder + quality factors, max 70) and market (social + market factors, max 30) must each independently clear 60% before a token can advance. Auto-classifies tokens as HOT (85+), QUALIFIED (70-84), WATCH (50-69), or SKIP (<50).
Scoring Categories (4 categories, 11 factors, max 100 points)
Market (30 points max)
| Factor | Max | How it's scored |
|---|
| market_cap | 10 | Tiered by MCap range ($100K-$50M = full marks, penalizes extremes) |
| liquidity | 10 | Liquidity-to-MCap ratio (3%+ with $100K+ liq = full marks) |
| volume | 10 | Volume-to-MCap ratio (10%+ = full marks) |
Safety (30 points max)
| Factor | Max | How it's scored |
|---|
| contract_safety | 15 | RugCheck verdict + score (Good/80+ = full, Warning = 10, <30 = 2) |
| holder_dist | 15 | Circulating/total supply ratio from CoinGecko (80%+ = full) |
Social (20 points max)
| Factor | Max | How it's scored |
|---|
| team_identity | 10 | CoinGecko project listing as proxy for team visibility (listed = 6, not = 3) |
| social_presence | 10 | CoinGecko project listing as proxy for community (listed = 6, not = 3) |
Quality (20 points max)
| Factor | Max | How it's scored |
|---|
| token_age | 5 | Days since pair creation (90d+ = 5, 30d+ = 4, 7d+ = 3, <1d = 1) |
| deployer_history | 5 | Default 3/5. Pump.fun tokens receive -10 composite penalty |
| web_footprint | 5 | CoinGecko listing = 4, not listed = 2 |
| momentum | 5 | 24h price change direction (positive = 4, negative = 2) |
Honest Limitations
- team_identity and social_presence use CoinGecko listing as a proxy for team/community presence. Not a direct social metrics analysis. Tokens not on CoinGecko score 3/10.
- deployer_history uses a default score of 3/5 without deep on-chain deployer wallet analysis. Pump.fun tokens get a composite penalty.
- momentum is a binary check on 24h price direction, not RSI/MACD technical analysis.
- holder_dist estimates from circulating/total supply ratio, not individual wallet analysis.
- Stacks SIP-010 support is basic — uses Hiro API for token existence and DexScreener for market data if available.
Dual-Gate Verification
Both gates must pass independently:
- Fundamentals gate (safety + holder + quality): score >= 42/70 (60%)
- Market gate (social + market): score >= 18/30 (60%)
If either gate fails, classification is capped at WATCH regardless of composite score.
Supported Chains
- Solana — Full support (DexScreener + RugCheck + CoinGecko)
- Base — Full support (DexScreener + CoinGecko)
- BSC — Full support (DexScreener + CoinGecko)
- Stacks — Basic SIP-010 support (Hiro API + DexScreener where available)
Why agents need it
Any agent evaluating tokens for trading, listing, or portfolio decisions needs systematic due diligence beyond price action. This skill replaces narrative-driven evaluation with data-backed composite scoring. The dual-gate prevents tokens with inflated social metrics but poor fundamentals from passing, and vice versa.
Safety notes
- This skill is READ-ONLY. It never writes to chain or moves funds.
- All data is pulled from public APIs (DexScreener, CoinGecko, RugCheck, Hiro).
- No wallet funds required for execution.
- Scores are informational — not financial advice.
Commands
doctor
Checks API connectivity to all data sources and reports readiness.
bun run token-scoring/token-scoring.ts doctor
run
Scores a token by contract address. Pulls data from all sources, computes composite score, applies dual-gate, and returns classification.
bun run token-scoring/token-scoring.ts run --address <contract_address> --chain <solana|base|bsc|stacks>
Without arguments, scores the top trending token from DexScreener:
bun run token-scoring/token-scoring.ts run
Output contract
All outputs are JSON to stdout.
{
"status": "success | error | blocked",
"action": "review score and classification for trading/listing decision",
"data": {
"address": "contract address",
"chain": "solana",
"composite_score": 67,
"classification": "watch",
"dual_gate": {
"pass": true,
"fundamentals": { "score": 45, "max": 70, "threshold": 42, "pass": true },
"market": { "score": 22, "max": 30, "threshold": 18, "pass": true }
},
"components": {
"safety": { "score": 15, "max": 15 },
"holder_dist": { "score": 10, "max": 15 },
"market_cap": { "score": 10, "max": 10 },
"liquidity": { "score": 8, "max": 10 },
"volume": { "score": 5, "max": 10 },
"team_identity": { "score": 6, "max": 10 },
"social_presence": { "score": 6, "max": 10 },
"token_age": { "score": 4, "max": 5 },
"deployer_history": { "score": 3, "max": 5 },
"web_footprint": { "score": 4, "max": 5 },
"momentum": { "score": 4, "max": 5 }
},
"flags": ["pump_fun_detected", "low_liquidity"],
"verdict": "PROCEED | MONITOR | REJECT"
},
"error": null
}
Known constraints
- DexScreener free tier: 300 requests/min (sufficient for scoring)
- CoinGecko free tier: 30 requests/min (rate-limited internally)
- RugCheck may return 400 for non-Solana tokens (graceful degradation)
- Scores are point-in-time snapshots — re-score after 24h for stability check
- Pump.fun tokens auto-penalized (-10 points) due to low-mcap rug risk
