Getting Started

Sentinel Security Agent provides multi-chain smart contract security auditing through a REST API. Scan contracts for free or run AI-enhanced paid audits with PDF reports.

Quick Start: Free Scan

curl -X POST https://sentinel-security-api.fly.dev/audit/basic \
  -H "Content-Type: application/json" \
  -d '{
    "source_code": "pragma solidity ^0.8.0; contract Vault { ... }",
    "filename": "Vault.sol"
  }'

Response

{
  "verdict": "VULNERABLE",
  "risk_score": 32,
  "grade": "D",
  "severity_counts": {"CRITICAL": 1, "HIGH": 2, "MEDIUM": 0},
  "findings": [
    {
      "type": "reentrancy",
      "severity": "CRITICAL",
      "title": "Reentrancy Vulnerability",
      "location": "function withdraw()"
    }
  ]
}

Scan by On-Chain Address

Provide a contract address and chain to fetch verified source automatically.

curl -X POST https://sentinel-security-api.fly.dev/audit/address \
  -H "Content-Type: application/json" \
  -d '{"address": "0x1234...abcd", "chain": "mainnet"}'

Authenticated Scan with Full Details

Pass an API key to unlock full finding descriptions and fix suggestions on the free tier.

curl -X POST https://sentinel-security-api.fly.dev/audit \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{"source_code": "...", "filename": "Token.sol"}'

Supported Chains

Sentinel supports 16+ blockchain networks across multiple smart contract languages.

For EVM chains, use the chain parameter: mainnet, bsc, base, polygon, arbitrum, optimism, avalanche, celo, linea, blast, zksync, fantom, cronos, gnosis.

API Reference

Base URL: https://sentinel-security-api.fly.dev

Interactive API explorer available at /docs (Swagger UI).

Core Scan Endpoints

{
  "source_code": "string",   // Contract source code (required)
  "filename": "string",      // e.g. "Vault.sol" (required)
  "contract_name": "string"  // Optional display name
}

{
  "address": "0x...",         // Contract address (required)
  "chain": "mainnet"          // Chain name (default: mainnet)
}

curl -X POST https://sentinel-security-api.fly.dev/audit/file \
  -F "file=@contracts/Vault.sol"

{
  "source_code": "string",
  "filename": "string",
  "tx_hash": "0x...",           // Payment transaction hash
  "sender_address": "0x...",    // Your wallet address
  "chain": "base",              // Payment chain: base, mainnet, bsc
  "email": "user@example.com",  // Optional, for delivery
  "tier": "audit"               // "audit" ($49) or "deep" ($149)
}

Advanced Endpoints

{
  "source_code": "string",     // Source code to verify
  "address": "0x...",          // Deployed contract address
  "chain": "mainnet"           // Chain name
}

{
  "address": "0x...",
  "chain": "mainnet",
  "bytecode_size": 4826,
  "match_score": 0.95,
  "matched": true,
  "deployed_selectors": ["0xa9059cbb", "0x70a08231"],
  "source_functions": ["transfer", "balanceOf"],
  "deployed_only": [],
  "source_only": [],
  "warning": null
}

{
  "source_v1": "string",      // V1 source code
  "source_v2": "string",      // V2 source code
  "filename": "Vault.sol"
}

{
  "v1_summary": {"total": 5, "score": 35, "verdict": "VULNERABLE"},
  "v2_summary": {"total": 2, "score": 72, "verdict": "VULNERABLE"},
  "new_in_v2": [...],
  "fixed_in_v2": [...],
  "unchanged": [...],
  "new_count": 0,
  "fixed_count": 3,
  "unchanged_count": 2
}

{
  "audit_id": "abc-123",
  "feedbacks": [
    {"finding_type": "reentrancy", "verdict": "confirmed"},
    {"finding_type": "floating_pragma", "verdict": "not_applicable"}
  ]
}

B2B / Integration Endpoints

Utility Endpoints

Authentication

The free scan endpoints require no authentication. Paid features and full finding details support three auth methods.

1. API Key

Pass your API key in the X-Api-Key header.

curl -H "X-Api-Key: your-api-key" \
  https://sentinel-security-api.fly.dev/audit \
  -X POST -H "Content-Type: application/json" \
  -d '{"source_code": "...", "filename": "Token.sol"}'

