@402mdvaleo/agent

Make AI agents 402.md-aware. Discover pricing manifests and pay for content automatically.

Install

npm install @402mdvaleo/agent

Quick Start

import { check402 } from "@402mdvaleo/agent";

// Check if a site has pricing
const manifest = await check402("example.com");

if (manifest) {
  console.log(`${manifest.domain} charges for ${manifest.endpoints.length} endpoints`);
  console.log(`Cheapest: ${manifest.endpoints[0].price}`);
  console.log(`Network: ${manifest.network}`);
  console.log(`Facilitator: ${manifest.facilitator}`);
}

Auto-Paying Fetch

import { createPaidFetcher } from "@402mdvaleo/agent";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const wallet = createWalletClient({
  account: privateKeyToAccount("0x..." as `0x${string}`),
  chain: base,
  transport: http(),
});

const paidFetch = createPaidFetcher({
  wallet,
  maxPriceMicros: 50_000, // Max $0.05 per request
  onPaymentMade: (endpoint, url) => {
    console.log(`Paid ${endpoint.price} for ${url}`);
  },
});

// Works like normal fetch — but pays when needed
const response = await paidFetch("https://example.com/api/data");
const data = await response.json();

Check a Specific URL

import { checkUrl } from "@402mdvaleo/agent";

const match = await checkUrl("https://example.com/api/data");

if (match) {
  console.log(`This URL costs ${match.endpoint.price}`);
  console.log(`Proxy: ${match.proxyUrl}`);
}

Configuration

const manifest = await check402("example.com", {
  timeout: 3000,
  checkDirect: true,
  checkRegistry: true,
  useCache: true,
  registryUrl: "https://402md.valeoprotocol.io",
});

How It Works

1. Discovery: check402() fetches https://domain.com/402.md (self-hosted) and falls back to https://402md.valeoprotocol.io/m/domain.com/raw (registry).

2. Parsing: The YAML frontmatter is parsed to extract endpoints, pricing, wallet address, network, and facilitator.

3. Matching: checkUrl() matches a specific URL path against the manifest's endpoint patterns (exact, *, and ** globs).

4. Payment: createPaidFetcher() wraps fetch() to detect 402 responses and pay via the 402md proxy or x402 with a configured wallet.

What is 402.md?

402.md is an open standard for machine-readable pricing manifests. Websites place a 402.md file at their root to tell AI agents what their content costs.

Learn more: https://402md.valeoprotocol.io