# RugGuard

> Pay-per-call rug-check API for crypto smart contracts, built for AI agents on Agentic.market (x402). Single HTTP call, no API key, no account, fractional USDC pricing. Returns a 0-100 risk score and structured red flags in under 300ms. The wallet that pays is the identity.

RugGuard is a pre-trade systemic check: agents call it before each token purchase, the same way a binary is scanned before execution. Heuristics are deterministic and explainable; the catalog evolves weekly. This is data analytics, not a security guarantee — see /security.html.

## Capabilities

For a token contract address on a supported chain, RugGuard returns:

- a weighted risk score `0-100`
- a verdict in `safe | low_risk | medium_risk | high_risk | critical`
- a list of named flags (e.g. `OWNER_NOT_RENOUNCED`, `HONEYPOT_DETECTED`, `LP_NOT_LOCKED`, `MINT_AUTHORITY_ACTIVE`, `HIDDEN_OWNER`, `OWNER_CAN_PAUSE`, `TOP10_CONCENTRATION_HIGH`, `SOURCE_NOT_VERIFIED`, `HONEYPOT_TAX_HIGH`, `HONEYPOT_ASYMMETRIC`)
- a `summary` object with the underlying signals (owner address, top-10 concentration %, buy/sell tax %, source-verified bool, etc.)
- a `disclaimer` reminding callers this is best-effort analytics
- a `scan_id` (UUID) usable for `/v1/explain`

Supported chains today: `base` (Base mainnet, Ethereum L2). Planned: `solana`, `ethereum`, `bnb`, `tron`, `berachain`, `sonic`.

## Endpoints

- `GET /v1/scan/{chain}/{contract}` — quick scan, $0.01, <300ms, ~10 heuristics — the default pre-trade call
- `GET /v1/scan/deep/{chain}/{contract}` — deep scan, $0.05, ~2s (honeypot simulation, deployer profile, bytecode similarity) — Phase 1
- `POST /v1/watch/{chain}/{contract}` — webhook subscription, $0.005 per check, signed via HMAC SHA-256 — Phase 1
- `GET /v1/explain?scan_id={uuid}` — audit trail, $0.005, returns each heuristic's evidence — Phase 1
- `GET /health` — free liveness probe
- `GET /openapi.json` — machine-readable schema (free)

## Payment (x402)

Every paid endpoint replies `402 Payment Required` on the unauthenticated request. The agent settles via the Coinbase CDP facilitator on Base mainnet using USDC. The successful response carries `x-payment-response` confirming settlement. There is no API key, no signup, no rate-limit tier — just a wallet and the protocol. See https://x402.org for the spec.

## Example call

```
curl https://rugguard.io/v1/scan/base/0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed
```

Example response shape (truncated):

```
{
  "scan_id": "01J9...",
  "chain": "base",
  "contract": "0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed",
  "score": 32,
  "verdict": "low_risk",
  "flags": [
    {"code": "OWNER_NOT_RENOUNCED", "severity": "high"},
    {"code": "LP_NOT_LOCKED", "severity": "critical"},
    {"code": "MINT_AUTHORITY_ACTIVE", "severity": "critical"}
  ],
  "summary": {
    "owner_renounced": false,
    "top10_concentration_pct": 57.34,
    "buy_tax_pct": 0.0,
    "sell_tax_pct": 0.0,
    "mintable": true,
    "hidden_owner": false,
    "transfer_pausable": false,
    "source_verified": true
  },
  "scanned_at": "2026-04-26T18:00:00Z",
  "disclaimer": "RugGuard is a data analytics tool, not a security guarantee."
}
```

## Limitations

- Phase 0 prototype: heuristic catalog evolves weekly. Track changes via the project's TASKS.md.
- Coverage is best-effort. False positives can occur on tokens with legitimate non-burnt LP (DeFi blue chips). False negatives can occur on novel rug patterns not yet captured. We track true-positive rate ex-post.
- Concentrated-liquidity DEXes (Uniswap V3, Aerodrome Slipstream) are not yet covered for `LP_NOT_LOCKED`.
- The flag catalog and weights may change between releases; integrate via flag `code` rather than score thresholds when possible.

## Contact

- Security disclosures: `security@rugguard.io` (responsible reporting; see /security.html).
- API and integration questions: open an issue on the public repo (TBD).
- No support email for general questions — use the API and read the OpenAPI spec.

## Terms

Best-effort analytics, not financial or security advice. By calling the API you accept the terms in /terms.html. Liability is limited to the cost of the call.