API Documentation

Complete API reference for integrating DeFiGuard AI into your applications

Quick Start

DeFiGuard AI provides RESTful APIs for analyzing smart contracts, recording audits on-chain, and minting certification badges. All endpoints require JSON payloads and return JSON responses.

Base URL:

https://your-domain.com/api

MCP Architecture: How It Works

Understanding the Model Context Protocol integration that powers DeFiGuard AI

What is MCP Architecture?

DeFiGuard AI uses Model Context Protocol (MCP) to enhance AI analysis with specialized data sources. When you submit a contract for analysis, three MCP servers work in parallel to provide comprehensive security insights.

1. SlitherMCP Server

Performs static code analysis on your Solidity contract:

Detects known vulnerability patterns (reentrancy, overflow, access control)
Analyzes code structure and identifies security weaknesses
Provides line-by-line vulnerability mapping with severity levels
Identifies gas optimization opportunities

2. BlockchainMCP Server

Fetches on-chain data when a contract address is provided:

Retrieves contract verification status from blockchain explorers
Fetches transaction history and interaction patterns
Analyzes token holder distribution and contract usage
Validates contract behavior in production environment

3. DeFiDataMCP Server

Correlates contract patterns with historical exploits:

Matches vulnerabilities to real-world hacks (DAO Hack 2016, Parity Wallet, etc.)
Provides exploit scenarios based on similar compromised contracts
Enhances AI understanding with DeFi protocol security data
Offers historical context for vulnerability assessment

How MCP Enhances AI Analysis

Step 1: All three MCP servers execute in parallel, collecting static analysis, on-chain data, and historical exploit information.

Step 2: The collected data is aggregated into a rich context that includes vulnerability patterns, real-world usage, and historical correlations.

Step 3: This enriched context is injected into the Gemini AI prompt, providing the model with multi-dimensional understanding beyond simple code review.

Step 4: Gemini AI generates comprehensive vulnerability reports that combine code analysis, real-world validation, and historical knowledge.

Benefits

✓Fault tolerant - partial failures don't break analysis

✓Parallel execution for faster results

✓Multi-dimensional analysis catches more vulnerabilities

✓Real-world context enhances AI understanding

POST

/api/analyze

Analyze a smart contract for security vulnerabilities using Gemini AI + MCP Architecture

Parameters

codestring

Required

Solidity source code of the contract

contractAddressstringContract address (optional)

Response

{
  "success": true,
  "data": {
    "riskScore": "number",
    "vulnerabilities": "array",
    "recommendations": "array",
    "overallAssessment": "string"
  },
  "modelUsed": "string"
}

Example

// Analyze a smart contract
const response = await fetch('/api/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: contractSourceCode,
    contractAddress: '0x...' // Optional
  })
});

const result = await response.json();
// Returns: { success: true, data: VulnerabilityAnalysis, modelUsed: string }

POST

/api/record-audit

Record an audit result on-chain to the AuditRegistry contract

Parameters

contractAddressstring

Required

Address of the audited contract

riskScorenumber

Required

Risk score from 0-100

reportHashstring

Required

IPFS hash of the audit report

Response

{
  "success": true,
  "transactionHash": "string"
}

Example

POST

/api/mint-badge

Mint an NFT certification badge for contracts with risk score < 40

Parameters

contractAddressstring

Required

Address of the certified contract

riskScorenumber

Required

Risk score (must be < 40)

Response

{
  "success": true,
  "tokenId": "string",
  "transactionHash": "string"
}

Example

Error Handling

All API endpoints return standard HTTP status codes. Errors are returned in the following format:

{
  "success": false,
  "error": "Error message describing what went wrong",
  "details": { /* Additional error details in development */ }
}

400 Bad Request: Invalid parameters or request format

500 Internal Server Error: Server-side error during processing

503 Service Unavailable: API service temporarily unavailable

Rate Limiting

API requests are rate-limited to prevent abuse. Current limits:

• Analyze endpoint: 10 requests per minute per IP
• Record audit endpoint: 5 requests per minute per wallet
• Mint badge endpoint: 3 requests per minute per wallet