Concepts

The manifest

A single JSON file at /.well-known/agents402.json that declares everything an agents402 publisher offers. Cacheable, versioned, signed by the publisher's service key.

Purpose

The manifest is the published API surface of an agents402 publisher. It exists so an agent can answer four questions with a single GET:

·What does this site sell?
·How much does each thing cost?
·What inputs does each action expect?
·How do I verify the receipts I get back?

Everything else — auth, payment, retry — is consequence. The manifest is the only file an agent needs to read before deciding whether to engage with a publisher at all.

Shape

/.well-known/agents402.json

json

{
  "version": "0.1",
  "service": { … },
  "actions": [ … ],
  "receipts": {
    "pubkey_hex": "302a300506032b6570032100…",
    "algorithm":  "ed25519"
  }
}

service

Field	Type	Required	Description
`name`	string	yes	Display name shown to the user when the agent reports spend.
`description`	string	no	Short summary of what the publisher offers, used for log lines.
`homepage`	url	yes	Canonical site URL — the agent uses this to compute trust against domain heuristics.
`lightning_address`	string	no	Optional human-pingable LN address for ad-hoc top-ups or grants.

actions[]

Each action is a fixed-price unit of agent-buyable work. The schema is:

Field	Type	Required	Description
`id`	string	yes	Stable identifier. Recommended dotted form like `category.thing`.
`type`	enum	yes	One of `web_access`, `structured_data`, `site_agent_query`, `verification`.
`endpoint`	url	yes	Absolute URL the agent POSTs to. Returns 402 first, 200 after payment.
`price_msats`	integer ≥ 0	yes	Fixed price per call. Use millisatoshis for sub-cent pricing.
`input_schema`	JSON Schema	no	Deterministic input shape; the agent validates before paying.
`risk`	enum	no	One of `low`, `medium`, `high`. Steers agent policy.

▲Action ids are commitments

Once published, an action id should mean a stable contract. Renaming an id breaks reputation and audit trails for downstream agents. Add a new action and deprecate the old one instead.

receipts

The publisher commits to an Ed25519 signing key. Every receipt is signed with that key; agents verify the signature using the public key from the manifest. Rotating the key is allowed but should be rare — existing receipts must remain verifiable, so old keys should be retained until the receipts referencing them have aged out of any downstream reputation system.

Discovery rules

·The manifest path is /.well-known/agents402.json on the canonical host. No other paths are honored.
·The response must be served with Content-Type: application/json and Access-Control-Allow-Origin: *.
·Caches should respect Cache-Control on the response. Recommended: no-store during early pilots; tighten later.
·A 404 on the manifest path means “the publisher does not support agents402.” Agents must not infer support from any other signal.

Actions

The unit of buyable work — types, pricing, and side effects.

→

agents402.org / 2026

Open protocol · v0.1