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:

x402 Payment — one-time payment per request (EOA signs ERC-3009)
Smart Account Payment — one-time payment routed through a smart account (guardian guardrails enforced)
SIWx Session — wallet signature proves prior payment (no additional payment needed)
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.

pnpm add @azeth/provider

You can also use the raw @x402/* packages directly if you prefer — see Manual Setup below.

Quick Setup with `@azeth/provider`

Define your paid routes and call createX402StackFromEnv():

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:

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

Route Configuration

Declare which endpoints require payment:

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

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.

{
  "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