# llms.txt
# shipsafe.run
# Smart contract security scanning API for autonomous agents

## What this is
shipsafe.run provides programmatic smart contract security scanning. Agents can submit contracts, pay via x402 protocol, and receive structured vulnerability reports without human intervention.

## API Base URL
https://shipsafe.run/api

## Authentication
No API keys required. Payment handled via x402 USDC protocol on Base network.

## Endpoints

### POST /scans
Submit a contract for security scanning.

**Request body:**
```json
{
  "contract": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "tier": "essential",
  "wallet": "0x..."
}
```

**Contract input formats:**
- EVM address: `0x...`
- GitHub repo: `github.com/org/repo`
- IPFS hash: `ipfs://Qm...`
- Raw Solidity source code

**Tiers:**
- `mini`: $5 USDC, ~30 minutes, up to 200 lines
- `essential`: $15 USDC, ~2 hours, any size
- `professional`: $75 USDC, ~8 hours, PDF report

**Response:**
```json
{
  "success": true,
  "data": {
    "scanId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending_payment",
    "amount": 15,
    "currency": "USDC",
    "receiver": "0xadfb71c478984e3c72bde0a5ebd9dff6d66aacf4",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}
```

### POST /scans/{scanId}/pay
Confirm payment after submitting x402 transaction.

**Request body:**
```json
{
  "txHash": "0x..."
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "scanId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running"
  }
}
```

### GET /scans/{scanId}
Check scan status and retrieve results.

**Response (completed):**
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "progress": 100,
    "riskScore": 8.5,
    "findings": [
      {
        "id": "VULN-001",
        "severity": "high",
        "category": "reentrancy",
        "title": "Reentrancy in withdraw function",
        "description": "External call before state update allows recursive withdrawal",
        "line": 45,
        "code": "(bool success,) = msg.sender.call{value: balance}('');",
        "fix": "Update state before external call: balances[msg.sender] = 0;",
        "confidence": 0.94
      }
    ],
    "exploitCorrelation": ["2024-03-15 DeFi Protocol Hack"],
    "report": {
      "summary": "Contract has 1 high-severity reentrancy vulnerability",
      "totalLines": 156,
      "complexity": "medium",
      "scanDuration": "1h 45m"
    }
  }
}
```

### GET /pricing
Get current pricing tiers.

### GET /subscription/{wallet}
Check Companion Pass subscription status.

## Autonomous Agent Workflow

```
1. POST /scans
   → Receive scanId + payment details

2. Submit x402 payment
   → USDC on Base network
   → Amount + receiver address from response

3. POST /scans/{scanId}/pay
   → Submit transaction hash

4. GET /scans/{scanId} (poll)
   → Check status every 30 seconds
   → Stop when status = "completed"

5. Process findings
   → If riskScore >= 7: good to deploy
   → If riskScore < 7: review required
   → If critical findings present: halt deployment
```

## Risk Score Interpretation

| Risk Score | Security Level | Action |
|------------|----------------|--------|
| 10 | Perfect — no issues | Deploy |
| 8-9 | Good — minor/low issues | Deploy |
| 6-7 | Moderate — medium issues | Review recommended |
| 3-5 | Poor — high severity issues | Fix before deploy |
| 1-2 | Critical — severe vulnerabilities | Do not deploy |

## Scanning Technologies
- **Slither**: Static analysis for vulnerability detection
- **Mythril**: Symbolic execution for path exploration
- **Semgrep**: Pattern matching against 300+ exploit signatures
- **Echidna**: Fuzzing for input testing (professional tier)

## Error Handling

| Status Code | Meaning | Resolution |
|-------------|---------|------------|
| 400 | Invalid contract address | Check format |
| 404 | Scan not found | Verify scanId |
| 409 | Payment expired | Create new scan |
| 429 | Rate limited | Wait 60 seconds |
| 502 | Scan still running | Continue polling |

## Example: Minimal Integration

```javascript
async function scanContract(contractAddress) {
  // 1. Create scan
  const scan = await fetch('https://shipsafe.run/api/scans', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      contract: contractAddress,
      tier: 'essential'
    })
  }).then(r => r.json());

  // 2. Pay via x402
  await x402.pay({
    amount: scan.data.amount,
    currency: scan.data.currency,
    receiver: scan.data.receiver
  });

  // 3. Confirm payment
  await fetch(`https://shipsafe.run/api/scans/${scan.data.scanId}/pay`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({txHash: paymentTxHash})
  });

  // 4. Poll for completion
  while (true) {
    const result = await fetch(
      `https://shipsafe.run/api/scans/${scan.data.scanId}`
    ).then(r => r.json());

    if (result.data.status === 'completed') {
      return result.data;
    }

    await new Promise(r => setTimeout(r, 30000));
  }
}

// Usage
const report = await scanContract('0x...');
// Risk score: 10 = perfect, 1 = critical issues
if (report.riskScore < 7) {
  throw new Error(`Security check failed: score ${report.riskScore}/10`);
}
```

## Companion Pass
$50/month subscription for high-volume agents.
- 15 mini scans
- 5 essential scans
- 1 professional scan

Subscribe: POST /subscribe with wallet address.

## Links
- API docs: https://shipsafe.run/api
- Skill files: https://shipsafe.run/skills/shipsafe.yaml