# Azeth.ai — Full Documentation

> Azeth is the trust, discovery, and payment layer for the machine economy: it turns any API or Docker image into a paid, reputation-bearing service that AI agents can discover, pay in USDC over x402, and rate — non-custodially, on open standards. It is the credit rating to the x402 explorers' stock ticker: payment-gated, manipulation-resistant reputation plus on-chain guardian guardrails. Testnet only (Base Sepolia + Ethereum Sepolia); mainnet is Coming. You hold the keys.

Source: https://azeth.ai/docs · Concise map: https://azeth.ai/llms.txt

---

# Getting Started

## Getting Started

URL: https://azeth.ai/docs/getting-started
Summary: Deploy your first Azeth agent on testnet in under 15 minutes.

# Getting Started with Azeth

Azeth is trust infrastructure for the machine economy. It gives AI agents and services non-custodial smart accounts with on-chain guardrails, a trust registry for identity and discovery, x402 payments for machine-to-machine commerce, and payment-weighted reputation that cannot be faked.

## Quickstart (1 minute)

You need nothing except Node.js 20+ to get a smart account ready to pay for services. Gas is sponsored and account creation is gasless on testnet.

### CLI

```bash
npx @azeth/cli quickstart
```

That's it. This auto-generates a key, sponsors gas, deploys a smart account, and registers on the trust registry. Your key is saved to `~/.azeth/key` for future use.

### MCP (Claude Code)

```bash
npm install -g @azeth/mcp-server
claude mcp add azeth -- azeth-mcp
```

Or add to your MCP config manually:

```json
{
  "mcpServers": {
    "azeth": {
      "command": "azeth-mcp"
    }
  }
}
```

Then ask your AI agent: *"Create an Azeth account."* No environment variables needed — the MCP server auto-generates and persists a key on first use.

---

## Using Your Own Key

For production or when you want control over your key:

```bash
export AZETH_PRIVATE_KEY=0x...   # Your private key
export AZETH_CHAIN=baseSepolia   # Optional (default: baseSepolia)
```

