cavion-sdk

v0.1.3

Published

21 days ago

AI-powered Solana rug pull detector SDK & CLI

0High
0Medium
0Low

ponks

solana rug-pull defi web3 security dex

AI-powered Solana rug pull detector

Badges

Dependency audit

Latest committed npm audit output lives in docs/audit/ (index). Regenerate after dependency changes:

npm run audit:report

| Report | Scope | | ------ | ----- | | docs/audit/npm-audit.txt | All dependencies (including dev) | | docs/audit/npm-audit-production.txt | Production only (--omit=dev) |

Continuous audit: .github/workflows/security-audit.yml (push, PR, weekly schedule).

Links

| Resource | URL | | -------- | --- | | npm package | https://www.npmjs.com/package/cavion-sdk | | Source code (GitHub) | https://github.com/ponkssol/Cavion | | Issues | https://github.com/ponkssol/Cavion/issues | | Pull requests | https://github.com/ponkssol/Cavion/pulls |

The published SDK on npm is cavion-sdk. The CLI is available as cavion or cavion-sdk (same binary). The clone example below checks out the repo into a local directory named cavion for convenience.

What is Cavion?

Cavion is a TypeScript SDK + CLI that helps you assess Solana token risk before you buy. It combines on-chain checks (mint/freeze authorities), liquidity signals, dev wallet analysis, honeypot detection, and transaction-pattern heuristics to generate a risk score (0–100) with a clear, human-readable recommendation. It is designed to be production-ready, easy to integrate into bots, dashboards, or pipelines, and friendly for quick terminal checks.

⚠️ Disclaimer

This tool is for educational purposes only. Not financial advice. Always DYOR.

Features

🧊 Liquidity analysis: liquidity amount in USD, locked/unlocked signals, lock duration, pool address
👤 Dev wallet holdings: deployer/creator holdings as % of supply, selling behavior heuristics
🪤 Honeypot detection: can sell, buy/sell tax estimates, reason (via RugCheck API)
🏭 Mint authority status: detect if new tokens can be minted
🧷 Freeze authority status: detect if wallets can be frozen
🔁 Transaction pattern analysis: wash trading heuristics, fake volume estimation, suspicious wallets
🧮 Risk score + risk factors: 0–100 score, risk level buckets, factor breakdown + warnings
🧰 SDK + CLI: import into TypeScript apps or run npx cavion-sdk check <TOKEN_ADDRESS>
🤖 AI agent explanation (optional): add --explain to get an AI-generated summary and next steps

How Risk Score Works

The score is computed from weighted factors. Higher score = higher rug risk. Some factors (like honeypot) can push the token into CRITICAL.

| Factor | Weight | Description | | ----------------------- | ------------------: | ------------------------------------------------------------ | | Mint authority active | +25 | Token supply can potentially be inflated after launch. | | Freeze authority active | +20 | Wallets can potentially be frozen, blocking transfers/sells. | | Dev wallet > 20% supply | +20 | High concentration increases rug/market-manipulation risk. | | Liquidity not locked | +15 | LP can be pulled if liquidity is not locked/timelocked. | | Honeypot detected | +35 (auto max risk) | If selling is blocked, this is typically catastrophic. | | Suspicious tx patterns | +10 | Wash trading / fake volume signals. | | Low liquidity (< $10k) | +10 | Thin liquidity makes price easy to manipulate. |

Installation

Install as a dependency (SDK):

npm install cavion-sdk

Using other package managers:

pnpm add cavion-sdk
yarn add cavion-sdk

Or run the CLI without installing (recommended for quick checks):

npx cavion-sdk check <TOKEN_ADDRESS>

From source (GitHub)

git clone https://github.com/ponkssol/Cavion.git cavion
cd cavion
npm install
npm run build

Run the CLI locally after build:

node dist/cli.js --help
# or
npm start

Quick Start

SDK (minimal)

import { RugAnalyzer } from "cavion-sdk";

