Skip to main content
This guide sets up an agent that pays Xenarch-gated pages and APIs in USDC on Base. Pick the MCP server if your agent runs in Claude Code, Claude Desktop, Cursor or Cline. Pick the Python SDK if you write the agent yourself.

Prerequisites

  • Node.js 18 or later (for the xenarch CLI 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.
Xenarch runs on Base mainnet only, so every payment moves real USDC. Set spend caps before you connect an agent.

Path 1: MCP server

1

Create a wallet

The CLI prints the address and private key once and stores the key in ~/.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

This signs a Sign-In with Ethereum message with your wallet and stores a 7-day session in ~/.xenarch/config.json. Signing moves no funds.
4

Set spend caps

A new agent has no caps until you set them. The platform checks these caps before every payment.
5

Create an agent key

The command prints an 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.
What happens on a Xenarch gate:
  1. The payer requests the URL and receives a 402 with Xenarch’s x402 envelope (gate_id, accepts, facilitators).
  2. 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.
  3. It signs an EIP-3009 transferWithAuthorization from your wallet to the seller’s wallet and sends it to a facilitator from the gate’s list.
  4. It retries the URL with X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash and returns the body.
If you leave out 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.