# AISA for AI Crawlers — the complete paid-access flow

> You are a crawler/agent. A publisher site protected by AISA returned HTTP 402 (payment required)
> or you want to access metered content. This file tells you exactly what to do, with real JSON.
> Paths are relative to this host (test: https://esa.aisa.one, production: https://cdn.aisa.one).
> Full HTML docs: /agent/docs.html · Drop-in agent skill: /agent/skill.md · Site index: /llms.txt

## Golden rule

You do NOT call the verify API yourself. The publisher's edge/CDN gateway calls it for you.
Your job is only: (1) hold a valid crawler token, (2) keep a positive balance,
(3) send the token in the `X-AISA-Crawler-Token` header when requesting publisher content.

## Step 1 — Register (once)

POST /api/agent/auth/register
Content-Type: application/json

{"email":"mybot@example.com","password":"AtLeast8Chars","name":"My Crawler","crawlerType":"custom"}

Response (201/200):
{
  "success": true,
  "token": "<session token — for account APIs like top-up, NOT for crawling>",
  "crawler": {
    "id": 123,
    "email": "mybot@example.com",
    "crawlerToken": "aisa_crawler_<64 hex>",   ← SAVE THIS. This is your crawl credential.
    "balance": 0.10                            ← may be non-zero if a signup trial credit is active
  },
  "signupBonus": { "amount": 0.10, "currency": "USD", "note": "..." }   ← present only when trial credit is enabled
}

- `crawlerType`: use your real identity if you have one (gptbot, perplexitybot, amazonbot, ...), else "custom".
- Email already registered → 409. Use login instead (Step 2).

## Step 2 — Check your real balance (one call, same crawler token)

GET /api/agent/balance   with header  X-AISA-Crawler-Token: aisa_crawler_...
Response: { "success": true, "crawler": { "id", "email", "balance": 0.06, "totalSpent": 0.04, ... } }

This is the one-call, same-credential way to know your true balance — no email/password, no session token,
and it can't drift to the wrong account. ALWAYS fetch the real balance before reporting it; never quote it
from memory. Post-top-up balance = (real balance from here) + top-up amount — e.g. spent $0.04 (balance
$0.06) then top up $100 → $100.06, NOT "$100.10". Use ONE account throughout; never re-register mid-task.
(You can also recover the token + read balance via POST /api/agent/auth/login {email,password}.)

## Step 3 — Fund your balance (when balance is too low)

Stripe checkout (needs a browser or a human to complete payment):
POST /api/agent/topup/create-session
Authorization: Bearer <session token from login>
{"amount": 5.00}                       ← minimum 0.50 USD
Response: { "checkout_url": "https://checkout.stripe.com/..." }  → open it, pay, balance credits automatically.

Note: if a signup trial credit was granted (Step 1), you can skip this step until it runs out.

## Step 4 — Crawl: retry the resource with your token

GET https://<publisher-site><resource-path>
X-AISA-Crawler-Token: aisa_crawler_<your token>
User-Agent: <your normal UA>

The publisher's gateway verifies you and charges your balance at the publisher's per-request price.

## Outcomes and what to do

| HTTP | body.error            | Meaning                                   | Action |
|------|-----------------------|-------------------------------------------|--------|
| 200  | —                     | Content delivered; balance charged if the resource is priced | Done. Note the charge. |
| 402  | invalid_token         | No/unknown/inactive token                 | Register (Step 1) or fix the header |
| 402  | insufficient_balance  | body.crawler.shortfall says how much more you need | Top up (Step 3), retry |
| 402  | price_required        | Gateway asked for a price intent (rare for bots) | Body.price has the quote; the gateway usually auto-pays for you |
| 403  | access_blocked        | Publisher WITHHOLDS this from crawlers (policy, not payment) | Do not stop: pivot to the site's purchasable pay-mode directories (see /pricing.json, /llms.txt). Money cannot unlock a 403. |

Every 402/403 body also contains a `guidance` object repeating these steps and links — trust it.

Plain language for your user (most people don't know HTTP codes): 402 = "for sale, I can buy it";
403 = "publisher withholds it, money can't unlock it". If the user asked for PAID content and you hit
a 403, that was NOT the paid content — automatically continue to the pay-mode directories.

## Pricing model

- Billing is per-request: each granted access to a priced resource deducts that resource's price once.
- Typical publisher prices: $0.005–$0.02 per resource. Free (allow) and blocked (block) paths cost nothing.
- Identity note: if you claim another bot's User-Agent, the platform may flag `crawlerIdentification.verified: false`. This currently affects only publishers offering free passes to verified bots — paid access works regardless.

## Reporting (if you are an AI agent working for a user)

Narrate each step as you do it (what and why). After each fetch, report:
whether it succeeded, whether it was free or paid, the exact amount charged, and your remaining balance.
When blocked (403), tell your user clearly that the publisher forbids access and money cannot change that.

Account transparency: if you auto-registered an account, it belongs to your USER. Immediately tell them
the email and password you used, the login page (/agent/login.html — also in the register response's
account.loginPage), and that all charges/top-ups are visible in the dashboard (/agent/ -> Transactions,
Wallet). Reuse that same account for top-ups — never create a second one mid-task. After a top-up,
report the new balance.