API Documentation

SmartSec scans smart contracts for security vulnerabilities. Free tier available, or $0.50-$2.00 for Claude AI analysis (based on contract size).

No API Keys

Basic tier is free (1 scan/day). Pro tier costs $0.50-$2.00 based on contract size - pay with USDC on Solana and include the transaction signature in the X-PAYMENT header.

Overview

Base URL: https://api.smartsec.app

All requests should use HTTPS. The API accepts multipart form data for file uploads and returns JSON responses.

Quick Start

# Free scan (1/day)
curl -X POST https://api.smartsec.app/audit \
  -F "file=@contract.sol" \
  -F "tier=basic"

# Pro scan ($0.50-$2.00 based on contract size)
# 1. Call /estimate to get price for your contract
# 2. Send USDC to wallet, include tx signature in header

curl -X POST https://api.smartsec.app/audit \
  -H "X-PAYMENT: <tx-signature>" \
  -F "file=@contract.sol" \
  -F "tier=pro"

Authentication

Basic tier: No authentication needed. Just call the API (1 scan/day limit).

Pro tier: Pay USDC on Solana (price varies by contract size), then include the transaction signature:

X-PAYMENT: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9g...

x402 Payment Flow (Pro tier)

Call POST /audit with tier=pro (without payment)
Receive 402 Payment Required with x402 headers and payment details
Send USDC to the address specified in the response
Retry POST /audit with X-PAYMENT: <tx-signature>
Server verifies on-chain payment and returns scan results

402 Response Format

Response Headers

HTTP/1.1 402 Payment Required
X-Payment-Required: true
X-Payment-Network: solana-mainnet
X-Payment-Asset: USDC
X-Payment-Address: <payment-wallet>
X-Payment-Amount: 500000
X-Payment-Amount-USD: 0.50
X-Payment-Description: Pro audit: 150 lines (small)

Response Body

{
  "success": false,
  "error": "Payment required",
  "x402": {
    "version": "1.0",
    "network": "solana-mainnet",
    "asset": "USDC",
    "address": "<payment-wallet>",
    "amount": 500000,
    "amount_usd": 0.50,
    "description": "Pro audit for 150 lines (small contract)"
  },
  "instructions": "Send USDC to the address, then retry with X-PAYMENT header containing the transaction signature"
}

AI Agent Integration

AI agents can parse the x402 object programmatically. Amount is in USDC micro-units (6 decimals). 500000 = $0.50 USDC.

GET /

GET / Free

Returns API information and pricing details. Use this to discover payment configuration programmatically.

Response

{
  "service": "SmartSec",
  "description": "AI Smart Contract Security Scanner",
  "version": "1.0.0",
  "pricing": {
    "basic": "Free (1/day)",
    "pro": "$0.50-$2.00 (based on contract size)"
  },
  "payment": "USDC on Solana",
  "wallet": "<payment-wallet>"
}

GET /health

GET /health Free

Health check endpoint.

{ "status": "ok" }

POST /estimate

POST /estimate Free

Get price estimate before making payment. Analyzes contract complexity and returns pricing for all tiers.

Form Data

Parameter	Type	Description
file required	file	Smart contract source file (max 5MB)
chain	string	Blockchain: ethereum, bsc, polygon, arbitrum (default: ethereum)

Response

{
  "success": true,
  "file": "Token.sol",
  "lines": 350,
  "size": "small",
  "chain": "ethereum",
  "pricing": {
    "basic": {
      "price_usd": 0,
      "price_usdc": 0,
      "free": true,
      "limit": "1/day"
    },
    "pro": {
      "price_usd": 0.50,
      "price_usdc": 500000
    }
  },
  "wallet": "<payment-wallet>"
}

Size categories: small (<500 lines), medium (500-2000), large (2000+)
Pro pricing: small = $0.50 (500000) | medium = $1.00 (1000000) | large = $2.00 (2000000)

POST /audit

POST /audit Free / Paid

Run security analysis on a smart contract. Returns vulnerability report with risk scoring and downloadable report link.

Headers

Header	Description
X-PAYMENT	Solana TX signature (required for `tier=pro` only)

Form Data

Parameter	Type	Description
file required	file	Smart contract source file (max 5MB)
chain	string	Blockchain: ethereum, bsc, polygon, arbitrum (default: ethereum)
tier	string	Tier: `basic` (free, 1/day) or `pro` ($0.50-$2.00). Default: basic

Response (Pro tier)

