@webacy/sdk-threat

Threat and risk analysis SDK for the Webacy Risk Score API. Analyze addresses, contracts, and URLs for security risks.

Installation

npm install @webacy/sdk-threat

Or install the full SDK:

npm install @webacy/sdk

Quick Start

import { ThreatClient, RiskModule } from '@webacy/sdk-threat';

const client = new ThreatClient({
  apiKey: process.env.WEBACY_API_KEY!,
});

// Analyze address risk
const risk = await client.addresses.analyze('0x742d35Cc...', {
  chain: 'eth',
});

console.log(`Risk Score: ${risk.overallRisk}/100`);
console.log(`High severity issues: ${risk.high}`);

Features

Address Risk Analysis

Comprehensive security analysis for blockchain addresses.

const risk = await client.addresses.analyze('0x742d35Cc...', {
  chain: 'eth',
  modules: [RiskModule.FUND_FLOW_SCREENING, RiskModule.SANCTIONS_COMPLIANCE],
  detailed: true,
});

console.log(`Overall Risk: ${risk.overallRisk}/100`);
console.log(`Is Contract: ${risk.isContract}`);
console.log(`Address Type: ${risk.addressType}`);
console.log(`High Issues: ${risk.high}`);
console.log(`Medium Issues: ${risk.medium}`);

// Detailed fund flow analysis
if (risk.details?.fund_flows?.risk) {
  const flowRisk = risk.details.fund_flows.risk;
  if (flowRisk.ofac) console.log('Connected to OFAC addresses');
  if (flowRisk.tornado) console.log('Used Tornado Cash');
  if (flowRisk.mixers) console.log('Used mixing services');
}

Sanctions Screening

Screen addresses against OFAC and other sanctions lists.

const result = await client.addresses.checkSanctioned('0x...', {
  chain: 'eth',
});

if (result.is_sanctioned) {
  console.log('Address is sanctioned!');
  console.log(`Source: ${result.sanction_details?.source}`);
  console.log(`List: ${result.sanction_details?.list_name}`);
}

Address Poisoning Detection

Detect dust attack and address poisoning attempts.

const result = await client.addresses.checkPoisoning('0x...', {
  chain: 'eth',
});

if (result.is_poisoned) {
  console.log('Poisoning detected!');
  console.log(`Similar addresses: ${result.poisoning_details?.similar_addresses?.length}`);
  console.log(`Dust transactions: ${result.poisoning_details?.dust_tx_count}`);
}

Contract Analysis

Analyze smart contracts for vulnerabilities.

const contract = await client.contracts.analyze('0xContract...', {
  chain: 'eth',
});

console.log(`Risk Score: ${contract.overallRisk}/100`);
console.log(`Verified: ${contract.is_verified}`);

// Vulnerabilities
for (const vuln of contract.vulnerabilities || []) {
  console.log(`${vuln.severity}: ${vuln.name}`);
}

// Get source code
const source = await client.contracts.getSourceCode('0xContract...', {
  chain: 'eth',
});

// Get buy/sell taxes
const taxes = await client.contracts.getTaxes('0xToken...', {
  chain: 'eth',
});
console.log(`Buy Tax: ${taxes.buy_tax}%`);
console.log(`Sell Tax: ${taxes.sell_tax}%`);

URL Safety

Check URLs for phishing and malware.

const result = await client.url.check('https://suspicious-site.com');

if (result.is_malicious) {
  console.log(`Risk Score: ${result.risk_score}/100`);
  console.log(`Threats: ${result.threat_types?.join(', ')}`);
}

// Report a malicious URL
await client.url.add('https://phishing-site.xyz');

Wallet Analysis

Analyze wallet transactions and token approvals.

// Get recent transactions
const txs = await client.wallets.getTransactions('0x...', {
  chain: 'eth',
  limit: 10,
});

// Get token approvals
const approvals = await client.wallets.getApprovals('0x...', {
  chain: 'eth',
});

for (const approval of approvals.approvals || []) {
  console.log(`${approval.token_symbol}: ${approval.amount}`);
  if (approval.risk_score > 70) {
    console.log('  ⚠️ High risk approval!');
  }
}

Ledger Scan

Scan hardware wallet transactions for security.

const scan = await client.ledger.scanTransaction('ethereum', {
  tx: {
    from: '0x...',
    to: '0x...',
    data: '0x...',
  },
  chain: 1,
});

console.log(`Risk Level: ${scan.risk_level}`);
for (const warning of scan.warnings || []) {
  console.log(`Warning: ${warning}`);
}

Account Trace

Trace fund flows for an address.

const trace = await client.accountTrace.trace('0x...', {
  chain: 'eth',
});

console.log(`Traced transactions: ${trace.transactions?.length}`);

API Usage

Monitor your API usage and quota.

const usage = await client.usage.getCurrent();
console.log(`Requests used: ${usage.requests_used}`);
console.log(`Requests limit: ${usage.requests_limit}`);

API Reference

ThreatClient

const client = new ThreatClient({
  apiKey: string;           // Required: Your Webacy API key
  baseUrl?: string;         // Optional: Custom API URL
  timeout?: number;         // Optional: Request timeout (ms)
  retry?: RetryConfig;      // Optional: Retry configuration
});

Resources

| Resource | Method | Description | |----------|--------|-------------| | addresses | analyze(address, options) | Analyze address risk | | addresses | checkSanctioned(address, options) | Check sanctions status | | addresses | checkPoisoning(address, options) | Check for poisoning | | contracts | analyze(address, options) | Analyze contract risk | | contracts | getSourceCode(address, options) | Get contract source | | contracts | getTaxes(address, options) | Get token taxes | | contracts | analyzeSolidity(body) | Analyze Solidity code | | url | check(url) | Check URL safety | | url | add(url) | Report malicious URL | | wallets | getTransactions(address, options) | Get wallet transactions | | wallets | getApprovals(address, options) | Get token approvals | | ledger | scanTransaction(family, body) | Scan Ledger transaction | | ledger | scanEip712(family, body) | Scan EIP-712 message | | accountTrace | trace(address, options) | Trace fund flows | | usage | getUsage(options) | Get usage history | | usage | getCurrent() | Get current usage | | usage | getPlans() | Get available plans |

Risk Modules

import { RiskModule } from '@webacy/sdk-threat';

const modules = [
  RiskModule.FUND_FLOW_SCREENING,
  RiskModule.SANCTIONS_COMPLIANCE,
  RiskModule.CONTRACT_ANALYSIS,
  RiskModule.TOKEN_SECURITY,
  // ... and more
];

Supported Chains

• Ethereum (eth)
• Base (base)
• BSC (bsc)
• Polygon (pol)
• Arbitrum (arb)
• Optimism (opt)
• Solana (sol)
• TON (ton)
• Sui (sui)
• Stellar (stellar)
• Bitcoin (btc)

Error Handling

import { ThreatClient, RateLimitError, AuthenticationError } from '@webacy/sdk-threat';

try {
  const risk = await client.addresses.analyze('0x...', { chain: 'eth' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  }
}

License

MIT