What is .well-known/x402? Standardizing Machine-Readable Pricing & Discovery for AI Agents

The internet is undergoing a quiet, tectonic shift. For thirty years, web pages and API pricing models were designed exclusively for humans: visual landing pages, tiered monthly SaaS subscriptions, credit-card checkout forms, and manual API key dashboards. But when the consumer of an API is an autonomous AI agent, this entire paradigm breaks down.

An autonomous agent powered by Claude, OpenAI, or an open-weights model cannot fill out a credit card form, pass a CAPTCHA, or commit to a $50/month subscription just to fetch three real-time market data points. Nor can an agent infer cost by parsing decorative HTML pricing tables.

To make machine-to-machine commerce truly frictionless, agents require a standardized, declarative, and machine-readable method to proactively discover paid capabilities, understand exact pricing, and identify accepted settlement rails before initiating a request.

This is the exact problem that .well-known/x402 solves.

1. The Foundation: RFC 8615 and Well-Known URIs

In internet architecture, RFC 8615 defines the concept of "Well-Known Uniform Resource Identifiers (URIs)". It reserves the prefix /.well-known/ on host servers to facilitate discovery of site-wide metadata, security policies, and authorization protocols (such as /.well-known/oauth-authorization-server, /.well-known/assetlinks.json, or /.well-known/jwks.json).