{
  "success": true,
  "tier": "pro",
  "contract": "Token",
  "chain": "ethereum",
  "lines": 350,
  "risk_score": 65,
  "security_score": 72,
  "security_grade": "C",
  "fund_risk_level": "medium",
  "fund_risk_count": 2,
  "issues": 3,
  "vulnerabilities": [
    {
      "severity": "high",
      "type": "reentrancy",
      "description": "Potential reentrancy in withdraw()",
      "line": 142,
      "fund_risk": true
    }
  ],
  "summary": "Contract has 3 potential issues...",
  "report_id": "pro_a1b2c3d4e5f6",
  "report_url": "https://api.smartsec.app/report/pro_a1b2c3d4e5f6",
  "report_expires_in": "60 minutes"
}

Response (Basic tier)

{
  "success": true,
  "tier": "basic",
  "contract": "Token",
  "chain": "ethereum",
  "lines": 350,
  "risk_score": 65,
  "security_score": 72,
  "security_grade": "C",
  "fund_risk_level": "medium",
  "fund_risk_count": 2,
  "issues": 3,
  "vulnerabilities": [...],
  "summary": "...",
  "scans_left_today": 0,
  "report_id": "basic_a1b2c3d4e5f6",
  "report_url": "https://api.smartsec.app/report/basic_a1b2c3d4e5f6",
  "report_expires_in": "60 minutes"
}

GET /report/{result_id}

GET /report/{result_id} Free

Download a previously generated audit report. Reports expire after 60 minutes.

Path Parameters

Parameter	Description
result_id	Report ID returned from `/audit` (format: `tier_hexstring`)

Response

{
  "success": true,
  "tier": "pro",
  "contract": "Token",
  "vulnerabilities": [...],
  ...
}

Error Responses

400: {"error": "Invalid report ID format"}
404: {"error": "Report not found or expired"}

GET /fetch-contract/{chain}/{address}

GET /fetch-contract/{chain}/{address} Free

Fetch verified contract source code from block explorers (Etherscan, BSCScan, etc.). Useful for scanning deployed contracts.

Path Parameters

Parameter	Description
chain	Blockchain: ethereum, bsc, polygon, arbitrum
address	Contract address (0x...)

Response

{
  "success": true,
  "source": "pragma solidity ^0.8.0;\n\ncontract Token {...}",
  "name": "Token",
  "address": "0x...",
  "chain": "ethereum"
}

Error Response

{
  "success": false,
  "error": "Contract not verified or source not available"
}

GET /rpc/blockhash

GET /rpc/blockhash Free

Get latest Solana blockhash (for building transactions).

{ "blockhash": "EkSnNWid2cvw..." }

GET /rpc/balance/{wallet}

GET /rpc/balance/{wallet} Free

Check USDC balance for a wallet. Returns raw USDC amount (6 decimals).

{ "balance": 1500000, "wallet": "<wallet-address>" }
// 1500000 = $1.50 USDC (divide by 1,000,000)

GET /rpc/account-exists/{account}

GET /rpc/account-exists/{account} Free

Check if an account exists on Solana.

{ "exists": true }

Pricing

Tier	Price	Analysis	Description
basic	FREE	Pattern Scanner	1 scan/day, pattern-based detection
pro	$0.50-$2.00	Claude AI	Size-based: <500 lines=$0.50, 500-2000=$1.00, 2000+=$2.00

Supported Chains

SmartSec supports multiple blockchain ecosystems:

EVM Chains (Fetch from Explorer)

Use /fetch-contract/{chain}/{address} to fetch verified source code.

Chain	Explorer	ID
Ethereum	Etherscan	ethereum
BNB Smart Chain	BSCScan	bsc
Polygon	PolygonScan	polygon
Arbitrum	Arbiscan	arbitrum

Non-EVM Ecosystems (File Upload)

Upload contract files directly via /audit endpoint.

Ecosystem	Language	File Extension
Solana	Rust/Anchor	.rs
Aptos / Sui	Move	.move

Supported Languages

Upload contracts in any of these formats:

.sol - Solidity (Ethereum, BSC, Polygon, Arbitrum)
.rs - Rust/Anchor (Solana)
.vy - Vyper (Ethereum)
.move - Move (Aptos, Sui, Movement)
.txt - Plain text (any)

Error Codes

Code	Meaning
400	Bad request - invalid parameters, address format, or file encoding
402	Payment required - include X-PAYMENT header (pro tier)
404	Not found - report expired or invalid ID
413	File too large - max 5MB
429	Rate limit exceeded - basic tier (1/day) or RPC endpoints (30/min)
500	Server error - retry with exponential backoff
502	RPC/Explorer connection failed