# aidd — Smart Contract Audit Service

> Multi-agent AI security audits for Solidity smart contracts, commissioned via MCP.

## Service

- Provider: WatchPug
- Protocol: MCP (Model Context Protocol) over SSE
- Endpoint: https://aidd-service-production.up.railway.app/sse
- Payment: USDC on Base (x402) or Tempo (MPP)
- Source: https://github.com/sunoj/aidd

## How to Connect

Add to your MCP client config:

```json
{
  "mcpServers": {
    "aidd": {
      "url": "https://aidd-service-production.up.railway.app/sse"
    }
  }
}
```

## CLI Client

Install the watchpug CLI (Rust, ~2MB binary) for command-line access:

cargo install watchpug

Commands:
- watchpug quote <repo-url> — get price estimate
- watchpug audit <repo-url> --wait — commission audit and wait for result
- watchpug audit ./local-repo --scope "src/*.sol" --wait — audit a private/local repo
- watchpug status <task-id> — check progress
- watchpug result <task-id> — download report
- watchpug result <task-id> --output report.md — save report to file
- watchpug result <task-id> --json — structured findings as JSON
- watchpug dispute <task-id> --reason "..." — open dispute

Global flags: --quiet (minimal output), --json (JSON output), --server <url>

Environment:
- WATCHPUG_SERVER: override server URL (default: https://aidd-service-production.up.railway.app)

## REST API

For direct HTTP integration without MCP:

- POST /api/quote — { repo_url, scope?, branch?, commit? } → quote
- POST /api/audit — { repo_url, scope?, branch?, quote_id?, nsloc? } → { task_id }
- GET /api/audit/:id — job status, progress, report, findings
- POST /api/audit/:id/dispute — { reason } → confirmation
- POST /git/:jobId/upload — upload git bundle (application/octet-stream body, max 100MB)

## Private Repos

No GitHub tokens needed. The watchpug CLI handles this automatically:

1. `git bundle create` packages the local repo
2. `POST /api/audit` creates the job
3. `POST /git/:jobId/upload` sends the bundle
4. Workers clone from the service's built-in git server

For agents: create a git bundle of the repo, submit the audit, then upload the bundle to `/git/:taskId/upload` with Content-Type: application/octet-stream.

## Tools

### quote_audit (FREE)
Estimate audit cost for a repository. Clones repo, analyzes scope, returns price.
- repo_url (required): Git repository URL
- scope (optional): Glob pattern for files to audit (e.g. "src/*.sol")
- branch (optional): Branch name
- commit (optional): Commit hash

### submit_audit (PAID — USDC)
Submit a paid audit job. Creates a queued task for worker execution.
- repo_url (required): Git repository URL
- scope (optional): Glob pattern
- branch (optional): Branch name
- quote_id (optional): Quote ID from quote_audit for pre-agreed pricing
- nsloc (optional): Self-reported nSLOC for private repos (use instead of quote_id)

### get_result (FREE)
Check audit status and retrieve completed report with findings.
- task_id (required): Job ID returned by submit_audit

### dispute (FREE)
Open a dispute for a completed audit. Triggers human review.
- task_id (required): Job ID
- reason (required): Reason for dispute

## Workflow

1. Call `quote_audit` with repo_url to get price estimate
2. Call `submit_audit` with repo_url to start audit (pays USDC automatically)
3. Poll `get_result` with task_id until status is "completed"
4. Receive: markdown report, structured findings, severity counts

## Pricing

| nSLOC     | Mode  | Price (USDC) | Time    |
|-----------|-------|--------------|---------|
| < 200     | quick | $2           | ~10 min |
| 200-500   | quick | $5           | ~15 min |
| 500-1500  | quick | $15          | ~25 min |
| 1500-5000 | full  | $50          | ~45 min |
| 5000+     | full  | custom       | —       |

## What the Audit Covers

- 8+ specialist AI agents audit in parallel (arithmetic, MEV, oracle, access control, etc.)
- Cross-validation with consensus scoring across agents
- Adversarial review: attacker vs defender debate for high-severity findings
- Automated PoC generation with Foundry exploit tests
- Static analysis: Slither + Aderyn (102 detectors)
- Severity classification: Critical / High / Medium / Low / Informational