Skip to content

WELL_KNOWN_SPEC.md

Latest commit

 

History

History
45 lines (32 loc) · 1.71 KB

WELL_KNOWN_SPEC.md

File metadata and controls

45 lines (32 loc) · 1.71 KB

FairAd well-known manifest specification

This document defines the FairAd manifest as a well-known URI per RFC 8615 (Well-Known Uniform Resource Identifiers).

Location

Merchants MUST serve the FairAd manifest at:

https://<domain>/.well-known/fairad.json
  • Scheme: HTTPS required in production (RFC 2818 / RFC 9110).
  • Path: Exactly /.well-known/fairad.json (RFC 8615 well-known prefix).
  • Content-Type: application/json (RFC 8259) recommended.

Schema

Field Type Required Description
mcp_endpoint string (URL) Yes Full URL of the Merchant MCP server (e.g. https://shop.example.com/mcp).
public_key string Yes Base64-encoded Ed25519 public key used to verify Payment Commitments.
bidding_categories array of strings Yes At least one category the merchant bids on (e.g. ["electronics", "apparel"]).
currency string No (default: USD) ISO 4217 currency code.
min_bid string Yes Minimum bid amount in the smallest currency unit (e.g. cents for USD).

Additional fields are not defined by this spec; consumers should ignore unknown keys.

Example

{
  "mcp_endpoint": "https://shop.example.com/mcp",
  "public_key": "J2nlmFsgoUtF3Avdmkt...",
  "bidding_categories": ["electronics", "apparel", "home"],
  "currency": "USD",
  "min_bid": "100"
}

Discovery

Agents or crawlers may request this URL for any domain. A 200 OK response with valid JSON and required fields indicates a FairAd-enabled merchant. Invalid or missing manifest (4xx, 5xx, or invalid schema) means the domain should not be treated as a FairAd merchant.