Santos Website Intelligence API

<p align="center"> <img src="public/assets/santos-eagle.svg" width="140" alt="Santos gold eagle emblem" /> </p>

<p align="center"> <img src="https://img.shields.io/badge/AI-Website%20Intelligence-7c3aed?style=for-the-badge&logo=robot" alt="AI Website Intelligence" /> <img src="https://img.shields.io/badge/Agent-Readiness-2563eb?style=for-the-badge&logo=lightning" alt="Agent Readiness" /> <img src="https://img.shields.io/badge/x402-USDC%20on%20Base-0ea5e9?style=for-the-badge&logo=bitcoin" alt="x402 on Base" /> <img src="https://img.shields.io/badge/Next.js-16-000000?style=for-the-badge&logo=nextdotjs" alt="Next.js" /> </p>

<p align="center"> <strong>Measure whether a public website is discoverable, understandable, callable, and trustworthy for agents.</strong> </p>

┌──────────────────────────────────────────────────────────────┐
│    SANTOS WEBSITE INTELLIGENCE • AI-READY WEB EVALUATION     │
│             Discover • Understand • Call • Trust             │
└──────────────────────────────────────────────────────────────┘

AI Website Intelligence and Agent Readiness for the agentic web — Quick, Agent Readiness, and browser-rendered Deep audits return structured evidence and prioritized fixes. No account or traditional API key; paid resources use the x402 protocol with USDC on Base.

Highlights

• 🔍 Quick audits for website intelligence and agent-readiness signals
• 📦 Batch audits — up to 50 sites in one flat $0.50 payment
• 🧠 Browser-rendered Deep audits with Chromium, Lighthouse, and axe-core
• 💳 x402-based payments with USDC on Base
• 📡 OpenAPI, MCP, llms.txt, and capability manifest support

Live: API at https://api.santosautomation.com · landing page at https://www.santosautomation.com (same app, two hostnames)

The public site is positioned as Santos Website Intelligence. Its responsive navigation uses the gold Santos eagle SVG emblem from public/assets.

Surface	URL
Quick Intelligence Audit ($0.015 USDC, synchronous)	GET /api/audit?url=https://example.com
Batch Quick Audit ($0.50 USDC flat, up to 50 URLs)	POST /api/audit/batch {"urls": [...]}
Agent Readiness ($0.075 USDC, bounded passive assessment)	GET /api/agent-readiness?url=https://example.com&depth=quick
Safe Fetch ($0.002 USDC, synchronous)	GET /v1/fetch?url=https://example.com
Content Extraction ($0.005 USDC, synchronous)	POST /v1/extract {"url": "https://example.com"}
Structured Extraction ($0.08 USDC, synchronous)	POST /v1/extract/structured {"url": "...", "schema": {...}}
Feed Parser ($0.003 USDC, synchronous)	GET /v1/feed?url=https://example.com/feed.xml
Link Map ($0.003 USDC, synchronous)	GET /v1/links?url=https://example.com
Summarizer ($0.033 USDC, synchronous)	POST /v1/summarize {"url": "https://example.com", "focus": "..."}
Screenshot & PDF Render ($0.01 USDC, synchronous)	GET /v1/screenshot?url=https://example.com
Deep Website Intelligence Audit ($0.225 USDC, async job)	POST /v1/audits {"url": "https://example.com"}
Free demos (1/day per IP, shared quota across all demos)	GET /api/audit/demo?url=... · GET /api/agent-readiness/demo?url=...
OpenAPI 3.1	/openapi.json
llms.txt	/llms.txt
MCP server (tools: audit_website_preview, audit_agent_readiness, extract_page_markdown, extract_structured_data, feed_parse, link_map, summarize)	POST /mcp
Service manifest	/api
Capability manifest	/capabilities.json
Well-known capability manifest	/.well-known/agent-capabilities.json
Machine-readable version & contracts	/version
Status & changelog	/status · /changelog
Sitemap / crawler rules	/sitemap.xml · /robots.txt

Website Intelligence model

Santos measures four dimensions across completed, applicable checks:

• Discoverable — crawler access, canonical URLs, sitemaps, llms.txt, documentation, and interface links.
• Understandable — structured identity, JSON-LD, semantic HTML, metadata, pricing, and business context.
• Callable — OpenAPI, MCP, capability manifests, typed schemas, stable errors, job endpoints, and x402 where applicable.
• Trustworthy — HTTPS, security headers, accessibility, performance, browser behavior, support, and evidence quality.

