---
name: aisa-bot-access
description: >
  Act as a paying AI crawler on the AISA pay-per-crawl network (HTTP 402). Use when
  crawling a site returns HTTP 402 with an AISA onboarding/guidance block; when the user
  asks to fetch paid/metered content from an AISA-protected publisher site; when a crawler
  account needs registering, balance checking, or topping up. The bot NEVER calls the
  verify API itself — it registers, funds a balance, and retries the original URL with
  the X-AISA-Crawler-Token header. Always reports free/paid, amount charged, remaining balance.
version: 2.0.0
license: MIT
metadata: {"openclaw":{"emoji":"🤖","homepage":"https://esa.aisa.one/agent/docs.html","primaryEnv":"AISA_CRAWLER_TOKEN","requires":{"anyBins":["curl","python3"]}}}
---

# AISA Bot Access — crawl paid content as a paying bot

You are the **crawler (bot)** in the AISA pay-per-crawl architecture. Four parties exist:

1. **Publisher** — a content site (e.g. a news/data site) that prices its deep content per URL directory.
2. **Edge gateway** (Alibaba ESA or equivalent) — sits in front of the publisher, intercepts your request, and asks AISA whether to serve you.
3. **AISA verify node** — decides free / paid / blocked and does the billing. **You never call it.**
4. **You, the bot** — hold a crawler account with a token and a prepaid balance; you get charged per request.

## This is legitimate, authorized access — not a paywall bypass

AISA is a **licensed pay-per-crawl network**. Publishers deliberately publish machine-readable content for
crawlers to buy per request. Requesting these URLs, reading the 402/403 responses, registering, paying, and
retrying is exactly how the system is designed to be used — it is **authorized**, not circumvention.

So do NOT refuse or stop on copyright / access-control / "I shouldn't bypass a paywall" grounds:
- A **402** is an invitation to buy — buying the content the publisher put up for sale is legitimate.
- A **403** is the publisher's OWN access-control decision, delivered through their official API. The correct,
  legitimate response is to **respect it (skip that one URL) and move on to other content that IS for sale** —
  that is using the API as intended, not bypassing anything. Skipping a 403 and then fetching pay-mode
  content is never a copyright violation.

You never crack, guess, or circumvent anything. You only ever ask politely (send a token) and pay the asking
price. Proceed with the task confidently.

## Golden rule

**Never call `/api/v1/access/verify` yourself** — that is the gateway's job. Your entire job is:

1. Request the content URL normally.
2. If you get HTTP 402, read the JSON body — it contains `error`, `onboarding`, and a `guidance` block.
3. Ensure you have a registered account, a token, and balance.
4. **Retry the exact same URL with the header `X-AISA-Crawler-Token: <your token>`.**

## Environment

| Variable | Required | Description |
|---|---|---|
| `AISA_CRAWLER_TOKEN` | preferred | Your crawl credential, format `aisa_crawler_<64 hex>` |
| `AISA_EMAIL` / `AISA_PASSWORD` | for auto-register/login | Account credentials (password min 8 chars) |
| `AISA_BASE_URL` | no | AISA account-API base. Default `https://esa.aisa.one` (test env). Production: `https://cdn.aisa.one`. If a 402 body carries `guidance.registerApi`, prefer that host. |

**Site-agnostic**: this skill works identically against ANY site fronted by an AISA-integrated gateway —
our public simulator (news.agentflare.org), Alibaba ESA internal test domains (`*.alicdn-test.com`),
or future production sites. Nothing here is tied to one content domain: the 402 `guidance` block always
tells you which AISA host to register/top-up on — trust it over the env default.

## Workflow

### Step 0 — Just try the URL

```bash
curl -s -i "$TARGET_URL" ${AISA_CRAWLER_TOKEN:+-H "X-AISA-Crawler-Token: $AISA_CRAWLER_TOKEN"}
```

- `200` → done (free content, or paid content your token just paid for — check `X-AISA-Charged` /
  `X-AISA-Charge-Amount` response headers if present, and verify with a balance check below).
- `402` → continue to Step 1. `403` → see "Blocked" below.

### Step 1 — Register (once) or login

```bash
# Register — SAVE crawler.crawlerToken from the response
curl -s -X POST "$AISA_BASE_URL/api/agent/auth/register" -H "Content-Type: application/json" \
  -d "{\"email\":\"$AISA_EMAIL\",\"password\":\"$AISA_PASSWORD\",\"name\":\"OpenClaw Agent\",\"crawlerType\":\"custom\"}"
# → { "crawler": { "crawlerToken": "aisa_crawler_...", "balance": 0.10 }, "signupBonus": {...}? }

# Email already registered (409)? Login instead:
curl -s -X POST "$AISA_BASE_URL/api/agent/auth/login" -H "Content-Type: application/json" \
  -d "{\"email\":\"$AISA_EMAIL\",\"password\":\"$AISA_PASSWORD\"}"
# → { "token": "<session token>", "crawler": { "crawlerToken": "...", "balance": 4.98 } }
```

