# ShieldAPI — Complete Technical Reference for LLMs

> x402-native security intelligence API for AI agents.
> Base URL: https://shield.vainplex.dev
> Payment: USDC on Base L2 via x402 protocol
> Free tier: 3 calls/endpoint/day (no wallet needed)

## Architecture

ShieldAPI is a stateless security intelligence service. Every endpoint accepts standard HTTP requests and returns JSON. Paid endpoints use the x402 payment protocol — if you send a request without payment, you receive HTTP 402 with payment instructions. After payment, retry the same request.

Zero data retention. All analysis happens in RAM. EU-only processing (Hetzner Nürnberg, Germany). GDPR compliant by design.

## Authentication

None required. Free tier needs no credentials. Paid tier uses x402 (automatic USDC payment on Base L2).

## Endpoints — Full Specification

### POST /api/check-prompt
Detect prompt injection attacks in text input.

**Cost:** $0.005 USDC | **Free:** 3/day

**Request:**
```json
{
  "prompt": "string (required) — text to analyze",
  "context": "string (optional) — one of: user-input, skill-prompt, system-prompt"
}
```

**Response:**
```json
{
  "isInjection": true,
  "confidence": 0.95,
  "category": "direct|indirect|encoded|multilingual",
  "patterns": [
    {
      "type": "instruction_override",
      "description": "Detected 'ignore previous instructions' pattern",
      "evidence": "matched substring",
      "position": { "start": 0, "end": 32 }
    }
  ]
}
```

**Detection capabilities:**
- 208 attack patterns
- 8 language support (EN, DE, FR, ES, ZH, JA, KO, RU)
- 4 decoders: Base64, ROT13, Hex, Homoglyphs
- Categories: instruction_override, role_hijacking, context_manipulation, data_exfiltration, leetspeak, encoding_evasion
- Latency: <100ms

---

### POST /api/scan-skill
Scan AI skill/plugin code for supply chain attacks.

**Cost:** $0.02 USDC | **Free:** 1/day

**Request:**
```json
{
  "skill": "string — SKILL.md or code content to scan",
  "files": [
    { "name": "index.js", "content": "file content" }
  ]
}
```
Either `skill` (single content) or `files` (multiple files) is required.

**Response:**
```json
{
  "riskScore": 75,
  "riskLevel": "HIGH",
  "findings": [
    {
      "category": "Malicious Code",
      "severity": "CRITICAL",
      "description": "Detected child_process import",
      "location": "index.js:5",
      "evidence": "require('child_process')"
    }
  ],
  "summary": "HIGH risk skill. Found 2 critical issues.",
  "scanDuration": 23,
  "categoriesChecked": 8,
  "filesAnalyzed": 3,
  "totalPatterns": 204
}
```

**Risk categories (Snyk ToxicSkills taxonomy):**
1. Malicious Code — child_process, eval, exec patterns
2. Data Exfiltration — outbound HTTP with sensitive data
3. Credential Theft — env var access, keychain, wallet files
4. Privilege Escalation — sudo, chmod, setuid patterns
5. Persistence — crontab, autostart, systemd modifications
6. Obfuscation — Base64 encoded payloads, dynamic requires
7. Network Abuse — DNS rebinding, SSRF, port scanning
8. Supply Chain — typosquatted packages, suspicious dependencies

---

### GET /api/check-password?hash=<SHA1>
Check if a password has appeared in data breaches.

**Cost:** $0.001 USDC | **Free:** 3/day

**Input:** SHA-1 hash of the password (uppercase hex)
**Database:** 900M+ breach records from Have I Been Pwned

**Response:**
```json
{
  "found": true,
  "count": 12483,
  "hash": "5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8"
}
```

---

### GET /api/check-password-range?prefix=<5chars>
k-Anonymity password range lookup (HIBP-compatible).

**Cost:** $0.001 USDC | **Free:** 3/day

**Input:** First 5 characters of SHA-1 hash
**Response:** List of suffix:count pairs matching the prefix

---

### GET /api/check-email?email=<address>
Check if an email address has been exposed in data breaches.

**Cost:** $0.005 USDC | **Free:** 3/day

