| name | authoring-specs |
| description | Guidelines for authoring x402 specification files. Use when writing or proposing a new x402 spec, such as a per-network scheme spec (scheme_<name>_<chain>.md). |
Authoring x402 specs
Guidance for writing x402 specification files under specs/. Use RFC-2119 keywords for normative statements (MUST / MUST NOT, SHOULD / SHOULD NOT, MAY).
General rules
These apply to every spec type (scheme, extension). The references below add type-specific detail.
Naming
- Name schemes and extensions in lowercase, hyphen-separated kebab-case (e.g.
batch-settlement, offer-receipt), never camelCase.
Protocol version, networks, and units
- Target protocol v2 only:
x402Version: 2, the amount field (not v1's maxAmount), and the PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE headers (not v1's X-PAYMENT / X-PAYMENT-RESPONSE). See the v1 to v2 migration guide.
- Use canonical CAIP-2 network notation (e.g.
eip155:84532, not base-sepolia).
- Use atomic units for all amounts.
Wire format
- Be transport agnostic: specify message contents, not how a particular transport carries them.
- Reference core types (
PaymentRequirements, PaymentPayload, SettlementResponse) from x402-specification-v2.md.
- Every field a spec defines on the wire must be consumed by a downstream role. Do not include human-readable or otherwise purely informational fields.
- Reuse field names, patterns, and conventions established by existing specs instead of coining new ones.
References
