OpenParable
Skip to content
← Back to skills

Authoring Specs

Documents
authoring-specs

Authoring Specs is an Agent Skill for documents published in the x402-foundation/x402 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/x402-foundation/x402/blob/HEAD/.agents/skills/authoring-specs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/authoring-specs, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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