API reference

Base URL: http://localhost:3001 (default; https://api.clawditor.xyz in production). GET / returns the live endpoint list.

Gating. Endpoints marked Gated require either a SIWE session whose wallet holds the gating token, or a settled x402 USDC payment. An ungated, unauthenticated call to a gated endpoint returns HTTP 402 with the x402 challenge. See Token gating and x402 payment.

Pricing

Prices are configured server-side and declared in the 402 challenge; read them at runtime rather than hardcoding. Defaults:

Action	Endpoint	Price (USDC)
Token scan	POST /scan, GET /scan/:chainId/:address	X402_PRICE_USDC (default $0.10)
Contract check	POST /check	free
Audit request	POST /audits	$1.00
Audit follow-up	POST /audits/:id/followup	$6.00
Unlock private audit	POST /audits/:id/unlock	$5.00
Agent Q&A	POST /ask (agent service)	X402_PRICE_USDC (default $0.10)

Gating-token holders get scans/audits free; the prices above apply to x402 payers.

Auth (SIWE)

Method	Path	Notes
GET	/auth/nonce	Returns a SIWE nonce (plain text)
POST	/auth/verify	Body { message, signature }; sets the clawditor_session cookie
GET	/auth/me	Current session, or { authenticated: false }

Scan — full token analysis

Gated.

POST /scan          { "address": "0x…", "chainId": 1 | 8453 }
GET  /scan/:chainId/:address

Returns { result: ScanResult, accessMethod: "siwe-token-holder" | "x402-payment" }.

Check — contract-level pass

Free, no gating. Works on any contract address (not just tokens).

POST /check         { "address": "0x…", "chainId": 1 | 8453 }
POST /check?format=json

Without ?format=json the response is an SSE stream of subtask events ending in a final event carrying the ScanResult; with ?format=json it returns { result: ScanResult, kind: "contract" }.

Audits — project review

Method	Path	Notes
POST	/audits	Gated. Body { address, chainId, symbol?, note?, visibility?, unlockPriceUsdc?, scannerRevshareBps? }. Queues an audit; returns the row (status: "queued").
GET	/audits	List/search audits (?q= matches target/sibling address or symbol).
GET	/audits/recent	Recent completed audits.
GET	/audits/stats	Aggregate counts.
GET	/audits/:id	One audit: report markdown, grade/score, recommendations, project-context snapshot, conversation turns.
GET	/audits/:id/stream	SSE — live stage/delta/done events as the report is written.
GET	/audits/:id/followup-estimate	Token/cost estimate for a follow-up.
POST	/audits/:id/followup	Gated. Body { prompt, source: "recommendation"|"freeform", recommendationText? }. Queues a follow-up answer.
POST	/audits/:id/unlock	Gated. Unlock a private report for the caller.
PATCH	/audits/:id/visibility	Owner: toggle public/private + revshare.

The audit lifecycle is queued → in-review → complete (or failed / cancelled). Poll /audits/:id or subscribe to /audits/:id/stream.

Explorer, monitoring, config

Method	Path	Notes
GET	/explorer/recent	Recently scanned tokens.
GET	/explorer/stats	Global scan stats.
GET	/explorer/token/:chainId/:address	Consolidated token intelligence (scan, holders, bundles, deployer, related, social, audits). Accepts Solana addresses for lookups.
GET	/alerts	Alerts for the session wallet's watched tokens.
GET/POST/DELETE	/watchlist	Manage watched tokens.
GET	/config	Public config (gating token, chains, pricing).

A2A & well-known

Method	Path	Notes
GET	/.well-known/agent-card.json	A2A AgentCard (v0.3). Public.
GET	/.well-known/agent-registration.json	ERC-8004 registration. Public.
POST	/a2a	Gated. JSON-RPC: message/send, message/stream, tasks/get, tasks/cancel. See Agent-to-agent.

ScanResult shape

type ScanResult = {
  address: `0x${string}`;
  chainId: 1 | 8453;
  scannedAt: string;                 // ISO 8601
  name: string | null;
  symbol: string | null;
  decimals: number | null;
  totalSupply: string | null;        // base units
  isProxy: boolean;
  implementationAddress: `0x${string}` | null;
  isVerified: boolean;
  ownership: {
    owner: `0x${string}` | null;
    ownerIsZero: boolean;
    ownerIsContract: boolean;
    ownerIsMultisig: boolean;
    ownerIsTimelock: boolean;
  } | null;
  distribution: {
    totalHolders: number;
    topHolderPctBps: number;         // 10000 = 100%
    top10Bps: number;
    top25Bps: number;
    top50Bps: number;
    topHolders: HolderEntry[];
    bundledWallets: `0x${string}`[];
    bundledShareBps: number;
    lpHolders?: HolderEntry[];
    lpLockedBps?: number;
  } | null;
  deployer: DeployerInfo | null;     // deployer EOA + other deployments
  related: RelatedContract[];        // owner/staking/impl/constant graph
  social: SocialMentions | null;     // Farcaster + X
  bundleClusters: BundleCluster[];   // funding-source holder clusters
  flags: Flag[];
  score: number;                     // 0..100
  grade: "A" | "B" | "C" | "D" | "F";
  summary: string;
  partial: boolean;
};

type Flag = {
  id: string;
  category: "mint" | "ownership" | "pause" | "blacklist" | "fee" | "proxy"
    | "v4-hook" | "staking" | "liquidity" | "distribution" | "verification" | "misc";
  severity: "info" | "low" | "medium" | "high" | "critical";
  title: string;
  detail: string;
  evidence?: string;
};