# 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](https://rugcheck.xyz). Ships with a CLI binary and runnable examples.

## Add to Cargo.toml

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

## Quick Start

```rust
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)

```rust
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

```rust
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

```bash
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

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