Skip to main content
The ThreatClient provides access to Webacy’s threat and risk analysis APIs. Use it to analyze addresses for security risks, screen for sanctions, check smart contract vulnerabilities, and verify URL safety.

Initialization

import { ThreatClient, Chain } from '@webacy-xyz/sdk';

const client = new ThreatClient({
  apiKey: process.env.WEBACY_API_KEY,
  defaultChain: Chain.ETH, // Optional: set default chain
});

Resources

The ThreatClient provides access to these resources:
ResourceDescription
addressesAddress risk analysis, sanctions screening, poisoning detection
contractsSmart contract security analysis
urlURL safety and phishing detection
walletsWallet activity and approval analysis
ledgerHardware wallet transaction scanning
accountTraceFund flow tracing
usageAPI usage statistics

Addresses

Analyze Address Risk

Get comprehensive risk analysis for any blockchain address.
const result = await client.addresses.analyze(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  { chain: Chain.ETH }
);

console.log(result.overallRisk);  // 0-100 risk score
console.log(result.issues);       // Array of risk factors
console.log(result.isContract);   // true if smart contract
Response:
{
  "count": 1,
  "medium": 0,
  "high": 1,
  "overallRisk": 75.5,
  "issues": [
    {
      "tag": "Mixer User",
      "severity": "high",
      "description": "Address has interacted with mixing services"
    }
  ],
  "isContract": false
}
Options:
OptionTypeDescription
chainChainBlockchain to analyze (optional if defaultChain set)
modulesRiskModule[]Specific risk modules to run
detailedbooleanInclude detailed analysis data
deployerRiskbooleanInclude deployer risk for contracts

Check Sanctions

Screen an address against OFAC and other sanctions lists.
const result = await client.addresses.checkSanctioned(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  { chain: Chain.ETH }
);

if (result.is_sanctioned) {
  console.error('Address is sanctioned!');
  console.log(result.sanction_details);
}

Check Address Poisoning

Detect address poisoning (dust attack) attempts.
const result = await client.addresses.checkPoisoning(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  { chain: Chain.ETH }
);

if (result.is_poisoned) {
  console.warn('Address poisoning detected!');
  console.log(result.poisoning_details?.similar_addresses);
}

Contracts

Analyze Contract

Get security analysis for a smart contract.
const result = await client.contracts.analyze(
  '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
  { chain: Chain.ETH }
);

console.log(result.overallRisk);
console.log(result.vulnerabilities);

Get Contract Tax

Check buy/sell tax for a token contract.
const result = await client.contracts.getTax(
  '0xTokenAddress...',
  { chain: Chain.ETH }
);

console.log(`Buy tax: ${result.buyTax}%`);
console.log(`Sell tax: ${result.sellTax}%`);

URL Safety

Check URL

Analyze a URL for phishing and malware.
const result = await client.url.check('https://suspicious-site.com');

if (result.isPhishing) {
  console.error('Phishing site detected!');
}

console.log(result.riskScore);
console.log(result.categories);

Wallets

Get Approvals

List token approvals for a wallet.
const result = await client.wallets.getApprovals(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  { chain: Chain.ETH }
);

for (const approval of result.approvals) {
  console.log(`${approval.token} approved to ${approval.spender}`);
  console.log(`Amount: ${approval.amount}`);
}

Scan Transactions

Scan wallet transactions for risks.
const result = await client.wallets.scanTransactions(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  { chain: Chain.ETH }
);

Usage

Get API Usage

Monitor your API usage and quotas.
const usage = await client.usage.get();

console.log(`Requests used: ${usage.requestsUsed}`);
console.log(`Requests remaining: ${usage.requestsRemaining}`);
console.log(`Reset date: ${usage.resetDate}`);

Full Example

import { ThreatClient, Chain, ValidationError, RateLimitError } from '@webacy-xyz/sdk';

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

async function analyzeWallet(address: string) {
  try {
    // Get overall risk
    const risk = await client.addresses.analyze(address);

    if (risk.overallRisk > 70) {
      console.warn(`High risk wallet: ${risk.overallRisk}`);

      // Check sanctions
      const sanctions = await client.addresses.checkSanctioned(address);
      if (sanctions.is_sanctioned) {
        throw new Error('Sanctioned address - cannot proceed');
      }

      // Check for address poisoning
      const poisoning = await client.addresses.checkPoisoning(address);
      if (poisoning.is_poisoned) {
        console.warn('Address may be a poisoning attempt');
      }
    }

    return { safe: risk.overallRisk < 50, risk };

  } catch (error) {
    if (error instanceof ValidationError) {
      console.error('Invalid address:', error.message);
    } else if (error instanceof RateLimitError) {
      console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
    }
    throw error;
  }
}

Next Steps