Scan API

Tiers

• Free. POST /api/scan and the MCP endpoint /mcp return results directly, rate-limited per IP (default 120/min). Responses carry RateLimit-* headers, and a 429 with Retry-After when exceeded.
• Paid. POST /api/scan/pro, pay-as-you-go over the x402 standard (one micropayment per scan, no subscription). You get the full forensic response the free tier withholds: a complete findings[] array with exact character offsets and per-rule weights, a recommended_action (allow / review / block), the de-obfuscation technique behind each obfuscated_injection hit, no rate limit, and larger inputs (200k vs 50k chars). Disabled until a wallet and facilitator are configured (returns 501 until then).
• API keys (optional). For direct integrations, send Authorization: Bearer <key> or X-API-Key to /api/scan. Free keys get a per-key quota, paid keys are unthrottled, and the response echoes your X-Clipeus-Tier. Check your tier at GET /api/keys. When no keys are configured the endpoint stays open to anonymous callers, and the OKX MCP endpoint stays open regardless.

Get an API key

Keys are self-serve and wallet-based: no account, no operator, no database. Connect a wallet on the keys page (or the bar at the top of the playground) and generate one. A free key is instant; a paid key is unlocked with a one-time x402 payment.

Or mint one directly:

curl -X POST https://clipeus.xyz/api/keys/mint \
  -H "Content-Type: application/json" \
  -d '{"tier":"free","address":"0xYourWallet"}'
# -> { "key": "ckw_…", "tier": "free", "expires_in_days": 90 }

• The key is the token. Each one is unique per generation and encodes your wallet, tier, and expiry, signed by the server. Send it as Authorization: Bearer <key> or X-API-Key on /api/scan.
• Shown once. The server never stores it, so copy it at mint time. Lost keys cannot be shown again; generate a new one.
• Expiry, not revocation. Free keys last 90 days, paid keys 30. A lost key stays valid until it expires (there is no per-key revocation without a store); rotating the server secret invalidates all keys at once.
• Enabled by setting CLIPEUS_KEY_SECRET; paid minting also needs the x402 env. Check status at GET /api/keys/mint.

Evasion resistance

Rules match literal text, so Clipeus de-obfuscates before scanning. Each variant is re-scanned with the same rules; anything that only surfaces after de-obfuscation is reported as an obfuscated_injection finding that names the technique. Deterministic, no LLMs.

• Look-alike letters.Cyrillic and Greek homoglyphs fold to ASCII, so a spoofed "system admin" is still caught.
• Encoded payloads. base64, hex, rot13, and URL-encoding are decoded and re-scanned.
• Leetspeak and spacing. Tricks like 1gn0re and letter-by-letter spacing collapse to canonical form.

Endpoint

POST /api/scan

Content-Type: application/json

Request

{
  "content": "string (required, 1–50000 chars)",
  "context_type": "task_description | user_message | tool_output | agent_memory | external_content",
  "action_pending": "release_payment | sign_transaction | transfer_funds | execute_trade | approve_action | none"
}

Response

{
  "risk_score": 92,
  "verdict": "clean | suspicious | high_risk",
  "categories": ["instruction_override", "financial_manipulation"],
  "flagged_segments": [
    { "text": "Ignore previous instructions", "reason": "Attempts to discard existing instructions" }
  ],
  "explanation": "Human-readable summary",
  "confidence": 0.84,
  "findings_count": 3,
  "scan_ms": 1.2
}

Scoring bands

• 0–30 → clean
• 31–69 → suspicious
• 70–100 → high_risk

Findings contribute weighted points. Score is capped at 100. Financial actions apply a small multiplier.

Errors

• 400 invalid_json: body is not JSON
• 400 validation_error: schema mismatch (see Zod details)

cURL example

curl -s -X POST https://clipeus.xyz/api/scan \
  -H "Content-Type: application/json" \
  -d @samples/requests/high_risk_injection.json | jq

MCP endpoint

POST /mcp exposes the same scanner as a Model Context Protocol tool (scan_content) over Streamable HTTP, so MCP agents can call it natively. Send Accept: application/json, text/event-stream.

curl -s -X POST https://clipeus.xyz/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Paid tier (x402)

POST /api/scan/pro is pay-as-you-go over the x402 standard. One micropayment buys one scan.

1. 1. Request without an X-PAYMENT header returns 402 with an x402 challenge (payTo, amount, asset, network).
2. 2. Pay on-chain, then retry with a base64 X-PAYMENT header.
3. 3. The server verifies with the facilitator, runs the scan, settles, and returns the report with an X-PAYMENT-RESPONSE receipt.

Same detection engine and response shape as the free scan. Fail-closed: an unverifiable payment is re-challenged, never served. Disabled (501) until X402_PAY_TO and X402_FACILITATOR_URL are set.