API keys are scoped to a tier and have configurable TTL. Contact support to request a key.

2. Wallet Authentication (JWT)

Crypto-native auth using wallet signature verification. No passwords needed.

Step 1: Request a challenge.

POST /auth/challenge
Body: {"wallet_address": "0xYourAddress"}

Response: {"challenge": "Sign this message: sentinel-auth-abc123..."}

Step 2: Sign the challenge with your wallet (MetaMask, Phantom, etc) and verify.

POST /auth/verify
Body: {
  "wallet_address": "0xYourAddress",
  "signature": "0xSignedMessage..."
}

Response: {"token": "eyJhbGci...", "expires_in": 86400}

Step 3: Use the JWT token in subsequent requests.

curl -H "Authorization: Bearer eyJhbGci..." \
  https://sentinel-security-api.fly.dev/user/audits

3. Payment-Based Access

Paid endpoints (/audit/paid) authenticate via on-chain payment verification. Provide tx_hash and sender_address in the request body.

Async Audits

Paid audits with AI specialists take approximately 5 seconds. For CI/CD and automation, use the async flow.

Submit an Async Audit

POST /api/v1/audit/async
Body: {
  "source_code": "...",
  "filename": "Vault.sol",
  "webhook_url": "https://your-server.com/hook"  // optional
}

Response: {"audit_id": "abc-123", "status": "pending"}

Poll for Status

GET /api/v1/audit/abc-123/status

Response: {
  "status": "completed",
  "progress": 100,
  "findings_count": 3
}

WebSocket Updates

Connect to the WebSocket endpoint for real-time audit progress notifications.

ws://sentinel-security-api.fly.dev/ws/audit/abc-123

Error Codes

All error responses return JSON with a detail field.

Example error response:

{
  "detail": "Source code is required",
  "error_code": "MISSING_SOURCE"
}

Rate Limits

We apply per-IP rate limits to keep the free tier sustainable. Limits scale up as you authenticate:

• Anonymous — modest daily quota suitable for evaluation.
• Wallet authenticated — higher quota after signing in (JWT).
• Paid API key — unmetered access for production workloads.

If you hit a limit you'll receive HTTP 429 Too Many Requests with a Retry-After header indicating when to try again. File-upload endpoints carry a tighter per-minute throttle to protect shared I/O capacity.

Finding Types

Sentinel detects vulnerability classes across all supported chains. Each finding includes a type, severity, title, and location in the source code.

Severity Levels

What we look for

Sentinel detects a broad set of vulnerability classes across every supported chain. Coverage areas include:

• EVM contracts — reentrancy, access-control gaps, oracle manipulation, signature malleability, governance attacks, slippage misuse, proxy initialization, and dozens more deterministic patterns plus AI-grounded business-logic checks.
• Solana programs — Anchor signer / PDA / account-constraint issues, CPI safety, and arithmetic checks across native and framework code.
• Sui & Aptos (Move) — capability and object-ownership patterns, shared-object concurrency, and silent integer truncation.
• StarkNet (Cairo) — felt arithmetic edge cases, dispatcher reentrancy, component-storage hazards, and L1↔L2 message handling.

Each finding in your paid report includes a plain-English description, the affected source location, a fix suggestion, and a proof-of-concept sketch where applicable. The full per-chain catalog ships with each report rather than as a public list.

AI Specialists

Paid audits (AI Basic, Full AI, and Pro tiers) include AI-powered analysis that goes beyond pattern matching. AI specialists reason about code semantics and intent to catch complex vulnerabilities that static analysis alone cannot detect.

What the AI tier reasons about

Paid audits include AI specialists trained on protocol patterns and historical exploits. They reason about code semantics — business-logic gaps, economic-design flaws, composability risks, governance manipulation, and chain-specific concerns — and surface findings the deterministic engine alone misses. Each specialist's output is verified against the contract source via tool-use schemas before being added to your report (no hallucination).

Coverage scales with the tier you choose:

• AI Basic ($29) — the full AI-specialist lineup with detailed annotations and fix suggestions.
• Full AI ($69) — adds Halmos formal-verification templates, NatSpec spec-vs-impl matching, and a separate risk_surface bucket for ambiguous signals worth a human review.
• Pro ($149) — adds a Foundry exploit-PoC cascade, N-round dialectic verification, an agent-based economic simulator, and a goal-oriented attack planner for the most consequential audits.

