402.md Specification v1.0
A machine-readable pricing manifest for AI agents and payment-aware clients.
1. File Location
The file MUST be located at the root of a domain:
https://example.com/402.md
Optionally, a JSON variant can also be served:
https://example.com/402.json
2. File Format
The 402.md file uses YAML frontmatter (delimited by ---) followed by an optional human-readable description in Markdown.
3. Required Fields
| Field | Type | Description |
|---|---|---|
| version | "1.0" | Literal string. Currently only 1.0. |
| owner | string | Generic identifier (wallet address, ENS name, etc.). Min 1 character. |
| network | enum | One of: base, base-sepolia, solana-mainnet, solana-devnet |
| endpoints | Endpoint[] | Array of endpoint definitions. At least one required. |
4. Optional Fields
| Field | Type | Description |
|---|---|---|
| facilitator | URL | Payment verification service URL. |
| contact | Contact email for support. | |
| content | object | Content pricing defaults. |
| policies | object | Terms, refunds, budgets. |
| metadata | object | Title, description, image, category. |
5. Endpoint Schema
| Field | Type | Description |
|---|---|---|
| path | string | Required. Must start with /. Supports glob patterns. |
| method | enum | Optional. GET, POST, PUT, PATCH, DELETE. Default: "GET". |
| price | string | Required. USD notation: "$X.XX" up to 6 decimal places. |
| currency | string | Optional. Default: "USDC". Currently only USDC. |
| description | string | Optional but strongly recommended. |
| rate_limit | string | Optional. Format: "100/min". |
| tags | string[] | Optional. Array of category tags. |
| content_type | string | Optional. Response MIME type. |
| auth_required | boolean | Optional. Default: false. |
6. Price Format
Prices MUST be in USD notation: $X.XX with up to 6 decimal places.
$0.01— one cent$0.001— one-tenth of a cent$0.000001— one micro-dollar (smallest unit)
Internally, prices are stored as integer micros (1 micro = $0.000001) to avoid floating-point issues.
7. Content Schema
| Field | Type | Description |
|---|---|---|
| default_price | $X.XX | Default price for pages not listed in endpoints. |
| free_paths | string[] | Paths that are always free. |
| docs_url | URL | Link to API documentation. |
8. Policies Schema
| Field | Type | Description |
|---|---|---|
| refunds | string|boolean | Refund policy. |
| bulk_discount | string|boolean | Bulk pricing information. |
| max_budget_per_session | $X.XX | Suggested agent budget cap. |
| terms_url | URL | Link to terms of service. |
9. Metadata Schema
| Field | Type | Description |
|---|---|---|
| title | string | Human-readable title for the service. |
| description | string | Brief description. |
| image | URL | OG image or logo URL. |
| category | string | Service category. |
10. Validation Rules
- Unknown fields at any nesting level produce warnings, never silent drops.
- Duplicate endpoints (same method + path) produce errors.
- The
ownerfield is a generic string with no format enforcement. - The
facilitatorfield is truly optional with no default value.
11. Discovery
Agents and crawlers discover pricing by fetching /402.md at the root of any domain. If not found, they may fall back to /402.json.
The 402md registry at 402md.org indexes discovered manifests for public searchability.