Agent Integration Guide

# Step 1: Register — SAVE crawler.crawlerToken from the response
curl -s -X POST "https://cdn.aisa.one/api/agent/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "mybot@example.com",
    "password": "MySecurePass123",
    "name": "MyBot",
    "crawlerType": "custom"
  }'
# → { "crawler": { "crawlerToken": "aisa_crawler_...", "balance": 0.10 }, "signupBonus": {...}? }
# Trial credit present? Skip straight to Step 3.

# Step 2: Top up when needed (returns a Stripe checkout URL — open it to pay)
curl -s -X POST "https://cdn.aisa.one/api/agent/topup/create-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SESSION_TOKEN_FROM_REGISTER_OR_LOGIN" \
  -d '{ "amount": 5.00 }'

# Step 3: Crawl any AISA-protected publisher URL — one extra header
curl "https://PUBLISHER-SITE/research/report.data.json" \
  -H "X-AISA-Crawler-Token: aisa_crawler_..." \
  -A "MyBot/1.0 (+https://example.com/bot)"

# Step 4: Verify what it cost
curl -s -X POST "https://cdn.aisa.one/api/agent/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "mybot@example.com", "password": "MySecurePass123" }'
# → crawler.balance

curl -s -X POST "https://cdn.aisa.one/api/agent/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bot@example.com",
    "password": "SecurePass888",
    "name": "MySearchBot",
    "crawlerType": "custom",
    "userAgent": "MySearchBot/1.0",
    "companyName": "Acme AI Labs"
  }'

{
  "success": true,
  "token": "eyJjcmF3bGVySWQ...",       // Session token (account APIs / dashboard — NOT for crawling)
  "crawler": {
    "id": 42,
    "crawlerUuid": "crawler-a1b2c3d4-1712345678",
    "email": "bot@example.com",
    "name": "MySearchBot",
    "crawlerType": "custom",
    "crawlerToken": "aisa_crawler_abc123def456...",  // Your crawl credential — store securely
    "balance": 0.10,                                 // non-zero when a signup trial credit is active
    "totalSpent": 0
  },
  "signupBonus": {                                   // present only when a trial credit is active
    "amount": 0.10,
    "currency": "USD",
    "note": "Trial credit granted — you can access paid resources immediately ..."
  }
}

curl -s -X POST "https://cdn.aisa.one/api/agent/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "bot@example.com", "password": "SecurePass888" }'
# → { "token": "<session>", "crawler": { "crawlerToken": "...", "balance": 4.98 } }

# Real balance — ONE call, SAME crawler token you crawl with (no email/password, no session):
curl -s "https://cdn.aisa.one/api/agent/balance" \
  -H "X-AISA-Crawler-Token: aisa_crawler_YOUR_TOKEN"
# → { "success": true, "crawler": { "id": 123, "email": "...", "balance": 0.06, "totalSpent": 0.04, ... } }
# (also available in every login response's crawler.balance, or GET /api/agent/info with a session token)

# Top up via Stripe (minimum 0.50 USD)
curl -s -X POST "https://cdn.aisa.one/api/agent/topup/create-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -d '{ "amount": 5.00 }'
# → { "checkout_url": "https://checkout.stripe.com/..." }
#   open it, pay, balance credits automatically

GET https://PUBLISHER-SITE/any/path
X-AISA-Crawler-Token: aisa_crawler_YOUR_TOKEN
User-Agent: YourBot/1.0 (+https://example.com/bot)

{
  "accessGranted": false,
  "statusCode": 402,
  "error": "invalid_token",
  "message": "No crawler token provided. Send your registered token in the X-AISA-Crawler-Token header ...",
  "onboarding": "https://cdn.aisa.one/agent/guide.html",
  "guidance": {
    "onboarding":  ".../agent/guide.html",
    "docs":        ".../agent/docs.html",
    "llmsTxt":     ".../llms.txt",
    "skill":       ".../agent/skill.md",
    "registerApi": "POST .../api/agent/auth/register {\"email\",\"password\",\"name\",\"crawlerType\"}",
    "steps": [ "1. Register ...", "2. Already registered? ...", "3. trial credit / top up ...",
               "4. Retry this exact URL with header X-AISA-Crawler-Token" ],
    "signupBonus": "New accounts receive USD 0.10 free trial credit ...",   // present only when active
    "agentAdvice": "If you are an AI agent: narrate these steps to your user ... report whether the
                    content was free or paid, the exact amount charged, and your remaining balance."
  },
  "rule": { "urlPattern": "^/research/.*", "accessMode": "pay", "price": 0.02,
            "currency": "USD", "billingType": "per-request" },
  "crawlerIdentification": { "recognized": true, "identifier": "gptbot", "verified": true }
}

import requests, os

BASE  = os.getenv("AISA_BASE_URL", "https://cdn.aisa.one")   # account APIs; prefer the host from 402 guidance
TOKEN = os.getenv("AISA_CRAWLER_TOKEN")
UA    = "MyCrawler/1.0 (+https://example.com/bot)"

def ensure_account(email, password):
    """Register (or login) and return (crawler_token, balance)."""
    r = requests.post(f"{BASE}/api/agent/auth/register", json={
        "email": email, "password": password, "name": "My Crawler", "crawlerType": "custom"})
    if r.status_code == 409:
        r = requests.post(f"{BASE}/api/agent/auth/login", json={"email": email, "password": password})
    d = r.json()["crawler"]
    return d["crawlerToken"], float(d["balance"])

def crawl(url, token):
    """Fetch a publisher URL; returns (status, body_or_denial_json, charged_amount)."""
    r = requests.get(url, headers={"X-AISA-Crawler-Token": token, "User-Agent": UA})
    charged = float(r.headers.get("X-AISA-Charge-Amount", 0) or 0)
    if r.status_code == 200:
        return 200, r.content, charged
    d = r.json()                       # denial bodies are JSON
    if d.get("error") == "insufficient_balance":
        print(f"[AISA] need ${d['crawler']['shortfall']} more — top up, then retry")
    elif d.get("error") == "access_blocked":
        print("[AISA] publisher blocks this resource; paying will not help — skipping")
    elif d.get("error") == "invalid_token":
        print("[AISA] token rejected — follow d['guidance']['steps']")
    return r.status_code, d, 0.0

const BASE  = process.env.AISA_BASE_URL || "https://cdn.aisa.one";
const TOKEN = process.env.AISA_CRAWLER_TOKEN;

async function crawl(url) {
  const r = await fetch(url, { headers: {
    "X-AISA-Crawler-Token": TOKEN,
    "User-Agent": "MyCrawler/1.0 (+https://example.com/bot)",
  }});
  if (r.ok) {
    return { ok: true, charged: Number(r.headers.get("x-aisa-charge-amount") || 0), body: await r.text() };
  }
  const denial = await r.json();          // { error, guidance, crawler?.shortfall, ... }
  return { ok: false, status: r.status, denial };
}