async function main() {
  const analyzer = RugAnalyzer.fromEnv();
  const res = await analyzer.analyze("So11111111111111111111111111111111111111112");

  console.log(res.riskScore, res.riskLevel);
  console.log(res.recommendation);
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

CLI (minimal)

npx cavion-sdk check So11111111111111111111111111111111111111112 --output table

SDK Usage

Basic analyze

import { RugAnalyzer } from "cavion-sdk";

const analyzer = RugAnalyzer.fromEnv({
  timeoutMs: 20_000,
});

const result = await analyzer.analyze("So11111111111111111111111111111111111111112");

console.log({
  token: result.metadata.symbol,
  score: result.riskScore,
  level: result.riskLevel,
  warnings: result.warnings,
});

Batch analyze

import { RugAnalyzer } from "cavion-sdk";

const analyzer = RugAnalyzer.fromEnv();

const batch = await analyzer.analyzeBatch(
  ["So11111111111111111111111111111111111111112", "Es9vMFrzaCER9gVgk1TKoPY1TGVtC6zqD2cEJtQh7rxx"],
  5
);

console.log("Analyzed:", batch.results.length);
console.log("Failed:", batch.failedAddresses);

Custom weights

import { RugAnalyzer } from "cavion-sdk";

const analyzer = RugAnalyzer.fromEnv({
  customWeights: {
    liquidityNotLocked: 20,
    lowLiquidity: 15,
    suspiciousPatterns: 5,
  },
});

const res = await analyzer.analyze("So11111111111111111111111111111111111111112");
console.log(res.riskScore, res.riskFactors);

TypeScript types

import type { AnalysisResult, RiskLevel, TokenAddress } from "cavion-sdk";

function isCritical(r: AnalysisResult): boolean {
  return r.riskLevel === ("CRITICAL" as RiskLevel);
}

const mint = "So11111111111111111111111111111111111111112" as TokenAddress;
console.log(mint);

CLI Usage

Commands

# Analyze a token (default shorthand)
npx cavion-sdk check <TOKEN_ADDRESS>

# Equivalent (explicit)
npx cavion-sdk analyze <TOKEN_ADDRESS>

# Choose output format
npx cavion-sdk check <TOKEN_ADDRESS> --output table
npx cavion-sdk check <TOKEN_ADDRESS> --output json
npx cavion-sdk check <TOKEN_ADDRESS> --output minimal

# AI agent explanation
npx cavion-sdk check <TOKEN_ADDRESS> --explain

# Auto-run AI explanation without flags
# (requires ANTHROPIC_API_KEY)
CAVION_EXPLAIN=1 npx cavion-sdk check <TOKEN_ADDRESS>

# Verbose logs (helpful for debugging API/rate-limit issues)
npx cavion-sdk check <TOKEN_ADDRESS> --verbose

# Disable colors (CI, logs, piping)
npx cavion-sdk check <TOKEN_ADDRESS> --no-color

Example output (table)

CAVION  Solana Rug Risk Analysis

Token:        EXAMPLE (EXM)
Mint:         So11111111111111111111111111111111111111112
Risk Score:   72 / 100
Risk Level:   HIGH
Recommendation: 🚨 High risk detected — avoid or use minimal amounts

┌───────────────────────────────┬───────────┬─────────┐
│ Risk factor                   │ Detected  │ Score   │
├───────────────────────────────┼───────────┼─────────┤
│ Mint authority is active (...)│ yes       │ +25     │
│ Freeze authority is active (...)│ no      │ +0      │
│ Dev wallet holds 24.80% of supply│ yes    │ +20     │
│ Liquidity appears not locked  │ yes       │ +15     │
│ Honeypot detected (...)       │ no        │ +0      │
│ Suspicious transaction patterns (...)│ yes│ +10     │
│ Low liquidity: $7200.00 (< $10k)│ yes     │ +10     │
└───────────────────────────────┴───────────┴─────────┘

Warnings:
- High risk: Liquidity is not locked
- High risk: Dev wallet holds 24.8% of supply
- Moderate risk: Wash trading patterns detected (fake volume ~11%)

Example output (AI explanation)

AI explanation:
Skor risiko HIGH (72/100). Ada kombinasi kontrol supply dan konsentrasi kepemilikan yang berpotensi berbahaya, ditambah liquidity yang terlihat tidak terkunci.

Key findings:
- Mint authority masih aktif sehingga supply dapat bertambah.
- Dev wallet memegang porsi besar supply (24.8%).
- Liquidity terlihat tidak locked dan total liquidity rendah, rawan ditarik/dimanipulasi.

Next steps:
- Hindari entry besar; kalau tetap masuk, gunakan ukuran kecil dan pasang rencana exit.
- Verifikasi lock LP secara manual (locker address + unlock time) dan cek distribusi holder.
- Uji sell di amount kecil sebelum trade lebih besar.

Example output (json)

{
  "tokenAddress": "So11111111111111111111111111111111111111112",
  "metadata": {
    "name": "Example",
    "symbol": "EXM",
    "decimals": 9,
    "totalSupply": "1000000000000000",
    "createdAt": null,
    "creator": "8Yk...Dev"
  },
  "liquidity": {
    "totalUSD": 7200,
    "isLocked": false,
    "lockDurationDays": 0,
    "lockedPercent": 0,
    "poolAddress": "9pQ...Pool"
  },
  "devWallet": {
    "address": "8Yk...Dev",
    "holdingPercent": 24.8,
    "hasSold": false,
    "firstSeenDaysAgo": 2,
    "txCount": 41
  },
  "honeypot": { "isHoneypot": false, "canSell": true, "sellTaxPercent": 6, "buyTaxPercent": 4 },
  "authority": {
    "mintAuthorityActive": true,
    "freezeAuthorityActive": false,
    "mintAuthority": "8Yk...Dev",
    "freezeAuthority": null
  },
  "patterns": {
    "washTradingDetected": true,
    "fakevolumePercent": 11,
    "uniqueBuyers": 134,
    "uniqueSellers": 92,
    "suspiciousWallets": ["F1a...X", "9Zz...Q"]
  },
  "riskScore": 72,
  "riskLevel": "HIGH",
  "riskFactors": [
    {
      "name": "mintAuthorityActive",
      "description": "Mint authority is active",
      "severity": "HIGH",
      "score": 25,
      "detected": true
    }
  ],
  "analyzedAt": "2026-04-10T00:00:00.000Z",
  "warnings": ["High risk: Liquidity is not locked"],
  "recommendation": "🚨 High risk detected — avoid or use minimal amounts"
}

API Reference

Public exports (SDK)

| Export | Type | Description | | ------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------- | | RugAnalyzer | class | Main analyzer orchestrator. | | RiskLevel | enum | Risk buckets: SAFE/LOW/MEDIUM/HIGH/CRITICAL. | | TokenAddress | type | Branded string type for Solana mints. | | AnalysisResult | interface | Full analysis output. | | BatchAnalysisResult | interface | Batch output with failures. | | AnalyzerConfig | interface | SDK config (keys, endpoint, timeout, weights). | | RiskWeights | interface | Weight overrides for scoring. | | LiquidityInfo / DevWalletInfo / HoneypotInfo / AuthorityInfo / PatternInfo | interfaces | Per-module outputs. |

`RugAnalyzer` methods

| Method | Parameters | Returns | Notes | | --------------------------------------- | --------------------------------------------- | ------------------------------ | ---------------------------------------------- | | constructor(config) | config: AnalyzerConfig | RugAnalyzer | Create analyzer with API keys and options. | | analyze(tokenAddress) | tokenAddress: string | Promise<AnalysisResult> | Validates address and runs checks in parallel. | | analyzeBatch(addresses, concurrency?) | addresses: string[], concurrency?: number | Promise<BatchAnalysisResult> | Runs multiple analyses with concurrency limit. | | fromEnv(config?) | config?: Partial<AnalyzerConfig> | RugAnalyzer | Convenience constructor using process.env. |

Environment Variables

Create a .env file (see .env.example) or export variables in your shell.

| Variable | Required | Description | | --------------------- | :------: | -------------------------------------------------------- | | HELIUS_API_KEY | ✅ | Helius key for metadata and transaction queries. | | BIRDEYE_API_KEY | ✅ | Birdeye key for liquidity/price data. | | SOLANA_RPC_ENDPOINT | ❌ | Custom RPC endpoint (defaults to mainnet-beta). | | CAVION_TIMEOUT_MS | ❌ | HTTP timeout in milliseconds (e.g. 20000). | | ANTHROPIC_API_KEY | ❌ | Enables optional --explain via the Anthropic API. | | ANTHROPIC_MODEL | ❌ | Overrides the default chat model id for --explain. | | CAVION_EXPLAIN | ❌ | Set to 1 to auto-run AI explanation in CLI. |

Supported DEXes

Raydium
Jupiter
Pump.fun
Orca
Meteora

Contributing

Contributions are welcome! 🎉

Cavion is developed in the open; use the GitHub repository above for issues and pull requests.

Fork the Cavion repository on GitHub and create your branch: git checkout -b feat/amazing-feature
Keep changes focused: one feature or fix per PR
Run checks locally: npm test, npm run lint, and npm run build (TypeScript compile)
Add tests for non-trivial logic (scoring, parsers, API clients)
Write clear PR descriptions (what/why/how) and link issues if applicable

PR guidelines

Use strict TypeScript (no any)
Handle API errors gracefully (never crash on a single provider failure)
Keep outputs deterministic and well-typed
Avoid breaking changes unless necessary (and document them)

Roadmap

[ ] Browser extension (Chrome/Brave)
[ ] Real-time wallet monitoring
[ ] Telegram/Discord bot integration
[ ] Historical rug pull database
[ ] Machine learning risk model
[ ] Mobile app notifications

License

MIT. See LICENSE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Badges

Dependency audit

Links

What is Cavion?

⚠️ Disclaimer

Features

How Risk Score Works

Installation

From source (GitHub)

Quick Start

SDK (minimal)

CLI (minimal)

SDK Usage

Basic analyze

Batch analyze

Custom weights

TypeScript types

CLI Usage

Commands

Example output (table)

Example output (AI explanation)

Example output (json)

API Reference

Public exports (SDK)

RugAnalyzer methods

Environment Variables

Supported DEXes

Contributing

PR guidelines

Roadmap

License

Built with ❤️ by the community

`RugAnalyzer` methods