xenarch package on PyPI (version 1.1.0, MIT license) covers both sides of a payment:
Installation
Requires Python 3.12 or later.x402 extra installs x402-agent 0.2 and pay.json.
Paying: xenarch.x402
pay() requests the URL and acts on the response:
- Not a 402. Returns
{"status": "no_payment_required", "url", "http_status", "body"}. - A Xenarch 402 (the body has
xenarch: true, agate_idandfacilitators). Signs an EIP-3009 USDC authorization to the seller’s wallet, settles it through a facilitator from the gate’s list, then retries the URL withX-Xenarch-Gate-IdandX-Xenarch-Tx-Hash. - Any other x402 402. Signs the payment and retries against that server with the payment header its x402 version expects.
error key, for example budget_exceeded (with reason set to max_per_call or max_per_session), control_plane_daily_cap, control_plane_unreachable or no_facilitator_settled. pay() does not raise on payment errors.
XenarchPayer arguments
Without a token, the payer skips the platform preflight and only
budget_policy limits spending. Use one payer per concurrent payment.
Agent framework tools: xenarch.tools
Each tool is named
xenarch_pay, takes one input (url), and returns the payer’s result as a JSON string. All four take private_key and budget_policy like XenarchPayer.
See LangChain and CrewAI for complete agents.
Getting paid: xenarch.merchant
MerchantClient calls the same API as the dashboard. It authenticates with the wallet session from xenarch agent login and signs new pay links with the merchant wallet’s key.
links.create and links.revoke raise ConfirmationRequired unless you pass confirm=True or build the client with require_confirm=False. links.create raises PayLinkValidationError with the missing fields if the params are incomplete. The create response holds the link’s webhook secret once.
To build the client without the CLI, pass the values yourself: MerchantClient(session_token, private_key="0x...", api_base="https://api.xenarch.dev"). See Pay links for the params a link takes.
Webhooks: xenarch.webhooks
verify checks the t=<unix>,v1=<hex> header in constant time and rejects timestamps older than 300 seconds (tolerance_seconds). It returns False on failure, or raises WebhookVerificationError if you pass raise_on_failure=True. See Webhooks.
Gating a site: middleware and decorator
api_base. The default, https://xenarch.dev, does not serve the API. Prices come from your site settings, not from code. Requests whose User-Agent matches a known AI crawler get the 402 from POST /v1/gates. Retries with X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash are verified with POST /v1/gates/{gate_id}/verify and cached for cache_ttl_s seconds (default 300). See FastAPI middleware.
Bot detection
is_bot is a case-insensitive match against 21 AI crawler names, including GPTBot, ClaudeBot, PerplexityBot, Google-Extended and CCBot.
Other exports
xenarch.x402.XenarchClient(site_token, api_base="https://api.xenarch.dev"): async client forcreate_gate,verify_paymentandget_gate, authenticated with a site token. Passapi_baseexplicitly, as with the middleware.xenarch.Router,FacilitatorConfig,PaymentContext,HealthState: facilitator ranking. The router scores facilitators by fee, uptime, spec version, latency and publisher preference, and skips one for 5 minutes after 5 failures in 60 seconds.