Skip to main content
pay.json is an open standard that tells AI agents what content costs and how to pay before they request it. Publishers serve it at /.well-known/pay.json. The current version of the specification is v1.2, and validators that follow it reject older files. The WordPress and Joomla plugins serve pay.json for you. For other sites, generate the file and host it yourself.

Quick start

Generate a pay.json file with your own wallet:
--wallet sets both seller_wallet and receiver. With Xenarch, both are your own wallet, because USDC goes straight to you with no contract in between. Other options: --receiver, --protocol (default x402), --network (default base), --asset (default USDC), --facilitators, --verifier and --provider. Serve the file at https://yourdomain.com/.well-known/pay.json over HTTPS with Content-Type: application/json.

Specification (v1.2)

Required fields

Optional fields

Each rule has path and price_usd (a decimal string such as "0.003"). A rule may also carry terms (what one payment buys, for example {"type": "per_request"}) and budget_hints (suggested agent caps). v1.2 replaced the single-string facilitator field of earlier versions with the facilitators array.

Example

This is the example from the specification:

Pricing rules

Rules are evaluated top to bottom. The first match wins.
This is how agents read pay.json. The Xenarch platform resolves the price of a gate differently: when several dashboard rules match a URL, the longest pattern wins. Keep the two in agreement by listing specific rules before catch-all rules.

Glob patterns

Special values

  • "0" or "0.00": explicitly free
  • No matching rule: the path is free
  • No pay.json file: the whole site is free

Validation

Checks JSON syntax and schema compliance, and warns when a wildcard rule shadows a more specific rule listed after it.

Discovery priority

Agents should discover pricing in this order:
  1. pay.json at /.well-known/pay.json: the most authoritative source
  2. Meta tag <meta name="x402" content="price=0.003&wallet=0x...&network=base&protocol=x402">: fallback for HTML pages
  3. HTTP 402 response: the server returns payment terms
Agents must not combine pricing from several sources.

Packages

JavaScript (validator and generator):
Python (reader):
Source and full specification: github.com/xenarch-ai/pay-json