Prerequisites
- Node.js 18 or later (for the
xenarchCLI and the MCP server) - Python 3.12 or later (only for the Python path)
- A wallet with USDC on Base mainnet. It does not need ETH. A third-party x402 facilitator submits each transfer and pays the gas.
Path 1: MCP server
1
Create a wallet
~/.xenarch/config.json with owner-only permissions. Back up the key. To use a key you already have, run npx xenarch wallet import instead.2
Fund it with USDC on Base
Send USDC on Base to the address from the previous step. Keep only what you are willing to let the agent spend.
3
Sign in to the agent control plane
~/.xenarch/config.json. Signing moves no funds.4
Set spend caps
5
Create an agent key
xa_live_ key once. The MCP server refuses to pay without it.6
Add the server to your client
For Claude Code:The server signs with the wallet the CLI stored in
~/.xenarch/config.json. See Installation for Claude Desktop, Cursor and Cline.7
Ask your agent to pay
“Check whether https://example.com/premium-article is gated by Xenarch. If the price is under $0.01, pay for it and summarize the page.”The agent calls
xenarch_check_gate, then xenarch_pay. See the tools reference for what each call returns.Path 2: Python SDK
XenarchPayer fetches a URL, answers an HTTP 402 by signing an EIP-3009 USDC authorization, and returns the response body.
- The payer requests the URL and receives a 402 with Xenarch’s x402 envelope (
gate_id,accepts,facilitators). - It checks the price against
XenarchBudgetPolicy. With a token set, it also asks the platform’s preflight to check your caps, scope rules and pause switch. - It signs an EIP-3009
transferWithAuthorizationfrom your wallet to the seller’s wallet and sends it to a facilitator from the gate’s list. - It retries the URL with
X-Xenarch-Gate-IdandX-Xenarch-Tx-Hashand returns the body.
xenarch_token and XENARCH_API_TOKEN is unset, the payer skips the platform preflight and only XenarchBudgetPolicy limits spending. Always pass agent_control_plane_url="https://api.xenarch.dev" when you use a token. The default value does not serve the API, so preflight fails and the payer refuses every payment.
For LangChain, CrewAI, AutoGen and LangGraph tools, see LangChain, CrewAI and the Python SDK reference.
Next steps
MCP tools
Inputs, outputs and refusal reasons for each payment tool.
How it works
The 402 response, settlement and the retry headers.