Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xenarch.com/llms.txt

Use this file to discover all available pages before exploring further.

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