Accessibility Auditor

WCAG 2.1 accessibility audit service for websites — with pay-per-use via x402 protocol.

Built by a blind developer for blind and low-vision users.

🤖 Telegram Bot: @accessibilityAuditAgentBot | 🌐 Web: hexdrive.tech

GenLayer provenance prototype

This repository is the main Accessibility Auditor service. The GenLayer adjudication prototype lives here: https://github.com/web3blind/genlayer-accessibility-court

The prototype adds an independent GenLayer judgement / provenance layer on top of selected accessibility audit evidence.

What It Does

Audits any website for WCAG 2.1 accessibility compliance. Returns a score (0–100), letter grade (A–F), and detailed issue breakdown across 12 categories:

• Semantic HTML structure
• Image alt text
• Link text quality
• Heading hierarchy
• Form accessibility (labels, IDs)
• Keyboard navigation
• ARIA attributes
• Media captions (video/iframe)
• Contrast ratio
• Language declaration
• Page structure and landmarks
• Responsive design (viewport)

x402 Payment Integration

AI agents and developers can pay per audit via the x402 protocol — no API keys required.

POST https://hexdrive.tech/api/audit/paid
Payment: 0.10 USDC on Base Sepolia (testnet)
Network: eip155:84532
Facilitator: https://x402.org/facilitator

Discovery endpoint:

GET https://hexdrive.tech/api/x402/info

The discovery response also describes the auditor as an ERC-8004 registered agent on Arc Testnet and exposes a simple pay-per-audit model for other agents. Client agents should treat the published price as a spending-policy input: check their maximum price per audit, remaining daily budget, and allowed target domains before submitting payment.

Free audits are available via the web interface only (not via API).

AgentKit Integration

Any AgentKit-powered agent can call this service directly:

from agentkit_action_provider import accessibility_audit_action_provider
from coinbase_agentkit import AgentKit, AgentKitConfig

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider,
    action_providers=[accessibility_audit_action_provider()]
))
# Agent can now call:
# accessibility_paid_audit(
#     url="https://example.com",
#     max_price_usd=0.10,
#     remaining_daily_budget_usd=1.00,
# )

Python client example

from eth_account import Account
from x402.client import x402Client
from x402.http.clients.httpx import x402HttpxClient
from x402.mechanisms.evm.exact.client import ExactEvmScheme
from x402.mechanisms.evm.signers import EthAccountSigner

account = Account.from_key("YOUR_PRIVATE_KEY")
client = x402Client()
client.register("eip155:84532", ExactEvmScheme(signer=EthAccountSigner(account)))

async with x402HttpxClient(client) as http:
    response = await http.post(
        "https://hexdrive.tech/api/audit/paid",
        json={"url": "https://example.com"},
    )
    print(response.json())  # score, grade, issues, report_url

Fortytwo x402Escrow Multi-Page Audits

The public web UI and Telegram bot intentionally stay single-page and free. Multi-page website audits are reserved for Fortytwo x402Escrow-style paid agent flows because the final cost depends on how many pages are discovered and successfully audited.

Discovery / quote:

GET  https://hexdrive.tech/api/x402escrow/info
POST https://hexdrive.tech/api/site-audit/quote

Paid endpoint:

POST https://hexdrive.tech/api/x402escrow/site-audit
X-PAYMENT: <Fortytwo x402Escrow authorization>

Request body:

{
  "url": "https://example.com",
  "max_pages": 30,
  "include_summary": true,
  "same_domain_only": true,
  "max_budget_usdc": "3.30",
  "output_format": "markdown",
  "per_page_timeout_seconds": 45,
  "max_duration_seconds": 600
}

Safety boundaries:

• hard cap: 100 pages;
• same-domain only;
• dangerous/private paths such as logout, admin, checkout, payment and account pages are skipped;
• per-page timeout and whole-job timeout prevent hanging scans;
• pages that fail before a report is produced are not billed;
• Markdown output is available for agents at /site-audits/{site_audit_id}.md and /api/site-audits/{site_audit_id}/markdown.

If the endpoint is called without X-PAYMENT, it returns HTTP 402 with the payment requirements. Local dry-run requests can be enabled only by the operator with X402ESCROW_ALLOW_DRY_RUN_REQUESTS=1; production should leave that off.

