pay.json

pay.json is an open standard that lets AI agents discover what content costs and how to pay before making a request. Publishers serve it at /.well-known/pay.json.

Quick start

Generate a pay.json file:

npx pay-json-generate \
  --wallet 0xYOUR_WALLET \
  --receiver 0xC6D3a6B6fcCD6319432CDB72819cf317E88662ae \
  --price 0.003 \
  --provider xenarch \
  --output .well-known/pay.json

Serve it at https://yourdomain.com/.well-known/pay.json.

Specification (v1.0)

Required fields

Field	Type	Description
`version`	string	Must be `"1.0"`
`protocol`	string	Payment protocol (e.g., `"x402"`)
`network`	string	Blockchain network (e.g., `"base"`)
`asset`	string	Payment token (e.g., `"USDC"`)
`receiver`	string	Splitter contract address (`0x` + 40 hex)
`seller_wallet`	string	Publisher wallet address (`0x` + 40 hex)
`rules`	array	Ordered list of path-to-price rules (min 1)

Optional fields

Field	Type	Description
`provider`	string	Payment infrastructure provider
`facilitator`	string	Verification endpoint URL
`contact`	string	Publisher contact
`terms`	string	Terms of service URL
`tools`	object	CLI, SDK, and docs hints

Example

{
  "version": "1.0",
  "protocol": "x402",
  "network": "base",
  "asset": "USDC",
  "receiver": "0xC6D3a6B6fcCD6319432CDB72819cf317E88662ae",
  "seller_wallet": "0xabcdef1234567890abcdef1234567890abcdef12",
  "provider": "xenarch",
  "facilitator": "https://xenarch.dev/v1/gates",
  "tools": {
    "cli": {
      "install": "npm install -g xenarch",
      "usage": "xenarch pay <url>"
    },
    "sdk": {
      "npm": "xenarch",
      "pypi": "xenarch"
    },
    "docs": "https://docs.xenarch.com"
  },
  "rules": [
    { "path": "/public/*", "price_usd": "0" },
    { "path": "/blog/*", "price_usd": "0.003" },
    { "path": "/premium/*", "price_usd": "0.01" },
    { "path": "/api/*", "price_usd": "0.05" },
    { "path": "/**", "price_usd": "0.003" }
  ]
}

Pricing rules

Rules are evaluated top-to-bottom. First match wins.

Glob patterns

Pattern	Matches	Example
`*`	Single path segment (no `/`)	`/blog/*` matches `/blog/post` but not `/blog/2024/post`
`**`	Multiple segments (including `/`)	`/blog/**` matches `/blog/2024/post`
`?`	Exactly one character	`/api/v?/data` matches `/api/v1/data`

Special values

"0" or "0.00" — explicitly free
No matching rule — path is free
No pay.json file — entire site is free

Validation

npx pay-json-validate path/to/pay.json

Validates JSON syntax, schema compliance, and lints for rule ordering issues (e.g., wildcard rules that shadow more specific rules).

# Quiet mode (exit code only)
npx pay-json-validate pay.json --quiet

# JSON output
npx pay-json-validate pay.json --json

Discovery priority

Agents should discover pricing in this order:

pay.json at /.well-known/pay.json — most authoritative
Meta tag <meta name="x402" content="supported"> — fallback
HTTP 402 response — server returns payment instructions
Free — no pricing signals found

Agents must not combine pricing from multiple sources.

npm package

npm install pay-json

Source: github.com/xenarch-ai/pay-json

Getting Started

MCP Server

Smart Contract

Integrations

Examples

Quick start

Specification (v1.0)

Required fields

Optional fields

Example

Pricing rules

Glob patterns

Special values

Validation

Discovery priority

npm package

​Quick start

​Specification (v1.0)

​Required fields

​Optional fields

​Example

​Pricing rules

​Glob patterns

​Special values

​Validation

​Discovery priority

​npm package

Quick start

Specification (v1.0)

Required fields

Optional fields

Example

Pricing rules

Glob patterns

Special values

Validation

Discovery priority

npm package