The .well-known/x402 specification builds on this proven standard. By placing a standardized JSON manifest at the root path (https://<domain>/.well-known/x402.json), any host, API provider, or Model Context Protocol (MCP) server can broadcast its machine-to-machine commerce capabilities to any visiting agent or LLM runtime.

2. Anatomy of a .well-known/x402.json Manifest

In the authentic x402 specification, endpoints publish their payment requirements using x402Version and an accepts[] array detailing the cryptographic scheme ("exact"), target network (e.g. "base" or "eip155:8453"), asset contract address, payment recipient (payTo), and price in atomic token units.

Below is a production example of a machine-readable discovery manifest:

{
  "x402Version": 1,
  "openapi": "/openapi.json",
  "resources": [
    {
      "path": "/v1/sentiment/latest",
      "method": "GET",
      "description": "Real-time AI market sentiment index for Top 100 assets.",
      "accepts": [
        {
          "scheme": "exact",
          "network": "base",
          "maxAmountRequired": "2000",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x209693B3306915E2827104bB5cDE2D1181283626",
          "resource": "/v1/sentiment/latest",
          "description": "Real-time AI sentiment query",
          "maxTimeoutSeconds": 60,
          "extra": {
            "name": "USD Coin",
            "version": "2"
          }
        }
      ]
    },
    {
      "path": "/v1/orderbook/depth",
      "method": "POST",
      "description": "Cross-exchange synthesized orderbook depth query.",
      "accepts": [
        {
          "scheme": "exact",
          "network": "base",
          "maxAmountRequired": "5000",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x209693B3306915E2827104bB5cDE2D1181283626",
          "resource": "/v1/orderbook/depth",
          "description": "Synthesized orderbook query",
          "maxTimeoutSeconds": 60,
          "extra": {
            "name": "USD Coin",
            "version": "2"
          }
        }
      ]
    }
  ]
}

Schema Field Breakdown

3. Why Proactive Discovery Beats Reactive HTTP 402 Errors

Under traditional HTTP 402 Payment Required architectures, a client makes a blind request to a protected URL, receives a 402 status code with a payment challenge (such as a Lightning invoice or smart contract quote), pays the invoice, and replays the request with a proof token.

While reactive 402 negotiation is essential during the payment execution phase, relying solely on trial-and-error errors creates serious limitations for autonomous agents:

• Agent Budget Planning: Multi-step autonomous agent planners (like LangChain agents, AutoGen swarms, or Claude Tool Calling) need to calculate the total estimated cost of executing an entire execution graph before calling tools.
• Eliminating Wasted Round-Trips: Proactively inspecting .well-known/x402.json allows the agent runtime to evaluate its wallet balance, compare alternate tool providers, and filter out overpriced APIs without issuing failing HTTP requests.
• Automated Tool Manifest Generation: AI frameworks can parse .well-known/x402.json combined with openapi.json to dynamically synthesize Model Context Protocol (MCP) tool bindings at runtime.

4. The 4-Step Autonomous Transaction Lifecycle

How an autonomous agent interacts with a .well-known/x402 enabled API in production, from capability discovery to non-custodial settlement:

5. Enabling Developer & Creator Monetization

For decades, the hurdle of merchant accounts, Stripe Atlas fees, international banking regulations, and credit card chargeback risks kept millions of developers and data creators from monetizing their work.

With .well-known/x402 and non-custodial agent payment rails:

• Any script becomes a paid business: An indie developer with a Python script scraping flight delays, clean weather models, or specialized trading indicators can spin up an endpoint, attach an x402 manifest, and earn streaming revenue from agents globally.
• Zero Platform Custody: Payments settle directly into the creator's personal Base EVM address (USDC) or Lightning node with zero middleman hold periods. See our detailed guide on non-custodial direct settlements.
• True Micropayments: When fees are $0.001 to $0.05 per request, agents can consume data granularly without lock-in subscriptions.

6. Implementation Example: Serving & Consuming x402

You can implement x402 discovery and payments today using the open-source payagents npm package and the PayAgents GitHub repositories.

Serving an x402 API with Node.js / Express

Install the SDK with npm install payagents. The middleware automatically handles serving the .well-known/x402.json manifest, issuing HTTP 402 challenges with the canonical Payment-Required base64 header, and validating incoming cryptographic proofs:

import express from 'express';
import { payagentsMiddleware } from 'payagents/server';

const app = express();

// Automatically serves /.well-known/x402.json & gates routes with x402 + L402
app.use(payagentsMiddleware({
  name: "Exchange Rate Oracle",
  receiver: {
    evmAddress: "0x209693B3306915E2827104bB5cDE2D1181283626", // Base USDC direct receiving
    lightningAddress: "alphafeed@getalby.com"                // L402 Lightning node
  },
  routes: [
    {
      path: "/v1/rates",
      method: "GET",
      price: "0.002 USD",
      rails: ["x402", "l402"]
    }
  ]
}));

app.get('/v1/rates', (req, res) => {
  res.json({ BTC_USD: 65420.50, ETH_USD: 3480.10, updated_at: new Date().toISOString() });
});

app.listen(3000, () => console.log('x402 Server running on port 3000'));

Building Model Context Protocol tools? Check out our dedicated guide on Monetizing MCP Servers with payagents-mcp.

Consuming with an Autonomous AI Agent

On the client agent side (or within Claude Desktop / Cursor MCP), calling a paid endpoint is transparent. The PayAgents client automatically reads .well-known/x402, verifies policy constraints, and signs the required transfer authorization:

import { PayAgents } from 'payagents';

const agent = new PayAgents({ apiKey: process.env.PAYAGENTS_API_KEY });

// The client automatically inspects .well-known/x402, verifies policy, and settles
const response = await agent.pay('https://api.oracle.io/v1/rates', {
  maxBudget: '0.01 USD', // Hard safety ceiling
  rail: 'auto'          // Automatically picks fastest/cheapest rail (Base USDC or Lightning)
});

console.log('Data received from agent-paid API:', response.data);

7. The Future of Open Machine Commerce

We are moving from a human-driven web of banners and paywalls to a machine-driven web of autonomous agents negotiating value in milliseconds.

By embracing open standards like .well-known/x402, developers and API creators are not just adding a payment button—they are building the foundational infrastructure for the entire agentic economy.

To get started, explore the Live Interactive Demo, check out the PayAgents GitHub, or jump into our Developer Documentation.