Live settlement is wired behind explicit env switches. To activate it, configure:

export X402ESCROW_LIVE=true
export X402ESCROW_NETWORK=base        # or monad
export X402ESCROW_RPC_URL="..."
export X402ESCROW_FACILITATOR_PRIVATE_KEY="..."
# optional override if Fortytwo changes/deploys a different proxy:
export X402ESCROW_CONTRACT_ADDRESS="0x9562f50f73d8ee22276f13a18d051456d8d137a0"

Before enabling production traffic, verify the configured wallet:

GET https://hexdrive.tech/api/x402escrow/facilitator-status

The address must have FACILITATOR_ROLE on the configured Fortytwo contract; otherwise settle() / release() will revert and the service must not run the multi-page job. Fortytwo docs say DEFAULT_ADMIN_ROLE can grant/revoke facilitators. If this deployment is not the contract admin, request the role from Fortytwo or deploy an owned escrow instance.

Access

Telegram Bot

Send any URL to @accessibilityAuditAgentBot:

/start              — welcome and help
https://example.com — send a URL to audit

Web Interface

Open https://hexdrive.tech, enter a URL and click Analyze. Results appear at https://hexdrive.tech/audits/<audit_id>.

How It Works

1. Request arrives via Telegram, web form, or paid API (/api/audit/paid).
2. For paid requests: x402 middleware intercepts, requires 0.10 USDC payment via EIP-3009.
3. On payment confirmation: headless Chromium (Playwright) fetches the full page.
4. BeautifulSoup runs 12 accessibility checks.
5. Score + HTML report generated, returned immediately for paid requests.

For agentic workflows, the intended control pattern is deliberately simple: ERC-8004 identity for discoverability, x402 settlement for one audit, and client-side spending limits before payment.

Tech Stack

• Python 3.12 / FastAPI / Uvicorn
• Playwright — headless Chromium for full page rendering
• BeautifulSoup4 — HTML parsing and accessibility checks
• x402 (pip install x402[evm,fastapi]) — HTTP payment protocol
• python-telegram-bot 20.x — Telegram integration
• nginx — reverse proxy with TLS
• coinbase-agentkit — AgentKit action provider

Installation

git clone https://github.com/web3blind/accessibility-auditor.git
cd accessibility-auditor
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium

Configure

export TELEGRAM_BOT_TOKEN="your_token"
export X402_SERVER_ADDRESS="your_wallet_address"   # receives payments
# Optional:
export X402_NETWORK="eip155:84532"                 # default: Base Sepolia
export X402_FACILITATOR_URL="https://x402.org/facilitator"

Run

python3 bot_final.py

Starts Telegram bot + FastAPI server on http://localhost:3000.

File Structure

accessibility-auditor/
├── bot_final.py                  # Telegram bot + FastAPI server + x402 middleware
├── agentkit_action_provider.py   # AgentKit action provider for AI agents
├── auditor.py                    # Core WCAG 2.1 checks
├── fetch_page.py                 # Playwright subprocess page fetcher
├── storage.py                    # Audit result persistence
├── report_generator.py           # HTML report generator
├── requirements.txt
├── nginx.conf
└── keep-alive.sh

API Reference

Endpoint	Method	Auth	Description
/api/audit/paid	POST	x402 (0.10 USDC)	Single-page audit, returns JSON immediately
/api/x402escrow/site-audit	POST	Fortytwo x402Escrow	Multi-page metered audit, JSON/Markdown result
/api/site-audit/quote	POST	none	Quote max budget for a multi-page paid audit
/api/x402/info	GET	none	Payment discovery info for agents
/api/x402escrow/info	GET	none	Fortytwo x402Escrow multi-page discovery
/api/audit	POST	none*	Submit single-page audit (web UI only)
/api/audit/{id}/status	GET	none	Poll audit status + result
/audits/{id}	GET	none	Single-page HTML report
/site-audits/{id}	GET	none	Multi-page HTML report
/site-audits/{id}.md	GET	none	Multi-page Markdown report for agents

*Free endpoint checks Referer: hexdrive.tech — not available for external API calls.

Security

• No secrets in repository — wallets_x402.json, .env, config.json are all gitignored
• Audit results stored locally, not public by default
• All input validated before processing

---

Built with Hermes Agent · Real problem. Real solution.