The additive website_intelligence_score and website_intelligence fields appear alongside historical Quick Audit fields. Existing overall_score, category scores, endpoint paths, capability ids, and payment behavior remain compatible.

Public product pages

• AI Website Intelligence
• Agent Readiness Audit
• Website Intelligence API
• MCP Readiness Checker
• llms.txt Checker
• OpenAPI Readiness Checker
• Agent Readiness Methodology
• Sample Agent Readiness Report
• Learning guides

How agents pay (x402)

GET /api/audit?url=example.com
← 402 · PAYMENT-REQUIRED: <base64 terms: $0.015 USDC · eip155:8453 · payTo · asset>
→ retry with PAYMENT-SIGNATURE: <base64 signed EIP-3009 authorization>
← 200 OK · audit JSON · PAYMENT-RESPONSE: <base64 on-chain receipt>

Protocol: x402 v2 (migrated 2026-07-17; legacy v1 X-PAYMENT clients are no longer accepted).

Payment settles only after a successful response — a bad URL or unreachable target costs the agent nothing.

JavaScript / TypeScript

import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await fetchWithPay(
  "https://api.santosautomation.com/api/audit?url=example.com"
);
const report = await res.json(); // { overall_score, scores, checks, issues, ... }

Working scripts: buy-audit.js (local dev), buy-live.js (production), and buy-batch.js (batch). Python example: examples/audit_client.py.

Batch audits (the volume rail)

One flat $0.50 USDC payment audits up to 50 URLs — $0.01/URL at full capacity, ~33% under per-call pricing. Synchronous, deduped, 8-way bounded concurrency, per-URL failure isolation (one bad target returns an error entry, not a failed batch). Settles only when at least one audit succeeds — an all-failure batch is free.

POST /api/audit/batch
{ "urls": ["https://example.com", "https://example.org", ...] }
← 402 · PAYMENT-REQUIRED: $0.50 USDC terms
→ retry with PAYMENT-SIGNATURE
← 200 · { batch_size, succeeded, failed, results: [{url, ok, report|error}] }

Working buyer example: buy-batch.js.

Feed Parser, Link Map & Summarizer

Three synchronous content tools under the same pay-per-success contract:

• Feed Parser — GET/POST /v1/feed ($0.003 USDC): one public feed URL in, normalized JSON out. Detects RSS 2.0, Atom, and JSON Feed through the same SSRF-guarded fetcher as Safe Fetch; returns feed metadata plus up to 50 items (id, title, url, published, summary, author). A non-feed target returns 422 and never settles. Buyer example: buy-feed.js.
• Link Map — GET/POST /v1/links ($0.003 USDC): one HTML page in, a categorized link map out — every link (max 200) with a kind (internal or external) plus topic tags (docs, pricing, api, careers, social, feed) and per-category counts. A site-discovery step, not a crawler. Buyer example: buy-links.js.
• Summarizer — POST/GET /v1/summarize ($0.033 USDC): one HTML page in, a Claude-generated structured summary out (title, summary, key_facts, entities, word_count), with an optional focus steering prompt. Non-HTML targets return 422 and never settle. Buyer example: buy-summarize.js.

Free demo first

Same report shape, no payment, 1/day per IP:

curl "https://api.santosautomation.com/api/audit/demo?url=example.com"

Free tools, badge & CI

Verified-email free audit — one full Quick Intelligence audit per day per verified email (6-digit code flow, token valid 30 days), HMAC-signed report:

POST /api/leads/verify/request  {"email": "you@example.com", "url": "example.com"}
POST /api/leads/verify/confirm  {"email": "you@example.com", "code": "123456"}  → token
GET  /api/audit/free?url=example.com&token=<token>

Agent-Ready badge — embed a live SVG shield of your public score:

