Developer Docs · For agent builders
One POST returns a verified, excerpt-cited answer from any page at 95–99% fewer tokens than scraping — and it cannot hallucinate. Five questions a day to evaluate; $0.01 per answered question over x402; only answered ever bills.
Every IP gets five answered questions a day to evaluate — no key needed, and only answered counts. Past that, pay per answer over x402 (login-less) or use a key. (Or try it in the browser on the product page.)
Request fields: url (required, https), question (required, ≤500 chars), max_tokens (optional, 1–2000, default 800), freshness (optional: 1h | 24h | 7d | any — how stale a cached snapshot may be).
Every outcome is HTTP 200 with the same JSON shape, distinguished by state — an agent parses one contract:
| state | Meaning |
|---|---|
| answered | Grounded answer (confidence: high) or verified excerpts only (medium). The ONLY state that ever bills or spends quota. |
| not_found | The answer isn't in the source — with a not_found_reason saying why (see below). Never a guess. |
| already_efficient | The page is already token-lean; fetch it yourself via the returned direct_url. |
| payment_required | The page returned HTTP 402 — a price, not a block. The x402 quote comes back in payment and source_cost_usd. |
| unreachable | Policy block (robots/no-AI signals), HTTP error, or timeout — with a reason. |
A not_found always says why via not_found_reason, and returns sources showing exactly which page was read:
| not_found_reason | Meaning |
|---|---|
| content_thin | The page had almost no readable text — usually a JavaScript-rendered SPA (the gateway doesn't execute JS). Try a docs/markdown URL for the same content. |
| unverifiable | The extractor proposed excerpts but none survived verbatim verification — rejected rather than risk a fabrication. |
| not_in_content | The page had substantial readable content and it simply doesn't answer the question. Point the gateway at a different page of the site. |
Every response carries a token-economics receipt — audit what the page would have cost raw, what was delivered, what you saved, what you paid, and what the source itself charged:
| receipt.* | Meaning |
|---|---|
| raw_tokens_at_source | What the page would cost an agent to fetch raw. |
| tokens_delivered | What the gateway actually returned. |
| reduction | Percentage saved, source → delivered. |
| est_tax_avoided_usd | The saving in dollars at the published reference rate (price_basis). |
| fee_usd | What you paid the gateway for this call — $0.01 on the paid route's answered responses, 0 otherwise. |
| source_cost_usd | What the SOURCE page itself charged (x402 402 quote or settled payment) — the paid web, itemized. |
| route | How the page was read: llms_txt | markdown_negotiation | openapi | html_distill. |
| cache | answer_hit | snapshot_hit | miss — repeats are served from cache at near-zero cost. |
Aggregated, these receipts are the Agent Tax Index — the public record of what the web costs agents to read.
| Method | Path | Description |
|---|---|---|
| POST | /api/answer | The direct endpoint. JSON body {"url","question"} → a grounded, excerpt-verified answer with a token receipt. Five answered questions/day per IP to evaluate, or a Bearer key. Returns 402 with x402 requirements when the allowance is spent. |
| POST | pay.botvisibility.com/api/v1/answer-gateway | Pay per answer — $0.01 USDC over x402 on Solana. HTTP 200 only for state=answered (that settles the payment); every other state returns 422 with the full result body and does NOT settle. |
| POST | pay.botvisibility.com/api/v1/answer-keys | Buy a prepaid key — $5.00 USDC once → a bvag_ Bearer key with 1,000 answered-question credits ($0.005/answer). The raw key is shown exactly once. |
Three tiers, one rule — only answered ever bills: a question the source can't answer costs nothing, on every tier.
When the daily allowance is spent, POST /api/answer returns HTTP 402 with a machine-readable x402 challenge (accepts[] + a key_offer) pointing at both paid paths. The billing rule is enforced by the protocol, not promised: the paid route returns 200 only for answered, and an x402 settlement completes only on 200.
A deterministic verifier checks every excerpt is a character-for-character span of the fetched page and that the composed answer stays inside what the excerpts support — including negation. Verification failure returns not_found, never a guess. A 40-case golden set gates every deploy at 100% grounded, zero fabrications — read the grounding report.
Try it in the browser — no key, no signup.
Ask any page a question