Run a pre-trade rug-pull risk scan on a token contract.

Returns a structured risk report. Pays $0.01 USDC on Base behind the scenes via x402. The spend is tracked against per-session and 24 h caps configured in the MCP server — if a cap is breached the call returns a spend_cap_exceeded error WITHOUT signing.

Args: chain: Chain identifier. base for Base mainnet EVM token (14 heuristics). solana for Solana SPL mint (5 heuristics). address: Token contract address — 0x... for EVM, base58 mint address for Solana.

Returns: On success: {score: 0-100, verdict: safe|low_risk|medium_risk|high_risk|critical|uncertain, score_confidence: high|medium|low|insufficient_data, rug_probability_30d: 0.0-1.0, flags: [{code, severity, evidence}, ...], scan_id: uuid for follow-up via explain_scan(...)}. On failure: {error, message}. error is one of missing_credentials, spend_cap_exceeded, payment_failed, request_failed, non_200.

In demo mode (RUGGUARD_MCP_DEMO=1 or `--demo`): returns one of three
canned scenarios deterministically by `address[-1]`. Response has
`_demo: true` — never trade on this. No wallet, no network call.

Pre-trade firewall: returns a prescriptive block | caution | allow decision plus a clamped max_suggested_exposure_usd, given a token, a trade size, and the agent's risk policy.

Costs $0.01 USDC on Base via x402 (same price as scan_token). Returns a signed JSON report when the deployment has signing configured — the signature and key_fingerprint fields prove what RugGuard said at the moment of trade, verifiable offline via the rugguard-verify CLI (pip install rugguard-verify) or against GET /v1/pubkey.

Args: chain: base or solana. address: Token contract address (EVM 0x… or Solana base58). intended_trade_usd: Trade size in USD. Used to clamp the returned max_suggested_exposure_usd. Must be > 0 and ≤ $1B. policy: Agent risk tolerance. One of: - conservative — block at medium_risk or worse (score ≥ 51) - balanced — block at high_risk or worse (score ≥ 71) [default] - aggressive — block at critical only (score ≥ 91) An uncertain verdict (sparse data) returns caution in all modes — absence of evidence is not evidence of safety.

Returns: On success: { scan_id, chain, contract, policy_recommendation: block | caution | allow, policy, risk_score: 0-100, verdict, confidence, reason: [{code, severity}, ...], # top 3 flags max_suggested_exposure_usd: float, # 100% if allow, 20% if caution, 0 if block intended_trade_usd, scanned_at, disclaimer, signature, key_fingerprint # null when signing is unconfigured } On failure: {error, message}. Same error codes as scan_token.

Disclaimer integrity: the disclaimer field is inside the signed bytes. Stripping or rewriting it breaks signature verification by design — a downstream proxy that drops the disclaimer will cause rugguard-verify to reject the report. That is the point.

Fetch the per-heuristic audit trail of a previous scan.

Costs $0.005 USDC. Use this when you need to know why a scan returned a specific verdict — e.g. for compliance, post-mortems, or building a user-visible explanation.

Args: scan_id: UUID returned by a prior scan_token call.

Returns: On success: {scan_id, scanned_at, score, verdict, heuristic_results: [...]}. On failure: {error, message}. Same error codes as scan_token.

In demo mode: returns a canned audit trail keyed by the scan_id
suffix (`demo-safe-01`, `demo-caution-01`, `demo-critical-01`).
Unknown scan_ids return a demo-safe trail. Response has `_demo: true`.