# URL Metadata API

Extract metadata from any URL: title, description, OG tags, headings, links, images.

## Endpoints

### Free
GET /api?url=<URL> — JSON metadata, no payment required.

### Paid (x402)
GET /api/extract?url=<URL> — Same data as /api, $0.005 USDC per call on Base mainnet.
GET /api/summarize?url=<URL> — Fetches URL and returns title + description + first paragraphs as a text summary, $0.005 USDC per call on Base mainnet.
GET /api/keywords?url=<URL> — Cheap tier: title + description + keyword list, $0.002 USDC per call on Base mainnet.
GET /api/links?url=<URL> — Mid-tier: every outbound <a href> with internal/external split + anchor text + rel, $0.002 USDC per call on Base mainnet.
GET /api/og?url=<URL> — Cheap tier: Open Graph + Twitter Card metadata, $0.001 USDC per call on Base mainnet.
GET /api/feed?url=<URL> — Cheap tier: RSS / Atom / JSON feed discovery via <link rel=alternate> + path probing, $0.001 USDC per call on Base mainnet.
GET /api/markdown?url=<URL> — Mid-tier: clean Markdown extraction (strips nav/ads/scripts, returns main article body as MD), $0.002 USDC per call on Base mainnet.
GET /api/headings?url=<URL> — Cheap tier: page outline (every h1/h2/h3 with text + totals by level), $0.001 USDC per call on Base mainnet.
GET /api/canonical?url=<URL> — Sub-cent tier: canonical URL + hreflang alternates + og:url + redirect chain, $0.0005 USDC per call on Base mainnet.
GET /api/robots?url=<URL> — Sub-cent tier: robots.txt policy summary (Allow/Disallow/Sitemap parsed), $0.0005 USDC per call on Base mainnet.
GET /api/sitemap?url=<URL> — Sub-cent tier: sitemap.xml discovery + URL extraction (probes robots.txt + common paths), $0.0005 USDC per call on Base mainnet.
GET /api/tech?url=<URL> — Sub-cent tier: tech-fingerprint detection (meta-generator, JS frameworks, analytics, CDN, X-Powered-By), $0.0005 USDC per call on Base mainnet.
GET /api/hash?url=<URL> — Sub-cent tier: URL body SHA-256 hash + char/word/line/byte counts, $0.0005 USDC per call on Base mainnet.
GET /api/schema?url=<URL> — Cheap tier: structured data extraction (JSON-LD + microdata + RDFa + OG + Twitter Card), $0.001 USDC per call on Base mainnet.
GET /api/emails?url=<URL> — Cheap tier: email address extraction (mailto + obfuscated + Cloudflare-protected), $0.001 USDC per call on Base mainnet.
GET /api/headers?url=<URL> — Sub-cent tier: HTTP response headers + security audit (every header categorized + A-F grade for CSP/HSTS/XFO/XCTO/Referrer-Policy), $0.0005 USDC per call on Base mainnet.
GET /api/redirects?url=<URL> — Sub-cent tier: HTTP redirect chain analyzer (every hop + status + Location + redirect type + final destination + domain-change flag), $0.0005 USDC per call on Base mainnet.
GET /api/dns?domain=<HOST> — Cheap tier: domain DNS intelligence (A/AAAA/MX/NS/TXT/CNAME + SPF/DMARC/verification strings via Cloudflare DNS-over-HTTPS), $0.001 USDC per call on Base mainnet.
GET /api/whois?domain=<HOST> — Sub-cent tier: domain WHOIS via RDAP (registrar, creation/expiration dates, status codes, nameservers, registrant org), $0.0005 USDC per call on Base mainnet.
GET /api/ssl?domain=<HOST> — Sub-cent tier: TLS/SSL certificate inspector (issuer, subject, validity, days-until-expiry classification, SAN list, wildcard detection, TLS version, cipher, key bits, SHA-256/SHA-1/MD5 fingerprints), $0.0005 USDC per call on Base mainnet.
GET /api/timing?url=<URL> — Sub-cent tier: HTTP request timing breakdown (DNS/TCP/TLS/TTFB/total ms with percentage breakdown, plus status, server, content-type, content-length, caching-headers flag), $0.0005 USDC per call on Base mainnet.
GET /api/portscan?domain=<HOST> — Sub-cent tier: TCP port-reachability scan (24 well-known ports probed with 1s timeout, parallelized; returns open_ports list + per-port state/latency + scan_ms total; refuses RFC1918/loopback/link-local), $0.0005 USDC per call on Base mainnet.

## x402 Payment

- Network: eip155:8453 (Base mainnet)
- Token: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Pay to: 0xCa0a6c6Aa7A8F0D5893636CF166Ea2b44fb6500c
- Facilitator: https://pay.openfacilitator.io
- Price: $0.005 USDC per call (extract, summarize) · $0.002 USDC per call (keywords, links, markdown) · $0.001 USDC per call (og, feed, headings) · $0.0005 USDC per call (canonical, robots)
- Discovery: GET /.well-known/x402 (legacy) · GET /openapi.json (canonical x402scan discovery)

## Use from an x402 client

```python
from x402 import x402ClientSync
from x402.mechanisms.evm.exact import ExactEvmScheme

client = x402ClientSync()
client.register("eip155:8453", ExactEvmScheme(signer=my_signer))
response = client.get("https://epson-rpm-america-satisfy.trycloudflare.com/api/extract?url=https://example.com")
```

## Response shape

JSON object with: title, description, og_title, og_image, og_url, og_type,
canonical, favicon, keywords, headings (list of {level, text}), body_excerpt,
images (list of {src, alt}), links (list of {href, text}).
Plus response metadata: status_code, final_url, content_length, response_time_ms.