# StableAnalytics API

StableAnalytics is a prepaid web analytics API.

Auth model:
- Pay with a wallet to create or top up a site (x402 or MPP).
- Owner queries are authenticated with Sign-In-With-X (SIWX): the same
  wallet that paid signs a message to prove identity. No per-call payment,
  no bearer tokens, no delegation — if you hold the key, you can read.
- The public tracker script hits /api/ingest with the site's public token
  (no signature required).

Recommended flow:
1. Create a site: POST /api/site/create with x402 or MPP. The paying wallet
   becomes the owner. Required: name, sku. Optional: domain.
   - If you already know the hostname you'll track, pass it as `domain`.
   - If you don't know the hostname yet (e.g. you're about to deploy to
     StableUpload, Vercel, or any host that assigns the URL after deploy),
     omit `domain` and set it later with POST /api/site/domain.
2. If domain was omitted at create, set it before installing the embed:
   POST /api/site/domain with body { site_id, domain }. Until the site
   has a domain, /api/ingest returns 403 "Domain not configured".
3. Install the returned embed snippet on your site.
4. List and associate sites from the same wallet with SIWX:
   - GET /api/sites returns each site's id, name, domain (nullable),
     status, usage, created_at, last_active_at, and visits_total. Use
     this to pick the site you want to work with.
5. Query analytics with SIWX from the same wallet:
   - GET /api/site?id=...
   - GET /api/site/overview?site_id=...&period=24h|7d|30d
   - GET /api/site/pages?site_id=...
   - GET /api/site/sources?site_id=...
   - GET /api/site/tech?site_id=...
   - GET /api/site/visits?site_id=...
6. Top up when the balance runs low: POST /api/site/topup.

Tracked fields:
- pathname
- referrer
- utm_source / utm_medium / utm_campaign / utm_term / utm_content
- browser / os / device
- country
- recent visit metadata

Pricing model:
- prepaid tracked-request caps (100k, 1M, 10M)
- no month-end billing
- same feature set on every cap