Skip to main content
The xenarch package on PyPI (version 1.1.0, MIT license) covers both sides of a payment:

Installation

Requires Python 3.12 or later.
The 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, a gate_id and facilitators). 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 with X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash.
  • Any other x402 402. Signs the payment and retries against that server with the payment header its x402 version expects.
A successful payment returns:
Refusals and failures return a dict with an 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.
In version 1.1.0 the framework tools do not accept agent_control_plane_url, so their preflight goes to https://xenarch.dev and fails. Leave XENARCH_API_TOKEN unset in processes that use them, or every payment is refused. Their spending limit is then XenarchBudgetPolicy. If you need platform caps in Python, use XenarchPayer as shown above.
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

Always pass 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 for create_gate, verify_payment and get_gate, authenticated with a site token. Pass api_base explicitly, 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.

Constants