# 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" />
  <a href="https://www.santosautomation.com/integrations/grok"><img src="https://img.shields.io/badge/Grok-Remote%20MCP%20ready-000000?style=for-the-badge&logo=x" alt="Grok Remote MCP ready" /></a>
  <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>

<div align="center">
<pre>
┌──────────────────────────────────────────────────────────────┐
│    SANTOS WEBSITE INTELLIGENCE • AI-READY WEB EVALUATION     │
│             Discover • Understand • Call • Trust             │
└──────────────────────────────────────────────────────────────┘
</pre>
</div>

**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](https://x402.org) 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 site](https://img.shields.io/website?url=https%3A%2F%2Fwww.santosautomation.com&label=live%20site)](https://www.santosautomation.com/)
[![Vercel production](https://img.shields.io/badge/production-Vercel-black?logo=vercel)](https://vercel.com/thereal-baitjets-projects/santos-api)
[![API version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.santosautomation.com%2Fversion&query=%24.api_version&prefix=v&label=API&color=d4a24e)](https://api.santosautomation.com/openapi.json)
[![Agent-Ready badge](https://api.santosautomation.com/v1/badge?url=santosautomation.com)](https://www.santosautomation.com/reports/santosautomation.com)
[![x402](https://img.shields.io/badge/payments-x402%20v2%20%7C%20USDC%20on%20Base-2775ca)](https://x402.org/)
[![OpenAPI](https://img.shields.io/badge/spec-OpenAPI%203.1-6ba539)](https://api.santosautomation.com/openapi.json)
[![santos-audit-api MCP server](https://glama.ai/mcp/servers/thereal-baitjet/santos-audit-api/badges/score.svg)](https://glama.ai/mcp/servers/thereal-baitjet/santos-audit-api)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

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"}` |
| OpenAPI 3.1 | [`/openapi.json`](https://api.santosautomation.com/openapi.json) |
| llms.txt | [`/llms.txt`](https://api.santosautomation.com/llms.txt) |
| MCP server (`audit_website_preview` is free, 1/day per IP; `audit_agent_readiness`, `extract_page_markdown`, `extract_structured_data`, `feed_parse`, `link_map`, `summarize` return x402 handoffs) | `POST /mcp` |
| Service manifest | [`/api`](https://api.santosautomation.com/api) |
| Capability manifest | [`/capabilities.json`](https://api.santosautomation.com/capabilities.json) |
| Well-known capability manifest | [`/.well-known/agent-capabilities.json`](https://www.santosautomation.com/.well-known/agent-capabilities.json) |
| Machine-readable version & contracts | [`/version`](https://www.santosautomation.com/version) |
| Status & changelog | [`/status`](https://www.santosautomation.com/status) · [`/changelog`](https://www.santosautomation.com/changelog) |
| Sitemap / crawler rules | [`/sitemap.xml`](https://www.santosautomation.com/sitemap.xml) · [`/robots.txt`](https://www.santosautomation.com/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](https://www.santosautomation.com/ai-website-intelligence)
- [Agent Readiness Audit](https://www.santosautomation.com/agent-readiness-audit)
- [Website Intelligence API](https://www.santosautomation.com/website-intelligence-api)
- [MCP Readiness Checker](https://www.santosautomation.com/mcp-readiness-checker)
- [llms.txt Checker](https://www.santosautomation.com/llms-txt-checker)
- [OpenAPI Readiness Checker](https://www.santosautomation.com/openapi-readiness-checker)
- [Agent Readiness Methodology](https://www.santosautomation.com/methodology/agent-readiness)
- [Sample Agent Readiness Report](https://www.santosautomation.com/reports/sample-agent-readiness)
- [Learning guides](https://www.santosautomation.com/learn/what-is-ai-website-intelligence)

## For humans (card, no crypto)

- [Buy a report by card](https://www.santosautomation.com/agent-readiness/buy) — **$9 Quick** (Agent Readiness, fetch-based) or **$29 Deep** (Website Intelligence, browser-rendered), one-time, formatted and emailed. x402 prices remain the agent price (raw API); card prices are the human report.
- [Santos Monitoring](https://www.santosautomation.com/monitoring) — **$9/mo** subscription: weekly re-audit of one URL, an email alert when the score moves 5+ points, and a monthly digest. Cancel anytime.

## 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

```js
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`](buy-audit.js) (local dev),
[`buy-live.js`](buy-live.js) (production), and [`buy-batch.js`](buy-batch.js)
(batch). Python example: [`examples/audit_client.py`](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`](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`](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`](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`](buy-summarize.js).

### See the output before paying

The free HTTP tier is retired — the old `/demo` endpoints answer `402` naming
their paid successor, its price, and the exact URL to call. To judge the output
first, read a completed report in the [public archive](https://www.santosautomation.com/reports)
or call the free MCP tool `audit_website_preview` (1/day per calling IP).

## Free tools, badge & CI

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

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

**Report verification** — every report carries an HMAC-SHA256 signature. Verify
one free with `POST /v1/verify` (30/hour) or at
[/verify](https://www.santosautomation.com/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`](examples/agent-readiness-ci.yml) (GitHub
Actions) and [`examples/agent-readiness-ci.sh`](examples/agent-readiness-ci.sh)
(any CI). Guide: [/ci](https://www.santosautomation.com/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`](buy-deep.js). Architecture + go-live
runbook: [`docs/deep-audit.md`](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`](docs/agent-readiness-scoring.md) and
[`docs/agent-readiness-spec-baseline.md`](docs/agent-readiness-spec-baseline.md).

## Response shape (Quick Intelligence Audit)

```json
{
  "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

```bash
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:

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

### Environment variables

See [`.env.example`](.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`](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