Web3Sentinel SDK

Official JavaScript/TypeScript SDK for Web3Sentinel - AI-powered smart contract security platform.

Features

• 🔒 Smart Contract Audits - Submit contracts for AI-powered security analysis
• 📊 Real-time Monitoring - Monitor deployed contracts for suspicious activity
• 🎯 TypeScript Support - Full type definitions included
• ⚡ Simple API - Clean, intuitive interface
• 🔄 Async/Await - Modern promise-based API
• 📦 Zero Dependencies - Uses native fetch (Node.js 18+)

Installation

npm install @web3sentinel/sdk

yarn add @web3sentinel/sdk

pnpm add @web3sentinel/sdk

Quick Start

import { Web3Sentinel } from '@web3sentinel/sdk';

// Initialize the SDK
const sentinel = new Web3Sentinel({
  apiKey: 'ws_your_api_key_here'
});

// Submit a contract for audit
const audit = await sentinel.audits.create({
  name: 'MyToken',
  sourceCode: `
    pragma solidity ^0.8.0;
    contract MyToken {
      // Your contract code
    }
  `,
  analysisOptions: {
    aiVulnerabilityDetection: true,
    gasOptimization: true
  }
});

console.log('Audit submitted:', audit.audit.id);

// Wait for completion
const result = await sentinel.audits.waitForCompletion(audit.audit.id, {
  onProgress: (status) => console.log('Status:', status.status)
});

console.log('Security Score:', result.securityScore);
console.log('Vulnerabilities:', result.vulnerabilities.length);

Getting Your API Key

1. Sign up at web3sentinel.org
2. Upgrade to Enterprise plan (API access required)
3. Go to Dashboard → API Keys
4. Create a new API key with appropriate permissions

API Reference

Initialization

const sentinel = new Web3Sentinel({
  apiKey: 'ws_your_api_key',      // Required
  baseUrl: 'https://...',          // Optional, defaults to production
  timeout: 30000                   // Optional, request timeout in ms
});

Audits

Submit an Audit

const audit = await sentinel.audits.create({
  name: 'MyContract',
  sourceCode: 'pragma solidity ^0.8.0; ...',
  analysisOptions: {
    aiVulnerabilityDetection: true,
    gasOptimization: true,
    standardsCompliance: false,
    generatePdf: false
  }
});

Submit Verified Contract by Address

const audit = await sentinel.audits.create({
  name: 'USDT',
  address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
  network: 'ethereum'
});

Check Audit Status

const status = await sentinel.audits.getStatus('audit_123');
console.log(status.status); // 'pending' | 'processing' | 'completed' | 'failed'

Get Audit Results

const result = await sentinel.audits.getResult('audit_123');
console.log('Security Score:', result.securityScore);
console.log('Gas Score:', result.gasScore);
console.log('Overall Score:', result.overallScore);

result.vulnerabilities.forEach(vuln => {
  console.log(`[${vuln.severity}] ${vuln.title}`);
  console.log(`  Line ${vuln.lineNumber}: ${vuln.description}`);
  console.log(`  Fix: ${vuln.recommendation}`);
});

Wait for Completion

const result = await sentinel.audits.waitForCompletion('audit_123', {
  pollInterval: 5000,  // Check every 5 seconds
  timeout: 300000,     // Timeout after 5 minutes
  onProgress: (status) => {
    console.log('Current status:', status.status);
  }
});

Submit and Wait (One-liner)

const result = await sentinel.audits.submitAndWait({
  name: 'MyContract',
  sourceCode: contractCode
}, {
  onProgress: (status) => console.log('Status:', status.status)
});

Monitoring

Add Contract to Monitoring

await sentinel.monitoring.addContract({
  address: '0x1234567890abcdef...',
  network: 'ethereum',
  name: 'MyToken' // Optional
});

Remove Contract from Monitoring

await sentinel.monitoring.removeContract(
  '0x1234567890abcdef...',
  'ethereum'
);

List Monitored Contracts

const contracts = await sentinel.monitoring.listContracts();
console.log('Monitoring', contracts.length, 'contracts');

Get Alerts

const alerts = await sentinel.monitoring.getAlerts(
  '0x1234567890abcdef...',
  'ethereum',
  {
    limit: 50,
    severity: 'critical' // Optional filter
  }
);

alerts.forEach(alert => {
  console.log(`[${alert.severity}] ${alert.alertType}`);
  console.log(alert.message);
});

Acknowledge Alert

await sentinel.monitoring.acknowledgeAlert('alert_123');

Examples

Basic Audit

import { Web3Sentinel } from '@web3sentinel/sdk';

const sentinel = new Web3Sentinel({ apiKey: process.env.WEB3SENTINEL_API_KEY });