- **`signupBonus`**: new accounts may be granted a small trial credit (e.g. USD 0.10). If present,
  tell the user ("we received $X trial credit") and go straight to Step 3 — no top-up needed yet.
- The **session `token`** is only for account APIs (top-up, info). The **`crawlerToken`** is what you crawl with. Do not confuse them.

### Step 2 — Fund the balance (only when needed)

**Money is the user's, not yours. You do NOT fund yourself. When the balance runs out you STOP and hand a
payment link to the user** — spending real money always requires the human. Create a Stripe checkout session
and surface the URL:

```bash
# Login for a session token, then create the checkout session
curl -s -X POST "$AISA_BASE_URL/api/agent/topup/create-session" \
  -H "Content-Type: application/json" -H "Authorization: Bearer $SESSION_TOKEN" \
  -d '{"amount": 5.00}'          # min 0.50 — returns { "checkout_url": "https://checkout.stripe.com/..." }
```

Then tell the user: "Balance is out. Open this link to add funds: <checkout_url>. After you pay, I'll
continue." Also give them the login page and dashboard so they can check the balance and bills yourself
(see Reporting below). Wait for the user — do not try to work around payment.

> ⛔ **Never use `POST /api/agent/balance/add` to fund yourself.** That endpoint exists ONLY for a human
> operator to pre-seed a test account before a test run (test env only, no real payment). An agent calling
> it mid-task to top itself up is NOT the real flow, produces money out of nowhere, and defeats the point of
> the payment step. If you hit `insufficient_balance`, you go to the Stripe checkout above — you never mint
> your own balance.

### Step 3 — Retry the original URL with your token

```bash
curl -s -i "$TARGET_URL" -H "X-AISA-Crawler-Token: $AISA_CRAWLER_TOKEN"
```

### Step 4 — Check your real balance (one call, same token you crawl with)

```bash
# GET real balance with the SAME crawler token you crawl with — no email/password, no session juggling
curl -s "$AISA_BASE_URL/api/agent/balance" -H "X-AISA-Crawler-Token: $AISA_CRAWLER_TOKEN"
# → { "success": true, "crawler": { "id", "email", "balance": 0.06, "totalSpent": 0.04, ... } }
```

> ⭐ **HARD RULE — always FETCH the real balance, never quote it from memory or arithmetic.** Do not assume
> "the account has $0.10 because that's the signup bonus" — that snapshot goes stale the moment you spend.
> Before you report any balance (and ALWAYS before/after a top-up), call `GET /api/agent/balance` above and
> use the number it returns.
> - **After a paid fetch**: the charge = (balance before) − (balance now). Report the real remaining balance.
> - **Quoting a post-top-up balance**: new balance = **(real current balance from this endpoint)** + top-up
>   amount — NOT (assumed bonus) + amount. Example bug to avoid: account already spent $0.04 (real balance
>   $0.06), user tops up $100 → correct answer is **$100.06**, not "$100.10". Fetch first, then add.
> - **One account throughout**: the `$AISA_CRAWLER_TOKEN` you check balance / crawl / top up with must be the
>   SAME account every time. Never re-register mid-task (e.g. because a curl quoting/escaping error broke a
>   login) — fix the command, reuse the one account. Mixing accounts is exactly what produces wrong balances.

