scanshield-js

Rug-pull scanner for EVM tokens. 6 chains. $0.01 per scan. 1-second response.

Prevents your trading bot from buying honeypots, rug-pulls, and high-tax traps.

Install

npm install scanshield-js

Quick Start

import { ScanShield } from "scanshield-js";

const client = new ScanShield({ apiKey: process.env.SCANSHIELD_API_KEY! });

// One-shot check
const result = await client.scan("0xdAC17F958D2ee523a2206206994597C13D831ec7", "eth");
console.log(result.status); // "SAFE" | "WARNING" | "DANGER" | "UNKNOWN"

// Strict gate for trading bots
if (await client.isSafe(tokenAddress, "base")) {
  // proceed with trade
}

// Throw if dangerous
await client.assertNotDanger(tokenAddress, "base");

What It Checks

| Check | Source | Detection | |---|---|---| | Honeypot | GoPlus | Is the token un-sellable? | | Mintable | GoPlus | Can the owner mint unlimited tokens? | | Buy/Sell Tax | GoPlus | Does the contract charge >10% tax? | | Liquidity | DexScreener | Is trading liquidity too low? | | Active Pairs | DexScreener | Are there any active trading pairs? |

Response Format

{
  token: string;          // 0x...
  chain: string;          // "1" | "8453" | "56" | ...
  status: "SAFE" | "WARNING" | "DANGER" | "UNKNOWN";
  details: string[];      // human-readable reasons
  liquidityUsd: number;
}

Status Semantics

| Status | Meaning | What your bot should do | |---|---|---| | SAFE | All checks passed | Proceed | | WARNING | Concerning but not fatal (mintable, low liquidity, medium tax) | Smaller position OR skip | | DANGER | Fatal (honeypot, zero liquidity, extreme tax) | Do not buy | | UNKNOWN | Upstream API failure — never silently SAFE | Skip or retry later |

The SDK never downgrades to SAFE on API failure. This is intentional: a bot that buys a honeypot because "the scanner was down" is worse than a bot that skips valid trades.

Supported Chains

| Alias | Chain ID | Name | |---|---|---| | eth, ethereum | 1 | Ethereum | | base | 8453 | Base | | bsc | 56 | BNB Smart Chain | | arbitrum | 42161 | Arbitrum One | | optimism | 10 | Optimism | | polygon | 137 | Polygon PoS |

You can also pass a raw chain ID string: client.scan(token, "42161").

Configuration

new ScanShield({
  apiKey: "ss_xxx",                    // Required
  baseUrl: "https://rugguard.online",  // Default
  timeoutMs: 10_000,                    // Default
  maxRetries: 2,                        // Default (retries on 5xx/429)
});

Error Handling

import { ScanShield, ScanShieldError } from "scanshield-js";

try {
  const result = await client.scan(token);
} catch (e) {
  if (e instanceof ScanShieldError) {
    // API error (4xx/5xx) or invalid input
    console.error(e.status, e.message, e.details);
  } else {
    // Network / timeout
  }
}

Pricing

• Pilot (current): Free API keys via DM. 100 scans/month.
• Production: $0.01 per scan via Virtuals Protocol ACP.

Examples

See examples/:

• pre-trade-check.ts — Gate before executing a trade

Links

• Homepage: https://rugguard.online
• API: https://rugguard.online/api/v1/scan
• Source: https://github.com/blazethrottle/Agent-Eco-Biz
• Virtuals Protocol ACP: https://app.virtuals.io/acp

License

MIT