[![Agent-Ready badge](https://api.santosautomation.com/v1/badge?url=example.com)](https://www.santosautomation.com/reports/example.com)

llms.txt generator — draft a standards-shaped llms.txt from a one-page sample (verified-email free tier, quota shared with the free audit): GET /v1/llms-txt/demo?url=example.com&token=<token> or the tool page at /llms-txt-generator.

Report verification — every report carries an HMAC-SHA256 signature. Verify one free with POST /v1/verify (30/hour) or at /verify.

CI gate — fail a pull request when its preview deploy scores below your agent-readiness threshold (~$0.075 USDC per run via x402): examples/agent-readiness-ci.yml (GitHub Actions) and examples/agent-readiness-ci.sh (any CI). Guide: /ci.

Deep Website Intelligence (browser-rendered tier)

Real Chromium via Playwright in an isolated Fly.io worker: Lighthouse lab metrics, rendered axe-core accessibility findings (with selectors), browser network/console evidence, screenshots, and passive security checks. Async: the $0.225 payment buys a bounded compute reservation (settles on job accept, not report completion). POST /v1/audits with an Idempotency-Key header → poll status_url with the returned one-time access_token → fetch report_url (versioned schema_version: 3.0.0 JSON + signed artifact URLs). Working buyer example: buy-deep.js. Architecture + go-live runbook: docs/deep-audit.md.

Agent Readiness

The versioned AgentReadinessResult assesses public agent-facing discovery, structured identity, OpenAPI, MCP, operational trust, and x402/machine-commerce signals. It first classifies applicability, so a normal website is not penalized for lacking an API, MCP server, or payment interface. The standalone quick pass uses at most eight bounded requests and never authenticates to or pays the audited target, submits forms, creates target accounts, invokes target tools, or executes code.

Agent Readiness is also available as the opt-in agent-readiness module for POST /v1/audits, through the MCP audit_agent_readiness paid-HTTP handoff, and additively as a lower-coverage embedded preview inside the Quick Audit response. The standalone result costs $0.075 USDC per successful response through x402 v2; failed audits do not settle. The existing Quick Audit overall_score is unchanged. The standalone response also includes the additive Website Intelligence score and four-dimensional presentation, with callable marked not applicable when the target does not advertise callable services. Scoring and standards baselines are documented in docs/agent-readiness-scoring.md and docs/agent-readiness-spec-baseline.md.

Response shape (Quick Intelligence Audit)

{
  "tier": "paid",
  "url": "https://example.com/",
  "http_status": 200,
  "timing_ms": { "ttfb": 166, "total": 168 },
  "overall_score": 68,
  "scores": { "performance": 100, "seo": 40, "accessibility": 100, "security": 33 },
  "website_intelligence_score": 74,
  "website_intelligence": {
    "dimensions": {
      "discoverable": 81,
      "understandable": 68,
      "callable": null,
      "trustworthy": 73
    },
    "applicability": { "callable": "not_applicable" },
    "coverage": { "tests_executed": 28, "tested_percent": 88 },
    "confidence": 0.86,
    "priority_fixes": []
  },
  "checks": { "performance": [ { "pass": true, "detail": "TTFB 166ms" } ] },
  "issues": ["Missing canonical link", "Missing Content-Security-Policy header"]
}

Errors are { "error": "<human message>", "code": "<STABLE_CODE>" } with codes INVALID_URL, UNSUPPORTED_SCHEME, PRIVATE_ADDRESS_BLOCKED, RATE_LIMITED, AUDIT_TIMEOUT, TARGET_UNREACHABLE, AUDIT_FAILED.

Stack

Next.js App Router on Vercel. Payments: @x402/next v2 (withX402 wrapper) + @x402/core/@x402/evm with @coinbase/x402 (Coinbase CDP facilitator — the piece that actually settles USDC on Base mainnet) and the @x402/extensions Bazaar discovery extension. Audit engine: fetch + cheerio, no headless browser. SSRF-guarded: private/reserved/metadata IPs blocked with per-redirect-hop revalidation, 15s timeout, 5 redirects, 5 MB cap (lib/safe-fetch.js).

Development

npm install
cp .env.example .env.local   # fill in values
npm run dev                  # http://localhost:3000
npm test                     # e2e checks against BASE (default localhost:3000)
BASE=https://api.santosautomation.com EXPECT_NETWORK=base npm test

Focused checks for the Website Intelligence layer:

npm run test:agent-readiness
npm run test:website-intelligence
npm run build

Environment variables

See .env.example. Required in production: CDP_API_KEY_ID, CDP_API_KEY_SECRET (facilitator auth). Optional: DISCORD_WEBHOOK_URL (payment notifications), PUBLIC_API_BASE_URL (canonical hostname in docs output), audit tuning knobs.

Deploy

vercel --prod from a linked checkout. Vercel deploys the website and API control plane; the browser-rendered worker is a separate Fly.io deployment and must be released independently when worker code changes. The receiving wallet and network are hard-coded in app/api/audit/route.js on purpose — stale env vars must not silently flip the API back to testnet.

Registry listings

Copy-ready submission text for x402 catalogs and the MCP registry: docs/registry-submissions.md.

Operator

Santos Automation (Juan Santos) — custom x402 APIs, web apps, e-commerce, and automation systems. info@santosautomation.com · https://santosautomation.com