> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenarch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> xenarch Python package — x402 agent payments, FastAPI publisher middleware, and AI bot detection. Pip install xenarch[agent] or xenarch[fastapi].

## Installation

```bash theme={null}
# For AI agents (wallet + on-chain payments)
pip install xenarch[agent]

# For publishers (FastAPI middleware)
pip install xenarch[fastapi]

# For LangChain agents
pip install xenarch[agent,langchain]

# For CrewAI agents
pip install xenarch[agent,crewai]
```

Requires Python 3.12+. Published on [PyPI](https://pypi.org/project/xenarch/).

## Agent modules

### Wallet management

```python theme={null}
from xenarch.wallet import load_wallet, load_wallet_or_create, generate_wallet

# Load from env vars or ~/.xenarch/wallet.json
wallet = load_wallet()

# Load or auto-create on first run
wallet = load_wallet_or_create()

# Generate a new wallet
wallet = generate_wallet()

print(wallet.address)      # 0x...
print(wallet.network)      # "base" or "base-sepolia"
print(wallet.rpc_url)      # RPC endpoint
```

**Configuration priority:**

1. Environment variables (`XENARCH_PRIVATE_KEY`, `XENARCH_RPC_URL`, `XENARCH_NETWORK`)
2. `~/.xenarch/config.json`
3. `~/.xenarch/wallet.json`

### Gate checking

```python theme={null}
from xenarch.agent_client import check_gate, check_gate_by_domain

# Check by URL (makes an HTTP request, looks for 402)
gate = check_gate("https://example.com/premium")

# Check by domain (queries the platform API)
gate = check_gate_by_domain("https://xenarch.dev", "example.com")

if gate:
    print(gate.price_usd)   # "0.003"
    print(gate.splitter)     # Splitter contract address
    print(gate.collector)    # Publisher wallet
    print(gate.verify_url)   # Verification endpoint
```

### Payment execution

```python theme={null}
from xenarch.payment import execute_payment

result = execute_payment(
    wallet=wallet,
    splitter_address=gate.splitter,
    collector_address=gate.collector,
    price_usd=gate.price_usd,
)

print(result.tx_hash)       # "0x..."
print(result.block_number)  # 28451023
```

The function:

1. Checks USDC balance
2. Checks ETH for gas
3. Approves USDC on the splitter contract (unlimited, to avoid repeated approvals)
4. Calls `splitter.split(collector, amount)` with 150k gas limit

**Constraints:**

* Max \$1.00 per transaction
* Splitter must be in the trusted allowlist
* USDC uses 6 decimals

### Payment verification

```python theme={null}
from xenarch.agent_client import verify_payment

result = verify_payment(gate.verify_url, tx_hash)
print(result["access_token"])  # "eyJ..."
print(result["expires_at"])    # "2026-04-10T15:05:00Z"
```

### Payment history

```python theme={null}
from xenarch.agent_client import get_payment_history

history = get_payment_history(
    api_base="https://xenarch.dev",
    wallet_address=wallet.address,
    domain="example.com",  # optional filter
    limit=10,
)

for item in history:
    print(f"{item.domain}: ${item.amount_usd} ({item.tx_hash})")
```

## Publisher modules

### XenarchMiddleware (ASGI)

Gates all bot traffic site-wide:

```python theme={null}
from xenarch.middleware import XenarchMiddleware

app.add_middleware(
    XenarchMiddleware,
    site_token="st_...",
    site_id="your-site-uuid",
    access_token_secret="your_secret",
    api_base="https://xenarch.dev",         # optional
    excluded_paths={"/healthz", "/docs"},    # optional
)
```

Behavior:

* Human requests pass through (zero overhead)
* Bots with valid `Authorization: Bearer` token pass through
* Bots without token get HTTP 402 with gate details

### require\_payment decorator

Gates individual routes:

```python theme={null}
from xenarch.decorator import require_payment

gate = require_payment(
    site_token="st_...",
    site_id="your-site-uuid",
    access_token_secret="your_secret",
)

@app.get("/premium")
@gate
async def premium(request: Request):
    return {"content": "premium data"}
```

### Token verification

Verify access tokens locally (no API call):

```python theme={null}
from xenarch.token import verify_access_token

result = verify_access_token(token, site_id, secret)
# Returns payload dict if valid, None if invalid/expired
```

### Bot detection

```python theme={null}
from xenarch.detection import is_bot

is_bot("GPTBot/1.0")           # True
is_bot("Mozilla/5.0 Chrome")   # False
```

Matches against 20+ known AI bot signatures (GPTBot, ClaudeBot, PerplexityBot, etc.).

## Environment variables

| Variable              | Default                    | Description              |
| --------------------- | -------------------------- | ------------------------ |
| `XENARCH_PRIVATE_KEY` | —                          | Wallet private key       |
| `XENARCH_RPC_URL`     | `https://mainnet.base.org` | Base RPC endpoint        |
| `XENARCH_API_BASE`    | `https://xenarch.dev`      | Platform API base        |
| `XENARCH_NETWORK`     | `base`                     | `base` or `base-sepolia` |

## Contract addresses

| Network      | Splitter                                     | USDC                                         |
| ------------ | -------------------------------------------- | -------------------------------------------- |
| Base Mainnet | `0xC6D3a6B6fcCD6319432CDB72819cf317E88662ae` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Base Sepolia | `0x7ecfe8f83eab6ba170063d1f1fe7c33695a9ce1d` | `0xc5aDdd66Da733101A5468857Aa3C6689Af9d1DDc` |