Skip to content

README.md

Latest commit

 

History

History
152 lines (112 loc) · 5.03 KB

README.md

File metadata and controls

152 lines (112 loc) · 5.03 KB
Raw

aignt-mint-security-scorer

A Rust library that calculates a comprehensive security score (0–100) for any Solana token using real-time data from the Birdeye API and rugcheck.xyz. Ships with a CLI binary and runnable examples.

Add to Cargo.toml

[dependencies]
aignt-mint-security-scorer = "0.1.0"
tokio = { version = "1", features = ["full"] }
anyhow = "1"
reqwest = { version = "0.12", features = ["json"] }

Quick Start

use birdeye_client::client::{BirdeyeClient, BirdeyeProvider};
use aignt_mint_scoring::{security_score, RiskLevel};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let birdeye = BirdeyeClient::new("your-birdeye-api-key", BirdeyeProvider::Birdeye, None)?;
    let rc_client = reqwest::Client::new();

    let mint = "So11111111111111111111111111111111111111112";

    // Full score with rugcheck LP data
    let result = security_score(&birdeye, Some(&rc_client), mint).await?;

    println!("Score: {:.1}/100", result.score);
    println!("Risk:  {:?}", result.risk_level);
    println!("Platform: {} ({})", result.launch_platform, result.platform_trust_level);

    if result.hard_stop_triggered {
        for v in &result.hard_stop_violations {
            eprintln!("[{}] {}", v.severity, v.message);
        }
    }

    match result.risk_level {
        RiskLevel::Excellent | RiskLevel::Good => println!("Safe to trade"),
        RiskLevel::Moderate                    => println!("Proceed with caution"),
        RiskLevel::Poor | RiskLevel::Critical  => println!("Do not invest"),
    }

    Ok(())
}

Without rugcheck (Birdeye only)

use aignt_mint_scoring::security_score;

// Pass None to skip rugcheck — liquidity category is granted full 25 pts
let result = security_score(&birdeye, None, mint).await?;

Score from already-fetched data

use aignt_mint_scoring::score;

let result = score(mint, &security, Some(&rugcheck_report));
// or pass None to skip liquidity scoring

Score Breakdown

Category Max pts Notes
Authority Controls 25 Mint & freeze authority revoked
Holder Distribution 20 Top-10 concentration, creator holdings
Metadata & Flags 15 Immutable metadata, no transfer fee
Trust Signals 15 Jupiter strict list, Birdeye fake flag
Exit Liquidity 25 LP lock % from rugcheck.xyz
Score Risk Level Meaning
90–100 Excellent Very Safe
75–89 Good Generally Safe
60–74 Moderate Exercise Caution
40–59 Poor High Risk
0–39 Critical Very High Risk / Likely Scam

Hard stops cap the score for critical issues (e.g. extreme holder concentration, non-transferable flag).

Platform-aware scoring avoids false positives for known launchpads: Pump.fun, Bonk Launchpad, Moonshot, LetsBonk.

Environment Variables

Variable Required Description
DATA_PROVIDER_API_KEY Yes API key for Birdeye or Uniblock
DATA_PROVIDER No birdeye (default) or uniblock

CLI Binary

export DATA_PROVIDER_API_KEY=your_key

# Text output (default)
cargo run --bin score -- --mint <MINT>

# JSON output
cargo run --bin score -- --mint <MINT> --format json

# Uniblock proxy
cargo run --bin score -- --mint <MINT> --provider uniblock

# Verbose: dump raw API responses
cargo run --bin score -- --mint <MINT> --verbose

Options: --mint, --api-key, --provider (birdeye|uniblock), --format (text|json), --verbose.

Examples

# Full analysis of a single mint
DATA_PROVIDER_API_KEY=xxx cargo run --example score_mint -- <MINT>

# Fetch and display a rugcheck report
DATA_PROVIDER_API_KEY=xxx cargo run --example rugcheck_report -- <MINT>

# Rugcheck rate-limit demo
DATA_PROVIDER_API_KEY=xxx cargo run --example rugcheck_rate_limit

Project Structure

mint-security-scorer/
├── src/
│   ├── lib.rs           # Public API re-exports
│   ├── fetch.rs         # Birdeye token security fetch
│   ├── scorer.rs        # Scoring logic (5 categories)
│   ├── hard_stops.rs    # Hard stop checks (3 severity levels)
│   ├── platform.rs      # Launch platform detection
│   ├── rugcheck.rs      # Rugcheck.xyz client + LP scoring
│   └── bin/
│       └── score.rs     # CLI binary
└── examples/
    ├── score_mint.rs        # Full analysis of a single mint
    ├── rugcheck_report.rs   # Fetch and display a rugcheck report
    └── rugcheck_rate_limit.rs

License

MIT