Skip to main content
The 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

Requires Python 3.12 or later.

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 the Origin 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:
A 402 response means the domain is now set. Until it is set, gate requests fail with 409 and the middleware lets bots through.

Pattern 1: Site-wide middleware

Parameters

Always pass api_base="https://api.xenarch.dev". The default https://xenarch.dev redirects to the homepage, every API call fails, and the middleware then serves bots for free.

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

  1. If the request carries X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash, the middleware calls POST /v1/gates/{gate_id}/verify with the transaction hash. On success it serves the route and caches the pair for cache_ttl_s seconds.
  2. Otherwise it checks the User-Agent against the AI crawler names in xenarch/detection.py (GPTBot, ClaudeBot, PerplexityBot, CCBot and others). Anything else, including browsers, passes through.
  3. For a matched bot it calls POST /v1/gates with the request path and returns the platform’s response with status 402.
The 402 body is an x402 version 1 envelope (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 (xenarch 1.1.0 on PyPI) accepts only the X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash headers as proof of payment.

Testing

Full example

See the FastAPI publisher example for a complete app.