@coinsensors/sdk

Official TypeScript SDK for the CoinSensors token security API. Scan tokens for rug pull indicators, get trust scores (0-100), and receive AI-powered risk analysis across Solana, Ethereum, BNB Chain, and Base.

Installation

npm install @coinsensors/sdk

Quick Start

import { CoinSensorsClient } from '@coinsensors/sdk';

const client = new CoinSensorsClient({
  apiKey: 'your-api-key',
});

// Scan a token
const result = await client.scan('TOKEN_MINT_ADDRESS');
console.log(result.score.trustScore); // 0-100
console.log(result.score.riskLevel); // LOW | MODERATE | HIGH

Usage

Scan a Token

// Basic scan
const result = await client.scan('TOKEN_MINT_ADDRESS');

// Specify chain (auto-detected by default)
const result = await client.scan('0xTOKEN_ADDRESS', { chain: 'ethereum' });

// Force rescan (bypass cache)
const result = await client.scan('TOKEN_MINT_ADDRESS', { force: true });

Get Token Details

const token = await client.getToken('TOKEN_MINT_ADDRESS');

console.log(token.info.name);
console.log(token.score.trustScore);
console.log(token.checks); // Individual check results
console.log(token.aiNarrative?.narrative); // AI risk analysis

List Analyzed Tokens

const tokens = await client.listTokens({
  page: 1,
  limit: 20,
  riskLevel: 'HIGH',
  sortBy: 'newest',
});

Scan a Wallet

// One-shot scan
const wallet = await client.scanWallet('WALLET_ADDRESS');
console.log(wallet.portfolio.overallScore);

// Stream results progressively via SSE
const stream = client.scanWalletStream('WALLET_ADDRESS');

stream.on('holdings_discovered', (data) => {
  console.log(`Found ${data.holdings.length} tokens`);
});

stream.on('token_scored', (data) => {
  console.log(`${data.token.symbol}: ${data.score.trustScore}`);
});

stream.on('scan_complete', (data) => {
  console.log('Done!', data.portfolio);
});

Real-Time Feed

const feed = client.subscribeFeed();

feed.on('message', (msg) => {
  console.log('New token:', msg);
});

feed.on('error', (err) => console.error(err));

Error Handling

import {
  CoinSensorsClient,
  ValidationError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ServerError,
} from '@coinsensors/sdk';

try {
  await client.scan('invalid-address');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log('Bad request:', err.message);
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof NotFoundError) {
    console.log('Token not found');
  } else if (err instanceof ServerError) {
    console.log('Server error:', err.message);
  }
}

Supported Chains

| Chain | Address Format | |-------|---------------| | Solana | Base58 (e.g. So11111111...) | | Ethereum | 0x + 40 hex chars | | BNB Chain | 0x + 40 hex chars | | Base | 0x + 40 hex chars |

Chain is auto-detected from the address format. You can also specify it explicitly via the chain option.

Types

All API types are re-exported from the SDK:

import type {
  TokenDetail,
  TokenInfo,
  TokenScore,
  ScanResponse,
  CheckResult,
  WalletScanResponse,
  Chain,
} from '@coinsensors/sdk';

License

MIT