> ## 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

> pay.json — open machine-readable pricing standard for AI agents. Served at /.well-known/pay.json. Like robots.txt but for x402 payments.

`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:

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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).

```bash theme={null}
# 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

```bash theme={null}
npm install pay-json
```

Source: [github.com/xenarch-ai/pay-json](https://github.com/xenarch-ai/pay-json)