Skip to main content
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

FieldTypeDescription
versionstringMust be "1.0"
protocolstringPayment protocol (e.g., "x402")
networkstringBlockchain network (e.g., "base")
assetstringPayment token (e.g., "USDC")
receiverstringSplitter contract address (0x + 40 hex)
seller_walletstringPublisher wallet address (0x + 40 hex)
rulesarrayOrdered list of path-to-price rules (min 1)

​
Optional fields

FieldTypeDescription
providerstringPayment infrastructure provider
facilitatorstringVerification endpoint URL
contactstringPublisher contact
termsstringTerms of service URL
toolsobjectCLI, 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

PatternMatchesExample
*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:
  1. pay.json at /.well-known/pay.json — most authoritative
  2. Meta tag <meta name="x402" content="supported"> — fallback
  3. HTTP 402 response — server returns payment instructions
  4. 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