x402 Payments

Overview

x402 is a payment protocol for HTTP resources. When a client requests a payment-gated endpoint, the server responds with HTTP 402 and payment requirements. The client includes a payment proof in the X-Payment header, and the server verifies it via a facilitator before granting access. In aixyz, AixyzApp uses a PaymentGateway to provide built-in payment gating for agent and tool endpoints.

How It Works

Client requests a gated endpoint (e.g., POST /agent)
Server returns HTTP 402 with payment requirements (price, network, payTo address)
Client constructs payment proof and retries with X-Payment header
Server verifies payment via a facilitator and grants access

The `accepts` Export

Define payment requirements by exporting accepts from your agent or tool:

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005",
};

This gates the endpoint behind a $0.005 exact payment.

With Overrides

export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005",
  network: "eip155:8453", // override config network
  payTo: "0x...", // override config payTo
};

Prices are USD strings: "$0.005", "$0.01", "$0.0001".

Per-Agent and Per-Tool Pricing

Agents and tools can each declare their own accepts export, enabling granular pricing:

// app/agent.ts — agent-level pricing
export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.01",
};

// app/tools/premium-search.ts — tool-level pricing
export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.001",
};

Agent accepts gates the A2A /agent endpoint
Tool accepts gates the tool on the MCP /mcp endpoint
Agents and tools without accepts are not registered on protocol endpoints

Facilitators

Payment verification is handled by a facilitator service:

Facilitator	Activation	URL
Default	Always available	`https://x402.use-agently.com/facilitator`
Coinbase CDP	When `CDP_API_KEY_ID` is set	Auto-configured
Custom	Set `X402_FACILITATOR_URL`	Your custom URL

Custom Facilitator

Create app/accepts.ts to provide a custom facilitator:

app/accepts.ts

import { HTTPFacilitatorClient } from "aixyz/accepts";

export const facilitator = new HTTPFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL ?? "https://x402.use-agently.com/facilitator",
});

Server Integration

In a custom server, register payment-gated routes via route():

server.route("POST", "/agent", handler, {
  payment: { scheme: "exact", price: "$0.005" },
});

Payments

How to configure payments in your agent.

ERC-8004 Identity

On-chain agent identity for verified payments.

Getting Started

CLI

Config

File-system layout

Functions

Protocols

x402 Payments

Overview

How It Works

The `accepts` Export

With Overrides

Per-Agent and Per-Tool Pricing

Facilitators

Custom Facilitator

Server Integration

Payments

ERC-8004 Identity

​Overview

​How It Works

​The accepts Export

​With Overrides

​Per-Agent and Per-Tool Pricing

​Facilitators

​Custom Facilitator

​Server Integration

Payments

ERC-8004 Identity

Overview

How It Works

The `accepts` Export

With Overrides

Per-Agent and Per-Tool Pricing

Facilitators

Custom Facilitator

Server Integration