xenarch Python package ships two ways to gate a FastAPI app: site-wide ASGI middleware and a per-route decorator. Both charge AI bots and let every other request through. Prices come from your site’s pricing in the Xenarch dashboard, not from code.
Installation
Prerequisites
- A site in the Xenarch dashboard and its site token (
st_...). See the publisher quickstart. - A receiving wallet on your account. The wallet you sign in to the dashboard with is used by default.
- The site domain set on the platform (see below).
Set the site domain once
Sites added in the dashboard start without a domain. The platform fills it in from theOrigin or Referer header of the first gate request. The middleware calls the API server to server and sends neither header, so set the domain once yourself:
Pattern 1: Site-wide middleware
Parameters
Pattern 2: Per-route decorator
require_payment(site_token, api_base="https://xenarch.dev", cache_ttl_s=300.0) takes the same settings as the middleware.
The decorated function must accept a
request: Request parameter. Without it the decorator cannot read headers and serves the route ungated.How it works
- If the request carries
X-Xenarch-Gate-IdandX-Xenarch-Tx-Hash, the middleware callsPOST /v1/gates/{gate_id}/verifywith the transaction hash. On success it serves the route and caches the pair forcache_ttl_sseconds. - Otherwise it checks the
User-Agentagainst the AI crawler names inxenarch/detection.py(GPTBot, ClaudeBot, PerplexityBot, CCBot and others). Anything else, including browsers, passes through. - For a matched bot it calls
POST /v1/gateswith the request path and returns the platform’s response with status 402.
x402Version and accepts) plus Xenarch fields (gate_id, price_usd, seller_wallet, facilitators, verify_url, expires). See Create Gate.
Things to know:
- The middleware does not apply the dashboard’s bot-category toggles. Every matched bot is charged. Use the WordPress, Joomla, or Cloudflare integrations if you need per-category control.
- If the Xenarch API cannot be reached, the request is served (fail open).
- The verification cache lives in each worker process.
- The published package (
xenarch1.1.0 on PyPI) accepts only theX-Xenarch-Gate-IdandX-Xenarch-Tx-Hashheaders as proof of payment.