# Tinstop Website Intelligence API: Full Reference

> Pay-per-call domain audit API. Gated with x402 (USDC on Base, EIP-3009 exact scheme).

## Payment flow
1. POST to any /v1 endpoint without payment -> HTTP 402 with a `Payment-Required` header (base64 x402 terms).
2. Sign an EIP-3009 TransferWithAuthorization for the quoted amount to `payTo`.
3. Retry the request with header `PAYMENT-SIGNATURE: <base64 payload>`.
4. On success the response includes `X-Payment-Response` and the audit result.

- Network: Base mainnet (eip155:8453)
- Asset: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (domain name 'USD Coin', version '2')
- OpenAPI: https://tinstop.com/openapi.json

## Common request body
`{ "domain": "example.com" }`  (no http/https prefix)

## Response metadata (all paid endpoints)
- scan_id: unique audit record id
- request_id: gateway request id (also X-Request-ID header)
- cached: true if served from the ~10-minute per-tool cache

## Performance notes
- POST /v1/website/performance returns live PageSpeed Insights data when available.
- Fields: pagespeed_available (bool), warnings (string[]). Metrics are null when PSI is rate-limited.
- Never invents scores on upstream failure.

## Email / headers check depth
- SPF: missing, multiple records, +all / ?all / missing all.
- DMARC: policy, pct partial enforcement, reporting addresses.
- Headers: presence grade plus weak HSTS max-age and obsolete X-Frame-Options ALLOW-FROM.

## Endpoints
### POST /v1/dmarc-check ($0.02)
DMARC policy, pct, alignment, and reporting targets.
curl -X POST https://tinstop.com/v1/dmarc-check -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/ssl-check ($0.02)
TLS cert validity, expiry, SANs, and hostname match.
curl -X POST https://tinstop.com/v1/ssl-check -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/headers-check ($0.02)
Security headers grade including weak HSTS and X-Frame-Options.
curl -X POST https://tinstop.com/v1/headers-check -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/domain/subdomains ($0.02)
Enumerate likely subdomains with DNS resolution status.
curl -X POST https://tinstop.com/v1/domain/subdomains -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/site/screenshot ($0.02)
Capture desktop or mobile screenshot metadata for a URL.
curl -X POST https://tinstop.com/v1/site/screenshot -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/email-security-check ($0.05)
SPF/DKIM/DMARC with +all, multi-record, and pct checks.
curl -X POST https://tinstop.com/v1/email-security-check -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/domain/security ($0.05)
Focused security posture: SSL, redirects, headers, email auth, grade.
curl -X POST https://tinstop.com/v1/domain/security -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/site/change-diff ($0.05)
Structured page diff versus previous snapshot or a baseline.
curl -X POST https://tinstop.com/v1/site/change-diff -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/domain/audit ($0.10)
Full audit: DNS, SSL, headers, and email auth with weighted score.
curl -X POST https://tinstop.com/v1/domain/audit -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/website/performance ($0.10+)
Live Google PageSpeed metrics; pagespeed_available flag if PSI is down.
curl -X POST https://tinstop.com/v1/website/performance -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/domain/overview ($0.15)
One-call domain dossier: RDAP, DNS, SSL, tech/hosting hints, risk flags.
curl -X POST https://tinstop.com/v1/domain/overview -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/website/ai-audit-report ($0.50+)
AI expert report: multi-check bundle + DeepSeek summary, issues, action plan.
curl -X POST https://tinstop.com/v1/website/ai-audit-report -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/website/ai-seo-readiness ($0.75)
AI SEO/UX readiness review from crawlability, metadata, and performance.
curl -X POST https://tinstop.com/v1/website/ai-seo-readiness -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

### POST /v1/website/ai-change-advisor ($1.00)
AI comparison of two scans or domains: regressions, improvements, actions.
curl -X POST https://tinstop.com/v1/website/ai-change-advisor -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: <base64>" -d '{"domain":"example.com"}'

## Errors
Standard envelope: {"error":{"code","message","request_id","details"}}.
Codes: 402 PAYMENT_REQUIRED, 422 VALIDATION_ERROR, 429 TOO_MANY_REQUESTS, 500 INTERNAL_SERVER_ERROR, 503 FACILITATOR_UNAVAILABLE/SETTLEMENT_AMBIGUOUS.