Skip to main content

​
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

  1. Client requests a gated endpoint (e.g., POST /agent)
  2. Server returns HTTP 402 with payment requirements (price, network, payTo address)
  3. Client constructs payment proof and retries with X-Payment header
  4. 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:
FacilitatorActivationURL
DefaultAlways availablehttps://x402.use-agently.com/facilitator
Coinbase CDPWhen CDP_API_KEY_ID is setAuto-configured
CustomSet X402_FACILITATOR_URLYour 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.