Skip to main content
Full Joomla 5.x package with admin dashboard, bot detection, and payment gating.

​
Requirements

  • Joomla 5.0+
  • PHP 8.1+
  • MySQL 8.0+

​
Installation

  1. Download pkg_xenarch.zip from the releases page
  2. Go to System → Install Extensions in your Joomla admin panel
  3. Upload pkg_xenarch.zip
The installer creates the required database tables and configures HTTP headers automatically.

​
What gets installed

The package contains three extensions:
ExtensionTypePurpose
com_xenarchComponentAdmin dashboard + REST API
plg_system_xenarchSystem PluginBot detection + payment gating
plg_webservices_xenarchWeb Services PluginAPI route registration

​
Configuration

After installation, go to Components → Xenarch to open the dashboard.

​
Onboarding flow

  1. Register — create your publisher account
  2. Add site — link your Joomla site to the Xenarch platform
  3. Set payout wallet — enter your Base/Ethereum address for USDC payouts

​
Settings

SettingDefaultDescription
default_price$0.003Price per page in USD
gate_enabledYesMaster toggle for payment gating
gate_unknown_trafficYesGate non-browser traffic
payout_wallet—Your Base address for payouts

​
Bot category policies

Control how each type of AI traffic is handled: 
{
  "ai_search": "allow",
  "ai_assistants": "charge",
  "ai_agents": "charge",
  "ai_training": "charge",
  "scrapers": "charge",
  "general_ai": "charge"
}

​
Per-bot overrides

Override the category default for specific bots: 
{
  "GPTBot": "allow",
  "ClaudeBot": "charge"
}

​
Pricing rules

Set different prices for specific paths: 
[
  { "path_contains": "/premium/", "price_usd": 0.01 },
  { "path_contains": "/research/", "price_usd": 0.005 }
]

​
How it works

​
Request flow

  1. Skip — logged-in users, static assets, and /.well-known/* paths always pass through
  2. Check token — if the request has a valid Authorization: Bearer <token>, allow it
  3. Detect bot — match User-Agent against 100+ known AI bot signatures, then score headers
  4. Apply policy — check per-bot override, then category default
  5. Respond — allow (200), challenge (403 + browser proof), or gate (402 + payment payload)

​
Discovery documents

The plugin automatically serves:
  • /.well-known/pay.json — machine-readable pricing for AI agents
  • /.well-known/xenarch.md — human-readable payment instructions

​
Bot detection

Detection runs in priority order:
  1. Signature match — 100+ known AI bot User-Agent strings
  2. Trusted search crawlers — Googlebot, Bingbot, etc. (always allowed)
  3. HTTP client signatures — python-requests, curl, wget, Go-http-client
  4. Browser proof cache — valid proof cookie from a previous challenge
  5. Header scoring — missing Accept, Accept-Language, Sec-Fetch-* headers increase suspicion score

​
Build from source

cd xenarch-plugins/joomla
./scripts/build-release.sh
# Output: src/packages/pkg_xenarch.zip

​
Local development

cd xenarch-plugins/joomla
docker compose up -d
# Joomla 5.4 + MySQL 8 at localhost:8889
Source files are mounted as volumes for live development.

​
Admin UI development

The dashboard is a React + TypeScript app: 
cd xenarch-plugins/joomla/admin-ui
npm install
npm run build
Build output goes to src/media/com_xenarch/js/ and src/media/com_xenarch/css/.