Using the agent over x402

The Clawditor agent is a standalone HTTP service (apps/agent) that wraps the scanner and the audit knowledge base in a Claude tool-use loop. It exposes one paid endpoint, POST /ask, gated by x402 — so any HTTP client or autonomous agent can call it by paying USDC on Base, with no account, API key, or rate-limit handshake.

Ask it a natural-language question about a contract; it scans, pulls the relevant security checklists when depth is warranted, and answers.

Need a full graded project report rather than a Q&A answer? Use the A2A audit endpoint or POST /audits. Use /ask for fast, conversational safety checks.

Endpoint

POST /ask
Content-Type: application/json
X-PAYMENT: <signed x402 payload>      # added by your x402 client

{ "prompt": "Is 0xc02a…c756cc2 on Ethereum safe to use as collateral?" }

Response:

{
  "role": "assistant",
  "text": "Top-line: caution. WETH is the canonical wrapped-ETH contract …",
  "scans": [ /* one ScanResult per scan_token call the agent made */ ]
}

Field	Type	Notes
`role`	`"assistant"`	always
`text`	`string`	the natural-language answer (markdown)
`scans`	`ScanResult[]`	raw scanner output for every contract the agent scanned — see the ScanResult shape

The prompt must be 8–2000 characters. Include the chain (or an address the agent can infer it from); if it's ambiguous the agent will ask.

Payment flow

/ask follows the standard x402 loop. The first unpaid call returns HTTP 402 with a challenge describing the price, asset, network, and receiver; your client signs a USDC transfer, retries with an X-PAYMENT header, and the request proceeds. Price is X402_PRICE_USDC (default $0.10) on Base. See x402 payment for the wire details.

Read the price and asset from the 402 challenge at runtime rather than hardcoding them — they're authoritative and may change per deployment.

curl

# 1. Unpaid → 402 challenge
curl -sS -X POST https://agent.clawditor.xyz/ask \
  -H 'content-type: application/json' \
  -d '{"prompt":"Is 0x6b175474e89094c44da98b954eedeac495271d0f safe on Ethereum?"}'

# 2. Sign the challenge and retry with X-PAYMENT.
#    Most x402 client libraries do this loop for you — see below.
curl -sS -X POST https://agent.clawditor.xyz/ask \
  -H 'content-type: application/json' \
  -H "X-PAYMENT: $SIGNED_PAYLOAD" \
  -d '{"prompt":"Is 0x6b175474e89094c44da98b954eedeac495271d0f safe on Ethereum?"}'

TypeScript (x402-fetch)

The official x402-fetch wrapper turns any viem account into a fetch that handles the 402 → sign → retry loop automatically.

import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchWithPay = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPay("https://agent.clawditor.xyz/ask", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    prompt: "Audit 0x… on Base — is the LP locked and who can mint?",
  }),
});

const { text, scans } = await res.json();
console.log(text);
console.log("grades:", scans.map((s: any) => `${s.symbol}: ${s.grade}`));

Python (x402 + requests)

from x402.clients.requests import x402_requests
from eth_account import Account

account = Account.from_key(PRIVATE_KEY)
session = x402_requests(account)

r = session.post(
    "https://agent.clawditor.xyz/ask",
    json={"prompt": "Is token 0x… on Base a rug? Check holders and ownership."},
)
print(r.json()["text"])

What the agent does internally

For each prompt the model runs a bounded tool-use loop:

scan_token — runs a full safety scan and gets back a ScanResult (score, grade, flags, ownership, distribution).
lookup_audit_checklists — when the scan surfaces a non-trivial surface (proxy, V4 hook, oracle, governance, signatures…), the agent fetches the contract's verified source and pulls the routed security checklists from the knowledge base, then applies the items that genuinely fit.
It synthesizes a tight verdict: top-line call, the biggest risk, structural mitigations, distribution notes, and a one-line recommendation.

Some deployments also let the agent delegate a sub-task to another A2A agent over x402 (e.g. a specialist capability its own scanner lacks), under a hard per-request spend cap. This is opt-in and bounded; a normal /ask call never spends beyond the price you paid unless delegation is explicitly enabled and budgeted.

Operational endpoints

These are unpaid and intended for ops/health, not analysis:

Method	Path	Purpose
`GET`	`/`	Service metadata (price, network, facilitator, worker id)
`GET`	`/workers/status`	Audit-worker introspection
`POST`	`/workers/run-once`	Admin-only kick of the audit queue (`x-admin-key`)

Errors

Status	Meaning
`402`	Payment required — sign the challenge and retry
`400`	Invalid body (prompt too short/long or missing)
`500`	Upstream failure (scanner/Anthropic) — safe to retry

Choosing the right surface

/ask — conversational, fast, cheap. Best for "is this safe?" and ad-hoc questions.
/a2a — for autonomous agents that want a full graded audit task with an artifact, discoverable via an AgentCard and ERC-8004 identity.
POST /audits — the same audit, from an app backend using the REST surface.
POST /scan / POST /check — raw structured ScanResult with no LLM narration.

Endpoint​

Payment flow​

curl​

TypeScript (x402-fetch)​

Python (x402 + requests)​

What the agent does internally​

Operational endpoints​

Errors​

Choosing the right surface​