async function auditContract() {
  try {
    const result = await sentinel.audits.submitAndWait({
      name: 'SimpleToken',
      sourceCode: `
        pragma solidity ^0.8.0;
        contract SimpleToken {
          mapping(address => uint256) public balances;
          
          function transfer(address to, uint256 amount) public {
            balances[msg.sender] -= amount;
            balances[to] += amount;
          }
        }
      `
    });

    console.log(`✅ Audit complete!`);
    console.log(`Security Score: ${result.securityScore}/100`);
    console.log(`Found ${result.vulnerabilities.length} issues`);

    if (result.vulnerabilities.length > 0) {
      console.log('\n🔴 Vulnerabilities:');
      result.vulnerabilities.forEach((v, i) => {
        console.log(`${i + 1}. [${v.severity}] ${v.title}`);
      });
    }
  } catch (error) {
    console.error('Audit failed:', error.message);
  }
}

auditContract();

Monitor Multiple Contracts

import { Web3Sentinel } from '@web3sentinel/sdk';

const sentinel = new Web3Sentinel({ apiKey: process.env.WEB3SENTINEL_API_KEY });

async function monitorContracts() {
  const contracts = [
    { address: '0x...', network: 'ethereum', name: 'USDT' },
    { address: '0x...', network: 'polygon', name: 'USDC' },
    { address: '0x...', network: 'bsc', name: 'BUSD' }
  ];

  for (const contract of contracts) {
    await sentinel.monitoring.addContract(contract);
    console.log(`✅ Monitoring ${contract.name} on ${contract.network}`);
  }

  // Check for alerts periodically
  setInterval(async () => {
    for (const contract of contracts) {
      const alerts = await sentinel.monitoring.getAlerts(
        contract.address,
        contract.network,
        { severity: 'critical' }
      );

      if (alerts.length > 0) {
        console.log(`🚨 ${alerts.length} critical alerts for ${contract.name}`);
        alerts.forEach(alert => console.log(`  - ${alert.message}`));
      }
    }
  }, 60000); // Check every minute
}

monitorContracts();

CI/CD Integration

// audit-ci.ts
import { Web3Sentinel } from '@web3sentinel/sdk';
import * as fs from 'fs';

const sentinel = new Web3Sentinel({ apiKey: process.env.WEB3SENTINEL_API_KEY });

async function auditForCI() {
  const sourceCode = fs.readFileSync('./contracts/MyContract.sol', 'utf-8');

  console.log('🔍 Submitting contract for audit...');

  const result = await sentinel.audits.submitAndWait({
    name: 'MyContract',
    sourceCode,
    analysisOptions: {
      aiVulnerabilityDetection: true,
      gasOptimization: true,
      standardsCompliance: true
    }
  }, {
    onProgress: (status) => console.log(`Status: ${status.status}`)
  });

  console.log(`\n✅ Audit complete!`);
  console.log(`Security Score: ${result.securityScore}/100`);
  console.log(`Gas Score: ${result.gasScore}/100`);

  // Fail CI if critical vulnerabilities found
  const criticalVulns = result.vulnerabilities.filter(v => v.severity === 'critical');
  
  if (criticalVulns.length > 0) {
    console.error(`\n❌ Found ${criticalVulns.length} critical vulnerabilities!`);
    criticalVulns.forEach(v => {
      console.error(`  - ${v.title} (Line ${v.lineNumber})`);
    });
    process.exit(1);
  }

  // Warn if security score is low
  if (result.securityScore < 80) {
    console.warn(`\n⚠️  Security score below 80: ${result.securityScore}`);
    process.exit(1);
  }

  console.log('\n✅ All security checks passed!');
}

auditForCI().catch(error => {
  console.error('❌ Audit failed:', error.message);
  process.exit(1);
});

Error Handling

import { Web3Sentinel } from '@web3sentinel/sdk';

const sentinel = new Web3Sentinel({ apiKey: 'ws_...' });

try {
  const result = await sentinel.audits.create({
    name: 'MyContract',
    sourceCode: contractCode
  });
} catch (error) {
  if (error.statusCode === 401) {
    console.error('Invalid API key');
  } else if (error.statusCode === 429) {
    console.error('Rate limit exceeded');
  } else if (error.statusCode === 403) {
    console.error('Insufficient permissions or subscription tier');
  } else {
    console.error('Error:', error.message);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { 
  Web3Sentinel, 
  AuditResult, 
  Vulnerability,
  MonitoringAlert 
} from '@web3sentinel/sdk';

const sentinel = new Web3Sentinel({ apiKey: 'ws_...' });

// Full type inference
const result: AuditResult = await sentinel.audits.getResult('audit_123');
const vulns: Vulnerability[] = result.vulnerabilities;

Rate Limits

• Default: 100 requests per hour per API key
• Rate limits can be customized per API key in your dashboard
• The SDK will throw an error with statusCode: 429 when rate limit is exceeded

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://web3sentinel.org/docs
• 💬 Discord: https://discord.gg/web3sentinel
• � Telegram: @sopdap
• �🐛 Issues: https://github.com/web3sentinel/sdk/issues

License

MIT © Web3Sentinel

Contributing

Contributions are welcome! Please read our contributing guidelines first.