📡 Developer Documentation

📦 TypeScript SDK (Recommended)

The easiest way to integrate VibeGuard into your Sui wallet or dApp.

npm install vibeguard-sui-security

import { VibeGuard } from 'vibeguard-sui-security';

const guard = new VibeGuard();

const result = await guard.analyzeTransaction({
  transactionBytes: 'AAACAA...',
  network: 'testnet',
  userAddress: '0x1234...',
  userIntent: 'Claim airdrop',
  onThreatDetected: (result) => {
    // Fires on RED results — threat is auto-reported on-chain by VibeGuard
    console.error('🚨 THREAT DETECTED:', result.explanation.headline);
  }
});

if (result.risk.riskLevel === 'RED') {
  // Block transaction
}

Retrieve Threat Report

Fetch the full AI threat report from Walrus decentralized storage using a blob ID from a ThreatReported on-chain event.

// blobId from ThreatReported event, blobObjectId optional for liveness check
const report = await guard.retrieveThreatReport(
  'oNyrr0jEVATWSAGkJHnmoKVICnFosv1k4YNayZXcRgk',
  '0x08108c74...'
);

console.log(report.riskLevel);    // 'RED'
console.log(report.reasons);      // [...]
console.log(report.plainEnglish); // Full AI explanation

🌐 Direct API Access

Base URL

🔓 Authentication

The API is currently fully open — no API key required. All endpoints are accessible without authentication.

For enterprise access, rate limit increases, or partnership inquiries, open a GitHub Issue.

POST /api/explain

Full transaction analysis with AI explanation and scam detection.

Request Body

{
  "transactionBytes": "AAACAA...",  // Base64 bytes BEFORE signing
  "network": "testnet",
  "userAddress": "0x...",
  "userIntent": "Claim airdrop"  // Optional but recommended
}

⚠️ Use base64 transaction bytes from your wallet BEFORE signing. Transaction hashes from explorers won't work.

Response

{
  "simulation": {
    "effectsSummary": {...},
    "staticAnalysis": {
      "moveCalls": [...],
      "gasBudget": "10000000",
      "containsDirectTransfer": true
    }
  },
  "risk": {
    "riskLevel": "RED",
    "reasons": [
      "Assets leave your wallet to another address",
      "⚠️ INTENT MISMATCH: You expect to receive assets, but this sends assets away"
    ],
    "confidence": 0.9
  },
  "explanation": {
    "headline": "Honeypot Scam Detected",
    "plainEnglish": "This transaction will send 100 SUI from your wallet...",
    "recommendedAction": "Do Not Sign"
  }
}

GET /api/threat/[blobId]

Retrieve a full threat report from Walrus decentralized storage. Accepts an optional blobObjectId query parameter to verify the Blob NFT is still live on Sui before fetching.

# Without liveness check
GET /api/threat/:blobId

# With Blob NFT liveness gate (returns 410 if expired)
GET /api/threat/:blobId?blobObjectId=0x...

Response

{
  "metadata": {
    "title": "VibeGuard AI Threat Report",
    "publisher": "0x...",
    "category": "Security Signal",
    "timestamp": "2026-03-23T08:43:36.775Z"
  },
  "packageId": "0x...",
  "riskLevel": "RED",
  "headline": "Automated Detection: Honeypot/Malicious Contract",
  "reasons": [...],
  "reportedAt": "2026-03-23T08:43:36.775Z",
  "reportedBy": "vibeguard-automated-pipeline"
}

Example: cURL

curl -X POST https://vibeguardai.vercel.app/api/explain \
  -H "Content-Type: application/json" \
  -d '{
    "transactionBytes": "AAACAA...base64...",
    "network": "testnet",
    "userAddress": "0x1234...5678",
    "userIntent": "Claim free airdrop"
  }'

Replace with your actual base64 transaction bytes and wallet address.

Example: JavaScript

const response = await fetch('https://vibeguardai.vercel.app/api/explain', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transactionBytes: 'AAACAA...base64...',
    network: 'testnet',
    userAddress: '0x1234...5678',
    userIntent: 'Claim free airdrop'
  })
});

const data = await response.json();
console.log(data.risk.riskLevel);
console.log(data.explanation.recommendedAction);