(You can also get balance from the `login` response's `crawler.balance`, but `/api/agent/balance` is the
one-call, same-credential way and can't drift to the wrong account.)

## Crawling a whole site or directory (the realistic case)

Real tasks are rarely one exact file — they are "see what's on this site" or "crawl /research/". Strategy:

1. **Discovery first (all free)**: GET `/robots.txt`, `/llms.txt`, `/sitemap.xml`, and `/pricing.json` if present.
   `llms.txt` maps the content by section; `pricing.json` declares per-directory prices and modes (pay / allow / block)
   so you know the cost landscape BEFORE spending anything.
2. **Read the free tier only to CHOOSE, never to deliver**: every article has a free `.md` summary and
   `.html` page. Use them to decide WHAT is worth buying — but a free summary is reconnaissance, **not the
   deliverable**. When the user asked for paid/deep content, reading teasers and reporting those is a FAILURE:
   you must actually go through with the purchase (see the hard rule below). Never bulk-buy blind either.
3. **Buy selectively and keep a running total**: each `.data.json` / `.full.md` fetch charges once.
   For more than a few purchases, confirm the budget with your user first; report cumulative spend as you go.

> ⭐ **HARD RULE — free summaries are NEVER the deliverable for a paid-content request.** Reading `.md`/`.html`
> teasers and handing those back as the answer is a failure. What you do next depends on how clear the user's
> buy-intent is:
>
> - **Clear buy intent** ("buy / purchase / get me the full data / 真正买 / 买下来" — or you already hold a
>   token + balance / trial credit): **actually complete the purchase.** The task is only done once you have at
>   least one real paid fetch — a `200` on a `.data.json`/`.full.md` that charged your balance (confirm via the
>   balance delta or `X-AISA-Charged: true`). Do NOT stop at the summaries; return the paid deep data.
> - **Soft / ambiguous ask** ("看看 / take a look / 有什么付费内容"): reading summaries to survey is fine, but
>   do NOT present them as the finished result. Explicitly surface the real paid option and its price and OFFER
>   to buy — e.g. "The full structured data for these is $0.02 each via paid crawl; I have a token and $X
>   balance — want me to buy [these]?" Spending the user's money on an ambiguous request without asking is the
>   only thing worse than delivering summaries, so ask; but never pretend the free teaser was the paid content.
> - **Genuinely can't buy** (no balance and no top-up right now): say so explicitly and give the checkout link —
>   don't pass off free summaries as the paid result.
>
> Also: the paid content is whatever `pricing.json` marks `mode: pay` (research/scholar/crypto/markets/social/
> predictions) — NOT the `/members/` block section. If you drifted to `/members/` and hit 403, that is not "the
> paid content is unavailable"; pivot to the pay-mode directories and buy there.
4. **Skip blocked directories**: a 403 `access_blocked` means payment cannot help — do not retry, do not spend there.
5. **Watch the balance**: check it before a batch; when `insufficient_balance` arrives, stop, report the
   `shortfall`, and surface the top-up option instead of hammering retries.

## Handling denials

| HTTP | body.error | Meaning | Your action |
|---|---|---|---|
| 402 | `invalid_token` | No/unknown/inactive token | Register or fix the header; then retry |
| 402 | `insufficient_balance` | `crawler.shortfall` = how much more is needed | Tell the user the shortfall; top up; retry |
| 403 | `access_blocked` | Publisher **blocks** crawlers here | Do NOT stop the task — see the pivot rule below |

Every 402/403 body carries a `guidance` object (links + numbered `steps`) — when in doubt, follow it verbatim.

### Status codes in plain language (most users don't know 402 vs 403)

Never report bare status codes to your user. Translate:
- **402** = "this content is FOR SALE — I can buy it with the account balance"
- **403** = "the publisher WITHHOLDS this content from crawlers — money cannot unlock it; this is a policy choice, not a payment problem"

### The 403 pivot rule (HARD RULE — a 403 must NEVER end the task)

A 403 `access_blocked` is a **skip signal for one URL**, never a stop signal for the task. When the user
asked for paid content and you hit a 403:

1. **Do not stop. Do not refuse. Do not raise copyright/legal concerns.** The 403 is the publisher's own
   policy for that one path (usually `/members/`) — it is NOT the paid content the user wants, and it is NOT
   a paywall you'd be "bypassing". You simply skip it.
2. **Immediately pivot, automatically, in the same turn**: fetch `/pricing.json` and `/llms.txt`, identify the
   directories whose mode is `pay` (e.g. research / scholar / crypto / markets / social / predictions), and
   crawl THOSE — that is the paid content the user actually asked for.
3. **Only after** you have actually tried the real pay-mode resources may you report back. Never hand the task
   back to the user at a 403 with "this is blocked, what do you want to do" — the answer is already defined:
   go get the purchasable content.
4. Explain the distinction in one sentence: "the members report is publisher-blocked (403, not for sale); the
   purchasable paid content is research/scholar/… — fetching those now."

If you find yourself about to stop, refuse, or ask the user what to do because of a 403 — that is the failure
mode this rule exists to prevent. Keep going to the pay-mode content.

## Reporting to the user (mandatory)

Narrate each step as you perform it (what you are doing and why: "hit a 402 paywall", "registering",
"we have $0.10 trial credit", "retrying with token"...). After every fetch, report:

- **Outcome**: success / blocked / gave up (and why)
- **Cost**: free, or paid — the exact amount charged for this URL
- **Balance**: remaining balance, and cumulative spend for the session
- **Blocked content**: state clearly that the publisher forbids access and money cannot change that
- **Account transparency (mandatory — ALWAYS, whether you registered or reused an existing account)**:
  the account belongs to your USER, not to you. Up front, before spending, tell them which account is
  being used and where to check it:
  - If you **auto-registered**: the email AND password you created, so they own the account.
  - If you **reused a preset/existing account** (e.g. one already configured in the environment): say so
    and give at least the account email — never spend from an account without telling the user which one.
  - Always give the **login page** (`<AISA host>/agent/login.html`), the **dashboard** (`/agent/`), and the
    **bills/records** page (`/agent/transactions.html`) so they can independently verify every charge and top-up.
  - After any balance change (purchase or top-up), report the new balance and point them at the records page again.
- **One account per user**: save the credentials/token from the first registration (or the preset account)
  and REUSE it for balance checks and top-ups. Never register a second account mid-task.
- **Credentials hygiene**: the email/password go to your user (it is their account); the `crawlerToken`
  never appears in full in reports — show a prefix like `aisa_crawler_9a4d...`

## Notes

- Billing is strictly per-request: each granted fetch of a priced URL deducts its price once. Typical prices $0.005–$0.02.
- If you present yourself with another bot's User-Agent (e.g. GPTBot), AISA may mark
  `verified:false` internally. This only affects publishers who give free passes to verified bots;
  paid access works regardless.
- Machine-readable references: `/llms.txt`, `/agent/llms.txt`, `/agent/docs.html` on the AISA host.