Higher tiers also include symbolic-execution path analysis (Z3) and multi-file analysis for cross-contract patterns like proxy chains, factory deployments, and oracle dependencies.

Report Format

Paid audits generate comprehensive PDF reports. Each report includes the following sections:

Reports are available in 5 languages: English, Chinese, Spanish, Korean, and Japanese. Set the lang parameter (en, zh, es, ko, ja) when requesting an audit.

View a sample report to see the output format.

Audit Tiers

Five tiers from a free safety verdict up through full agent-based exploit simulation. Pay-as-you-audit; no subscriptions. Pricing here mirrors the home page pricing section.

Payment accepted in ETH, BNB, or USDC on Ethereum, BSC, or Base networks. Base recommended for lowest gas fees. Real Enterprise tier ($1.5k+/audit, $5k+/mo with SLAs) launches post-brand-traction.

Payment Flow

1. Run a free scan on the home page or via the API.
2. Select your desired paid tier (Basic Det, AI Basic, Full AI, or Pro).
3. Choose a payment network (Base recommended for lowest gas).
4. Send the exact amount to the displayed wallet address.
5. Enter your sender wallet address and transaction hash.
6. Click Verify Payment — the API verifies on-chain (a small number of block confirmations are required; Base/Ethereum are quick, BSC slightly longer).
7. The full audit runs automatically and the PDF report is generated.

Troubleshooting payment verification

If verification fails, the front-end shows a Retry Verification button and counts your attempts. The backend caps retries at 3 per transaction; after that you'll be pointed to support. Most failures fall into one of these buckets:

Programmatic retry uses POST /audit/paid/retry with the original payment_id. The endpoint returns 429 once the 3-attempt cap is reached.

SDKs Coming Soon

Until the official client libraries land you can call the API directly with any HTTP client. Every endpoint accepts JSON and returns JSON; the curl examples earlier in this page are a working starting point in any language.

TypeScript / JavaScript

A typed client (@sentinel-security/sdk) covering the full endpoint surface is in private beta — zero external dependencies, native fetch on Node 18+. Helpers planned for free scan, paid audit, async polling, and history. Drop your handle in the early-access form on the home page or DM @SentinelEngine to be notified when the npm package publishes.

Python

A Python client (sentinel_sdk.py) is available as a single-file script in the development repository today. The pip-installable package and stable API guarantees ship after the public TypeScript release.

CLI Tool Coming Soon

A terminal client for one-shot scans, batch sweeps, and on-chain address audits is in beta. It will accept local files, directories, or chain addresses and emit human-readable, JSON, or SARIF (for GitHub Security tab integration).

If you want to run Sentinel from a build step today, the curl snippets in Getting Started work in any shell — the CLI just wraps those calls with formatting and exit codes.

CI/CD Integration Coming Soon

A drop-in GitHub Actions step (and adapters for GitLab CI, CircleCI, and Jenkins) is on the launch list. Once it ships, severity thresholds and ignore rules will be configurable via a small YAML file in your repo root, and findings can be uploaded to the GitHub Security tab as SARIF.

For early adopters: the API endpoints are stable enough today to integrate into a custom CI step using a few lines of curl. Reach out via @SentinelEngine if you'd like to be a design partner for the official action before public release.

Webhooks Coming Soon

Webhook delivery for async audit completion is being wired up — once enabled, your server will receive a POST when an audit finishes, with an HMAC-SHA256 signature for verification. Until then, paid audits return synchronously and async pollers can use the audit-status endpoint described in Async Audits.

Security & Privacy

• Source code is processed in-memory only and is not stored after the audit completes.
• Paid audit results are cached by source hash for 7 days for your convenience (same user only).
• No cookies, no tracking pixels, no third-party analytics.
• AI analysis is powered by Anthropic Claude. Source code is sent to the Anthropic API for AI-enhanced tiers only.
• Payment verification is done on-chain. We never handle or store your private keys.
• All connections are encrypted via HTTPS/TLS.
• Input validation: binary content detection, unicode sanitization, meaningful code checks, and filename sanitization are applied to all submissions.

See our Terms of Service and Privacy Policy for full details.

FAQ

Changelog

The API changelog is available programmatically at GET /api/changelog.

For the full version history, see the changelog endpoint.

Support