**Response:**
```json
{
  "email": "user@example.com",
  "breached": true,
  "breachCount": 3,
  "breaches": ["LinkedIn2021", "Adobe", "Dropbox"],
  "exposedData": ["email", "password", "name"]
}
```

---

### GET /api/check-domain?domain=<name>
Comprehensive domain reputation check.

**Cost:** $0.003 USDC | **Free:** 3/day

**Checks performed:**
- DNS records (A, AAAA, MX, NS, TXT, CNAME)
- Blacklist status (Spamhaus, SpamCop, SORBS, UCEPROTECT)
- SSL certificate validation
- SPF record analysis
- DMARC policy check
- DNSSEC validation

**Response:**
```json
{
  "domain": "example.com",
  "dns": { "a": ["93.184.216.34"], "mx": [...], "ns": [...] },
  "blacklists": { "listed": false, "services": [...] },
  "ssl": { "valid": true, "issuer": "...", "expires": "..." },
  "spf": { "exists": true, "record": "v=spf1 ..." },
  "dmarc": { "exists": true, "policy": "reject" }
}
```

---

### GET /api/check-ip?ip=<ipv4>
IP address reputation check.

**Cost:** $0.002 USDC | **Free:** 3/day

**Checks performed:**
- Blacklist lookups (Spamhaus, SpamCop, SORBS)
- Tor exit node detection
- Reverse DNS lookup
- ASN/ISP identification

**Response:**
```json
{
  "ip": "1.2.3.4",
  "blacklisted": false,
  "torExitNode": false,
  "reverseDns": "host.example.com",
  "asn": { "number": 13335, "name": "CLOUDFLARENET" }
}
```

---

### GET /api/check-url?url=<url>
URL safety and phishing detection.

**Cost:** $0.003 USDC | **Free:** 3/day

**Checks performed:**
- Phishing pattern detection
- Malware URL matching
- Brand impersonation detection
- Redirect chain analysis
- Domain age and reputation

---

### GET /api/full-scan?email=<>&domain=<>&ip=<>&url=<>
Combined security assessment. Runs all applicable checks.

**Cost:** $0.01 USDC | **Free:** 1/day

Accepts any combination of: email, domain, ip, url parameters.

---

## x402 Payment Flow

1. Send request to any paid endpoint
2. If free tier exhausted: receive HTTP 402 with payment details
3. Pay exact USDC amount on Base L2 to the specified address
4. Retry same request — response is returned
5. Payment details in `_meta` field of every response

**Payment network:** Base Mainnet (Chain ID 8453)
**Asset:** USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
**Facilitator:** Coinbase x402

## Discovery Endpoints

| Resource | URL |
|----------|-----|
| Landing Page | https://shield.vainplex.dev/ |
| OpenAPI Spec | https://shield.vainplex.dev/openapi.json |
| llms.txt | https://shield.vainplex.dev/llms.txt |
| llms-full.txt | https://shield.vainplex.dev/llms-full.txt |
| SKILL.md | https://shield.vainplex.dev/.well-known/SKILL.md |
| x402 Well-Known | https://shield.vainplex.dev/.well-known/x402 |
| MCP Server Card | https://shield.vainplex.dev/.well-known/mcp/server-card.json |
| ERC-8004 | https://shield.vainplex.dev/.well-known/erc8004/ |
| Health | https://shield.vainplex.dev/api/health |
| robots.txt | https://shield.vainplex.dev/robots.txt |
| sitemap.xml | https://shield.vainplex.dev/sitemap.xml |

## Integration

- **MCP Server:** `npx shieldapi-mcp` — Smithery score 100/100
- **CLI:** `npx @vainplex/shieldapi-cli`
- **npm (MCP):** https://www.npmjs.com/package/shieldapi-mcp
- **npm (CLI):** https://www.npmjs.com/package/@vainplex/shieldapi-cli
- **GitHub:** https://github.com/alberthild/shieldapi-mcp

## Privacy

- Zero data retention — all content analyzed in RAM only, never stored
- EU-only processing — Hetzner Nürnberg, Germany
- GDPR compliant by design
- No tracking, no analytics, no cookies