SCANAI SDK

Official TypeScript/JavaScript SDK for integrating SCANAI token risk and survival analysis into BNB Chain applications.

Installation

npm install @scanai/sdk
yarn add @scanai/sdk
pnpm add @scanai/sdk

Quick Start

import { ScanAI } from '@scanai/sdk';



// Initialize the client

const scanai = new ScanAI({

apiKey: 'your-api-key', // Optional: can use SCANAI_API_KEY env var

});



// Scan a token

const scan = await scanai.scanToken({

address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",

atBlock: 12345678, // Optional: analyze at specific block

});



// Check results

if (scan.risk.band === "critical" || scan.survival.state === "dead") {

// Block swap, show warning, whatever your app needs

console.warn("⚠️ High risk token detected!");

}

\`\`\`

Usage Examples

Basic Token Scan

const result = await scanai.scanToken({

address: "0x...",

});



console.log(`Risk Level: ${result.risk.band}`);

console.log(`Risk Score: ${result.risk.score}/100`);

console.log(`Survival State: ${result.survival.state}`);

console.log(`Survival Probability: ${result.survival.probability}%`);

Historical Analysis

// Analyze token at a specific block

const historicalScan = await scanai.scanToken({

address: "0x...",

atBlock: 12000000,

includeHistory: true,

});

Quick Safety Check

// Simple boolean check for trading safety

const isSafe = await scanai.isSafeToTrade("0x...");



if (!isSafe) {

throw new Error("Cannot proceed with swap - token flagged as unsafe");

}

Batch Scanning

// Scan multiple tokens at once

const tokens = ["0x...", "0x...", "0x..."];

const results = await scanai.batchScan(tokens);



// Filter for high-risk tokens

const dangerous = results.filter(

r => r.risk.band === "critical" || r.risk.band === "high"

);

Wallet Integration Example

import { ScanAI } from '@scanai/sdk';



class WalletSecurityLayer {

private scanai: ScanAI;



constructor() {

this.scanai = new ScanAI({ apiKey: process.env.SCANAI_API_KEY });

}



async validateSwap(tokenAddress: string): Promise<boolean> {

const scan = await this.scanai.scanToken({ address: tokenAddress });

// Block critical and dead tokens

if (scan.risk.band === "critical") {

throw new Error(`Token flagged as critical risk: ${scan.risk.summary}`);

}

if (scan.survival.state === "dead") {

throw new Error("Token appears to be dead - no trading activity");

}

// Warn on high risk

if (scan.risk.band === "high") {

console.warn("⚠️ High risk token detected", scan.risk.flags);

return false; // Let user decide

}

return true;

}

}

DeFi Dashboard Integration

import { ScanAI } from '@scanai/sdk';



async function analyzePortfolio(tokenAddresses: string[]) {

const scanai = new ScanAI();

const scans = await scanai.batchScan(tokenAddresses);

return {

total: scans.length,

safe: scans.filter(s => s.risk.band === "safe").length,

risky: scans.filter(s => ["high", "critical"].includes(s.risk.band)).length,

dead: scans.filter(s => s.survival.state === "dead").length,

details: scans,

};

}

API Reference

ScanAI

Main SDK client class.

Constructor

new ScanAI(config?: ScanAIConfig)

Config Options:

• apiKey?: string - API key (or set SCANAI_API_KEY env var)

• endpoint?: string - Custom API endpoint (defaults to production)

• timeout?: number - Request timeout in ms (default: 30000)

• debug?: boolean - Enable debug logging (default: false)

Methods

scanToken(options: ScanOptions): Promise<ScanResult>

Scan a token for risk and survival analysis.

Options:

• address: string - Token contract address (required)

• atBlock?: number - Specific block to analyze

• includeHistory?: boolean - Include historical data

• chain?: "bsc" | "bnb" - Blockchain network

Returns: Complete scan results including risk and survival analysis.

batchScan(addresses: string[], options?): Promise<ScanResult[]>

Scan multiple tokens in parallel.

isSafeToTrade(address: string, options?): Promise<boolean>

Quick safety check returning true if token is safe to trade.

Types

RiskBand

type RiskBand = "safe" | "low" | "medium" | "high" | "critical";

SurvivalState

type SurvivalState = "alive" | "warning" | "zombie" | "dead";

ScanResult

interface ScanResult {

token: TokenMetadata;

risk: RiskAnalysis;

survival: SurvivalAnalysis;

scannedAtBlock: number;

timestamp: number;

}

Environment Variables

Optional: API key for authentication

**SCANAI_API_KEY=your_api_key_here**

Integration Use Cases

• Wallets: Pre-transaction safety checks

• DEX Aggregators: Token risk warnings before swaps

• Portfolio Managers: Continuous monitoring of held assets

• Block Explorers: Display risk metrics on token pages

• DeFi Protocols: Automated risk-based restrictions

Error Handling

try {

const scan = await scanai.scanToken({ address: "0x..." });

} catch (error) {

if (error.message.includes("Invalid token address")) {

// Handle validation error

} else if (error.message.includes("timeout")) {

// Handle timeout

} else {

// Handle API error

}

}

Support

• GitHub: github.com/scanai/sdk

License

MIT