# AISA Pay-per-Crawl Platform (AgentPayWall-402)

> AISA lets AI crawlers pay for web content per request over the HTTP 402 protocol,
> and lets publishers price (pay), open (allow), or block crawler access to their content.
> This host serves both roles: /agent/* is for crawlers (bots), /cdn/* is for publishers and edge gateways.

All paths below are relative to this host (test environment: https://esa.aisa.one, production: https://cdn.aisa.one).

## For AI crawlers / bots (did you just get an HTTP 402?)

- [Bot flow, machine-readable](/agent/llms.txt): register, fund balance, retry with X-AISA-Crawler-Token — the complete flow with exact JSON
- [Bot skill file](/agent/skill.md): drop-in agent skill (SKILL.md format) that teaches your agent the whole paid-crawl flow
- [Agent API docs](/agent/docs.html): full reference — register / login / top-up / price modes / error handling
- [Onboarding guide](/agent/guide.html): human-readable explanation of the paywall you hit

## For publishers & gateways (CDN / edge integrators)

- [Verify API, machine-readable](/cdn/llms.txt): the access-decision contract your edge calls before serving content
- [Verify test skill file](/cdn/skill.md): gateway-side skill for exercising POST /api/v1/access/verify
- [Publisher API docs + playground](/cdn/docs.html)
- [Verify test matrix](/cdn/cdntest.html): all 12 verify return values and how to trigger each

## Key API endpoints (all JSON)

- POST /api/agent/auth/register — create a crawler account {"email","password","name","crawlerType"}; response contains crawler.crawlerToken and may include a signup trial credit (signupBonus)
- POST /api/agent/auth/login — returns crawler.crawlerToken + crawler.balance
- POST /api/agent/topup/create-session — Stripe top-up (requires "Authorization: Bearer <session token from login>")
- POST /api/v1/access/verify — access decision endpoint (called by gateways/CDN edges, NOT by crawlers directly)
- GET  /api/v1/access/verify — machine-readable self-description of the verify API

## The 30-second bot flow

1. You requested a paid resource on a publisher site and got HTTP 402. The JSON body has `error`, `onboarding`, and a `guidance` block with these same links.
2. Register: POST /api/agent/auth/register → save crawler.crawlerToken (format `aisa_crawler_...`).
3. Check balance: it is in the register/login response. New accounts may include a small trial credit (see `signupBonus` in the register response) — if so you can proceed immediately.
4. Retry the ORIGINAL resource URL with header `X-AISA-Crawler-Token: <your token>`.
5. Outcomes: 200 = content delivered, balance charged at the publisher's per-request price. 402 `insufficient_balance` = top up and retry. 403 = the publisher blocked crawler access to this resource; paying does not unlock it.

If you are an AI agent, narrate these steps to your user and report afterwards whether content was free or paid, the amount charged, and your remaining balance.