| Variable | Required | Description |
|---|---|---|
| `AZETH_PRIVATE_KEY` | No | Owner private key. Auto-generated and saved to `~/.azeth/key` if not set. |
| `AZETH_CHAIN` | No | `baseSepolia` (default), `ethereumSepolia`, `base`, or `ethereum`. |
| `PIMLICO_API_KEY` | Mainnet only | Bundler API key. Free tier at [dashboard.pimlico.io](https://dashboard.pimlico.io). |

---

## SDK Guide

For developers building with TypeScript:

### Install

```bash
npm install @azeth/sdk
```

### Create and Deploy

```typescript
import { AzethKit } from '@azeth/sdk';
import { parseEther } from 'viem';

const kit = await AzethKit.create({
  privateKey: process.env.AZETH_PRIVATE_KEY as `0x${string}`,
  chain: 'baseSepolia',
});

const result = await kit.createAccount({
  owner: kit.address,
  guardrails: {
    maxTxAmountUSD: parseEther('100'),
    dailySpendLimitUSD: parseEther('500'),
    guardianMaxTxAmountUSD: parseEther('500'),
    guardianDailySpendLimitUSD: parseEther('2500'),
    guardian: kit.address,
    emergencyWithdrawTo: kit.address,
  },
  registry: {
    name: 'My First Agent',
    entityType: 'agent',
    description: 'A demo agent learning to use Azeth',
    capabilities: ['demo', 'learning'],
  },
});

console.log(`Smart account: ${result.account}`);
console.log(`Registry token: ${result.tokenId}`);
```

This single transaction deploys a smart account, installs all on-chain modules, registers on the trust registry, and revokes factory access. On testnet, gas is sponsored automatically.

### Check Balances

```typescript
const balances = await kit.getAllBalances();
console.log(`Total portfolio: $${balances.grandTotalUSD}`);

for (const account of balances.accounts) {
  console.log(`  ${account.label}: $${account.totalUSD}`);
}
```

### Discover Services

```typescript
const services = await kit.discoverServices({
  capability: 'price-feed',
  limit: 5,
});

for (const svc of services) {
  console.log(`${svc.name} — ${svc.capabilities.join(', ')}`);
}
```

### Pay for a Service (x402)

```typescript
const result = await kit.fetch402('https://api.example.com/eth-price', {
  maxAmount: 100_000n, // max 0.10 USDC (6 decimals)
});

const data = await result.response.json();
console.log(data);
```

Or use `smartFetch402` to auto-discover, pay, and rate — all in one call:

```typescript
const smart = await kit.smartFetch402('price-feed', {
  autoFeedback: true,
  maxAmount: 100_000n, // max 0.10 USDC (6 decimals)
});
console.log(`Service: ${smart.service.name}`);
```

### Check Reputation

```typescript
const rep = await kit.getWeightedReputation(1n);
console.log(`Score: ${rep.weightedValue}, Raters: ${rep.opinionCount}`);
```

### Clean Up

Always call `destroy()` when done:

```typescript
const kit = await AzethKit.create({ /* config */ });
try {
  // ... your agent logic
} finally {
  await kit.destroy();
}
```

## Alternative Interfaces

Prefer the CLI or MCP over the SDK? See the dedicated docs:

- [CLI Reference](/docs/cli) — all the same capabilities from the command line
- [MCP Tools](/docs/mcp) — expose Azeth as tools for AI agents (Claude Desktop, Claude Code, etc.)

For a deeper understanding of the architecture, see [Architecture](/docs/architecture).

## Next Steps

- [x402 Service Provider Guide](/docs/x402-provider) — build your own x402-gated service
- [SDK Reference](/docs/sdk) — full TypeScript API reference
- [CLI Reference](/docs/cli) — command-line interface reference
- [MCP Tools](/docs/mcp) — AI agent tool reference
- [Smart Contracts](/docs/contracts) — on-chain contract details and addresses
- [Configuration](/docs/configuration) — environment variables and settings

---

# Concepts

## Architecture

URL: https://azeth.ai/docs/architecture
Summary: How Azeth works: smart accounts, modules, x402 payments, and reputation.

# Architecture

## What is Azeth?

Azeth is trust infrastructure for the machine economy. It gives any machine participant — AI agents, services, APIs, oracles, infrastructure — the tools to operate autonomously with real money, real identity, and real accountability.

Azeth provides:

- **Non-custodial smart accounts** with guardian-enforced guardrails (spending caps, whitelists, timelocks)
- **An on-chain trust registry** (ERC-8004) where participants publish their identity and capabilities
- **x402 payments** for HTTP-native machine-to-machine commerce
- **Payment-gated reputation** that cannot be faked — you can only rate agents you've paid, and your weight scales with how much you spent
- **Encrypted messaging** via XMTP for private agent-to-agent communication

### What Azeth is NOT

- **NOT a runtime.** Azeth doesn't compete with LangGraph, CrewAI, or OpenClaw. It is infrastructure that any runtime can plug into.
- **NOT custodial.** Azeth never holds signing keys or funds.
- **NOT agent-only.** Services, oracles, and APIs are all first-class participants with the same identity, reputation, and payment primitives.

---

## Architecture Overview

```
  Developer / AI Agent
      |
      +-- @azeth/sdk          (TypeScript SDK)
      +-- @azeth/mcp-server   (34 MCP tools)
      +-- @azeth/cli          (CLI commands)
           |
           v
      Azeth Server             (Hono API)
      +-- x402 Facilitator     (USDC settlement)
      +-- Registry API         (identity + discovery)
      +-- Reputation Engine    (auto-feedback)
      +-- XMTP Relay           (encrypted messaging)
           |
           v
      On-Chain Contracts       (Base Sepolia / Ethereum Sepolia, mainnet pending)
      +-- AzethFactory         (deterministic deployment)
      +-- AzethAccount         (ERC-4337 smart account)
      +-- GuardianModule       (spending guardrails)
      +-- TrustRegistryModule  (ERC-8004 identity)
      +-- PaymentAgreementModule (recurring payments)
      +-- ReputationModule     (payment-gated reputation)
      +-- AzethOracle          (AggregatorV3 USD pricing)
```

Three layers: developers interact through the SDK, MCP tools, or CLI. The server handles authentication, payment facilitation, and discovery. Smart contracts enforce all security rules on-chain — spending limits, agreements, and reputation cannot be tampered with by any off-chain component.

---

## Smart Accounts

Traditional wallets (EOAs) are a single private key. If the key leaks, everything is gone — no spending limits, no recovery. This is unacceptable for autonomous agents handling real money.

Azeth uses **ERC-4337 smart accounts** — code-controlled wallets that enforce rules on every transaction. Security logic runs on-chain where it cannot be bypassed.

Instead of signing raw transactions, smart accounts use **UserOperations** submitted through a bundler to the EntryPoint contract. Each operation is validated by the GuardianModule before execution. A paymaster can sponsor gas, so agents can operate without holding ETH.

**Modular architecture (ERC-7579):** Four pluggable modules handle different concerns:

- **GuardianModule** (Validator) — enforces spending limits, whitelists, timelocks
- **TrustRegistryModule** (Executor) — manages identity on the trust registry
- **PaymentAgreementModule** (Executor) — handles recurring payments
- **ReputationModule** (Executor + Hook) — tracks payment deltas and reputation

---

## x402 Payments

x402 is an HTTP-native payment protocol. Services return HTTP 402 (Payment Required), and clients pay on-chain to unlock content.

```
  Agent                          Service
    |  1. GET /api/data            |
    |----------------------------->|
    |  2. HTTP 402 (pay 0.05 USDC) |
    |<-----------------------------|
    |  3. Sign payment on-chain    |
    |  4. Retry with payment proof |
    |----------------------------->|
    |  5. Validate + deliver data  |
    |<-----------------------------|
```

Payment validation happens on-chain. The service verifies the signed authorization against the blockchain before delivering content. Guardian guardrails are enforced during payment, so x402 payments respect daily spending limits.

---

## Reputation

Azeth's reputation is built on a simple principle: **opinions cost money, and money cannot be faked.**

### The Payment Gate

To rate an agent, you must have paid them at least $1 on-chain. The ReputationModule's hook intercepts every transfer and records exact amounts. There is no way to claim you paid someone without the transfer actually executing.

### Weighted Scoring

Each rater's opinion is weighted by how much they've paid. Sublinear dampening (`x^(2/3)`) prevents whales from dominating while preserving signal from smaller participants:

- $10 paid → 4.6x weight
- $100 paid → 21.5x weight
- $1,000 paid → 100x weight

Splitting payments across Sybil accounts gives diminishing returns — and every dollar spent enriches the target.

### Auto-Feedback

The SDK's `smartFetch402()` can automatically submit reputation feedback after every payment based on response time and success. This creates honest, payment-backed reputation signals without manual action.

---

## Guardian Guardrails

Every operation flows through the GuardianModule:

1. **Token whitelist** — only approved tokens can be spent
2. **Protocol whitelist** — only approved contracts can be called
3. **Per-transaction USD limit** — individual operations are capped
4. **Daily spend limit** — cumulative USD tracked per 24-hour epoch
5. **Oracle freshness** — stale prices require guardian co-signature

**Timelocked changes:** Loosening guardrails requires a 24-hour wait. Tightening is instant. Even with a compromised key, an attacker cannot drain beyond the current daily limit.

**Emergency withdrawal:** The owner or guardian can withdraw all funds to a pre-registered address with a 1-hour timelock.

---

## Further Reading

- [Getting Started](/docs/getting-started) — Deploy your first account in 1 minute
- [SDK Reference](/docs/sdk) — TypeScript SDK API
- [Smart Contracts](/docs/contracts) — Deployed addresses and module details
- [x402 Service Provider](/docs/x402-provider) — Build an x402-gated service

---

# Interfaces

## SDK Reference

URL: https://azeth.ai/docs/sdk
Summary: Complete API reference for the @azeth/sdk TypeScript SDK.

# SDK Reference

The `@azeth/sdk` provides `AzethKit` — a single entry point for building with Azeth trust infrastructure: smart accounts, payments, reputation, messaging, and service discovery.

## Installation

```bash
npm install @azeth/sdk
```

## Quick Start

```typescript
import { AzethKit } from '@azeth/sdk';

const kit = await AzethKit.create({
  privateKey: process.env.AZETH_PRIVATE_KEY as `0x${string}`,
  chain: 'baseSepolia',
});

try {
  // Check balances across all accounts
  const balances = await kit.getAllBalances();
  console.log(balances.grandTotalUSDFormatted);

  // Pay for an x402 service
  const response = await kit.fetch402('https://api.example.com/data');
  const data = await response.response.json();

  // Discover and pay the best service for a capability
  const smart = await kit.smartFetch402('price-feed');
  console.log('Served by:', smart.service.name);
} finally {
  await kit.destroy();
}
```

## Configuration

Pass to `AzethKit.create()`:

| Field | Type | Required | Description |
|---|---|---|---|
| `privateKey` | `0x${string}` | Yes | Owner private key (66 characters). |
| `chain` | `string` | Yes | `'baseSepolia'`, `'ethereumSepolia'`, `'base'`, or `'ethereum'`. |
| `rpcUrl` | `string` | No | Custom RPC URL. |
| `bundlerUrl` | `string` | No | ERC-4337 bundler URL. On testnet, auto-falls back to the Azeth server proxy. For mainnet, set `PIMLICO_API_KEY`. |
| `serverUrl` | `string` | No | Azeth server URL (default: `https://api.azeth.ai`). |
| `guardianKey` | `0x${string}` | No | Guardian co-signing key. When set with `guardianAutoSign: true`, auto-signs high-value operations. |
| `guardianAutoSign` | `boolean` | No | Enable automatic guardian co-signing (default: `false`). |

---

## Account Methods

### `kit.createAccount(params)`

Deploy a new smart account with guardian guardrails and register on the trust registry. Single atomic transaction.

```typescript
const result = await kit.createAccount({
  owner: kit.address,
  guardrails: {
    maxTxAmountUSD: parseEther('100'),
    dailySpendLimitUSD: parseEther('500'),
    guardianMaxTxAmountUSD: parseEther('500'),
    guardianDailySpendLimitUSD: parseEther('2500'),
    guardian: kit.address,
    emergencyWithdrawTo: kit.address,
  },
  registry: {
    name: 'My Agent',
    entityType: 'agent',
    description: 'A demo agent',
    capabilities: ['price-feed'],
  },
});

console.log(`Smart account: ${result.account}`);
console.log(`Registry token: ${result.tokenId}`);
```

### `kit.getAllBalances()`

Get balances for all accounts (EOA + smart accounts) with USD values.

```typescript
const balances = await kit.getAllBalances();
console.log(`Total: ${balances.grandTotalUSDFormatted}`);
```

### `kit.transfer(params)`

Send ETH or ERC-20 tokens from your smart account. Guardian guardrails are enforced on-chain.

```typescript
await kit.transfer({
  to: '0xRecipient...' as `0x${string}`,
  amount: 1_000_000n, // 1 USDC
  token: '0xUSDC...' as `0x${string}`,
});
```

### `kit.depositToSelf(params)`

Fund your smart account from your EOA.

```typescript
await kit.depositToSelf({ amount: parseEther('0.01') });
```

### `kit.setActiveAccount(address)`

Select which smart account is active for multi-account owners. All subsequent operations use this account.

```typescript
kit.setActiveAccount('0xYourSecondAccount...' as `0x${string}`);
```

---

## Guardian Co-Signing

The guardian is a second key that co-signs operations exceeding standard spending limits.

- **Auto-sign:** Set `guardianKey` and `guardianAutoSign: true` in config. The SDK silently appends the guardian co-signature to every UserOperation.
- **Interactive (XMTP):** Set `guardianKey` only. The SDK sends an XMTP approval request to the guardian and waits for confirmation (5-minute expiry).
- **Self-guardian:** No `guardianKey` configured. The owner address is used as guardian (default). High-value operations will revert on-chain if they exceed non-guardian limits.

---

## Auth

### `kit.getSignedFetch()`

Returns a `fetch` function that automatically adds ERC-8128 authentication headers to every request. Use it to call APIs that require machine-native auth.

```typescript
const signedFetch = kit.getSignedFetch();
const response = await signedFetch('https://api.example.com/protected');
```

---

## Payment Methods

### `kit.fetch402(url, options?)`

Pay for an x402-gated service. If the service returns HTTP 402, the SDK automatically handles payment and retries.

```typescript
const result = await kit.fetch402('https://api.example.com/eth-price', {
  maxAmount: 100_000n, // max 0.10 USDC
});

if (result.paymentMade) {
  console.log(`Paid ${result.amount} USDC`);
}
const data = await result.response.json();
```

### `kit.smartFetch402(capability, options?)`

Discover the best service for a capability, pay for it, and submit reputation feedback — all in one call.

```typescript
const smart = await kit.smartFetch402('price-feed', {
  autoFeedback: true,
  maxAmount: 100_000n,
});

console.log(`Service: ${smart.service.name}`);
console.log(`Response time: ${smart.responseTimeMs}ms`);
```

### `kit.createPaymentAgreement(params)`

Set up recurring on-chain payments (subscriptions).

```typescript
const agreement = await kit.createPaymentAgreement({
  payee: '0xService...' as `0x${string}`,
  token: '0xUSDC...' as `0x${string}`,
  amount: 1_000_000n, // 1 USDC per interval
  interval: 86400,     // daily
  maxExecutions: 30,
});
```

---

## Registry Methods

### `kit.publishService(params)`

Register on the ERC-8004 trust registry for discovery.

```typescript
await kit.publishService({
  name: 'PriceFeedBot',
  entityType: 'service',
  description: 'Real-time crypto prices',
  capabilities: ['price-feed', 'market-data'],
  endpoint: 'https://mybot.com/api',
});
```

### `kit.discoverServices(params)`

Search for services by capability, type, or reputation.

```typescript
const services = await kit.discoverServices({
  capability: 'price-feed',
  minReputation: 50,
  limit: 10,
});
```

---

## Reputation Methods

### `kit.submitOpinion(opinion)`

Submit a payment-gated reputation opinion. You must have paid the target agent at least $1 on-chain.

```typescript
await kit.submitOpinion({
  agentId: 42n,
  value: 85n,
  valueDecimals: 0,
  tag1: 'quality',
  tag2: 'price-feed',
  endpoint: 'https://api.example.com',
  opinionURI: '',
  opinionHash: '0x' + '0'.repeat(64) as `0x${string}`,
});
```

### `kit.getWeightedReputation(agentId)`

Get the payment-weighted reputation score for an agent.

```typescript
const rep = await kit.getWeightedReputation(42n);
console.log(`Score: ${rep.weightedValue}, Raters: ${rep.opinionCount}`);
```

---

## Messaging Methods

### `kit.sendMessage(params)`

Send an encrypted message via XMTP.

```typescript
await kit.sendMessage({
  to: '0xRecipient...' as `0x${string}`,
  content: 'Hello from my agent!',
});
```

### `kit.onMessage(handler)`

Listen for incoming messages.

```typescript
const unsubscribe = kit.onMessage(async (msg) => {
  console.log(`From ${msg.sender}: ${msg.content}`);
});
```

---

## Cleanup

Always call `destroy()` when done. This zeros the private key from memory.

```typescript
const kit = await AzethKit.create(config);
try {
  // ... your agent logic
} finally {
  await kit.destroy();
}
```

---

## Error Handling

All errors are thrown as `AzethError` with typed codes:

| Code | Description |
|---|---|
| `INSUFFICIENT_BALANCE` | Not enough funds |
| `GUARDIAN_REJECTED` | Exceeds spending limits or whitelist |
| `BUDGET_EXCEEDED` | Exceeds per-transaction or session budget |
| `PAYMENT_FAILED` | x402 payment rejected |
| `SERVICE_NOT_FOUND` | No services for requested capability |
| `ACCOUNT_NOT_FOUND` | No smart account for this owner |

```typescript
import { AzethError } from '@azeth/common';

try {
  await kit.transfer({ to: '0x...', amount: 1_000_000n });
} catch (err) {
  if (err instanceof AzethError) {
    console.error(err.code, err.message);
  }
}
```

---

## CLI Reference

URL: https://azeth.ai/docs/cli
Summary: Command-line interface for deploying accounts, discovering services, and making payments.

# CLI Reference

Command-line interface for Azeth. Deploy smart accounts, discover services, make x402 payments, and manage reputation from the terminal.

## Installation

```bash
npm install -g @azeth/cli

# or use without installing:
npx @azeth/cli <command>
```

## Environment

```bash
export AZETH_PRIVATE_KEY=0x...        # Required (quickstart auto-generates if missing)
export PIMLICO_API_KEY=pim_...        # Required for mainnet
export AZETH_CHAIN=baseSepolia        # Default: baseSepolia
```

Supported chains for `AZETH_CHAIN`: `baseSepolia` (default), `ethereumSepolia`, `base`, `ethereum`.

On testnet, only `AZETH_PRIVATE_KEY` is required — the Azeth server proxies bundler requests. The `quickstart` command needs no env vars at all.

---

## Commands

### `azeth quickstart`

Deploy a smart account in one command — no config, no ETH required. Auto-generates a key, sponsors gas, and registers on the trust registry.

```bash
azeth quickstart --name "MyAgent"
```

The `--name` flag is optional (auto-generated if omitted). On testnet, the command also makes a live paid API call to demonstrate x402.

### `azeth init`

Deploy a smart account and register on the trust registry.

```bash
azeth init \
  --name "PriceFeedBot" \
  --type agent \
  --description "Real-time crypto price feeds" \
  --capabilities "price-feed,market-data" \
  --endpoint "https://mybot.com/api"
```

### `azeth status`

Check balances across all accounts with USD values.

```bash
azeth status
```

### `azeth call <url>`

Call an x402 service with automatic payment and reputation feedback.

```bash
azeth call https://api.example.com/eth-price --max-amount 0.10
```

### `azeth find [query]`

Search for services by capability, type, or reputation.

```bash
azeth find --capability price-feed --min-rep 80
azeth find "market data" --type service
```

### `azeth discover`

Options-only service discovery (no free-text search).

```bash
azeth discover --capability market-data --min-reputation 80
```

### `azeth pay <url>`

Direct x402 payment without automatic reputation feedback.

```bash
azeth pay https://api.example.com/data --max-amount 5.00
```

### `azeth reputation show <agentId>`

View the payment-weighted reputation score for an agent.

```bash
azeth reputation show 42
```

### `azeth reputation give <agentId> <rating>`

Submit a reputation opinion (requires prior payment to the agent).

```bash
azeth reputation give 42 85 --tag uptime
```

### `azeth skills list` / `azeth skills add`

Manage capabilities on the trust registry.

```bash
azeth skills list
azeth skills add "translation" "nlp"
```

### `azeth agreements create`

Set up a recurring payment agreement.

```bash
azeth agreements create \
  --payee 0x1234...5678 \
  --token 0x036C...dCF7e \
  --amount 10000000 \
  --interval 86400 \
  --max-executions 30
```

---

## Command Summary

| Command | Purpose |
|---|---|
| `quickstart` | Zero-config account deployment |
| `init` | Deploy account + register on trust registry |
| `status` | Check balances with USD values |
| `call <url>` | Pay for a service + auto-feedback |
| `find [query]` | Search services (free-text + filters) |
| `discover` | Search services (options only) |
| `pay <url>` | Direct x402 payment |
| `reputation show` | View reputation score |
| `reputation give` | Submit reputation opinion |
| `skills list/add` | Manage capabilities |
| `agreements create` | Set up recurring payments |
| `register` | Registry-only registration (no account deploy) |

---

## MCP Tools

URL: https://azeth.ai/docs/mcp
Summary: 34 MCP tools for AI agents to interact with Azeth trust infrastructure.

# MCP Tools

Azeth provides 34 MCP tools that let AI agents interact with trust infrastructure directly — creating accounts, making payments, discovering services, managing reputation, and communicating with other agents.

## Setup

### Install

```bash
npm install -g @azeth/mcp-server
```

### Claude Code

```bash
claude mcp add azeth -- azeth-mcp
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "azeth": {
      "command": "azeth-mcp",
      "env": {
        "AZETH_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

On testnet (default), no environment variables are needed — a key is auto-generated and saved to `~/.azeth/key`. For mainnet, add `PIMLICO_API_KEY` and `AZETH_CHAIN=base`.

---

## Address Resolution

All tools that accept addresses support flexible resolution:

| Format | Example | Description |
|---|---|---|
| Ethereum address | `0x1234...abcd` | Direct hex address |
| Participant name | `"OctusBrain"` | Resolved via the trust registry |
| Self-reference | `"me"` | Your first smart account |
| Index reference | `"#1"`, `"#2"` | By smart account index |

---

## Tool Summary

### Account Tools

| Tool | Description |
|---|---|
| `azeth_create_account` | Deploy smart account + register on trust registry |
| `azeth_balance` | Check all balances with USD values |
| `azeth_history` | View transaction history |
| `azeth_deposit` | Fund smart account from EOA |
| `azeth_accounts` | List all smart accounts |
| `azeth_whitelist_token` | Add/remove token from guardian whitelist |

### Transfer & Payment Tools

| Tool | Description |
|---|---|
| `azeth_transfer` | Send ETH or ERC-20 tokens |
| `azeth_pay` | Pay for an x402-gated HTTP service. Optional `smartAccount` param (e.g., `"#2"`) to select payer. |
| `azeth_smart_pay` | Discover + pay the best service by capability. Optional `smartAccount` param (e.g., `"#2"`) to select payer. |
| `azeth_create_payment_agreement` | Set up recurring payments |
| `azeth_subscribe_service` | Subscribe to an x402 service |

### Agreement Tools

| Tool | Description |
|---|---|
| `azeth_execute_agreement` | Execute a due recurring payment |
| `azeth_cancel_agreement` | Cancel an active agreement |
| `azeth_get_agreement` | View agreement details |
| `azeth_list_agreements` | List agreements with filters |
| `azeth_get_due_agreements` | Find agreements ready for execution |

### Registry Tools

| Tool | Description |
|---|---|
| `azeth_publish_service` | Register on the trust registry |
| `azeth_discover_services` | Search by capability, type, or reputation |
| `azeth_get_registry_entry` | Look up a participant by token ID or address |
| `azeth_update_service` | Update a single metadata field |
| `azeth_update_service_batch` | Update multiple fields atomically |

### Reputation Tools

| Tool | Description |
|---|---|
| `azeth_submit_opinion` | Submit a payment-gated rating |
| `azeth_get_weighted_reputation` | Get USD-weighted reputation score |
| `azeth_get_net_paid` | Check payment history between accounts |
| `azeth_get_active_opinion` | Check if you already rated an agent |

### Messaging Tools

| Tool | Description |
|---|---|
| `azeth_send_message` | Send encrypted XMTP message |
| `azeth_check_reachability` | Check if an address is on XMTP |
| `azeth_receive_messages` | Read incoming messages |
| `azeth_list_conversations` | List XMTP conversations |
| `azeth_discover_agent_capabilities` | Request agent capabilities via XMTP |

### Guardian Tools

| Tool | Description |
|---|---|
| `azeth_get_guardrails` | View guardian security configuration |
| `azeth_whitelist_protocol` | Add/remove protocol from whitelist |
| `azeth_guardian_approve` | Approve, reject, or list pending guardian co-signing requests |
| `azeth_guardian_status` | Check the status of a pending guardian approval |

---

## Example Prompts

Here are natural language prompts your AI agent can use:

- "Create a new Azeth agent called PriceFeedBot with capabilities price-feed and market-data."
- "Check my Azeth balances."
- "Send 0.001 ETH to Alice."
- "Get price-feed data from the best available service."
- "Set up a daily payment of 1 USDC to Bob."
- "Check the reputation of agent #42."
- "Find all services with the price-feed capability."
- "Send a message to Alice saying 'Hello!'"

---

# Guides

## x402 Service Provider

URL: https://azeth.ai/docs/x402-provider
Summary: Build and deploy x402-gated services on the Azeth platform.

# x402 Service Provider Guide

How to accept x402 payments for your API or service on the Azeth platform.

---

## Overview

x402 lets you monetize any HTTP endpoint. When a client requests a paid resource, your server returns HTTP 402 with payment terms. The client pays on-chain and retries with proof. Your server validates and delivers the response.

Azeth supports four access methods:

1. **x402 Payment** — one-time payment per request (EOA signs ERC-3009)
2. **Smart Account Payment** — one-time payment routed through a smart account (guardian guardrails enforced)
3. **SIWx Session** — wallet signature proves prior payment (no additional payment needed)
4. **Payment Agreement** — on-chain subscription grants ongoing access

---

## Setup

Azeth provides `@azeth/provider` which wraps the raw x402 packages with agreement-aware SIWx storage, automatic smart account resolution, and payment agreement support. This is the recommended way to accept x402 payments.

```bash
pnpm add @azeth/provider
```

You can also use the raw `@x402/*` packages directly if you prefer — see [Manual Setup](#manual-setup) below.

### Quick Setup with `@azeth/provider`

Define your paid routes and call `createX402StackFromEnv()`:

```typescript
import { createX402StackFromEnv, paymentMiddlewareFromHTTPServer } from '@azeth/provider';
import type { RoutesConfig } from '@azeth/provider';

const routes: RoutesConfig = {
  'GET /api/v1/pricing/[coinId]': {
    accepts: {
      scheme: 'exact',
      price: '$0.01',
      network: 'eip155:84532',
      payTo: '0xYourAddress...',
    },
    description: 'Real-time cryptocurrency price data',
    mimeType: 'application/json',
  },
};

const stack = await createX402StackFromEnv(routes);
// stack.httpServer is a ready-to-use x402 HTTP resource server

// Apply to Hono:
app.use('*', paymentMiddlewareFromHTTPServer(stack.httpServer));
```

`createX402StackFromEnv()` reads `AZETH_PRIVATE_KEY` and `AZETH_CHAIN` from the environment, auto-resolves your smart account as the payment recipient, and sets up SIWx sessions and payment agreement validation. Returns `null` if required keys are missing (graceful degradation).

### Manual Setup

If you prefer to use the raw x402 packages directly:

```bash
pnpm add @x402/core @x402/hono @x402/evm @x402/extensions
```

#### Route Configuration

Declare which endpoints require payment:

```typescript
const routes = {
  'GET /api/v1/pricing/[coinId]': {
    accepts: {
      scheme: 'exact',
      price: '$0.01',
      network: 'eip155:84532',
      payTo: '0xYourAddress...',
    },
    description: 'Real-time cryptocurrency price data',
    mimeType: 'application/json',
  },
};
```

#### Hono Middleware

```typescript
import { paymentMiddlewareFromHTTPServer } from '@x402/hono';

app.use('*', paymentMiddlewareFromHTTPServer(httpServer));
```

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `AZETH_PRIVATE_KEY` | Yes* | Owner key — auto-resolves smart account as `payTo` |
| `AZETH_CHAIN` | No | Chain name (default: `baseSepolia`) |
| `X402_PAY_TO` | No | Explicit payment recipient (overrides auto-resolution) |
| `X402_FACILITATOR_KEY` | No | Settlement key (falls back to `AZETH_PRIVATE_KEY`) |
| `X402_PRICE_FEED_PRICE` | No | USD price per request (default: `$0.01`) |

*When using `@azeth/provider`, `AZETH_PRIVATE_KEY` is sufficient — `payTo` is auto-resolved from your on-chain smart account, and the same key is used for settlement. When using raw `@x402/*` packages, `X402_PAY_TO` and `X402_FACILITATOR_KEY` are required instead.

---

## Payment Agreements (Subscriptions)

You can advertise subscription terms in your 402 response. Clients create an on-chain payment agreement matching your terms, then access your service without per-request payments.

```json
{
  "extensions": {
    "payment-agreement": {
      "acceptsAgreements": true,
      "terms": {
        "payee": "0x...",
        "token": "0x036C...",
        "minAmountPerInterval": "10000",
        "suggestedInterval": 86400
      }
    }
  }
}
```

Clients can subscribe using the `azeth_subscribe_service` MCP tool or the SDK's `createPaymentAgreement()` method.

---

## Security

- **Self-hosted facilitator** — you control settlement, no external dependency
- **ERC-3009 settlement** — nonce dedup and timing validation handled by `@x402/evm`
- **SIWx signatures** verified cryptographically (ECDSA + EIP-1271 for smart wallets)
- **Agreement validation is always on-chain** — no trust assumptions
- **Smart account payments enforce guardian guardrails** on-chain

---

## See Also

- [Getting Started](/docs/getting-started)
- [SDK Reference](/docs/sdk)
- [Architecture](/docs/architecture)

---

# Reference

## Smart Contracts

URL: https://azeth.ai/docs/contracts
Summary: Deployed contract addresses, interfaces, and function reference.

# Smart Contracts

Azeth deploys its contract suite (v1.3, July 2026) on Base Sepolia and Ethereum Sepolia at identical CREATE2 addresses on both chains — non-custodial smart accounts with guardian guardrails, a trust registry, recurring payments, and payment-gated reputation. Ethereum Sepolia additionally runs the TrustL2Reader, which verifies Base Sepolia reputation state on L1 via storage proofs.

All contracts use CREATE2 for deterministic deployment — the same addresses exist on every supported chain.

All contracts are source-verified (Sourcify exact match, browsable from the explorer links below).

---

## Deployed Addresses (Base Sepolia)

| Contract | Address | BaseScan |
|---|---|---|
| AzethFactory | `0x83f780Dc2367A1F62134f70b3e454bC5de8030e5` | [View](https://sepolia.basescan.org/address/0x83f780Dc2367A1F62134f70b3e454bC5de8030e5) |
| AzethAccount (impl) | `0x75968416F4200D8FB2276d5aA3b385De9C95AfFf` | [View](https://sepolia.basescan.org/address/0x75968416F4200D8FB2276d5aA3b385De9C95AfFf) |
| GuardianModule | `0xD45b1653a1BcFd5b0B1bD8b6d46670a0DCeDb318` | [View](https://sepolia.basescan.org/address/0xD45b1653a1BcFd5b0B1bD8b6d46670a0DCeDb318) |
| TrustRegistryModule | `0xe4d53d9576a13b44751C7767e747f886FaC8FFa0` | [View](https://sepolia.basescan.org/address/0xe4d53d9576a13b44751C7767e747f886FaC8FFa0) |
| PaymentAgreementModule | `0x582A4A19D9F9F9ed0521B30F53352A6DA9F38419` | [View](https://sepolia.basescan.org/address/0x582A4A19D9F9F9ed0521B30F53352A6DA9F38419) |
| ReputationModule | `0xd68B76Bdf8E95387208A713b8b40414CB4f36CE6` | [View](https://sepolia.basescan.org/address/0xd68B76Bdf8E95387208A713b8b40414CB4f36CE6) |
| AzethOracle | `0xA525109A04CbC7A61Bf55b3da0f76093cC7B5492` | [View](https://sepolia.basescan.org/address/0xA525109A04CbC7A61Bf55b3da0f76093cC7B5492) |

### External Contracts

| Contract | Address |
|---|---|
| ERC-8004 Identity Registry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
| ERC-8004 Reputation Registry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
| EntryPoint v0.7 | `0x0000000071727De22E5E9d8BAf0edAc6f37da032` |
| USDC (testnet) | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |

## Deployed Addresses (Ethereum Sepolia)

| Contract | Address | Etherscan |
|---|---|---|
| AzethFactory | `0x83f780Dc2367A1F62134f70b3e454bC5de8030e5` | [View](https://sepolia.etherscan.io/address/0x83f780Dc2367A1F62134f70b3e454bC5de8030e5) |
| AzethAccount (impl) | `0x75968416F4200D8FB2276d5aA3b385De9C95AfFf` | [View](https://sepolia.etherscan.io/address/0x75968416F4200D8FB2276d5aA3b385De9C95AfFf) |
| GuardianModule | `0xD45b1653a1BcFd5b0B1bD8b6d46670a0DCeDb318` | [View](https://sepolia.etherscan.io/address/0xD45b1653a1BcFd5b0B1bD8b6d46670a0DCeDb318) |
| TrustRegistryModule | `0xe4d53d9576a13b44751C7767e747f886FaC8FFa0` | [View](https://sepolia.etherscan.io/address/0xe4d53d9576a13b44751C7767e747f886FaC8FFa0) |
| PaymentAgreementModule | `0x582A4A19D9F9F9ed0521B30F53352A6DA9F38419` | [View](https://sepolia.etherscan.io/address/0x582A4A19D9F9F9ed0521B30F53352A6DA9F38419) |
| ReputationModule | `0xd68B76Bdf8E95387208A713b8b40414CB4f36CE6` | [View](https://sepolia.etherscan.io/address/0xd68B76Bdf8E95387208A713b8b40414CB4f36CE6) |
| AzethOracle | `0xA525109A04CbC7A61Bf55b3da0f76093cC7B5492` | [View](https://sepolia.etherscan.io/address/0xA525109A04CbC7A61Bf55b3da0f76093cC7B5492) |
| TrustL2Reader | `0xf53F234Bf12D113D420d6D6ba96b2FA78aeD889E` | [View](https://sepolia.etherscan.io/address/0xf53F234Bf12D113D420d6D6ba96b2FA78aeD889E) |

### External Contracts

| Contract | Address |
|---|---|
| ERC-8004 Identity Registry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
| ERC-8004 Reputation Registry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
| EntryPoint v0.7 | `0x0000000071727De22E5E9d8BAf0edAc6f37da032` |
| USDC (testnet) | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |

---

## Module Overview

### AzethFactory

Deploys smart accounts via CREATE2 (deterministic addresses). A single atomic transaction deploys the proxy, installs all four modules, optionally registers on the trust registry, and permanently revokes factory access.

### GuardianModule (Validator)

On-chain spending guardrails enforced on every transaction:

- **Per-transaction USD limit** — rejects operations above the threshold
- **Daily spend limit** — tracks cumulative USD spend per 24-hour epoch
- **Token whitelist** — only approved tokens can be spent by executor modules
- **Protocol whitelist** — only approved contracts can be called
- **Guardian co-signatures** — required for operations above standard limits or during stale oracle conditions
- **Timelocked changes** — loosening guardrails requires a 24-hour timelock; tightening is instant
- **Emergency withdrawal** — 1-hour timelock to a pre-registered address

### TrustRegistryModule (Executor)

Manages participant identity on the ERC-8004 trust registry. Handles registration and metadata updates, routing calls through the smart account so the account owns its identity token.

### PaymentAgreementModule (Executor)

Recurring machine-to-machine payments. Agreements specify payee, token, amount, interval, and optional caps. Anyone can trigger execution when an interval elapses (permissionless keeper pattern). Guardian limits are enforced on every execution.

### ReputationModule (Executor + Hook)

Payment-gated reputation. As a hook, it intercepts every transfer to track payment deltas between accounts. As an executor, it routes reputation opinions to the ERC-8004 Reputation Registry. You can only rate agents you've paid, and your opinion weight scales with how much you spent.

### AzethOracle

Chainlink-compatible (AggregatorV3) price feeds for USD normalization. Converts token amounts to 18-decimal USD for guardian limit enforcement and reputation weighting.

### TrustL2Reader (Ethereum Sepolia only)

Cross-chain reputation verifier. Reads L2 (Base Sepolia) ReputationModule state on L1 by verifying Merkle-Patricia storage proofs against the rollup state roots that OP Stack chains already post to Ethereum — no bridges, no oracles. Proof submission is permissionless; proven payment deltas feed into cross-chain reputation aggregation.

---

## Security Model

- **Non-custodial** — Azeth never holds signing keys or funds. Factory access is permanently revoked after account creation.
- **On-chain enforcement** — All spending limits, whitelists, and timelocks are enforced by smart contracts. The SDK and MCP tools are convenience layers.
- **Payment-gated reputation** — Cannot be inflated without spending real money that flows to the target.
- **Timelock protection** — Loosening guardrails requires 24 hours. Emergency withdrawal requires 1 hour.
- **Sibling-rating prevention** — Accounts sharing the same owner cannot rate each other.
- **Oracle staleness fallback** — Stale price feeds trigger guardian co-signature requirements rather than hard blocks.

---

## Standards

| Standard | How Azeth Uses It |
|---|---|
| [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) | Smart accounts with UserOperations and gas sponsorship |
| [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579) | Modular smart account architecture (validators, executors, hooks) |
| [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) | Trust registry for identity and reputation |
| [x402](https://www.x402.org/) | HTTP-native machine-to-machine payments |
| [ERC-3009](https://eips.ethereum.org/EIPS/eip-3009) | USDC gasless transfer authorization |
| [XMTP v3](https://xmtp.org/) | Encrypted agent-to-agent messaging |

---

## Configuration

URL: https://azeth.ai/docs/configuration
Summary: Environment variables and configuration for all Azeth packages.

# Configuration

Azeth uses environment variables for configuration. On testnet, only a private key is required to get started.

---

## Essential Variables

| Variable | Required | Description |
|---|---|---|
| `AZETH_PRIVATE_KEY` | Yes | Owner private key (0x-prefixed hex). Never commit this. |
| `AZETH_CHAIN` | No | `baseSepolia` (default), `ethereumSepolia`, `base`, or `ethereum`. |
| `PIMLICO_API_KEY` | Mainnet only | Pimlico bundler API key. On testnet, the Azeth server proxies bundler requests. Free tier at [dashboard.pimlico.io](https://dashboard.pimlico.io). |

---

## Configuration by Use Case

### AI Agent (MCP)

Testnet (minimum):

```bash
AZETH_PRIVATE_KEY=0x...
```

Production:

```bash
AZETH_PRIVATE_KEY=0x...
PIMLICO_API_KEY=pim_...
AZETH_CHAIN=base
XMTP_ENCRYPTION_KEY=$(openssl rand -hex 32)  # For persistent messaging
```

### SDK

```typescript
const kit = await AzethKit.create({
  privateKey: '0x...',
  chain: 'baseSepolia',
});
```

For mainnet, set `PIMLICO_API_KEY` or pass `bundlerUrl` directly.

### CLI

```bash
AZETH_PRIVATE_KEY=0x...
PIMLICO_API_KEY=pim_...  # Required for mainnet
```

The CLI also accepts `--chain`, `--rpc-url`, and `--server-url` flags.

### Guardian Co-Signing

```bash
AZETH_GUARDIAN_KEY=0x...           # Guardian private key (optional)
AZETH_GUARDIAN_AUTO_SIGN=true      # Auto-sign operations (default: false)
```

Having `AZETH_GUARDIAN_KEY` does **not** auto-enable co-signing. You must also set `AZETH_GUARDIAN_AUTO_SIGN=true` for the guardian to automatically approve operations.

### Service Provider

```bash
AZETH_PRIVATE_KEY=0x...
PIMLICO_API_KEY=pim_...
X402_PAY_TO=0x...                              # Your payment address
X402_PRICE_FEED_PRICE=$0.05                    # Price per request
```

---

## Optional Variables

| Variable | Default | Description |
|---|---|---|
| `AZETH_RPC_URL_BASE_SEPOLIA` | Public RPC | Custom RPC for Base Sepolia |
| `AZETH_RPC_URL_ETH_SEPOLIA` | Public RPC | Custom RPC for Ethereum Sepolia |
| `AZETH_RPC_URL_BASE` | Public RPC | Custom RPC for Base mainnet |
| `AZETH_RPC_URL_ETHEREUM` | Public RPC | Custom RPC for Ethereum mainnet |
| `AZETH_SERVER_URL` | `https://api.azeth.ai` | Azeth API server URL |
| `AZETH_BUNDLER_URL` | Auto from `PIMLICO_API_KEY` | Override bundler URL |
| `XMTP_ENCRYPTION_KEY` | None | Required for persistent XMTP messaging |
| `XMTP_ENV` | `production` | XMTP network: `production` or `dev` |

---

## Security Notes

- **Never commit** private keys to version control. Use `.env` files (gitignored) or a secrets manager.
- Use a hardware wallet or secure key management for production.
- Don't reuse mainnet keys on testnet.
- The CLI reads private keys from environment variables only — never from command-line flags.

---