{ "generated": "2026-11-13", "vocab": { "steps": [ { "id": "discover", "order": 1, "label": "Discover", "question": "What is here, and where?", "analog": "sitemap, .well-known", "definition": "How an agent learns that a resource, tool or agent exists at an origin, and where to find its description." }, { "id": "identify", "order": 2, "label": "Identify", "question": "Who is this agent? Who is this site?", "analog": "TLS certificate, WHOIS", "definition": "How an agent proves who it is to a site, and how a site or another agent proves who it is back." }, { "id": "permit", "order": 3, "label": "Permit", "question": "What may the agent do here?", "analog": "robots.txt, terms of use", "definition": "How a site states what agents may read, train on, or do, and how agents obtain authorisation to act." }, { "id": "read", "order": 4, "label": "Read", "question": "Give me the content", "analog": "HTML, RSS", "definition": "Representations of a site's content made for machine readers rather than browsers." }, { "id": "act", "order": 5, "label": "Act", "question": "Do something for me", "analog": "forms, REST APIs", "definition": "How an agent invokes a capability a site or tool exposes." }, { "id": "coordinate", "order": 6, "label": "Coordinate", "question": "Talk to another agent", "analog": "none; agent-to-agent is new", "definition": "How agents delegate to, negotiate with, and message other agents." }, { "id": "pay", "order": 7, "label": "Pay", "question": "Settle the bill", "analog": "HTTP 402, finally used", "definition": "How an agent pays for a resource, authorises a payment on a person's behalf, or completes a purchase." }, { "id": "present", "order": 8, "label": "Present", "question": "Show a human the result", "analog": "the browser", "definition": "How an agent renders output or a live interaction to a person." }, { "id": "account", "order": 9, "label": "Account", "question": "Prove what happened; be judged", "analog": "logs, audit trails", "definition": "How actions are recorded, verified after the fact, attributed and measured." } ], "parties": [ { "id": "agent-site", "label": "agent ↔ site", "definition": "An agent interacting with a website or API origin." }, { "id": "agent-agent", "label": "agent ↔ agent", "definition": "Two agents interacting directly." }, { "id": "agent-human", "label": "agent ↔ human", "definition": "An agent presenting to, or taking instruction from, a person." }, { "id": "agent-payment", "label": "agent ↔ payment network", "definition": "An agent and a payment rail, wallet, or card network." }, { "id": "agent-registry", "label": "agent ↔ registry", "definition": "An agent and a third-party index or registry." } ], "form": [ { "id": "well-known-file", "label": "well-known file", "definition": "A fixed-path file under /.well-known/ or the site root." }, { "id": "http-header", "label": "HTTP header", "definition": "A request or response header." }, { "id": "endpoint", "label": "endpoint", "definition": "An HTTP or RPC endpoint with a defined message format." }, { "id": "dns-record", "label": "DNS record", "definition": "A record type or name convention in DNS." }, { "id": "onchain-registry", "label": "on-chain registry", "definition": "A smart contract acting as a registry." }, { "id": "document-format", "label": "document format", "definition": "A file format or document convention." }, { "id": "browser-api", "label": "browser API", "definition": "A JavaScript API available to pages in a browser." } ], "track": [ { "id": "ietf", "label": "IETF", "definition": "Internet Engineering Task Force draft or RFC." }, { "id": "w3c", "label": "W3C", "definition": "W3C working or community group output." }, { "id": "linux-foundation", "label": "Linux Foundation", "definition": "A Linux Foundation project or sub-foundation." }, { "id": "industry-body", "label": "industry body", "definition": "A trade association such as IAB Tech Lab." }, { "id": "vendor-consortium", "label": "vendor consortium", "definition": "Several vendors publishing jointly without a standards body." }, { "id": "single-vendor", "label": "single vendor", "definition": "One company controls the specification." }, { "id": "community", "label": "community", "definition": "Open community project with no formal governance." }, { "id": "academic", "label": "academic", "definition": "Research output without a standards process." } ], "scope": [ { "id": "general", "label": "general", "definition": "Applies to any site or agent." }, { "id": "commerce", "label": "commerce", "definition": "Buying and selling goods or services." }, { "id": "advertising", "label": "advertising", "definition": "Ad buying, measurement, or attribution." }, { "id": "payments", "label": "payments", "definition": "Moving money." }, { "id": "coding-tools", "label": "coding tools", "definition": "Developer tooling and editors." } ], "phase": [ { "id": "idea", "label": "idea", "definition": "Proposed, no specification text." }, { "id": "draft", "label": "draft", "definition": "Specification text exists and is changing." }, { "id": "working-group", "label": "working group", "definition": "Adopted by a standards working group." }, { "id": "review", "label": "review", "definition": "In formal review or last call." }, { "id": "candidate", "label": "candidate", "definition": "Feature-complete, seeking implementations." }, { "id": "stable", "label": "stable", "definition": "Published as stable or final." }, { "id": "living", "label": "living", "definition": "Continuously updated with no versioned finals." }, { "id": "deprecated", "label": "deprecated", "definition": "Superseded or discouraged by its issuer." }, { "id": "replaced", "label": "replaced", "definition": "Replaced by a working-group or successor document." }, { "id": "withdrawn", "label": "withdrawn", "definition": "Withdrawn or archived." }, { "id": "unknown", "label": "unknown", "definition": "Not established." } ], "implementation": [ { "id": "none-found", "label": "none found", "definition": "No implementation located." }, { "id": "prototype", "label": "prototype", "definition": "Reference or experimental implementation only." }, { "id": "developer-trial", "label": "developer trial", "definition": "Behind a flag or origin trial." }, { "id": "shipping", "label": "shipping", "definition": "At least one production implementation." }, { "id": "multi-implementation", "label": "multi-implementation", "definition": "Independent production implementations from more than one party." }, { "id": "deprecated", "label": "deprecated", "definition": "Implementations being removed." }, { "id": "unknown", "label": "unknown", "definition": "Not established." } ], "adoption": [ { "id": "unmeasured", "label": "unmeasured", "definition": "Nobody has published a count." }, { "id": "claimed", "label": "claimed", "definition": "A party asserts adoption; the claimant is named." }, { "id": "observed", "label": "observed", "definition": "We or a third party have seen instances but not counted systematically." }, { "id": "measured", "label": "measured", "definition": "Counted by a documented probe run." }, { "id": "unknown", "label": "unknown", "definition": "Not established." } ], "evidence": [ { "id": "VERIFIED", "label": "verified", "definition": "Primary source, or two independent secondary sources, checked by us." }, { "id": "REPORTED", "label": "reported", "definition": "One secondary source." }, { "id": "THIN", "label": "thin", "definition": "Existence established; detail not." } ], "freshness": [ { "id": "current", "label": "current", "definition": "Verified within the review cadence." }, { "id": "review-due", "label": "review due", "definition": "Past cadence; not yet re-checked." }, { "id": "stale", "label": "stale", "definition": "Past twice the cadence." }, { "id": "source-unavailable", "label": "source unavailable", "definition": "Primary source no longer resolves." } ], "use_cases": [ { "id": "discover-my-api", "label": "Let agents discover my API or service", "definition": "Publish where an agent can find what an origin offers." }, { "id": "expose-tools-to-agents", "label": "Expose tools to agents", "definition": "Let a model call functions or actions you host." }, { "id": "let-agents-act-on-my-site", "label": "Let agents act on my website", "definition": "Forms, bookings and tasks performed by agents in a browser or via a page-level API." }, { "id": "serve-content-to-agents", "label": "Serve readable content to agents", "definition": "Give agents a machine-friendly version of pages and documents." }, { "id": "prove-agent-identity", "label": "Prove an agent's identity", "definition": "Let a server verify which agent, operator or workload is calling." }, { "id": "delegate-user-authority", "label": "Delegate a user's authority to an agent", "definition": "Scoped, revocable permission for an agent to act for a person." }, { "id": "control-ai-crawling", "label": "Control AI crawling and training use", "definition": "State what automated systems may do with your content." }, { "id": "accept-agent-payments", "label": "Accept payments from agents", "definition": "Charge an agent per request or per purchase." }, { "id": "agent-checkout", "label": "Let agents buy on behalf of a person", "definition": "Mandates, carts and checkout flows for agent purchases." }, { "id": "agent-to-agent-messaging", "label": "Let agents talk to other agents", "definition": "Discover, message and delegate between independent agents." }, { "id": "agent-naming", "label": "Name and resolve agents", "definition": "Stable names or records that resolve to an agent's endpoint." }, { "id": "render-agent-ui", "label": "Render agent output as a user interface", "definition": "Structured UI that a client renders from an agent." }, { "id": "audit-agent-actions", "label": "Audit what an agent did", "definition": "Tamper-evident records of actions and the authority behind them." }, { "id": "attribute-agent-traffic", "label": "Attribute and measure agent traffic", "definition": "Know which agents visited and what they did." }, { "id": "describe-agent-capabilities", "label": "Describe an agent's capabilities", "definition": "Cards, manifests and schemas that say what an agent can do." } ], "audience": [ { "id": "site-owner", "label": "Site or API owner", "definition": "Runs a website, API or shop that agents will use." }, { "id": "agent-builder", "label": "Agent builder", "definition": "Builds agents or the frameworks they run on." }, { "id": "platform", "label": "Platform or infrastructure", "definition": "CDNs, identity providers, payment networks, registries." }, { "id": "standards-body", "label": "Standards and policy", "definition": "People shaping or tracking the specifications themselves." } ] }, "records": [ { "acronym": "MCP", "adoption": { "level": "observed", "by": "Hugging Face, Cloudflare Docs, GitHub, Stripe, Linear, Claude, Visual Studio Code, Cursor, and 14 other verified implementations", "probe_run": null }, "aliases": [], "analog": "Language Server Protocol", "audience": [ "agent-builder", "platform", "standards-body" ], "collisions": [ "Microsoft Cloud Partner", "Master Control Program" ], "discovery": { "mechanism": "Operator-published remote URL. Optional Server Card at the recommended /server-card. Official MCP Registry is in preview.", "path": "No required path in the base protocol. server.json may name a remote server URL. Optional Server Card recommended at /server-card. Registry is in preview." }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. / The protocol uses JSON-RPC 2.0 messages to establish communication between / Version 2025-11-25 / Version 2024-11-05 / This specification defines the authoritative protocol requirements, based on the TypeScript schema in schema.ts . / Extensions are always opt-in and require explicit support from both client and server / MCP takes some inspiration from the Language Server Protocol , which standardizes how to add support for programming languages across a whole ecosystem of development tools. / The protocol uses JSON-RPC 2.0 messages to establish communication between: Hosts : LLM applications that initiate connections Clients : Connectors within the host application Servers : Services that provide context and capabilities / Expose tools and capabilities to AI systems / Skills over MCP : Rich, structured instructions for agent workflows, discovered and consumed through MCP", "ref": 1 }, { "label": "[2]", "url": "https://www.anthropic.com/news/model-context-protocol", "claim": "Anthropic, *Introducing the Model Context Protocol*, 2024-11-25", "date": "2024-11-25", "quote": "Every new data source requires its own custom implementation, making truly connected systems difficult to scale. / 2024-11-25 / It provides a universal, open standard for connecting AI systems with data sources / constrained by their isolation from data—trapped behind information silos and legacy systems. Every new data source requires its own custom implementation, making truly connected systems difficult to scale.", "ref": 2 }, { "label": "[3]", "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation", "claim": "The Linux Foundation, *Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF), Anchored by New Project Contributions Including Model Context Protocol (MCP), goose and AGENTS.md*, 2025-12-09", "date": "2025-12-09", "quote": "today announced the formation of the Agentic AI Foundation (AAIF), and founding contributions of three leading projects driving innovation in open source AI; Anthropic’s Model Context Protocol (MCP), Block's goose, and OpenAI's AGENTS.md / When we open sourced it in November 2024, we hoped other developers would find it as useful as we did / SAN FRANCISCO, Dec. 9, 2025 – The Linux Foundation , the nonprofit organization enabling mass innovation through open source, today announced the formation of the Agentic AI Foundation (AAIF) / founding contributions of three leading projects driving innovation in open source AI; Anthropic’s Model Context Protocol (MCP)", "ref": 3 }, { "label": "[4]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio", "claim": "Model Context Protocol (AAIF / Linux Foundation), *stdio Transport — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "In the stdio transport, the client launches the MCP server as a subprocess. / The server reads JSON-RPC messages from stdin and writes JSON-RPC messages to stdout. / Messages are delimited by newlines, and MUST NOT contain embedded newlines. / Each message is a single JSON-RPC request, notification, or response. / The server MUST NOT write anything to its stdout that is not a valid MCP message. / The server MAY write UTF-8 strings to stderr / SHOULD NOT assume stderr output indicates error conditions. / The wire format (one newline-delimited JSON-RPC message per line over a reliable bidirectional byte stream) works unchanged over Unix domain sockets, TCP connections, or any similar channel.", "ref": 4 }, { "label": "[5]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Streamable HTTP Transport — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "The client sends every JSON-RPC request or notification as its own HTTP POST. / The server MUST provide a single HTTP endpoint path (hereafter referred to as the MCP endpoint ) that supports POST. / the server MUST return either Content-Type: application/json (a single JSON object) or Content-Type: text/event-stream (an SSE response stream). / Streamable HTTP was introduced in protocol version 2025-03-26 as a replacement for the HTTP+SSE transport from protocol version 2024-11-05. / Removal of the GET stream endpoint. Removal of protocol-level sessions. / The client MUST include an Accept header listing both application/json and text/event-stream as supported content types. / Every POST request to the MCP endpoint MUST include an MCP-Protocol-Version header. / The body of the HTTP POST MUST be a single JSON-RPC request or notification. The client MUST NOT send JSON-RPC responses. / The header value MUST match the io.modelcontextprotocol/protocolVersion field carried in the request body's _meta. / Mcp-Method method All requests Mcp-Name params.name or params.uri tools/call , resources/read , prompts/get / the server MUST return either Content-Type: application/json (a single JSON object) or Content-Type: text/event-stream (an SSE response stream). The client MUST support both. / a Server-Sent Events (SSE) stream scoped to that request, carrying request-related notifications followed by the final response. / the server MUST return HTTP status code 202 Accepted with no body. / This is a change from Streamable HTTP in protocol versions 2025-03-26 through 2025-11-25 / servers could assign a session via the Mcp-Session-Id header (terminated with HTTP DELETE), clients could open a standalone SSE stream with HTTP GET", "ref": 5 }, { "label": "[6]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/changelog", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Key Changes (2026-07-28) — Model Context Protocol Specification*, 2026-07-28", "date": "2026-07-28", "quote": "Make MCP stateless: remove the initialize / notifications/initialized handshake. / Remove protocol-level sessions and the Mcp-Session-Id header from the Streamable HTTP transport. / previous revision, 2025-11-25 / Every request now carries its protocol version and client capabilities in _meta ( io.modelcontextprotocol/protocolVersion , io.modelcontextprotocol/clientCapabilities ). / Servers that need cross-call state use explicit, server-minted handles passed as ordinary tool arguments / resources/subscribe / resources/unsubscribe with subscriptions/listen / Remove ping, logging/setLevel, and notifications/roots/list_changed / Remove SSE stream resumability and message redelivery (the Last-Event-ID header and SSE event IDs) from the Streamable HTTP transport / Servers return an InputRequiredResult (resultType: \"input_required\") / Deprecate the roots, sampling, and logging features (SEP-2577) / Change resource not found error code from -32002 to -32602 (Invalid params) to align with JSON-RPC specification. / authorization servers SHOULD include the iss parameter in authorization responses per RFC 9207, and MCP clients MUST validate a present iss against the recorded issuer before redeeming the authorization code ( SEP-2468 ). / Clarify that client credentials are bound to the authorization server that issued them: clients MUST key persisted credentials by the issuer identifier, MUST NOT reuse them with a different authorization server / MUST NOT reuse them with a different authorization server, and MUST re-register when the authorization server changes ( SEP-2352 ).", "ref": 6 }, { "label": "[7]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Versioning and Compatibility — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Legacy : protocol versions that establish a session with an initialize handshake ( 2025-11-25 and earlier). / Modern : protocol versions that convey version, identity, and capabilities as per-request metadata (revision 2026-07-28 and later). / There is no negotiation handshake. Every request carries its protocol version, and the server accepts or rejects each request independently / Every request declares the protocol version it is using in its _meta field. On HTTP, this is also carried in the MCP-Protocol-Version header / Extensions are advertised in the extensions field of capabilities / io.modelcontextprotocol/tasks / it MUST respond with an UnsupportedProtocolVersionError listing the versions it does support / \"supported\": [ \"2026-07-28\", \"2025-11-25\" ] / The client SHOULD select a mutually supported version from the supported list and retry the request", "ref": 7 }, { "label": "[8]", "url": "https://blog.modelcontextprotocol.io/posts/mcp-roadmap/", "claim": "David Soria Parra and Den Delimarsky (Model Context Protocol Blog), *The New MCP Roadmap*, 2026-08-22", "date": "2026-08-22", "quote": "The new roadmap is organized into five priority areas. Several of them pick up work that the previous version of the roadmap listed as being on the horizon, including server-initiated events, result type improvements, and agent identity", "ref": 8 }, { "label": "[9]", "url": "https://blog.modelcontextprotocol.io/posts/ruby-sdk-tier-1/", "claim": "Koichi Ito (Model Context Protocol Blog), *The Official Ruby SDK for MCP Reaches Tier 1*, 2026-10-30", "date": "2026-10-30", "quote": "The official Ruby SDK for the Model Context Protocol is now a Tier 1 SDK under the MCP SDK tiering system, with full support for the 2026-07-28 MCP specification and a 100% conformance pass rate across both scored spec versions. / And as the specification evolves, the Ruby SDK team has committed to supporting the next MCP spec, targeted for late March 2027 , by its release date.", "ref": 9 }, { "label": "[10]", "url": "https://blog.modelcontextprotocol.io/posts/2026-07-28/", "claim": "David Soria Parra and Den Delimarsky (MCP Blog), *MCP 2026-07-28 Specification Release*, 2026-07-28", "date": "2026-07-28", "quote": "David Soria Parra Member of Technical Staff, Co-Inventor of MCP / Any request can now land on any server instance behind a plain round-robin load balancer without needing shared storage. / We leverage it with Foundry toolbox unified MCP endpoint that brings together tools while centralizing governance, identity, and observability. With stateless operations, Tasks for long-running work, and enterprise-managed identity, the next generation of MCP makes it easier than ever to build secure, scalable, production-ready agent systems. / All four Tier 1 SDKs speak 2026-07-28 as of today: TypeScript Python Go C# Beyond the Tier 1 set, the Rust SDK supports the new spec in beta. / Cloudflare’s Agents SDK supports the spec from day zero, so developers can run MCP servers directly in Workers, call tools without transport-session overhead, and enable richer flows like elicitation for approvals. / Across our Tier 1 SDKs, we’re seeing close to half-a-billion downloads a month, with both TypeScript and Python SDKs crossing the 1 billion total downloads threshold.", "ref": 10 }, { "label": "[11]", "url": "https://modelcontextprotocol.io/community/governance", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Governance and Stewardship — Model Context Protocol*, 2026-10-30", "date": "2026-10-30", "quote": "Justin Spahr-Summers (Co-Inventor, Lead Maintainer Emeritus) / Lead Maintainers are the final decision makers (also known as BDFL - Benevolent Dictator for Life). / All code and specification contributions to the project must be made using the Apache License, Version 2.0 / All documentation (excluding specifications) will be made available under Creative Commons Attribution 4.0 International license", "ref": 11 }, { "label": "[12]", "url": "https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Versioning — Model Context Protocol Documentation*, 2026-07-28", "date": "2026-07-28", "quote": "Current : the current protocol version, which is ready for use and may continue to receive backwards compatible changes. / The current protocol version is 2026-07-28 .", "ref": 12 }, { "label": "[13]", "url": "https://ruby.sdk.modelcontextprotocol.io/protocol-versions/", "claim": "MCP Ruby SDK, *Protocol Versions*, checked 2026-10-30", "date": null, "quote": "2026-07-28 Modern Stateless lifecycle: no handshake, version carried on every request (SEP-2575)", "ref": 13 }, { "label": "[14]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Base Protocol Overview — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "All messages between MCP clients and servers MUST follow the JSON-RPC 2.0 specification. / Server Features : Resources, prompts, and tools exposed by servers / Client Features : Elicitation, sampling and root directory lists provided by clients / JSON-RPC 2.0 reserves the range -32000 to -32099 for implementation-defined server errors. MCP partitions this range as follows: -32000 to -32019 - legacy. / -32020 to -32099 - reserved for the MCP specification. Error codes in this sub-range are defined exclusively by the MCP specification and recorded in the schema. / -32020 HeaderMismatch -32021 MissingRequiredClientCapability -32022 UnsupportedProtocolVersion / -32002 - Resource not found (2025-11-25 and earlier; replaced by -32602 ) / -32042 - URL elicitation required (2025-11-25 only).", "ref": 14 }, { "label": "[15]", "url": "https://modelcontextprotocol.io/registry/about", "claim": "Model Context Protocol (AAIF / Linux Foundation), *About the Official MCP Registry*, 2026-10-30", "date": "2026-10-30", "quote": "Server metadata is stored in a standardized server.json format / The MCP Registry is the official centralized metadata repository for publicly accessible MCP servers / The MCP Registry is intended to be consumed primarily by downstream aggregators, such as MCP server marketplaces. / The MCP Registry is currently in preview.", "ref": 15 }, { "label": "[16]", "url": "https://modelcontextprotocol.io/seps/2127-mcp-server-cards", "claim": "Model Context Protocol (AAIF / Linux Foundation), *SEP-2127: MCP Server Cards — HTTP Server Discovery*, 2026-01-21", "date": "2026-01-21", "quote": "Cards themselves can be hosted at any unreserved URI, with /server-card reserved as the recommended location. / Cards themselves can be hosted at any unreserved URI, with /server-card reserved as the recommended location.", "ref": 16 }, { "label": "[17]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Multi Round-Trip Requests — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "InputRequiredResult / resultType\": \"input_required\" / prompts/get Yes resources/read Yes tools/call Yes / Servers MUST send server-to-client requests (such as roots/list , sampling/createMessage , or elicitation/create ) using the MRTR pattern. / The previous pattern of server-initiated requests is no longer supported.", "ref": 17 }, { "label": "[18]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/architecture", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Architecture — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Servers should not be able to read the whole conversation, nor \"see into\" other servers / The Model Context Protocol (MCP) follows a client-host-server architecture where each host can run multiple client instances. MCP is a stateless protocol: every request is self-contained and carries its own protocol version and capabilities. / A host application creates and manages multiple clients, with each client having a 1:1 relationship with a particular server. / Can be local processes or remote services / Clients include their capabilities in _meta.io.modelcontextprotocol/clientCapabilities on every request. / Servers advertise their capabilities in response to server/discover", "ref": 18 }, { "label": "[19]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Authorization — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Authorization is OPTIONAL for MCP implementations. / Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment. / OAuth 2.1 / MCP servers MUST implement OAuth 2.0 Protected Resource Metadata ( RFC9728 ). / MCP clients MUST implement Resource Indicators for OAuth 2.0 as defined in RFC 8707 / Implementations using an HTTP-based transport SHOULD conform to this specification. / A protected MCP server acts as an OAuth 2.1 resource server / MCP clients MUST use OAuth 2.0 Protected Resource Metadata for authorization server discovery. / MUST be included in both authorization requests and token requests. / aligns with the resource parameter in RFC 9728 / OAuth 2.0 Dynamic Client Registration Protocol ( RFC7591 )", "ref": 19 }, { "label": "[20]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/server/discover", "claim": "Model Context Protocol, *Discovery — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "`server/discover` lets a client query a server’s supported protocol versions, capabilities, and identity before sending any other requests. Servers **MUST** implement it. / server/discover lets a client query a server's supported protocol versions, capabilities, and identity before sending any other requests. Servers MUST implement it. / supportedVersions / Calling server/discover is optional for clients / On stdio, there is no per-request HTTP status code to drive fallback. / legacy ( initialize handshake) servers SHOULD send server/discover first / serverInfo is self-reported by the server and is not verified by the protocol. It is intended for display, logging, and debugging. Clients SHOULD NOT use it to change their behavior, and SHOULD NOT rely on it for security decisions", "ref": 20 }, { "label": "[21]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/client/sampling", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Sampling — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "The Sampling feature is deprecated as of protocol version 2026-07-28 ( SEP-2577 ). / existing implementations SHOULD migrate to integrating directly with LLM provider APIs. / request LLM sampling (\"completions\" or \"generations\") from language models via clients. / with no server API keys necessary. / Servers can request text, audio, or image-based interactions", "ref": 21 }, { "label": "[22]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/client/roots", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Roots — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "The Roots feature is deprecated as of protocol version 2026-07-28 ( SEP-2577 ). / existing implementations SHOULD migrate to passing directories or files via tool parameters, resource URIs, or server configuration. / expose filesystem \"roots\" to servers. / They are informational guidance rather than an access-control mechanism. / The protocol does not enforce that servers stay within roots.", "ref": 22 }, { "label": "[23]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/deprecated", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Deprecated Features Registry — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "First revision released on or after 2027-07-28 / Logging SEP-2577 2026-07-28 / Dynamic Client Registration / Dynamic Client Registration PR #2858 2026-07-28 Client ID Metadata Documents", "ref": 23 }, { "label": "[24]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/server/tools", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Tools — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Tools in MCP are designed to be model-controlled , meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts. / there SHOULD always be a human in the loop with the ability to deny tool invocations. / Servers that support tools MUST declare the tools capability / To discover available tools, clients send a tools/list request. / MUST NOT vary per-connection or as a side effect of other requests on the connection. / The set MAY vary by the authorization presented on the request / Servers MAY respond to tools/call with an InputRequiredResult / resultType\": \"input_required\" / For trust & safety and security, clients MUST consider tool annotations to be untrusted unless they come from trusted servers.", "ref": 24 }, { "label": "[25]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/server/resources", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Resources — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Resources in MCP are designed to be application-driven / such as files, database schemas, or application-specific information. / Each resource is uniquely identified by a URI / clients send a resources/list request. / resources/read / \"resources\": { \"listChanged\": true, \"subscribe\": true } / Clients subscribe to change notifications for specific resources by sending a / notifications.resourceSubscriptions", "ref": 25 }, { "label": "[26]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/server/prompts", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Prompts — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "Prompts are designed to be user-controlled , meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use. / as slash commands / clients send a prompts/list request. / prompts/get / MUST NOT vary per-connection", "ref": 26 }, { "label": "[27]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Elicitation — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "The Model Context Protocol (MCP) provides a standardized way for servers to request additional information from users through the client during interactions. / Form mode : Servers can request structured data from users with optional JSON schemas to validate responses / URL mode : Servers can direct users to external URLs for sensitive interactions that must not pass through the MCP client / Servers MUST use URL mode for interactions involving such sensitive information / passwords, API keys, access tokens, or payment credentials / echoed requestState", "ref": 27 }, { "label": "[28]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Security Best Practices — Model Context Protocol (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "MCP Servers MUST NOT accept any tokens that were not explicitly issued for the MCP server / Local MCP servers with inadequate restrictions or from untrusted sources introduce several critical security risks: Arbitrary code execution", "ref": 28 }, { "label": "[29]", "url": "https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Client Registration — Model Context Protocol Specification (2026-07-28)*, 2026-07-28", "date": "2026-07-28", "quote": "enables clients to use HTTPS URLs as client identifiers / client_id_metadata_document_supported / The metadata document MUST include at least the following properties: client_id , client_name , redirect_uris", "ref": 29 }, { "label": "[30]", "url": "https://webmachinelearning.github.io/webmcp/", "claim": "Web Machine Learning Community Group (editors Brandon Walderman, Khushal Sagar, Dominic Farolino, and Samuel Dallstream), *WebMCP*, Draft Community Group Report, 11 November 2026", "date": null, "quote": "partial interface Document { [ SecureContext , SameObject ] readonly attribute ModelContext modelContext ; };", "ref": 30 }, { "label": "[31]", "url": "https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp", "claim": "Model Context Protocol (MCP), *SEP-1865: MCP Apps — Interactive User Interfaces for MCP*, 2026-01-26", "date": "2026-01-26", "quote": "declaring UI resources via the ui:// URI scheme, associating them with tools through metadata, and facilitating bi-directional communication", "ref": 31 }, { "label": "[32]", "url": "https://huggingface.co/mcp", "claim": "Hugging Face, *Live MCP endpoint*, 2026-10-30", "date": "2026-10-30", "quote": "\"supportedVersions\":[\"2026-07-28\"],\"capabilities\":{\"tools\":{\"listChanged\":false},\"resources\":{\"listChanged\":false,\"subscribe\":false},\"extensions\":{\"io.modelcontextprotocol/skills\":{\"directoryRead\":true}}} / \"_meta\":{\"io.modelcontextprotocol/serverInfo\":{\"name\":\"huggingface.co/mcp\",\"version\":\"0.4.31\",\"title\":\"Hugging Face\"", "ref": 32 }, { "label": "[33]", "url": "https://huggingface.co/docs/hub/agents-mcp", "claim": "Hugging Face, *Hugging Face MCP Server*, checked 2026-10-30", "date": null, "quote": "Hugging Face MCP Server: https://huggingface.co/mcp", "ref": 33 }, { "label": "[34]", "url": "https://docs.mcp.cloudflare.com/mcp", "claim": "Cloudflare, *Live MCP endpoint*, 2026-10-30", "date": "2026-10-30", "quote": "{\"result\":{\"supportedVersions\":[\"2026-07-28\"],\"capabilities\":{\"tools\":{\"listChanged\":true},\"prompts\":{\"listChanged\":true}},\"resultType\":\"complete\",\"ttlMs\":0,\"cacheScope\":\"private\",\"_meta\":{\"io.modelcontextprotocol/serverInfo\":{\"name\":\"docs-ai-search\",\"version\":\"0.5.0\"}}},\"jsonrpc\":\"2.0\",\"id\":1}", "ref": 34 }, { "label": "[35]", "url": "https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/", "claim": "Cloudflare, *Cloudflare's own MCP servers*, checked 2026-10-30", "date": null, "quote": "https://docs.mcp.cloudflare.com/mcp", "ref": 35 }, { "label": "[36]", "url": "https://api.githubcopilot.com/mcp/", "claim": "GitHub, *Live MCP endpoint*, 2026-10-30", "date": "2026-10-30", "quote": "www-authenticate: Bearer error=\"invalid_request\", error_description=\"No access token was provided in this request\", resource_metadata=\"https://api.githubcopilot.com/.well-known/oauth-protected-resource/mcp/\"", "ref": 36 }, { "label": "[37]", "url": "https://github.com/github/github-mcp-server", "claim": "GitHub, *github/github-mcp-server*, checked 2026-10-30", "date": null, "quote": "The GitHub MCP Server connects AI tools directly to GitHub's platform. / For non-interactive stdio deployments, see **[GitHub App Authentication](docs/github-app-auth.md)**.", "ref": 37 }, { "label": "[38]", "url": "https://mcp.stripe.com", "claim": "Stripe, *Live MCP endpoint*, 2026-10-30", "date": "2026-10-30", "quote": "www-authenticate: Bearer resource_metadata=\"https://mcp.stripe.com/.well-known/oauth-protected-resource\" / {\"error\":\"Unauthorized. See https://docs.stripe.com/mcp for usage instructions.\",\"error_code\":\"missing_api_key\",\"error_description\":\"No valid API key provided.\"}", "ref": 38 }, { "label": "[39]", "url": "https://docs.stripe.com/mcp", "claim": "Stripe, *Model Context Protocol (MCP)*, checked 2026-10-30", "date": null, "quote": "Stripe’s MCP server supports two authentication methods: OAuth : Use OAuth when a client accesses Stripe on behalf of your Stripe user account. Agent API keys : Use an agent API key when an AI application needs independent, persistent access to Stripe.", "ref": 39 }, { "label": "[40]", "url": "https://mcp.linear.app/mcp", "claim": "Linear, *Live MCP endpoint*, 2026-10-30", "date": "2026-10-30", "quote": "www-authenticate: Bearer realm=\"OAuth\", resource_metadata=\"https://mcp.linear.app/.well-known/oauth-protected-resource/mcp\", scope=\"read write\"", "ref": 40 }, { "label": "[41]", "url": "https://linear.app/docs/mcp", "claim": "Linear, *MCP server*, checked 2026-10-30", "date": null, "quote": "Read-write access is provided through https://mcp.linear.app/mcp by default. For read-only access, you have two options: Connect to https://mcp.linear.app/mcp/readonly , which only ever exposes read tools.", "ref": 41 }, { "label": "[42]", "url": "https://registry.modelcontextprotocol.io/v0.1/servers/com.atlassian%2Fatlassian-mcp-server/versions/2.0.0", "claim": "Official MCP Registry, *com.atlassian/atlassian-mcp-server version 2.0.0 (Official MCP Registry)*, version 2.0.0 (publishedAt 2026-09-09T17:53:32.01107Z; retained snapshot fetched 2026-10-30)", "date": null, "quote": "\"name\":\"com.atlassian/atlassian-mcp-server\",\"description\":\"Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.\",\"title\":\"Atlassian Rovo MCP Server\",\"repository\":{\"url\":\"https://github.com/atlassian/atlassian-mcp-server\",\"source\":\"github\"},\"version\":\"2.0.0\",\"websiteUrl\":\"https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/\",\"remotes\":[{\"type\":\"streamable-http\",\"url\":\"https://mcp.atlassian.com/v2/mcp\"},{\"type\":\"streamable-http\",\"url\":\"https://mcp.atlassian.com/v1/mcp/authv2\"}]", "ref": 42 }, { "label": "[43]", "url": "https://registry.modelcontextprotocol.io/v0.1/servers/com.notion%2Fmcp/versions/1.0.1", "claim": "Official MCP Registry, *com.notion/mcp version 1.0.1 (Official MCP Registry)*, version 1.0.1 (publishedAt 2025-09-11T22:25:50.737872Z; retained snapshot fetched 2026-10-30)", "date": null, "quote": "\"name\":\"com.notion/mcp\",\"description\":\"Official Notion MCP server\",\"repository\":{},\"version\":\"1.0.1\",\"remotes\":[{\"type\":\"streamable-http\",\"url\":\"https://mcp.notion.com/mcp\"},{\"type\":\"sse\",\"url\":\"https://mcp.notion.com/sse\"}]", "ref": 43 }, { "label": "[44]", "url": "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.microsoft%2Fplaywright-mcp/versions/0.0.82", "claim": "Official MCP Registry, *io.github.microsoft/playwright-mcp version 0.0.82 (Official MCP Registry)*, version 0.0.82 (publishedAt 2026-09-18T23:41:20.46032Z; retained snapshot fetched 2026-10-30)", "date": null, "quote": "\"name\":\"io.github.microsoft/playwright-mcp\",\"description\":\"Playwright Tools for MCP\",\"repository\":{\"url\":\"https://github.com/microsoft/playwright-mcp\",\"source\":\"github\"},\"version\":\"0.0.82\",\"packages\":[{\"registryType\":\"npm\",\"identifier\":\"@playwright/mcp\",\"version\":\"0.0.82\",\"transport\":{\"type\":\"stdio\"}}]", "ref": 44 }, { "label": "[45]", "url": "https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp", "claim": "Anthropic, *Get started with custom connectors using remote MCP*, modified 2026-10-30", "date": null, "quote": "Local MCP servers configured in Claude Desktop via claude_desktop_config.json are a separate mechanism and do use your local network, but those aren't available in Cowork or claude.ai. / Under OAuth client , choose how Claude identifies itself to the server’s authorization server: “Use Claude’s published identity (Recommended),” “Register automatically,” or “Use your own OAuth client.”", "ref": 45 }, { "label": "[46]", "url": "https://claude.com/resources/articles/bringing-mcp-2026-07-28-to-claude", "claim": "Anthropic, *MCP 2026-07-28 spec: stateless core, coming to Claude*, 2026-07-28", "date": "2026-07-28", "quote": "The fifth spec release of the Model Context Protocol, MCP 2026-07-28 , is live today. The latest spec moves MCP to a stateless core, while hardening authorization and graduating official extensions. Support is being rolled out across Claude products.", "ref": 46 }, { "label": "[47]", "url": "https://code.visualstudio.com/blogs/2025/06/12/full-mcp-spec-support", "claim": "Microsoft / Harald Kirschner, Connor Peet and Tyler Leonhardt, *The Complete MCP Experience: Full Specification Support in VS Code*, 2025-06-12", "date": "2025-06-12", "quote": "Beyond the initial tools and workspace awareness we introduced in May , you can now use authorization, prompts, resources, and sampling. / Combined with streamable HTTP transport (which landed in our previous version), this enables remote MCP servers that can scale independently while maintaining enterprise-grade security.", "ref": 47 }, { "label": "[48]", "url": "https://cursor.com/changelog/1-0", "claim": "Cursor, *Cursor 1.0*, 2025-06-04", "date": "2025-06-04", "quote": "You can now set up MCP servers in Cursor with one click, and together with OAuth support, you can easily authenticate servers that support it.", "ref": 48 }, { "label": "[49]", "url": "https://blog.google/innovation-and-ai/technology/developers-tools/introducing-gemini-cli-open-source-ai-agent/", "claim": "Google, *Gemini CLI: your open-source AI agent*, published 2025-06-25; modified 2026-01-07", "date": null, "quote": "Extend Gemini CLI’s capabilities through built-in support for the Model Context Protocol (MCP) or bundled extensions / Because Gemini CLI is fully open source (Apache 2.0) , developers can inspect the code to understand how it works and verify its security implications.", "ref": 49 }, { "label": "[50]", "url": "https://modelcontextprotocol.io/registry/registry-aggregators", "claim": "Model Context Protocol, *MCP Registry Aggregators*, checked 2026-10-30", "date": null, "quote": "A subregistry is an aggregator that also implements the OpenAPI spec defined by the MCP Registry. / The base URL for the MCP Registry REST API is https://registry.modelcontextprotocol.io. / GET /v0.1/servers - List all servers. GET /v0.1/servers/{serverName}/versions - List all versions of a server. GET /v0.1/servers/{serverName}/versions/{version} - Get a specific version of a server. Use the special version latest", "ref": 50 }, { "label": "[51]", "url": "https://github.blog/ai-and-ml/github-copilot/meet-the-github-mcp-registry-the-fastest-way-to-discover-mcp-servers/", "claim": "Toby Padilla, GitHub Blog, *Meet the GitHub MCP Registry: The fastest way to discover MCP Servers*, published 2025-09-16", "date": null, "quote": "\"datePublished\":\"2025-09-16T09:27:54-07:00\" / self-publish MCP servers directly to the OSS MCP Community Registry / those servers will automatically appear in the GitHub MCP Registry", "ref": 51 }, { "label": "[52]", "url": "https://glama.ai/mcp/methodology", "claim": "Glama, *How Glama indexes the MCP ecosystem*, checked 2026-10-30", "date": null, "quote": "Glama ingests and re-publishes everything in the official registry, and layers its own sandbox-derived data on top / the behavioural analysis, the schema captures from actual server runs, the TDQS scores", "ref": 52 }, { "label": "[53]", "url": "https://www.pulsemcp.com/work-with-us", "claim": "PulseMCP, *Work With Us*, checked 2026-10-30", "date": null, "quote": "We ingest from the official registry and supplement with our own indexing across the web", "ref": 53 }, { "label": "[54]", "url": "https://www.pulsemcp.com/posts/newsletter-claude-code-competition-ai-fundraising-abounds-mcp-registry-launch", "claim": "PulseMCP, *Claude Code has competition, AI fundraising abounds, Official MCP Registry launched*, published 2025-09-09", "date": null, "quote": "we’re setting PulseMCP up as a sub-registry of the official registry / use our data (like estimated downloads, standardized names and descriptions) to curate your MCP marketplaces", "ref": 54 }, { "label": "[55]", "url": "https://www.pulsemcp.com/servers/", "claim": "PulseMCP, *MCP Server Directory*, checked 2026-11-06", "date": null, "quote": "New server submissions and listing changes are still paused while we rework how we ingest and manage listings.", "ref": 55 }, { "label": "[56]", "url": "https://mcpcensus.com/compare/mcp-registries", "claim": "MCP Census (Jaco Veldsman), *MCP registries compared*, 2026-11-04", "date": "2026-11-04", "quote": "returns PASS, REVIEW, BLOCK or UNKNOWN / 57,777 server rows (read 4 November 2026) / Updated 2026-11-04 / 115,336 servers (page title, 4 November 2026). Tags include Remote 45,340, Local 43,442 / 21,602 servers / 300+ / stopped on 31 October 2026 / Every statement about another site comes from the pages in the Sources list, read on 4 November 2026. / 21,602 servers (page, undated; the title says / the API, Connect, accounts, CLI and proxy URLs stopped on 31 October 2026", "ref": 56 }, { "label": "[57]", "url": "https://modelcontextprotocol.io/docs/sdk", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Official MCP SDKs*, 2026-10-30", "date": "2026-10-30", "quote": "Build MCP servers and clients using our official SDKs in TypeScript, Python, Go, Kotlin, Swift, Java, C#, Ruby, Rust, and PHP. / TypeScript modelcontextprotocol/typescript-sdk Tier 1 Python modelcontextprotocol/python-sdk Tier 1 C# modelcontextprotocol/csharp-sdk Tier 1 Go modelcontextprotocol/go-sdk Tier 1 Rust modelcontextprotocol/rust-sdk Tier 1 Ruby modelcontextprotocol/ruby-sdk Tier 1", "ref": 57 }, { "label": "[58]", "url": "https://modelcontextprotocol.io/docs/tools/inspector", "claim": "Model Context Protocol (AAIF / Linux Foundation), *MCP Inspector*, 2026-07-28", "date": "2026-07-28", "quote": "It ships as a single package, @modelcontextprotocol/inspector , providing three clients behind one binary / All three are built on the same shared core, so a connection behaves identically across them: the same transports, the same configuration files, the same OAuth state on disk, and the same protocol-era negotiation (legacy vs. modern 2026-07-28). / npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list / npx @modelcontextprotocol/inspector --tui node path/to/server/index.js", "ref": 58 }, { "label": "[59]", "url": "https://developers.cloudflare.com/agents/model-context-protocol/", "claim": "Cloudflare, *Model Context Protocol (MCP) · Cloudflare Agents docs*, checked 2026-10-30", "date": null, "quote": "Remote MCP connections : MCP clients connect to MCP servers over the Internet, establishing a connection using Streamable HTTP , and authorizing the MCP client access to resources on the user's account using OAuth . / When a token lacks a scope, return an insufficientScope() challenge so the client asks the user to approve it (step-up authorization) instead of requesting every scope up front.", "ref": 59 }, { "label": "[60]", "url": "https://raw.githubusercontent.com/modelcontextprotocol/mcpb/main/README.md", "claim": "Model Context Protocol, *MCP Bundles (MCPB) Specification & Toolchain README*, 2026-10-30", "date": "2026-10-30", "quote": "MCP Bundles (`.mcpb`) are zip archives containing a local MCP server and a `manifest.json` that describes the server and its capabilities. / `@anthropic-ai/dxt` package will be moved to `@anthropic-ai/mcpb`", "ref": 60 }, { "label": "[61]", "url": "https://blog.modelcontextprotocol.io/posts/2025-11-25-first-mcp-anniversary/", "claim": "Model Context Protocol Blog, *One Year of MCP: November 2025 Spec Release*, 2025-11-25", "date": "2025-11-25", "quote": "It's the central index for all available MCP servers that now has close to two thousand entries since its announcement in September. / That's a 407% growth from the initial batch of servers we onboarded that same month.", "ref": 61 }, { "label": "[62]", "url": "https://www.anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation", "claim": "Anthropic, *Donating the Model Context Protocol and establishing the Agentic AI Foundation*, 2025-12-09", "date": "2025-12-09", "quote": "Across the ecosystem: There are now more than 10,000 active public MCP servers, covering everything from developer tools to Fortune 500 deployments;", "ref": 62 }, { "label": "[63]", "url": "https://www.localcan.com/blog/state-of-mcp-server-development", "claim": "Jarek Ceborski, LocalCan, *State of MCP Server Development: October 2026*, 2026-10-15", "date": "2026-10-15", "quote": "Every number below was measured or checked on 14 October 2026 / The official MCP Registry lists 43,012 active servers / 59.6% are remote-only, 34.6% ship only as a package you run yourself, 4.7% offer both, and 1.1% list neither", "ref": 63 }, { "label": "[64]", "url": "https://www.apideck.com/blog/mcp-server-directories", "claim": "Apideck, *MCP server directories*, 2026-10-31", "date": "2026-10-31", "quote": "Every count below is from 31 October 2026. / The registry held 53,541 servers on 31 October 2026 / 113,204 open-source servers and 40,151 remote connectors on 31 October / PulseMCP listed 21,614 servers / MCP Market showed 50,999 servers / The Cursor Marketplace linked about 490 plugins on 31 October", "ref": 64 }, { "label": "[65]", "url": "https://arxiv.org/html/2611.06897v1", "claim": "Khalid Tounoussi, Mohammed Sayagh, Ali Ouni, and Yutaro Kashiwa, *MCP-Eco: A Linked Dataset of MCP Servers, Consumers, and Development Activity*, 2026-11-04", "date": "2026-11-04", "quote": "exported the release to Parquet on 2026-06-23 / 78,302 candidate server projects / The crawler queries the APIs of the official MCP registry, Glama, Smithery, PulseMCP. For MCP.so, it reads server listing pages found through sitemaps.", "ref": 65 } ], "form": "endpoint", "governance": "Agentic AI Foundation (AAIF), a directed fund under the Linux Foundation, since 2025-12-09; a Series of LF Projects, LLC; Lead Maintainers are the final decision makers", "group": null, "hatnote_md": "This article covers the Model Context Protocol (MCP) for host-to-server context and tool exchange. For the browser DOM API, see [WebMCP](/protocols/webmcp/); for server discovery, see [Official MCP Registry](/protocols/mcp-registry/) and [MCP Server Cards](/protocols/mcp-server-cards/).", "history": [ { "date": "2026-09-06", "note": "verified against modelcontextprotocol.io/specification/2026-07-28, github.com/modelcontextprotocol/experimental-ext-server-card, github.com/modelcontextprotocol/registry, modelcontextprotocol.io/docs/2026-07-28/sdk, modelcontextprotocol.io/docs/extensions/apps, en.wikipedia.org/wiki/Model_Context_Protocol, workos.com MCP-2026 blog" }, { "date": "2026-10-16", "note": "Server Cards (SEP-2127) Final 6 Oct 2026; Skills over MCP (SEP-2640) Final 13 Sep 2026; next spec release cadence under discussion (SEP-3398)" }, { "date": "2026-10-17", "note": "prose brought in line with the infobox and history: SEP-2127 Server Cards are Final (2026-10-06), not experimental; reserved location, media type and the superseded /.well-known/mcp.json noted" }, { "date": "2026-10-20", "note": "server-card evidence line marked superseded (SEP-2127 Final; repo renamed to ext-server-card)" }, { "date": "2026-10-20", "note": "probe now uses server/discover for 2026-07-28 with initialize as the legacy fallback; SEP-2127 card is Final; three registry censuses recorded with their units and dates" }, { "date": "2026-10-28", "note": "Re-verified record against 27 sources on 2026-10-28: 5 live remote MCP endpoints (Hugging Face and Cloudflare via server/discover HTTP 200; GitHub Copilot, Stripe, and Linear via HTTP 401 + RFC 9728 OAuth protected-resource metadata HTTP 200), 7 client vendor statements, and 3 press sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "mcp", "implementation": "multi-implementation", "last_verified": "2026-11-11", "name": "Model Context Protocol", "native_status": "Open protocol. The current version, 2026-07-28, is ready for use. The next specification is targeted for late March 2027.", "origin": { "date": "2024-11-25", "org": "Anthropic" }, "pairs_with": [ "a2a", "webmcp", "mcp-apps", "mcp-registry", "ag-ui", "anthropic-agent-skills-format" ], "part_of": null, "parties": [ "agent-site" ], "phase": "living", "prerequisites": [], "probe": { "method": "POST", "on_absent": "Connection refused, 404, or a non-JSON-RPC response means no MCP server is exposed at that endpoint. SEP-2127 is Final: GET {endpoint}/server-card as application/mcp-server-card+json is a static discovery signal, discovered via /.well-known/ai-catalog.json. /.well-known/mcp.json is the legacy SEP-1649 path. When the static card and a live server/discover response disagree, the live call wins.", "parse": "For protocol 2026-07-28, POST a JSON-RPC 2.0 request with method server/discover. The 2026-07-28 specification made MCP stateless and retired initialize, initialized, and Mcp-Session-Id. Each request carries the MCP-Protocol-Version header, and the method and tool name travel in Mcp-Method and Mcp-Name. server/discover is optional; any other request can land on any instance. On success, the returned protocol version (for example 2026-07-28) and the server name prove an MCP server is present. For servers that still speak 2025-11-25 and earlier, fall back to the legacy initialize handshake and read response.result.protocolVersion and response.result.serverInfo.name.", "path": "{endpoint}/mcp" }, "question": "How does an AI application call tools and pull structured context, prompts, and data from an external server?", "scope": "general", "spec_url": "https://modelcontextprotocol.io/specification/2026-07-28", "step": "act", "summary_md": "The **Model Context Protocol** (**MCP**) is an open protocol that uses `JSON-RPC 2.0` messages to connect LLM host applications with servers that provide context and capabilities. Anthropic introduced it on 2024-11-25 as a universal, open standard for connecting AI systems with data sources. The Linux Foundation's Agentic AI Foundation (AAIF) now stewards MCP as a founding project, alongside Block's goose and OpenAI's AGENTS.md. On `stdio`, the client launches the MCP server as a subprocess; the server reads JSON-RPC messages from `stdin` and writes JSON-RPC messages to `stdout`, delimited by newlines. On Streamable HTTP, every JSON-RPC request is its own HTTP `POST` to a single MCP endpoint, and the server answers with either `Content-Type: application/json` or `Content-Type: text/event-stream`. The 2025-11-25 revision serves as the legacy Streamable HTTP session baseline (succeeding 2025-03-26 and 2024-11-05), while the 2026-07-28 revision retires the `initialize` / `notifications/initialized` handshake, `Mcp-Session-Id` headers, and standalone GET SSE streams. A roadmap published on 2026-08-22 organizes later specification work into five priority areas, picking up server-initiated events, result type improvements, and agent identity, together with HTTP-native transport and SDK developer experience. On 2026-10-30 the official Ruby SDK reached Tier 1, with full support for the 2026-07-28 specification and a 100% conformance pass rate across both scored spec versions. The Ruby SDK team has committed to supporting the next MCP specification, targeted for late March 2027, by its release date.", "track": "linux-foundation", "use_cases": [ "expose-tools-to-agents", "describe-agent-capabilities", "discover-my-api", "render-agent-ui" ], "version": { "date": "2026-07-28", "label": "2026-07-28" }, "watch": [ { "type": "page", "url": "https://modelcontextprotocol.io/specification/2026-07-28/index", "selector": "main", "cadence": "weekly" }, { "type": "github", "repo": "modelcontextprotocol/modelcontextprotocol", "mode": "tag" }, { "type": "feed", "url": "https://blog.modelcontextprotocol.io/index.xml" }, { "type": "page", "url": "https://modelcontextprotocol.io/specification/versioning", "selector": "main" } ], "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "harnesses_rpc_ui", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-11", "v05_hatnote_html_md": "This article covers the Model Context Protocol (MCP) for host-to-server context and tool exchange. For the browser DOM API, see [WebMCP](/protocols/webmcp/); for server discovery, see [Official MCP Registry](/protocols/mcp-registry/) and [MCP Server Cards](/protocols/mcp-server-cards/). [1]", "v05_elevator_pitch_md": "MCP is a universal connector standard that lets AI applications (such as Claude, VS Code, or Cursor) plug into external data sources and tools (such as GitHub, Stripe, or Notion) without custom point-to-point integration code. Instead of building a bespoke connector for every AI host and external service, developers expose one MCP server with standardized `tools`, `resources`, and `prompts` that any MCP-compatible host can call over local `stdio` or HTTP. [1][2]", "v05_lead_md": "The **Model Context Protocol** (**MCP**) is an open protocol that uses `JSON-RPC 2.0` messages to connect LLM host applications with servers that provide context and capabilities. Anthropic introduced it on 2024-11-25 as a universal, open standard for connecting AI systems with data sources. The Linux Foundation's Agentic AI Foundation (AAIF) now stewards MCP as a founding project, alongside Block's goose and OpenAI's AGENTS.md. [1][2][3] On `stdio`, the client launches the MCP server as a subprocess; the server reads JSON-RPC messages from `stdin` and writes JSON-RPC messages to `stdout`, delimited by newlines. On Streamable HTTP, every JSON-RPC request is its own HTTP `POST` to a single MCP endpoint, and the server answers with either `Content-Type: application/json` or `Content-Type: text/event-stream`. [4][5] The 2025-11-25 revision serves as the legacy Streamable HTTP session baseline (succeeding 2025-03-26 and 2024-11-05), while the 2026-07-28 revision retires the `initialize` / `notifications/initialized` handshake, `Mcp-Session-Id` headers, and standalone GET SSE streams. [5][6][7] A roadmap published on 2026-08-22 organizes later specification work into five priority areas, picking up server-initiated events, result type improvements, and agent identity, together with HTTP-native transport and SDK developer experience. [8] On 2026-10-30 the official Ruby SDK reached Tier 1, with full support for the 2026-07-28 specification and a 100% conformance pass rate across both scored spec versions. [9] The Ruby SDK team has committed to supporting the next MCP specification, targeted for late March 2027, by its release date. [9]", "v05_identity_sentence_md": "The **Model Context Protocol** (**MCP**) is an open protocol that uses `JSON-RPC 2.0` messages to connect LLM host applications with servers that provide context and capabilities. Anthropic introduced it on 2024-11-25 as a universal, open standard for connecting AI systems with data sources. The Linux Foundation's Agentic AI Foundation (AAIF) now stewards MCP as a founding project, alongside Block's goose and OpenAI's AGENTS.md. [1][2][3]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Act](/category/act/) (`act`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "Anthropic; co-invented by David Soria Parra and Justin Spahr-Summers (open-sourced November 2024) [3][10][11]" }, { "label": "Governed by", "value_md": "Agentic AI Foundation (AAIF) under the Linux Foundation since 2025-12-09; Lead Maintainers hold final decision authority [3][11]" }, { "label": "Track", "value_md": "Foundation / Consortium Specification (`linux-foundation`); founding project of the Agentic AI Foundation [3]" }, { "label": "Status", "value_md": "Active open standard; current stateless specification version `2026-07-28` is ready for use; next specification targeted for late March 2027 [9][12]" }, { "label": "Version", "value_md": "`2026-07-28` (stateless core); prior handshake revisions: `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05`; next specification targeted for late March 2027 [1][9][13]" }, { "label": "Message format", "value_md": "JSON-RPC 2.0 requests, responses, and notifications (`application/json` and `text/event-stream`) [5][14]" }, { "label": "Transports", "value_md": "`stdio` (newline-delimited JSON-RPC over subprocess streams) and Streamable HTTP (`POST` to one MCP endpoint) [4][5]" }, { "label": "Specification", "value_md": "[Model Context Protocol Specification (2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28) [1]" }, { "label": "Found at", "value_md": "Operator endpoint URL or `server.json` in [Official MCP Registry](/protocols/mcp-registry/); optional [MCP Server Card](/protocols/mcp-server-cards/) at any unreserved URI (with `/server-card` reserved as the recommended location) [15][16]" }, { "label": "Licence", "value_md": "Apache License 2.0 for outbound code and specifications; CC BY 4.0 for non-specification documentation [11]" } ], "v05_problem_md": "Before MCP, connecting AI assistants to external content repositories and legacy systems required a custom integration for every data source, isolating models behind information silos. Even after MCP standardized JSON-RPC host-to-server connectors, revisions through 2025-11-25 opened a stateful session via an `initialize` handshake and `Mcp-Session-Id` header, preventing follow-up requests from landing freely on any instance behind a plain round-robin load balancer without shared storage. [2][6][7][10] Revision 2026-07-28 puts `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in `_meta` on every JSON-RPC request, and Streamable HTTP repeats that version in `MCP-Protocol-Version`. A server that needs more input during `tools/call`, `resources/read`, or `prompts/get` returns `InputRequiredResult` with `input_required` instead of starting its own JSON-RPC request. [5][6][17] Servers remain isolated from the full conversation and from other connected servers, while optional protocol extensions require explicit opt-in from both client and server. HTTP authorization is optional and uses OAuth 2.1 Protected Resource Metadata (`RFC 9728`) and Resource Indicators (`RFC 8707`), whereas `stdio` retrieves credentials from the environment. [1][18][19]", "v05_mechanism_delta_md": "Revision 2026-07-28 puts `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in `_meta` on every JSON-RPC request, and Streamable HTTP repeats that version in `MCP-Protocol-Version`. A server that needs more input during `tools/call`, `resources/read`, or `prompts/get` returns `InputRequiredResult` with `input_required` instead of starting its own JSON-RPC request. [5][6][17]", "v05_scope_boundary_md": "Servers remain isolated from the full conversation and from other connected servers, while optional protocol extensions require explicit opt-in from both client and server. HTTP authorization is optional and uses OAuth 2.1 Protected Resource Metadata (`RFC 9728`) and Resource Indicators (`RFC 8707`), whereas `stdio` retrieves credentials from the environment. [1][18][19]", "v05_fuzzy_additions": [ { "id": "server-discovery-and-stateless-transports-on-stdio-and-streamable-http", "heading": "Server discovery and stateless transports on stdio and Streamable HTTP", "body_md": "Revision 2026-07-28 replaces the stateful `initialize` session used in 2025-11-25 and earlier with stateless per-request metadata. There is no negotiation handshake: every request declares its protocol version in `_meta` (and, on HTTP, in `MCP-Protocol-Version`) alongside `_meta.io.modelcontextprotocol/clientCapabilities`, and the server accepts or rejects each request independently. Servers advertise supported capabilities and optional `extensions` such as `io.modelcontextprotocol/tasks` through `server/discover`. [7][18]", "bullets": [ { "label": "Discover and version mismatch", "text_md": "Servers MUST implement `server/discover` (returning `supportedVersions`). Clients MAY skip `server/discover` and handle `UnsupportedProtocolVersionError` (for example, `\"supported\": [ \"2026-07-28\", \"2025-11-25\" ]`), then SHOULD retry a mutually supported version. On `stdio`, a dual-era client SHOULD send `server/discover` before `initialize`. [7][20]" }, { "label": "Streamable HTTP request", "text_md": "One MCP endpoint supports `POST`. Each JSON-RPC message is its own HTTP POST. Accept MUST list `application/json` and `text/event-stream`. The body is one request or notification, never a response. `MCP-Protocol-Version` MUST match `io.modelcontextprotocol/protocolVersion` in `_meta`. `Mcp-Method` names the method; `Mcp-Name` carries `params.name` or `params.uri` for `tools/call`, `resources/read`, and `prompts/get`. [5]" }, { "label": "JSON, SSE, retired sessions, and 2026-07-28 breaking changes", "text_md": "A request returns `Content-Type: application/json` or `Content-Type: text/event-stream`; clients MUST support both, and SSE stays scoped to that POST until the final response. Accepted notifications return `202 Accepted` with no body. Revision 2026-07-28 removes `Mcp-Session-Id` sessions and standalone GET SSE streams so cross-call state uses explicit server-minted handles passed as ordinary tool arguments; it also replaces `resources/subscribe` and `resources/unsubscribe` with `subscriptions/listen`, removes `ping`, `logging/setLevel`, `notifications/roots/list_changed`, and `Last-Event-ID` SSE stream resumability, and requires a `resultType` discriminator (`complete` vs. `input_required` in `InputRequiredResult`). [5][6]" }, { "label": "`stdio` subprocess framing", "text_md": "`stdio` launches the server as a subprocess. JSON-RPC on `stdin` and `stdout` is one newline-delimited message, with no embedded newlines, and `stdout` carries nothing else. Logs MAY use `stderr` and are not an error signal. `stdio` SHOULD NOT follow the HTTP authorization specification; credentials come from the environment. [4][19]" } ] }, { "id": "server-primitives-client-primitives-oauth-2-1-and-security-considerations", "heading": "Server primitives, client primitives, OAuth 2.1, and security considerations", "body_md": "Servers expose resources, prompts, and tools; clients may expose elicitation, `sampling`, and `roots`. Revision 2026-07-28 deprecates `sampling`, `roots`, and `logging` (`SEP-2577`), along with OAuth Dynamic Client Registration (`PR #2858`), with earliest removal in the first revision released on or after 2027-07-28: implementations SHOULD replace `sampling` with direct LLM provider APIs and pass directories or files via tool parameters or resource URIs instead of `roots`. Server-to-client calls (`roots/list`, `sampling/createMessage`, and `elicitation/create`) MUST use the Multi Round-Trip Requests (`MRTR`) pattern rather than server-initiated requests. [6][14][17][21][22][23]", "bullets": [ { "label": "Model-controlled tools", "text_md": "Tools are model-controlled, and a person SHOULD be able to deny a call. Servers declare the `tools` capability. `tools/list` MUST NOT vary per-connection, though it MAY follow the request's authorization. `tools/call` MAY return `InputRequiredResult` with `input_required` when the tool needs more input. [24]" }, { "label": "Resources, prompts, and JSON-RPC 2.0 server error codes", "text_md": "Resources are application-driven and identified by a URI; clients call `resources/list` and `resources/read`, while servers that advertise the `resources` `listChanged` or `subscribe` capability flags deliver resource-specific update notifications when clients subscribe via `subscriptions/listen` (`notifications.resourceSubscriptions`). Prompts are user-controlled templates—often surfaced as slash commands—accessed via `prompts/list` and `prompts/get` (neither list may vary per-connection). MCP partitions the JSON-RPC 2.0 server-error block (`-32000` to `-32099`) into `-32000` to `-32019` for legacy implementation-defined server errors (where `-32002` was used in 2025-11-25 and earlier for resource not found before 2026-07-28 standardized `-32602`) and `-32020` to `-32099` reserved for the MCP specification (`-32020` `HeaderMismatch`, `-32021` `MissingRequiredClientCapability`, `-32022` `UnsupportedProtocolVersion`, plus reserved 2025-11-25 code `-32042` for URL elicitation required). [6][14][25][26]" }, { "label": "Elicitation, sampling, roots, and security considerations", "text_md": "Elicitation runs inside another call: Form mode takes structured data with an optional JSON schema, while URL mode is required for passwords, API keys, access tokens, and payment credentials so they do not pass through the client, and on resumption the server checks the echoed `requestState` before returning a final result. `sampling` requests model output via the client without server API keys, and `roots` are informational filesystem guidance that the protocol does not enforce. For trust, safety, and security, `serverInfo` is self-reported and unverified (clients SHOULD NOT use it to change behavior or make security decisions), and clients MUST consider tool annotations untrusted unless received from trusted servers. MCP servers MUST NOT accept tokens not explicitly issued for the server, and local `stdio` servers from untrusted sources carry arbitrary code execution risks. [20][21][22][24][27][28]" }, { "label": "OAuth 2.1 resource metadata", "text_md": "Authorization is OPTIONAL; `stdio` SHOULD NOT follow it. Servers MUST publish `RFC 9728` Protected Resource Metadata, which clients use to discover the authorization server. `RFC 8707` requires `resource` on authorization and token requests, set to the canonical URI. `client_id` is an HTTPS URL when `client_id_metadata_document_supported` is set, and the document MUST include `client_id`, `client_name`, and `redirect_uris`. `RFC 7591` is deprecated as of 2026-07-28. Authorization servers SHOULD include the `iss` parameter in authorization responses per `RFC 9207`, and MCP clients MUST validate a present `iss` against the recorded issuer before redeeming the authorization code (`SEP-2468`). Client credentials are bound to the issuing authorization server: clients MUST key persisted credentials by the issuer identifier and MUST NOT reuse them with a different authorization server (`SEP-2352`). [6][19][23][29]" } ] } ], "v05_diagram": { "title": "Client-host-server architecture", "heading": "Client-host-server architecture", "mermaid": "flowchart LR\n subgraph Host[\"Host application\"]\n Coord[\"Coordinator: consent, auth, context\"]\n C1[\"Client 1\"]\n C2[\"Client 2\"]\n Coord --> C1\n Coord --> C2\n end\n S1[\"Server: local process\"]\n S2[\"Server: remote service\"]\n C1 <-->|\"JSON-RPC, 1:1\"| S1\n C2 <-->|\"JSON-RPC, 1:1\"| S2", "caption_md": "A host application creates and manages multiple clients, each with a `1:1` relationship to one server. Those servers can be local processes or remote services. MCP is a stateless protocol built on `JSON-RPC`: every request is self-contained and carries its own protocol version and capabilities. [18]" }, "v05_wire_artifact": { "title": "server/discover request and response (2026-07-28)", "heading": "server/discover request and response (2026-07-28)", "lang": "json", "code": "{\n \"jsonrpc\": \"2.0\",\n \"id\": \"discover-1\",\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"ExampleClient\",\n \"version\": \"1.0.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}\n\n{\n \"jsonrpc\": \"2.0\",\n \"id\": \"discover-1\",\n \"result\": {\n \"resultType\": \"complete\",\n \"supportedVersions\": [\"2026-07-28\"],\n \"capabilities\": {\n \"tools\": {},\n \"resources\": {}\n },\n \"_meta\": {\n \"io.modelcontextprotocol/serverInfo\": {\n \"name\": \"ExampleServer\",\n \"version\": \"1.0.0\"\n }\n },\n \"instructions\": \"This server provides weather and resource utilities.\",\n \"ttlMs\": 3600000,\n \"cacheScope\": \"public\"\n }\n}", "caption_md": "`server/discover` request and response (servers MUST implement `server/discover`; clients MAY skip it before sending other requests). The result carries protocol version `2026-07-28`, capabilities, and identity in `_meta`, with `ttlMs` and `cacheScope`, in place of the legacy `initialize` handshake. [20]" }, "v05_counterparts": { "classic_analogues": [ { "name": "JSON-RPC 2.0 Specification", "spec_or_rfc": "JSON-RPC 2.0", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Profiles JSON-RPC 2.0 over stdio or Streamable HTTP POST with stateless per-request version and capability metadata in `_meta`. [6][14]" }, { "name": "Language Server Protocol (LSP)", "spec_or_rfc": "LSP", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Adapts LSP's reusable client-server architecture from IDE language intelligence to AI host integration with tools, resources, and prompts. [1]" } ], "agentic_peers": [ { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "A2A delegates multi-turn tasks between opaque peer agents, whereas MCP connects a host client to server tools and resources. [1]" }, { "target_id": "webmcp", "target_name": "WebMCP", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "WebMCP registers page-scoped tools on `document.modelContext` in browser JavaScript, whereas MCP connects hosts to stdio or HTTP servers. [4][5][30]" }, { "target_id": "mcp-apps", "target_name": "MCP Apps", "relation_type": "has_component", "relation_label": "Has component", "delta_md": "SEP-1865 extension declaring interactive `ui://` resources linked to tools for bidirectional host-iframe communication. [31]" }, { "target_id": "mcp-registry", "target_name": "Official MCP Registry", "relation_type": "has_component", "relation_label": "Has component", "delta_md": "Centralized preview metadata index publishing `server.json` records for public MCP packages and remote server URLs. [15]" }, { "target_id": "ag-ui", "target_name": "Agent-User Interaction Protocol (AG-UI)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "AG-UI streams agent-to-frontend UI state events over HTTP, whereas MCP connects the backend agent host to tool servers. [1]" }, { "target_id": "anthropic-agent-skills-format", "target_name": "Agent Skills", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Packages filesystem `SKILL.md` workflow instructions, which MCP also exposes dynamically through the optional Skills over MCP extension. [1]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (22 probed or cited examples across 4 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "MCP Servers (Remote Endpoints & Local Packages)", "col4_header": "Transport, Capabilities & Scope", "note_md": "HTTP 200 and HTTP 401 probe responses and vendor documentation establish endpoint presence or declared support as of the stated check date rather than verified 2026-07-28 wire conformance. [7]", "rows": [ { "actor": "Hugging Face", "role": "Remote MCP server", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Streamable HTTP at `https://huggingface.co/mcp` returning `2026-07-28`, `tools`, `resources`, and `io.modelcontextprotocol/skills`.", "source_md": "[huggingface.co/mcp](https://huggingface.co/mcp) [32] · [HF Hub MCP docs](https://huggingface.co/docs/hub/agents-mcp) [33]" }, { "actor": "Cloudflare Docs", "role": "Remote MCP server", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Streamable HTTP at `https://docs.mcp.cloudflare.com/mcp` (`docs-ai-search` `0.5.0`) advertising `2026-07-28`, `tools`, and `prompts`.", "source_md": "[docs.mcp.cloudflare.com/mcp](https://docs.mcp.cloudflare.com/mcp) [34] · [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/) [35]" }, { "actor": "GitHub", "role": "Remote & local MCP server", "status": "Live (HTTP 401)", "status_display": "Live (HTTP 401) · checked 2026-10-30", "col4_md": "Remote HTTP server at `https://api.githubcopilot.com/mcp/` with OAuth `resource_metadata` challenge and Go `stdio` server.", "source_md": "[api.githubcopilot.com/mcp/](https://api.githubcopilot.com/mcp/) [36] · [github/github-mcp-server](https://github.com/github/github-mcp-server) [37]" }, { "actor": "Stripe", "role": "Remote & local MCP server", "status": "Live (HTTP 401)", "status_display": "Live (HTTP 401) · checked 2026-10-30", "col4_md": "Remote server at `https://mcp.stripe.com` with OAuth `resource_metadata` challenge, Agent API keys, and `missing_api_key` error.", "source_md": "[mcp.stripe.com](https://mcp.stripe.com) [38] · [Stripe MCP docs](https://docs.stripe.com/mcp) [39]" }, { "actor": "Linear", "role": "Remote MCP server", "status": "Live (HTTP 401)", "status_display": "Live (HTTP 401) · checked 2026-10-30", "col4_md": "Streamable HTTP at `https://mcp.linear.app/mcp` with OAuth 2.1 `resource_metadata` challenge and `https://mcp.linear.app/mcp/readonly`.", "source_md": "[mcp.linear.app/mcp](https://mcp.linear.app/mcp) [40] · [Linear MCP docs](https://linear.app/docs/mcp) [41]" }, { "actor": "Atlassian Rovo", "role": "Remote MCP server", "status": "Listed", "status_display": "Listed · as of 2026-09-09", "col4_md": "Registry entry `com.atlassian/atlassian-mcp-server` (`2.0.0`) advertising `streamable-http` at `https://mcp.atlassian.com/v2/mcp` and `https://mcp.atlassian.com/v1/mcp/authv2`.", "source_md": "[MCP Registry (v2.0.0)](https://registry.modelcontextprotocol.io/v0.1/servers/com.atlassian%2Fatlassian-mcp-server/versions/2.0.0) [42]" }, { "actor": "Notion", "role": "Remote MCP server", "status": "Listed", "status_display": "Listed · as of 2025-09-11", "col4_md": "Registry entry `com.notion/mcp` (`1.0.1`) advertising `streamable-http` (`https://mcp.notion.com/mcp`) and `sse` (`https://mcp.notion.com/sse`).", "source_md": "[MCP Registry (v1.0.1)](https://registry.modelcontextprotocol.io/v0.1/servers/com.notion%2Fmcp/versions/1.0.1) [43]" }, { "actor": "Microsoft Playwright", "role": "Local MCP server", "status": "Listed", "status_display": "Listed · as of 2026-09-18", "col4_md": "Registry entry `io.github.microsoft/playwright-mcp` (`0.0.82`) distributing npm package `@playwright/mcp` over local `stdio`.", "source_md": "[MCP Registry (v0.0.82)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.microsoft%2Fplaywright-mcp/versions/0.0.82) [44]" } ] }, "side_b": { "visible": true, "heading": "AI Host Applications & IDEs", "col4_header": "Transport, Capabilities & Scope", "note_md": "Vendor documentation and release notes establish declared client and harness support rather than verified 2026-07-28 wire conformance. [7]", "rows": [ { "actor": "Claude", "role": "AI host application", "status": "Partial", "status_display": "Partial · as of 2026-10-30", "col4_md": "Remote MCP connectors (OAuth or headers) and local `claude_desktop_config.json` servers; stateless `2026-07-28` rollout in progress.", "source_md": "[Claude remote MCP connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) [45] · [Bringing MCP 2026-07-28 to Claude](https://claude.com/resources/articles/bringing-mcp-2026-07-28-to-claude) [46]" }, { "actor": "Visual Studio Code", "role": "IDE host", "status": "Supported", "status_display": "Supported · as of 2025-06-12", "col4_md": "Supports `streamable HTTP` and local transports, OAuth resource-server authorization, `tools`, `prompts`, `resources`, and `sampling`.", "source_md": "[VS Code full MCP spec support](https://code.visualstudio.com/blogs/2025/06/12/full-mcp-spec-support) [47]" }, { "actor": "Cursor", "role": "IDE host", "status": "Supported", "status_display": "Supported · as of 2025-06-04", "col4_md": "Supports one-click MCP server installation and OAuth authentication in Cursor `1.0`.", "source_md": "[Cursor 1.0 changelog](https://cursor.com/changelog/1-0) [48]" }, { "actor": "Gemini CLI", "role": "CLI coding agent", "status": "Supported", "status_display": "Supported · as of 2025-06-25", "col4_md": "Open-source (`Apache 2.0`) terminal agent with built-in Model Context Protocol client support and bundled extensions.", "source_md": "[Introducing Gemini CLI](https://blog.google/innovation-and-ai/technology/developers-tools/introducing-gemini-cli-open-source-ai-agent/) [49]" }, { "actor": "Microsoft Foundry", "role": "Enterprise agent platform", "status": "Supported (release announcement)", "status_display": "Supported (release announcement) · as of 2026-07-28", "col4_md": "Release announcement claims unified MCP endpoint with stateless `2026-07-28` and `Tasks`; no independent feature-matrix verification.", "source_md": "[MCP 2026-07-28 release blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/) [10]" } ] }, "additional_tables": [ { "visible": true, "heading": "Registries, Directories & Discovery Indexes", "col4_header": "Catalog & ingestion model", "note_md": "Discovery catalogs and sub-registries that index `server.json` metadata or crawl public MCP server packages (see also [MCP Registry](/protocols/mcp-registry/)). [15][50]", "rows": [ { "actor": "Official MCP Registry", "role": "Central metadata repository", "status": "Supported (preview)", "status_display": "Supported (preview) · checked 2026-10-30", "col4_md": "Official `server.json` catalog (`GET /v0.1/servers`) at `https://registry.modelcontextprotocol.io` for downstream aggregators.", "source_md": "[The MCP Registry](https://modelcontextprotocol.io/registry/about) [15] · [MCP Registry Aggregators](https://modelcontextprotocol.io/registry/registry-aggregators) [50]" }, { "actor": "GitHub MCP Registry", "role": "Sub-registry & IDE directory", "status": "Supported", "status_display": "Supported · as of 2025-09-16", "col4_md": "Ingests servers self-published to the OSS MCP Community Registry into GitHub and VS Code.", "source_md": "[Meet the GitHub MCP Registry](https://github.blog/ai-and-ml/github-copilot/meet-the-github-mcp-registry-the-fastest-way-to-discover-mcp-servers/) [51]" }, { "actor": "Glama", "role": "Aggregator & sandbox index", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Ingests the official registry and layers sandbox schema captures, behavioral analysis, and TDQS scores.", "source_md": "[Glama MCP methodology](https://glama.ai/mcp/methodology) [52]" }, { "actor": "PulseMCP", "role": "Sub-registry & directory", "status": "Partial", "status_display": "Partial · as of 2025-09-09", "col4_md": "Ingests the Official MCP Registry as a downstream sub-registry supplemented with web indexing; live directory temporarily pauses new submissions.", "source_md": "[PulseMCP Work With Us](https://www.pulsemcp.com/work-with-us) [53] · [PulseMCP Official Registry launch](https://www.pulsemcp.com/posts/newsletter-claude-code-competition-ai-fundraising-abounds-mcp-registry-launch) [54] · [PulseMCP server directory](https://www.pulsemcp.com/servers/) [55]" }, { "actor": "MCP Census", "role": "Trust-layer census over registries", "status": "Listed", "status_display": "Listed · as of 2026-11-04", "col4_md": "Trust layer returning PASS, REVIEW, BLOCK, or UNKNOWN; `57,777` rows.", "source_md": "[MCP registries compared](https://mcpcensus.com/compare/mcp-registries) [56]" } ] }, { "visible": true, "heading": "SDKs, Runtimes & Developer Tooling", "col4_header": "Supported languages / packaging", "note_md": "Reference protocol SDKs, serverless hosting frameworks, local archive formats, and conformance debuggers used to build and test MCP clients and servers. [57]", "rows": [ { "actor": "Official MCP SDKs", "role": "Client & server SDKs", "status": "Partial", "status_display": "Partial · as of 2026-10-30", "col4_md": "Current `Tier 1` roster lists 6 official SDKs (`TypeScript`, `Python`, `C#`, `Go`, `Rust`, and `Ruby`), plus Tier 2 `Java` and Tier 3 `Kotlin`, `Swift`, and `PHP` (July 2026 release covered `TypeScript`, `Python`, `Go`, `C#`, and `Rust` beta). The official Ruby SDK reached Tier 1 on 2026-10-30, with full support for the 2026-07-28 specification and a 100% conformance pass rate across both scored spec versions.", "source_md": "[Official MCP SDKs](https://modelcontextprotocol.io/docs/sdk) [57] · [MCP 2026-07-28 release blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/) [10] · [MCP Ruby SDK versions](https://ruby.sdk.modelcontextprotocol.io/protocol-versions/) [13] · [Ruby SDK reaches Tier 1](https://blog.modelcontextprotocol.io/posts/ruby-sdk-tier-1/) [9]" }, { "actor": "MCP Inspector", "role": "Developer testing client", "status": "Supported", "status_display": "Supported · as of 2026-07-28", "col4_md": "Reference `@modelcontextprotocol/inspector` package providing Web, `--cli`, and `--tui` clients across `stdio` and HTTP for `2026-07-28`.", "source_md": "[MCP Inspector docs](https://modelcontextprotocol.io/docs/tools/inspector) [58]" }, { "actor": "Cloudflare Agents SDK", "role": "Server & client runtime", "status": "Supported", "status_display": "Supported · as of 2026-10-27", "col4_md": "Workers runtime supporting stateless `2026-07-28` MCP servers, `Streamable HTTP`, `insufficientScope()` OAuth challenges, and `MCPClientManager`.", "source_md": "[Cloudflare Agents MCP docs](https://developers.cloudflare.com/agents/model-context-protocol/) [59] · [MCP 2026-07-28 blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/) [10]" }, { "actor": "MCP Bundles (MCPB)", "role": "Local server bundle format", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Zip archive format (`.mcpb`, formerly `.dxt`) bundling a local MCP server with `manifest.json` via `@anthropic-ai/mcpb`.", "source_md": "[modelcontextprotocol/mcpb](https://raw.githubusercontent.com/modelcontextprotocol/mcpb/main/README.md) [60]" } ] } ], "censuses": [ { "label": "One Year of MCP (2025-11-25)", "as_of": "2025-11-25", "value_md": "Close to 2,000 server entries indexed in the Official MCP Registry as of November 25, 2025, representing 407% growth from the initial batch onboarded at the registry's September 2025 launch. [61]" }, { "label": "Anthropic AAIF donation announcement (2025-12-09)", "as_of": "2025-12-09", "value_md": "More than 10,000 active public MCP servers published across the ecosystem as of December 9, 2025, when Anthropic donated MCP to the Linux Foundation's Agentic AI Foundation. [62]" }, { "label": "MCP 2026-07-28 release announcement", "as_of": "2026-07-28", "value_md": "Close to 500 million monthly downloads across official Tier 1 MCP SDKs as of July 28, 2026, with both the TypeScript and Python SDKs surpassing 1 billion total downloads. [10]" }, { "label": "MCP registries compared (read 4 November 2026)", "as_of": "2026-11-04", "value_md": "On 4 November 2026 the MCP Census comparison records Glama at 115,336 servers (Remote 45,340, Local 43,442), its own census at 57,777 server rows, PulseMCP at 21,602 servers, and the Docker MCP Catalog at 300+ servers. Smithery's API, Connect, accounts, CLI, and proxy URLs stopped on 31 October 2026. [56]" }, { "label": "State of MCP Server Development (LocalCan, checked 14 October 2026)", "as_of": "2026-10-14", "value_md": "LocalCan's census, measured on 14 October 2026, counts 43,012 active servers in the official MCP Registry. Across that set, 59.6% are remote-only, 34.6% ship only as a package, 4.7% offer both, and 1.1% list neither. [63]" }, { "label": "MCP server directories (Apideck, 31 October 2026)", "as_of": "2026-10-31", "value_md": "Apideck's 31 October 2026 table counts the official registry API at 53,541 servers, Glama at 113,204 servers and 40,151 connectors, PulseMCP at 21,614, MCP Market at 50,999, and the Cursor Marketplace at about 490 plugins. [64]" }, { "label": "MCP-Eco (arXiv HTML, Parquet export 2026-06-23)", "as_of": "2026-06-23", "value_md": "The MCP-Eco frozen release, exported to Parquet on 2026-06-23, covers 78,302 candidate server projects. Its crawler queries the official MCP registry, Glama, Smithery, and PulseMCP, and reads MCP.so listing pages found through sitemaps. [65]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "mcp-server-cards", "target_name": "MCP Server Cards", "relation_label": "Has component", "delta": "SEP-2127 is the MCP extension whose Server Card is read with `GET /server-card` before the client connects, and the card omits the tools, resources, and prompts the live server still provides.", "item_md": "**[MCP Server Cards](/protocols/mcp-server-cards/)** (Has component) — SEP-2127 is the MCP extension whose Server Card is read with `GET /server-card` before the client connects, and the card omits the tools, resources, and prompts the live server still provides." }, { "item_md": "**Depended on by:** [Ad Context Protocol (AdCP)](/protocols/adcp/), [Agentic Real Time Framework](/protocols/artf/), [Coral Protocol (CoralOS)](/protocols/coral-protocol/), [Discovery of Model Context Protocol Servers via DNS TXT Records](/protocols/mcp-dns-discovery/), [KYA-OS (Know Your Agent Operating System)](/protocols/kya-os/), [OpenAI Apps SDK manifests](/protocols/openai-apps-sdk-manifests/), [Per-Call Proof for Local Tool Invocation by AI Agents](/protocols/local-tool-call-proof/)" }, { "item_md": "**Peer alternatives:** [Agent Protocol](/protocols/agent-protocol-aief/), [agents.json](/protocols/agents-json/)" }, { "item_md": "**Complements:** [A2UI (Agent to UI) Protocol](/protocols/a2ui/), [Agent Client Protocol](/protocols/agent-client-protocol/), [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), [AGENTS.md](/protocols/agents-md/), [ERC-8004: Trustless Agents](/protocols/erc-8004/), [L402](/protocols/l402/), [OAuth Client ID Metadata Document](/protocols/oauth-cimd/), [OAuth Protected Resource and Authorization Server Metadata (as used for agent authorization)](/protocols/oauth-metadata-for-agents/), [Open Responses](/protocols/open-responses/), [Universal Commerce Protocol (UCP)](/protocols/ucp/), and [32 more in the protocol directory](/protocols/)" }, { "item_md": "**[Act protocols](/category/act/)** — Category index for `act` standards." } ], "v05_compiled_md": "---\nid: mcp\ntitle: \"Model Context Protocol\"\ntier: flagship\nlifecycle_status: active\ncategory: act\nform: endpoint\nwire_archetype: harnesses_rpc_ui\nspec_url: https://modelcontextprotocol.io/specification/2026-07-28\nlast_checked: 2026-11-11\n---\n\n# Model Context Protocol\n\n**Category:** [Act](/category/act/) (`act`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-11\n\n> *This article covers the Model Context Protocol (MCP) for host-to-server context and tool exchange. For the browser DOM API, see [WebMCP](/protocols/webmcp/); for server discovery, see [Official MCP Registry](/protocols/mcp-registry/) and [MCP Server Cards](/protocols/mcp-server-cards/). [1]*\n\n> **In brief:** MCP is a universal connector standard that lets AI applications (such as Claude, VS Code, or Cursor) plug into external data sources and tools (such as GitHub, Stripe, or Notion) without custom point-to-point integration code. Instead of building a bespoke connector for every AI host and external service, developers expose one MCP server with standardized `tools`, `resources`, and `prompts` that any MCP-compatible host can call over local `stdio` or HTTP. [1][2]\n\nThe **Model Context Protocol** (**MCP**) is an open protocol that uses `JSON-RPC 2.0` messages to connect LLM host applications with servers that provide context and capabilities. Anthropic introduced it on 2024-11-25 as a universal, open standard for connecting AI systems with data sources. The Linux Foundation's Agentic AI Foundation (AAIF) now stewards MCP as a founding project, alongside Block's goose and OpenAI's AGENTS.md. [1][2][3] On `stdio`, the client launches the MCP server as a subprocess; the server reads JSON-RPC messages from `stdin` and writes JSON-RPC messages to `stdout`, delimited by newlines. On Streamable HTTP, every JSON-RPC request is its own HTTP `POST` to a single MCP endpoint, and the server answers with either `Content-Type: application/json` or `Content-Type: text/event-stream`. [4][5] The 2025-11-25 revision serves as the legacy Streamable HTTP session baseline (succeeding 2025-03-26 and 2024-11-05), while the 2026-07-28 revision retires the `initialize` / `notifications/initialized` handshake, `Mcp-Session-Id` headers, and standalone GET SSE streams. [5][6][7] A roadmap published on 2026-08-22 organizes later specification work into five priority areas, picking up server-initiated events, result type improvements, and agent identity, together with HTTP-native transport and SDK developer experience. [8] On 2026-10-30 the official Ruby SDK reached Tier 1, with full support for the 2026-07-28 specification and a 100% conformance pass rate across both scored spec versions. [9] The Ruby SDK team has committed to supporting the next MCP specification, targeted for late March 2027, by its release date. [9]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Act](/category/act/) (`act`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | Anthropic; co-invented by David Soria Parra and Justin Spahr-Summers (open-sourced November 2024) [3][10][11] |\n| **Governed by** | Agentic AI Foundation (AAIF) under the Linux Foundation since 2025-12-09; Lead Maintainers hold final decision authority [3][11] |\n| **Track** | Foundation / Consortium Specification (`linux-foundation`); founding project of the Agentic AI Foundation [3] |\n| **Status** | Active open standard; current stateless specification version `2026-07-28` is ready for use; next specification targeted for late March 2027 [9][12] |\n| **Version** | `2026-07-28` (stateless core); prior handshake revisions: `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05`; next specification targeted for late March 2027 [1][9][13] |\n| **Message format** | JSON-RPC 2.0 requests, responses, and notifications (`application/json` and `text/event-stream`) [5][14] |\n| **Transports** | `stdio` (newline-delimited JSON-RPC over subprocess streams) and Streamable HTTP (`POST` to one MCP endpoint) [4][5] |\n| **Specification** | [Model Context Protocol Specification (2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28) [1] |\n| **Found at** | Operator endpoint URL or `server.json` in [Official MCP Registry](/protocols/mcp-registry/); optional [MCP Server Card](/protocols/mcp-server-cards/) at any unreserved URI (with `/server-card` reserved as the recommended location) [15][16] |\n| **Licence** | Apache License 2.0 for outbound code and specifications; CC BY 4.0 for non-specification documentation [11] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Server discovery and stateless transports on stdio and Streamable HTTP](#server-discovery-and-stateless-transports-on-stdio-and-streamable-http)\n3. [Server primitives, client primitives, OAuth 2.1, and security considerations](#server-primitives-client-primitives-oauth-2-1-and-security-considerations)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nBefore MCP, connecting AI assistants to external content repositories and legacy systems required a custom integration for every data source, isolating models behind information silos. Even after MCP standardized JSON-RPC host-to-server connectors, revisions through 2025-11-25 opened a stateful session via an `initialize` handshake and `Mcp-Session-Id` header, preventing follow-up requests from landing freely on any instance behind a plain round-robin load balancer without shared storage. [2][6][7][10] Revision 2026-07-28 puts `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in `_meta` on every JSON-RPC request, and Streamable HTTP repeats that version in `MCP-Protocol-Version`. A server that needs more input during `tools/call`, `resources/read`, or `prompts/get` returns `InputRequiredResult` with `input_required` instead of starting its own JSON-RPC request. [5][6][17] Servers remain isolated from the full conversation and from other connected servers, while optional protocol extensions require explicit opt-in from both client and server. HTTP authorization is optional and uses OAuth 2.1 Protected Resource Metadata (`RFC 9728`) and Resource Indicators (`RFC 8707`), whereas `stdio` retrieves credentials from the environment. [1][18][19]\n\n### Client-host-server architecture\n\n```mermaid\nflowchart LR\n subgraph Host[\"Host application\"]\n Coord[\"Coordinator: consent, auth, context\"]\n C1[\"Client 1\"]\n C2[\"Client 2\"]\n Coord --> C1\n Coord --> C2\n end\n S1[\"Server: local process\"]\n S2[\"Server: remote service\"]\n C1 <-->|\"JSON-RPC, 1:1\"| S1\n C2 <-->|\"JSON-RPC, 1:1\"| S2\n```\n\n*A host application creates and manages multiple clients, each with a `1:1` relationship to one server. Those servers can be local processes or remote services. MCP is a stateless protocol built on `JSON-RPC`: every request is self-contained and carries its own protocol version and capabilities. [18]*\n\n### server/discover request and response (2026-07-28)\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": \"discover-1\",\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"ExampleClient\",\n \"version\": \"1.0.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}\n\n{\n \"jsonrpc\": \"2.0\",\n \"id\": \"discover-1\",\n \"result\": {\n \"resultType\": \"complete\",\n \"supportedVersions\": [\"2026-07-28\"],\n \"capabilities\": {\n \"tools\": {},\n \"resources\": {}\n },\n \"_meta\": {\n \"io.modelcontextprotocol/serverInfo\": {\n \"name\": \"ExampleServer\",\n \"version\": \"1.0.0\"\n }\n },\n \"instructions\": \"This server provides weather and resource utilities.\",\n \"ttlMs\": 3600000,\n \"cacheScope\": \"public\"\n }\n}\n```\n\n*`server/discover` request and response (servers MUST implement `server/discover`; clients MAY skip it before sending other requests). The result carries protocol version `2026-07-28`, capabilities, and identity in `_meta`, with `ttlMs` and `cacheScope`, in place of the legacy `initialize` handshake. [20]*\n\n---\n\n## Server discovery and stateless transports on stdio and Streamable HTTP\n\nRevision 2026-07-28 replaces the stateful `initialize` session used in 2025-11-25 and earlier with stateless per-request metadata. There is no negotiation handshake: every request declares its protocol version in `_meta` (and, on HTTP, in `MCP-Protocol-Version`) alongside `_meta.io.modelcontextprotocol/clientCapabilities`, and the server accepts or rejects each request independently. Servers advertise supported capabilities and optional `extensions` such as `io.modelcontextprotocol/tasks` through `server/discover`. [7][18]\n\n- **Discover and version mismatch:** Servers MUST implement `server/discover` (returning `supportedVersions`). Clients MAY skip `server/discover` and handle `UnsupportedProtocolVersionError` (for example, `\"supported\": [ \"2026-07-28\", \"2025-11-25\" ]`), then SHOULD retry a mutually supported version. On `stdio`, a dual-era client SHOULD send `server/discover` before `initialize`. [7][20]\n- **Streamable HTTP request:** One MCP endpoint supports `POST`. Each JSON-RPC message is its own HTTP POST. Accept MUST list `application/json` and `text/event-stream`. The body is one request or notification, never a response. `MCP-Protocol-Version` MUST match `io.modelcontextprotocol/protocolVersion` in `_meta`. `Mcp-Method` names the method; `Mcp-Name` carries `params.name` or `params.uri` for `tools/call`, `resources/read`, and `prompts/get`. [5]\n- **JSON, SSE, retired sessions, and 2026-07-28 breaking changes:** A request returns `Content-Type: application/json` or `Content-Type: text/event-stream`; clients MUST support both, and SSE stays scoped to that POST until the final response. Accepted notifications return `202 Accepted` with no body. Revision 2026-07-28 removes `Mcp-Session-Id` sessions and standalone GET SSE streams so cross-call state uses explicit server-minted handles passed as ordinary tool arguments; it also replaces `resources/subscribe` and `resources/unsubscribe` with `subscriptions/listen`, removes `ping`, `logging/setLevel`, `notifications/roots/list_changed`, and `Last-Event-ID` SSE stream resumability, and requires a `resultType` discriminator (`complete` vs. `input_required` in `InputRequiredResult`). [5][6]\n- **`stdio` subprocess framing:** `stdio` launches the server as a subprocess. JSON-RPC on `stdin` and `stdout` is one newline-delimited message, with no embedded newlines, and `stdout` carries nothing else. Logs MAY use `stderr` and are not an error signal. `stdio` SHOULD NOT follow the HTTP authorization specification; credentials come from the environment. [4][19]\n\n---\n\n## Server primitives, client primitives, OAuth 2.1, and security considerations\n\nServers expose resources, prompts, and tools; clients may expose elicitation, `sampling`, and `roots`. Revision 2026-07-28 deprecates `sampling`, `roots`, and `logging` (`SEP-2577`), along with OAuth Dynamic Client Registration (`PR #2858`), with earliest removal in the first revision released on or after 2027-07-28: implementations SHOULD replace `sampling` with direct LLM provider APIs and pass directories or files via tool parameters or resource URIs instead of `roots`. Server-to-client calls (`roots/list`, `sampling/createMessage`, and `elicitation/create`) MUST use the Multi Round-Trip Requests (`MRTR`) pattern rather than server-initiated requests. [6][14][17][21][22][23]\n\n- **Model-controlled tools:** Tools are model-controlled, and a person SHOULD be able to deny a call. Servers declare the `tools` capability. `tools/list` MUST NOT vary per-connection, though it MAY follow the request's authorization. `tools/call` MAY return `InputRequiredResult` with `input_required` when the tool needs more input. [24]\n- **Resources, prompts, and JSON-RPC 2.0 server error codes:** Resources are application-driven and identified by a URI; clients call `resources/list` and `resources/read`, while servers that advertise the `resources` `listChanged` or `subscribe` capability flags deliver resource-specific update notifications when clients subscribe via `subscriptions/listen` (`notifications.resourceSubscriptions`). Prompts are user-controlled templates—often surfaced as slash commands—accessed via `prompts/list` and `prompts/get` (neither list may vary per-connection). MCP partitions the JSON-RPC 2.0 server-error block (`-32000` to `-32099`) into `-32000` to `-32019` for legacy implementation-defined server errors (where `-32002` was used in 2025-11-25 and earlier for resource not found before 2026-07-28 standardized `-32602`) and `-32020` to `-32099` reserved for the MCP specification (`-32020` `HeaderMismatch`, `-32021` `MissingRequiredClientCapability`, `-32022` `UnsupportedProtocolVersion`, plus reserved 2025-11-25 code `-32042` for URL elicitation required). [6][14][25][26]\n- **Elicitation, sampling, roots, and security considerations:** Elicitation runs inside another call: Form mode takes structured data with an optional JSON schema, while URL mode is required for passwords, API keys, access tokens, and payment credentials so they do not pass through the client, and on resumption the server checks the echoed `requestState` before returning a final result. `sampling` requests model output via the client without server API keys, and `roots` are informational filesystem guidance that the protocol does not enforce. For trust, safety, and security, `serverInfo` is self-reported and unverified (clients SHOULD NOT use it to change behavior or make security decisions), and clients MUST consider tool annotations untrusted unless received from trusted servers. MCP servers MUST NOT accept tokens not explicitly issued for the server, and local `stdio` servers from untrusted sources carry arbitrary code execution risks. [20][21][22][24][27][28]\n- **OAuth 2.1 resource metadata:** Authorization is OPTIONAL; `stdio` SHOULD NOT follow it. Servers MUST publish `RFC 9728` Protected Resource Metadata, which clients use to discover the authorization server. `RFC 8707` requires `resource` on authorization and token requests, set to the canonical URI. `client_id` is an HTTPS URL when `client_id_metadata_document_supported` is set, and the document MUST include `client_id`, `client_name`, and `redirect_uris`. `RFC 7591` is deprecated as of 2026-07-28. Authorization servers SHOULD include the `iss` parameter in authorization responses per `RFC 9207`, and MCP clients MUST validate a present `iss` against the recorded issuer before redeeming the authorization code (`SEP-2468`). Client credentials are bound to the issuing authorization server: clients MUST key persisted credentials by the issuer identifier and MUST NOT reuse them with a different authorization server (`SEP-2352`). [6][19][23][29]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **JSON-RPC 2.0 Specification** | `JSON-RPC 2.0` | Profiles classic standard | Profiles JSON-RPC 2.0 over stdio or Streamable HTTP POST with stateless per-request version and capability metadata in `_meta`. [6][14] |\n| **Language Server Protocol (LSP)** | `LSP` | Analogous to classic standard | Adapts LSP's reusable client-server architecture from IDE language intelligence to AI host integration with tools, resources, and prompts. [1] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Complements | A2A delegates multi-turn tasks between opaque peer agents, whereas MCP connects a host client to server tools and resources. [1] |\n| **[WebMCP](/protocols/webmcp/)** | Peer alternative | WebMCP registers page-scoped tools on `document.modelContext` in browser JavaScript, whereas MCP connects hosts to stdio or HTTP servers. [4][5][30] |\n| **[MCP Apps](/protocols/mcp-apps/)** | Has component | SEP-1865 extension declaring interactive `ui://` resources linked to tools for bidirectional host-iframe communication. [31] |\n| **[Official MCP Registry](/protocols/mcp-registry/)** | Has component | Centralized preview metadata index publishing `server.json` records for public MCP packages and remote server URLs. [15] |\n| **[Agent-User Interaction Protocol (AG-UI)](/protocols/ag-ui/)** | Complements | AG-UI streams agent-to-frontend UI state events over HTTP, whereas MCP connects the backend agent host to tool servers. [1] |\n| **[Agent Skills](/protocols/anthropic-agent-skills-format/)** | Complements | Packages filesystem `SKILL.md` workflow instructions, which MCP also exposes dynamically through the optional Skills over MCP extension. [1] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (22 probed or cited examples across 4 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### MCP Servers (Remote Endpoints & Local Packages)\n\nHTTP 200 and HTTP 401 probe responses and vendor documentation establish endpoint presence or declared support as of the stated check date rather than verified 2026-07-28 wire conformance. [7]\n\n| Actor | Role | Status | Transport, Capabilities & Scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Hugging Face** | Remote MCP server | Live (HTTP 200) · checked 2026-10-30 | Streamable HTTP at `https://huggingface.co/mcp` returning `2026-07-28`, `tools`, `resources`, and `io.modelcontextprotocol/skills`. | [huggingface.co/mcp](https://huggingface.co/mcp) [32] · [HF Hub MCP docs](https://huggingface.co/docs/hub/agents-mcp) [33] |\n| **Cloudflare Docs** | Remote MCP server | Live (HTTP 200) · checked 2026-10-30 | Streamable HTTP at `https://docs.mcp.cloudflare.com/mcp` (`docs-ai-search` `0.5.0`) advertising `2026-07-28`, `tools`, and `prompts`. | [docs.mcp.cloudflare.com/mcp](https://docs.mcp.cloudflare.com/mcp) [34] · [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/) [35] |\n| **GitHub** | Remote & local MCP server | Live (HTTP 401) · checked 2026-10-30 | Remote HTTP server at `https://api.githubcopilot.com/mcp/` with OAuth `resource_metadata` challenge and Go `stdio` server. | [api.githubcopilot.com/mcp/](https://api.githubcopilot.com/mcp/) [36] · [github/github-mcp-server](https://github.com/github/github-mcp-server) [37] |\n| **Stripe** | Remote & local MCP server | Live (HTTP 401) · checked 2026-10-30 | Remote server at `https://mcp.stripe.com` with OAuth `resource_metadata` challenge, Agent API keys, and `missing_api_key` error. | [mcp.stripe.com](https://mcp.stripe.com) [38] · [Stripe MCP docs](https://docs.stripe.com/mcp) [39] |\n| **Linear** | Remote MCP server | Live (HTTP 401) · checked 2026-10-30 | Streamable HTTP at `https://mcp.linear.app/mcp` with OAuth 2.1 `resource_metadata` challenge and `https://mcp.linear.app/mcp/readonly`. | [mcp.linear.app/mcp](https://mcp.linear.app/mcp) [40] · [Linear MCP docs](https://linear.app/docs/mcp) [41] |\n| **Atlassian Rovo** | Remote MCP server | Listed · as of 2026-09-09 | Registry entry `com.atlassian/atlassian-mcp-server` (`2.0.0`) advertising `streamable-http` at `https://mcp.atlassian.com/v2/mcp` and `https://mcp.atlassian.com/v1/mcp/authv2`. | [MCP Registry (v2.0.0)](https://registry.modelcontextprotocol.io/v0.1/servers/com.atlassian%2Fatlassian-mcp-server/versions/2.0.0) [42] |\n| **Notion** | Remote MCP server | Listed · as of 2025-09-11 | Registry entry `com.notion/mcp` (`1.0.1`) advertising `streamable-http` (`https://mcp.notion.com/mcp`) and `sse` (`https://mcp.notion.com/sse`). | [MCP Registry (v1.0.1)](https://registry.modelcontextprotocol.io/v0.1/servers/com.notion%2Fmcp/versions/1.0.1) [43] |\n| **Microsoft Playwright** | Local MCP server | Listed · as of 2026-09-18 | Registry entry `io.github.microsoft/playwright-mcp` (`0.0.82`) distributing npm package `@playwright/mcp` over local `stdio`. | [MCP Registry (v0.0.82)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.microsoft%2Fplaywright-mcp/versions/0.0.82) [44] |\n\n### AI Host Applications & IDEs\n\nVendor documentation and release notes establish declared client and harness support rather than verified 2026-07-28 wire conformance. [7]\n\n| Actor | Role | Status | Transport, Capabilities & Scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Claude** | AI host application | Partial · as of 2026-10-30 | Remote MCP connectors (OAuth or headers) and local `claude_desktop_config.json` servers; stateless `2026-07-28` rollout in progress. | [Claude remote MCP connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) [45] · [Bringing MCP 2026-07-28 to Claude](https://claude.com/resources/articles/bringing-mcp-2026-07-28-to-claude) [46] |\n| **Visual Studio Code** | IDE host | Supported · as of 2025-06-12 | Supports `streamable HTTP` and local transports, OAuth resource-server authorization, `tools`, `prompts`, `resources`, and `sampling`. | [VS Code full MCP spec support](https://code.visualstudio.com/blogs/2025/06/12/full-mcp-spec-support) [47] |\n| **Cursor** | IDE host | Supported · as of 2025-06-04 | Supports one-click MCP server installation and OAuth authentication in Cursor `1.0`. | [Cursor 1.0 changelog](https://cursor.com/changelog/1-0) [48] |\n| **Gemini CLI** | CLI coding agent | Supported · as of 2025-06-25 | Open-source (`Apache 2.0`) terminal agent with built-in Model Context Protocol client support and bundled extensions. | [Introducing Gemini CLI](https://blog.google/innovation-and-ai/technology/developers-tools/introducing-gemini-cli-open-source-ai-agent/) [49] |\n| **Microsoft Foundry** | Enterprise agent platform | Supported (release announcement) · as of 2026-07-28 | Release announcement claims unified MCP endpoint with stateless `2026-07-28` and `Tasks`; no independent feature-matrix verification. | [MCP 2026-07-28 release blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/) [10] |\n\n### Registries, Directories & Discovery Indexes\n\nDiscovery catalogs and sub-registries that index `server.json` metadata or crawl public MCP server packages (see also [MCP Registry](/protocols/mcp-registry/)). [15][50]\n\n| Actor | Role | Status | Catalog & ingestion model | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Official MCP Registry** | Central metadata repository | Supported (preview) · checked 2026-10-30 | Official `server.json` catalog (`GET /v0.1/servers`) at `https://registry.modelcontextprotocol.io` for downstream aggregators. | [The MCP Registry](https://modelcontextprotocol.io/registry/about) [15] · [MCP Registry Aggregators](https://modelcontextprotocol.io/registry/registry-aggregators) [50] |\n| **GitHub MCP Registry** | Sub-registry & IDE directory | Supported · as of 2025-09-16 | Ingests servers self-published to the OSS MCP Community Registry into GitHub and VS Code. | [Meet the GitHub MCP Registry](https://github.blog/ai-and-ml/github-copilot/meet-the-github-mcp-registry-the-fastest-way-to-discover-mcp-servers/) [51] |\n| **Glama** | Aggregator & sandbox index | Supported · checked 2026-10-30 | Ingests the official registry and layers sandbox schema captures, behavioral analysis, and TDQS scores. | [Glama MCP methodology](https://glama.ai/mcp/methodology) [52] |\n| **PulseMCP** | Sub-registry & directory | Partial · as of 2025-09-09 | Ingests the Official MCP Registry as a downstream sub-registry supplemented with web indexing; live directory temporarily pauses new submissions. | [PulseMCP Work With Us](https://www.pulsemcp.com/work-with-us) [53] · [PulseMCP Official Registry launch](https://www.pulsemcp.com/posts/newsletter-claude-code-competition-ai-fundraising-abounds-mcp-registry-launch) [54] · [PulseMCP server directory](https://www.pulsemcp.com/servers/) [55] |\n| **MCP Census** | Trust-layer census over registries | Listed · as of 2026-11-04 | Trust layer returning PASS, REVIEW, BLOCK, or UNKNOWN; `57,777` rows. | [MCP registries compared](https://mcpcensus.com/compare/mcp-registries) [56] |\n\n### SDKs, Runtimes & Developer Tooling\n\nReference protocol SDKs, serverless hosting frameworks, local archive formats, and conformance debuggers used to build and test MCP clients and servers. [57]\n\n| Actor | Role | Status | Supported languages / packaging | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Official MCP SDKs** | Client & server SDKs | Partial · as of 2026-10-30 | Current `Tier 1` roster lists 6 official SDKs (`TypeScript`, `Python`, `C#`, `Go`, `Rust`, and `Ruby`), plus Tier 2 `Java` and Tier 3 `Kotlin`, `Swift`, and `PHP` (July 2026 release covered `TypeScript`, `Python`, `Go`, `C#`, and `Rust` beta). The official Ruby SDK reached Tier 1 on 2026-10-30, with full support for the 2026-07-28 specification and a 100% conformance pass rate across both scored spec versions. | [Official MCP SDKs](https://modelcontextprotocol.io/docs/sdk) [57] · [MCP 2026-07-28 release blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/) [10] · [MCP Ruby SDK versions](https://ruby.sdk.modelcontextprotocol.io/protocol-versions/) [13] · [Ruby SDK reaches Tier 1](https://blog.modelcontextprotocol.io/posts/ruby-sdk-tier-1/) [9] |\n| **MCP Inspector** | Developer testing client | Supported · as of 2026-07-28 | Reference `@modelcontextprotocol/inspector` package providing Web, `--cli`, and `--tui` clients across `stdio` and HTTP for `2026-07-28`. | [MCP Inspector docs](https://modelcontextprotocol.io/docs/tools/inspector) [58] |\n| **Cloudflare Agents SDK** | Server & client runtime | Supported · as of 2026-10-27 | Workers runtime supporting stateless `2026-07-28` MCP servers, `Streamable HTTP`, `insufficientScope()` OAuth challenges, and `MCPClientManager`. | [Cloudflare Agents MCP docs](https://developers.cloudflare.com/agents/model-context-protocol/) [59] · [MCP 2026-07-28 blog](https://blog.modelcontextprotocol.io/posts/2026-07-28/) [10] |\n| **MCP Bundles (MCPB)** | Local server bundle format | Supported · checked 2026-10-30 | Zip archive format (`.mcpb`, formerly `.dxt`) bundling a local MCP server with `manifest.json` via `@anthropic-ai/mcpb`. | [modelcontextprotocol/mcpb](https://raw.githubusercontent.com/modelcontextprotocol/mcpb/main/README.md) [60] |\n\n### Ecosystem censuses\n\n- **One Year of MCP (2025-11-25)** (*as of 2025-11-25*): Close to 2,000 server entries indexed in the Official MCP Registry as of November 25, 2025, representing 407% growth from the initial batch onboarded at the registry's September 2025 launch. [61]\n- **Anthropic AAIF donation announcement (2025-12-09)** (*as of 2025-12-09*): More than 10,000 active public MCP servers published across the ecosystem as of December 9, 2025, when Anthropic donated MCP to the Linux Foundation's Agentic AI Foundation. [62]\n- **MCP 2026-07-28 release announcement** (*as of 2026-07-28*): Close to 500 million monthly downloads across official Tier 1 MCP SDKs as of July 28, 2026, with both the TypeScript and Python SDKs surpassing 1 billion total downloads. [10]\n- **MCP registries compared (read 4 November 2026)** (*as of 2026-11-04*): On 4 November 2026 the MCP Census comparison records Glama at 115,336 servers (Remote 45,340, Local 43,442), its own census at 57,777 server rows, PulseMCP at 21,602 servers, and the Docker MCP Catalog at 300+ servers. Smithery's API, Connect, accounts, CLI, and proxy URLs stopped on 31 October 2026. [56]\n- **State of MCP Server Development (LocalCan, checked 14 October 2026)** (*as of 2026-10-14*): LocalCan's census, measured on 14 October 2026, counts 43,012 active servers in the official MCP Registry. Across that set, 59.6% are remote-only, 34.6% ship only as a package, 4.7% offer both, and 1.1% list neither. [63]\n- **MCP server directories (Apideck, 31 October 2026)** (*as of 2026-10-31*): Apideck's 31 October 2026 table counts the official registry API at 53,541 servers, Glama at 113,204 servers and 40,151 connectors, PulseMCP at 21,614, MCP Market at 50,999, and the Cursor Marketplace at about 490 plugins. [64]\n- **MCP-Eco (arXiv HTML, Parquet export 2026-06-23)** (*as of 2026-06-23*): The MCP-Eco frozen release, exported to Parquet on 2026-06-23, covers 78,302 candidate server projects. Its crawler queries the official MCP registry, Glama, Smithery, and PulseMCP, and reads MCP.so listing pages found through sitemaps. [65]\n\n---\n\n## See also\n\n- **[MCP Server Cards](/protocols/mcp-server-cards/)** *(Has component)* — SEP-2127 is the MCP extension whose Server Card is read with `GET /server-card` before the client connects, and the card omits the tools, resources, and prompts the live server still provides.\n- **Depended on by:** [Ad Context Protocol (AdCP)](/protocols/adcp/), [Agentic Real Time Framework](/protocols/artf/), [Coral Protocol (CoralOS)](/protocols/coral-protocol/), [Discovery of Model Context Protocol Servers via DNS TXT Records](/protocols/mcp-dns-discovery/), [KYA-OS (Know Your Agent Operating System)](/protocols/kya-os/), [OpenAI Apps SDK manifests](/protocols/openai-apps-sdk-manifests/), [Per-Call Proof for Local Tool Invocation by AI Agents](/protocols/local-tool-call-proof/)\n- **Peer alternatives:** [Agent Protocol](/protocols/agent-protocol-aief/), [agents.json](/protocols/agents-json/)\n- **Complements:** [A2UI (Agent to UI) Protocol](/protocols/a2ui/), [Agent Client Protocol](/protocols/agent-client-protocol/), [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), [AGENTS.md](/protocols/agents-md/), [ERC-8004: Trustless Agents](/protocols/erc-8004/), [L402](/protocols/l402/), [OAuth Client ID Metadata Document](/protocols/oauth-cimd/), [OAuth Protected Resource and Authorization Server Metadata (as used for agent authorization)](/protocols/oauth-metadata-for-agents/), [Open Responses](/protocols/open-responses/), [Universal Commerce Protocol (UCP)](/protocols/ucp/), and [32 more in the protocol directory](/protocols/)\n- **Category:** [Act protocols](/category/act/)\n\n---\n\n## References\n\n1. Model Context Protocol (AAIF / Linux Foundation), *Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n2. Anthropic, *Introducing the Model Context Protocol* (2024-11-25) — \n3. The Linux Foundation, *Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF), Anchored by New Project Contributions Including Model Context Protocol (MCP), goose and AGENTS.md* (2025-12-09) — \n4. Model Context Protocol (AAIF / Linux Foundation), *stdio Transport — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n5. Model Context Protocol (AAIF / Linux Foundation), *Streamable HTTP Transport — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n6. Model Context Protocol (AAIF / Linux Foundation), *Key Changes (2026-07-28) — Model Context Protocol Specification* (2026-07-28) — \n7. Model Context Protocol (AAIF / Linux Foundation), *Versioning and Compatibility — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n8. David Soria Parra and Den Delimarsky (Model Context Protocol Blog), *The New MCP Roadmap* (2026-08-22) — \n9. Koichi Ito (Model Context Protocol Blog), *The Official Ruby SDK for MCP Reaches Tier 1* (2026-10-30) — \n10. David Soria Parra and Den Delimarsky (MCP Blog), *MCP 2026-07-28 Specification Release* (2026-07-28) — \n11. Model Context Protocol (AAIF / Linux Foundation), *Governance and Stewardship — Model Context Protocol* (2026-10-30) — \n12. Model Context Protocol (AAIF / Linux Foundation), *Versioning — Model Context Protocol Documentation* (2026-07-28) — \n13. MCP Ruby SDK, *Protocol Versions* (checked 2026-10-30) — \n14. Model Context Protocol (AAIF / Linux Foundation), *Base Protocol Overview — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n15. Model Context Protocol (AAIF / Linux Foundation), *About the Official MCP Registry* (2026-10-30) — \n16. Model Context Protocol (AAIF / Linux Foundation), *SEP-2127: MCP Server Cards — HTTP Server Discovery* (2026-01-21) — \n17. Model Context Protocol (AAIF / Linux Foundation), *Multi Round-Trip Requests — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n18. Model Context Protocol (AAIF / Linux Foundation), *Architecture — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n19. Model Context Protocol (AAIF / Linux Foundation), *Authorization — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n20. Model Context Protocol, *Discovery — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n21. Model Context Protocol (AAIF / Linux Foundation), *Sampling — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n22. Model Context Protocol (AAIF / Linux Foundation), *Roots — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n23. Model Context Protocol (AAIF / Linux Foundation), *Deprecated Features Registry — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n24. Model Context Protocol (AAIF / Linux Foundation), *Tools — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n25. Model Context Protocol (AAIF / Linux Foundation), *Resources — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n26. Model Context Protocol (AAIF / Linux Foundation), *Prompts — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n27. Model Context Protocol (AAIF / Linux Foundation), *Elicitation — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n28. Model Context Protocol (AAIF / Linux Foundation), *Security Best Practices — Model Context Protocol (2026-07-28)* (2026-07-28) — \n29. Model Context Protocol (AAIF / Linux Foundation), *Client Registration — Model Context Protocol Specification (2026-07-28)* (2026-07-28) — \n30. Web Machine Learning Community Group (editors Brandon Walderman, Khushal Sagar, Dominic Farolino, and Samuel Dallstream), *WebMCP* (Draft Community Group Report, 11 November 2026) — \n31. Model Context Protocol (MCP), *SEP-1865: MCP Apps — Interactive User Interfaces for MCP* (2026-01-26) — \n32. Hugging Face, *Live MCP endpoint* (2026-10-30) — \n33. Hugging Face, *Hugging Face MCP Server* (checked 2026-10-30) — \n34. Cloudflare, *Live MCP endpoint* (2026-10-30) — \n35. Cloudflare, *Cloudflare's own MCP servers* (checked 2026-10-30) — \n36. GitHub, *Live MCP endpoint* (2026-10-30) — \n37. GitHub, *github/github-mcp-server* (checked 2026-10-30) — \n38. Stripe, *Live MCP endpoint* (2026-10-30) — \n39. Stripe, *Model Context Protocol (MCP)* (checked 2026-10-30) — \n40. Linear, *Live MCP endpoint* (2026-10-30) — \n41. Linear, *MCP server* (checked 2026-10-30) — \n42. Official MCP Registry, *com.atlassian/atlassian-mcp-server version 2.0.0 (Official MCP Registry)* (version 2.0.0 (publishedAt 2026-09-09T17:53:32.01107Z; retained snapshot fetched 2026-10-30)) — \n43. Official MCP Registry, *com.notion/mcp version 1.0.1 (Official MCP Registry)* (version 1.0.1 (publishedAt 2025-09-11T22:25:50.737872Z; retained snapshot fetched 2026-10-30)) — \n44. Official MCP Registry, *io.github.microsoft/playwright-mcp version 0.0.82 (Official MCP Registry)* (version 0.0.82 (publishedAt 2026-09-18T23:41:20.46032Z; retained snapshot fetched 2026-10-30)) — \n45. Anthropic, *Get started with custom connectors using remote MCP* (modified 2026-10-30) — \n46. Anthropic, *MCP 2026-07-28 spec: stateless core, coming to Claude* (2026-07-28) — \n47. Microsoft / Harald Kirschner, Connor Peet and Tyler Leonhardt, *The Complete MCP Experience: Full Specification Support in VS Code* (2025-06-12) — \n48. Cursor, *Cursor 1.0* (2025-06-04) — \n49. Google, *Gemini CLI: your open-source AI agent* (published 2025-06-25; modified 2026-01-07) — \n50. Model Context Protocol, *MCP Registry Aggregators* (checked 2026-10-30) — \n51. Toby Padilla, GitHub Blog, *Meet the GitHub MCP Registry: The fastest way to discover MCP Servers* (published 2025-09-16) — \n52. Glama, *How Glama indexes the MCP ecosystem* (checked 2026-10-30) — \n53. PulseMCP, *Work With Us* (checked 2026-10-30) — \n54. PulseMCP, *Claude Code has competition, AI fundraising abounds, Official MCP Registry launched* (published 2025-09-09) — \n55. PulseMCP, *MCP Server Directory* (checked 2026-11-06) — \n56. MCP Census (Jaco Veldsman), *MCP registries compared* (2026-11-04) — \n57. Model Context Protocol (AAIF / Linux Foundation), *Official MCP SDKs* (2026-10-30) — \n58. Model Context Protocol (AAIF / Linux Foundation), *MCP Inspector* (2026-07-28) — \n59. Cloudflare, *Model Context Protocol (MCP) · Cloudflare Agents docs* (checked 2026-10-30) — \n60. Model Context Protocol, *MCP Bundles (MCPB) Specification & Toolchain README* (2026-10-30) — \n61. Model Context Protocol Blog, *One Year of MCP: November 2025 Spec Release* (2025-11-25) — \n62. Anthropic, *Donating the Model Context Protocol and establishing the Agentic AI Foundation* (2025-12-09) — \n63. Jarek Ceborski, LocalCan, *State of MCP Server Development: October 2026* (2026-10-15) — \n64. Apideck, *MCP server directories* (2026-10-31) — \n65. Khalid Tounoussi, Mohammed Sayagh, Ali Ouni, and Yutaro Kashiwa, *MCP-Eco: A Linked Dataset of MCP Servers, Consumers, and Development Activity* (2026-11-04) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "A2A", "adoption": { "level": "observed", "by": "Telnyx (Telnyx Assistant), Redocly, Pangram, Ticket Fairy, Warp (Warp Freight), Google (Gemini Enterprise), Microsoft (Foundry Agent Service), Microsoft (Copilot Studio), and 12 other verified implementations", "probe_run": null }, "aliases": [], "analog": "none", "collisions": [ "Account-to-Account payments (A2A, banking)" ], "discovery": { "mechanism": "Agent Card", "path": "GET https://{server_domain}/.well-known/agent-card.json (registered with IANA as a permanent well-known URI on 2025-08-01; renamed from /.well-known/agent.json in v0.3.0 via PR #841 on 2025-07-29), registry/catalog lookup, or direct configuration" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://a2a-protocol.org/latest/specification/", "claim": "A2A Protocol (The Linux Foundation), *Agent2Agent (A2A) Protocol Specification*, latest released version 1.0.0; checked 2026-10-30", "date": null, "quote": "The Agent2Agent (A2A) Protocol is an open standard designed to facilitate communication and interoperability between independent, potentially opaque AI agent systems. / A2A Servers MUST make an Agent Card available. / Enable agents to delegate tasks, exchange context, and work together on complex user requests. / Securely exchange information to achieve user goals without needing access to each other's internal state, memory, or tools. / In an ecosystem where agents might be built using different frameworks, languages, or by different vendors, A2A provides a common language and interaction model. / Its primary goal is to enable agents to: Discover each other's capabilities. Negotiate interaction modalities (text, files, structured data). Manage collaborative tasks. / Latest Released Version 1.0.0 Previous Versions 0.3.0 0.2.6 0.1.0 / The core ones officially supported are JSONRPC, GRPC and HTTP+JSON. / The JSON-RPC protocol binding provides a simple, HTTP-based interface using JSON-RPC 2.0 for method calls and Server-Sent Events for streaming. / The gRPC Protocol Binding provides a high-performance, strongly-typed interface using Protocol Buffers over HTTP/2. / The HTTP+JSON protocol binding provides a RESTful interface using standard HTTP methods and JSON payloads. / Header field name: A2A-Version / Header field name: A2A-Extensions / URI suffix: agent-card.json Change controller: A2A Protocol Working Group / This section provides registration templates for the A2A protocol's media type, HTTP headers, and well-known URI, intended for submission to the Internet Assigned Numbers Authority (IANA). / Type name: application Subtype name: a2a+json / Agent2Agent (A2A) Protocol Specification / Well-Known URI: Accessing https://{server_domain}/.well-known/agent-card.json / Copyright 2026 The Linux Foundation. Licensed under the Apache License, Version 2.0. / agents might be built using different frameworks, languages, or by different vendors / Bridge the communication gap between disparate agentic systems. / supportedInterfaces array of AgentInterface / The first entry in supportedInterfaces represents the preferred interface / Method Naming: PascalCase method names matching gRPC conventions (e.g., SendMessage, GetTask) / TASK_STATE_SUBMITTED Indicates that a task has been successfully submitted and acknowledged. / TASK_STATE_WORKING Indicates that a task is actively being processed by the agent. / Task: The fundamental unit of work managed by A2A, identified by a unique ID. Tasks are stateful and progress through a defined lifecycle. / Streaming: Server-Sent Events (text/event-stream) / Push Notifications: Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios. / Opaque Execution: Agents collaborate based on declared capabilities and exchanged information, without needing to share their internal thoughts, plans, or tool implementations. / without needing access to each other's internal state, memory, or tools. / A2A and MCP are complementary protocols designed for different aspects of agentic systems: / Model Context Protocol (MCP): Focuses on standardizing how AI models and agents connect to and interact with tools, APIs, data sources, and other external resources. / A2A Client: An application or agent that initiates requests to an A2A Server on behalf of a user or another system. / A2A Server (Remote Agent): An agent or agentic system that exposes an A2A-compliant endpoint, processing tasks and providing responses. / Agent Card: A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements. / Well-Known URI: Accessing `https://{server_domain}/.well-known/agent-card.json` / The agent MAY create a new Task to process the provided message asynchronously or MAY return a direct Message response for simple interactions. The operation MUST return immediately with either task information or response message. / A2A Servers MUST make an Agent Card available. The Agent Card describes the server's identity, capabilities, skills, and interaction requirements. / Agent Cards MAY be signed using JSON Web Signatures (JWS) as specified in the AgentCardSignature object (Section 4.4.7) / Clients SHOULD verify signatures when present / Registries/Catalogs: Querying curated catalogs of agents / Direct Configuration: Pre-configured Agent Card URLs or content / Declares a combination of a target URL, transport and protocol version for interacting with the agent. / url string Yes The URL or address where this interface is available. / The security scheme details used for authenticating with this agent. / This endpoint is available only if AgentCard.capabilities.extendedAgentCard is true. / Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. / The Get Extended Agent Card operation MUST require authentication / JSON Canonicalization Scheme (JCS) / Clients retrieving this extended card SHOULD replace their cached public Agent Card with the content received from this endpoint / The primary operation for initiating agent interactions. / Similar to Send Message but with real-time streaming of updates during processing. / Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. / Requests the cancellation of an ongoing task. The server will attempt to cancel the task, but success is not guaranteed / Part: The smallest unit of content within a Message or Artifact. Parts can contain text, file references, or structured data. / Artifact: An output (e.g., a document, image, structured data) generated by the agent as a result of a task, composed of Parts. / ListTasks / SubscribeToTask / CreateTaskPushNotificationConfig / GetTaskPushNotificationConfig / ListTaskPushNotificationConfigs / DeleteTaskPushNotificationConfig / Clients send a message to an agent and receive either a task that tracks the processing or a direct response message. / The agent MAY create a new Task to process the provided message asynchronously or MAY return a direct Message response for simple interactions. / Task processing MAY continue asynchronously after the response when a Task is returned. / TASK_STATE_INPUT_REQUIRED Indicates that the agent requires additional user input to proceed. This is an interrupted state. / TASK_STATE_AUTH_REQUIRED Indicates that authentication is required to proceed. This is an interrupted state. / TASK_STATE_COMPLETED Indicates that a task has finished successfully. This is a terminal state. / TASK_STATE_FAILED Indicates that a task has finished with an error. This is a terminal state. / TASK_STATE_CANCELED Indicates that a task was canceled before completion. This is a terminal state. / TASK_STATE_REJECTED Indicates that the agent has decided to not perform the task. / Subsequent events following a Task MAY include stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects / Part represents a container for a section of communication content. Parts can be purely textual, some sort of file (image, video, etc) or a structured data blob (i.e. JSON). / Streaming: Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via protocol-specific streaming mechanisms. / Implementations MUST scope results to the caller's authorized access boundaries / PushNotificationConfig.authentication / Agents SHOULD validate webhook URLs to prevent SSRF (Server-Side Request Forgery) attacks / Reject private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) / Reject localhost and link-local addresses / Clients MUST validate webhook authenticity / Clients SHOULD process notifications idempotently / Event Ordering: All implementations MUST deliver events in the order they were generated. / An agent MAY serve multiple concurrent streams to one or more clients for the same task. / Push notifications are delivered via HTTP POST to client-registered webhook endpoints. / Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with Send Message, or for fetching the final state of a task after being notified via a push notification or after a stream has ended. / Service: Implement the A2AService gRPC service / Content-Type: application/a2a+json SHOULD be used for requests and responses / Each interface MUST accurately declare its transport protocol and URL / protocolVersion string Yes The version of the A2A protocol this interface exposes. / SDK language bindings, schemas, and any other derived forms MUST be regenerated from the proto (directly or via code generation) rather than edited manually. / Initializing search A2A Python Go Java JS.NET Rust Home Documentation Extensions Specification", "ref": 1 }, { "label": "[2]", "url": "https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/", "claim": "A2A Protocol, *A New Chapter for A2A: Joining the Agentic AI Foundation*, 2026-08-27", "date": "2026-08-27", "quote": "Before A2A, handing off work between agents built on different frameworks required writing custom integration code from scratch for every new pairing. / The Agent2Agent (A2A) protocol has officially been accepted as a Growth Stage project at the Agentic AI Foundation (AAIF). / While the Model Context Protocol (MCP) serves as the vertical integration layer connecting agents to internal tools and databases, A2A acts as the horizontal protocol enabling peer-to-peer collaboration. / A2A is supported by major frameworks including LangGraph, CrewAI, Pydantic AI, AG2, and IBM BeeAI / backed by over 150 organizations", "ref": 2 }, { "label": "[3]", "url": "https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/", "claim": "Rao Surapaneni, Miku Jha, Michael Vakoc, and Todd Segal (Google), *Announcing the Agent2Agent Protocol (A2A)*, 2025-04-09", "date": "2025-04-09", "quote": "Today, we're launching a new, open protocol called Agent2Agent (A2A) / \"datePublished\": \"2025-04-09\" / APRIL 9, 2025 / with support and contributions from more than 50 technology partners / and leading service providers including Accenture, BCG, Capgemini, Cognizant, Deloitte, HCLTech, Infosys, KPMG, McKinsey, PwC, TCS, and Wipro", "ref": 3 }, { "label": "[4]", "url": "https://a2a-protocol.org/v0.3.0/specification/", "claim": "A2A Protocol, *Agent2Agent (A2A) Protocol Official Specification v0.3.0*, v0.3.0", "date": null, "quote": "`https://{server_domain}/.well-known/agent-card.json` / https://{server_domain}/.well-known/agent-card.json", "ref": 4 }, { "label": "[5]", "url": "https://www.iana.org/assignments/well-known-uris", "claim": "IANA, *Well-Known URIs*, agent-card.json registered 2025-08-01", "date": null, "quote": "agent-card.json / 2025-08-01 / agent-card.json https://a2a-protocol.org/latest/specification/ permanent Linux Foundation 2025-08-01", "ref": 5 }, { "label": "[6]", "url": "https://github.com/a2aproject/A2A/pull/841", "claim": "holtskinner (a2aproject/A2A), *Change Well-Known URI for Agent Card hosting from agent.json to agent-card.json (PR #841)*, merged 2025-07-29", "date": null, "quote": "from `/.well-known/agent.json` to `/.well-known/agent-card.json` / I've updated the recommended and example well-known URI for hosting Agent Cards from /.well-known/agent.json to /.well-known/agent-card.json / \"mergedTime\":\"2025-07-29T18:45:00Z\"", "ref": 6 }, { "label": "[7]", "url": "https://github.com/a2aproject/A2A/blob/main/CHANGELOG.md", "claim": "a2aproject, *A2A CHANGELOG.md*, 1.0.1 (2026-05-26); 1.0.0 (2026-03-12); 0.3.0 (2025-07-30)", "date": null, "quote": "0.3.0 (2025-07-30) / 1.0.1 (2026-05-26) … prefer application/a2a+json in HTTP binding / \"text\":\"1.0.0 (2026-03-12)\" / 1.0.1 (2026-05-26) / 1.0.0 (2026-03-12) / 0.3.0 (2025-07-30) … Change Well-Known URI for Agent Card hosting from `agent.json` to `agent-card.json` / \"text\":\"0.3.0 (2025-07-30)\" / Change Well-Known URI for Agent Card hosting from agent.json to agent-card.json", "ref": 7 }, { "label": "[8]", "url": "https://a2a-protocol.org/latest/whats-new-v1/", "claim": "A2A Protocol (The Linux Foundation), *What's New in v1.0*, checked 2026-10-30", "date": null, "quote": "preferredTransport and additionalInterfaces consolidated into supportedInterfaces[] / Each interface has url, protocolBinding, and protocolVersion / Send Message (message/send → SendMessage) / Send Streaming Message (message/stream → SendStreamingMessage) / Get Task (tasks/get → GetTask) / Cancel Task (tasks/cancel → CancelTask)", "ref": 8 }, { "label": "[9]", "url": "https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents", "claim": "The Linux Foundation, *Linux Foundation Launches the Agent2Agent Protocol Project to Enable Secure, Intelligent Communication Between AI Agents*, 2025-06-23", "date": "2025-06-23", "quote": "today announced the launch of the Agent2Agent (A2A) project, an open protocol created by Google / \"datePublished\": \"2025-06-23T15:00:00.000Z\" / June 23, 2025 / 2025-06-23 / with growing support from more than 100 leading technology companies", "ref": 9 }, { "label": "[10]", "url": "https://developers.googleblog.com/en/google-cloud-donates-a2a-to-linux-foundation/", "claim": "Rao Surapaneni, Todd Segal, and Michael Vakoc (Google Cloud), *Google Cloud donates A2A to Linux Foundation*, 2025-06-23", "date": "2025-06-23", "quote": "seeded with Google's transfer of the groundbreaking Agent2Agent (A2A) protocol specification, accompanying SDKs, and developer tooling.", "ref": 10 }, { "label": "[11]", "url": "https://aaif.io/blog/a2a-joins-aaif", "claim": "Agentic AI Foundation, *A2A joins AAIF's open agentic stack*, published 2026-08-17; modified 2026-09-24", "date": null, "quote": "In August 2025, IBM's Agent Communication Protocol merged into A2A / \"datePublished\":\"2026-08-17\" / A2A v1.0, the first stable specification, shipped in March 2026. / Agent2Agent (A2A), the open standard for inter-agent communication, is joining the Agentic AI Foundation (AAIF) as a hosted project. / Google Cloud and PayPal are extending A2A into agentic commerce through the Agent Payments Protocol (AP2). Shopping and merchant agents communicate over A2A / Google Cloud supports developing and deploying A2A agents through ADK, Agent Engine, Cloud Run, and GKE. / It's backed by over 150 organizations / A2A's 150+ partner organizations include direct competitors.", "ref": 11 }, { "label": "[12]", "url": "https://raw.githubusercontent.com/i-am-bee/acp/main/README.md", "claim": "IBM BeeAI (i-am-bee/acp), *Agent Communication Protocol (ACP) README*, checked 2026-10-31", "date": null, "quote": "ACP is now part of A2A under the Linux Foundation / ACP is now part of A2A under the Linux Foundation! / acp-sdk", "ref": 12 }, { "label": "[13]", "url": "https://github.com/aaif/project-proposals/issues/37", "claim": "Agentic AI Foundation, *[Project Proposal] Agent2Agent Protocol (A2A) · Issue #37*, Technical Committee 2026-07-15; Governing Board 2026-08-04", "date": null, "quote": "The GB has approved A2A as a Growth Stage project for inclusion into the AAIF. / 2026-07-15T21:20:03Z … The AAIF TC has approved A2A as a Growth Stage project / 2026-08-04T16:26:05Z … The GB has approved A2A as a Growth Stage project for inclusion into the AAIF. / Cisco spearheaded the AGNTCY project / Google ADK (Agent Development Kit): Native A2A support in the ADK running anywhere, especially on Agent Platform Runtime (the evolution of Vertex AI Agent Engine), with first-class RemoteA2aAgent and to_a2a() helpers. / BeeAI Framework (IBM): The successor to IBM's deprecated ACP, BeeAI now ships native A2AServer and A2AAgent adapters, completing the ACP→A2A migration for the BeeAI platform. / Every deployed LangGraph agent gets a hosted A2A endpoint at /a2a/{assistant_id} with an auto-generated Agent Card, streaming via SSE, and LangSmith distributed tracing across multi-agent A2A conversations. / CrewAI + AMP: Production A2A hosting on the CrewAI AMP platform - A2AServerConfig provisions distributed state, enterprise auth (OIDC, OAuth2, mTLS), REST/JSON-RPC/gRPC transports, and signed webhook push notifications. / Pydantic AI: Native support via the FastA2A library, using.to_a2a() to convert any Pydantic AI agent into an ASGI A2A application in two lines of code. / AG2 (formerly AutoGen): Expose or connect agent swarms via A2A; the AG2 repo is tagged with a2a as a core capability.", "ref": 13 }, { "label": "[14]", "url": "https://github.com/a2aproject/A2A/commit/40cffc57314d1c84e47c5efe8301d6387880c3f8", "claim": "a2aproject, *Add Agent Card media type registration template (commit 40cffc57)*, 2026-10-27", "date": "2026-10-27", "quote": "`application/a2a-agent-card+json`, matching the A2A Agent Card media\\ntype advertised by AI Catalog, for inclusion in the 1.1 release. / These templates do not imply that IANA registration has been completed. / for inclusion in the 1.1 release. / \"date\":\"2026-10-27T16:07:05Z\"", "ref": 14 }, { "label": "[15]", "url": "https://github.com/a2aproject/A2A/blob/main/GOVERNANCE.md", "claim": "a2aproject, *Agent2Agent (A2A) Governance (GOVERNANCE.md)*, checked 2026-10-30", "date": null, "quote": "The Agent2Agent project is governed by the Technical Steering Committee. The Committee has nine seats, each held by the following companies:", "ref": 15 }, { "label": "[16]", "url": "https://github.com/a2aproject/A2A/releases/tag/v1.0.1", "claim": "a2aproject, *Release v1.0.1*, 2026-05-28 (changelog 2026-05-26)", "date": null, "quote": "published_at\": \"2026-05-28T11:34:36Z\" / 1.0.1 (2026-05-26)", "ref": 16 }, { "label": "[17]", "url": "https://a2a-protocol.org/latest/topics/agent-discovery/", "claim": "A2A Protocol, *Agent Discovery*, checked 2026-11-06", "date": null, "quote": "A2A standardizes agent self-descriptions through the Agent Card. / The Agent Card is a JSON document that serves as a digital \"business card\" for an A2A Server (the remote agent). / https://{agent-server-domain}/.well-known/agent-card.json / following the principles of RFC 8615 / The current A2A specification does not prescribe a standard API for curated registries. / Includes `name`, `description`, and `provider` information. / Lists supported features such as `streaming` or `pushNotifications`. / Describes the agent's tasks using `AgentSkill` objects / The curated registry acts as a central repository, allowing clients to query and discover agents based on criteria like \"skills\" or \"tags\". / Client applications utilize hardcoded details, configuration files, environment variables, or proprietary APIs for discovery. / Proprietary API-based discovery also lacks standardization. / We recommend the use of authenticated extended agent cards for sensitive information or for serving a more detailed version of the card. / The A2A specification strongly recommends the use of out-of-band dynamic credentials rather than embedding static secrets within the Agent Card.", "ref": 17 }, { "label": "[18]", "url": "https://github.com/protocol-registries/well-known-uris/issues/66", "claim": "protocol-registries/well-known-uris, *Well-Known URI registration for agent.json (issue 66)*, 2025-06-11", "date": "2025-06-11", "quote": "URI suffix: `.well-known/agent.json` / Change controller: Linux Foundation / `agent.json` is an extremely generic name for a vendor proposal. / users in production who are using `agent.json` / Yes, we will update the spec to use agent-card.json in version 0.3.0 / See a2aproject/A2A#841 for the update / Yes, we should proceed with the registration for `.well-known/agent-card.json` / Protocol Version 0.3.0 has been published with the new Well-Known URI", "ref": 18 }, { "label": "[19]", "url": "https://arxiv.org/abs/2609.10871", "claim": "Alireza Lotfi, Mirza Masfiqur Rahman, Imtiaz Karim, and Elisa Bertino, *A2ABreak: Systematic Security Analysis of the A2A Protocol (arXiv:2609.10871)*, submitted 9 Sep 2026; last revised 24 Oct 2026 (v3); fetched 2026-11-11", "date": null, "quote": "A2ABreak: Systematic Security Analysis of the A2A Protocol / last revised 24 Oct 2026 (this version, v3) / producing a unified model of 37 states and 76 transitions from 929 formalized statements / Our analysis uncovers 11 new vulnerabilities, each exploitable by a specification-compliant adversary without requiring any implementation flaw.", "ref": 19 }, { "label": "[20]", "url": "https://arxiv.org/html/2609.10871v3", "claim": "Alireza Lotfi, Mirza Masfiqur Rahman, Imtiaz Karim, and Elisa Bertino, *A2ABreak: Systematic Security Analysis of the A2A Protocol (v3 HTML)*, 24 October 2026 (v3)", "date": null, "quote": "This work targets protocol-level security analysis of the A2A specification v1.0.0", "ref": 20 }, { "label": "[21]", "url": "https://slim.agntcy.org/latest/slim/integrations/a2a/", "claim": "AGNTCY SLIM Documentation, *A2A over SLIM*, fetched 2026-10-30", "date": null, "quote": "SLIM provides a fourth, experimental binding: SLIMRPC. Instead of HTTP, it uses SLIM's encrypted session layer as the transport", "ref": 21 }, { "label": "[22]", "url": "https://github.com/a2aproject/a2a-rs/tree/main/a2a-slimrpc", "claim": "a2aproject, *a2a-slimrpc: SLIMRPC transport binding for A2A*, fetched 2026-10-30", "date": null, "quote": "The peer keys are set only when the session uses MLS (the SLIMRPC default), since MLS is what verifies the token.", "ref": 22 }, { "label": "[23]", "url": "https://datatracker.ietf.org/doc/draft-mpsb-agntcy-slim/", "claim": "IETF Datatracker, *Secure Low-Latency Interactive Messaging (SLIM) (draft-mpsb-agntcy-slim)*, fetched 2026-10-30", "date": null, "quote": "Cohn-Gordon, \"The Messaging Layer Security (MLS) Protocol\", RFC 9420, DOI 10.17487/RFC9420,", "ref": 23 }, { "label": "[24]", "url": "https://datatracker.ietf.org/wg/agentproto/about/", "claim": "IETF, *Agent Communication Protocols (agentproto) Working Group*, fetched 2026-11-11", "date": null, "quote": "State Active / Applications and Real-Time Area (art) / charter-ietf-agentproto-01 Approved / Chairs Leslie Daigle, Orie Steele / The agentic dialog management protocol neither replaces application-layer agent communication protocols nor defines a new transport protocol. / The dialog context is defined so that existing application-layer agent communication protocols (e.g., the Model Context Protocol (MCP) and the Agent2Agent (A2A) protocol) can carry it using their own mechanisms.", "ref": 24 }, { "label": "[25]", "url": "https://www.ietf.org/archive/id/draft-manyfolks-agentproto-arch-00.txt", "claim": "J. Rosenberg, Z. Sarker, T. Reddy, K. Yao, D. Liu, and S. Krishnan, *Architecture for AI Agent Communications on the Internet (draft-manyfolks-agentproto-arch-00)*, 30 October 2026; fetched 2026-11-11", "date": null, "quote": "30 October 2026 / draft-manyfolks-agentproto-arch-00 / It provides the foundational architectural elements for the Agent Communications Protocol (ACP) - also known as agentproto - a new protocol to be developed in the IETF. / ACP enables communication between user agent clients and AI agents, between AI Agents and other AI Agents, or between AI Agents and tools.", "ref": 25 }, { "label": "[26]", "url": "https://telnyx.com/.well-known/agent-card.json", "claim": "Telnyx, *Telnyx Assistant Agent Card*, 2026-11-03", "date": "2026-11-03", "quote": "\"name\": \"Telnyx Assistant\" / \"version\": \"1.1.0\" / \"supportedInterfaces\" / https://api.telnyx.com/v2/support_agent/public/a2a / \"protocolBinding\": \"JSONRPC\" / \"protocolVersion\": \"1.0\" / \"protocolVersion\": \"0.3\" / \"preferredTransport\": \"JSONRPC\" / \"streaming\": false / responses are delivered via task-state polling (tasks/get) / \"id\": \"public-pricing\" … \"id\": \"country-coverage\" … \"id\": \"product-and-evaluation\" … \"id\": \"ask-docs\" … \"id\": \"platform-status\" … \"id\": \"feature-requests\"", "ref": 26 }, { "label": "[27]", "url": "https://redocly.com/.well-known/agent-card.json", "claim": "Redocly, *Redocly Agent Card*, 2026-10-30", "date": "2026-10-30", "quote": "https://redocly.com/a2a / \"version\":\"0.0.1\" / \"preferredTransport\":\"HTTP+JSON\" / \"protocolVersion\":\"0.3.0\" / \"streaming\":false,\"pushNotifications\":false / \"id\":\"recheck-config\" … \"id\":\"recheck-lint\" … \"id\":\"redocly\" … \"id\":\"redocly-api-docs\" … \"id\":\"redocly-authoring\" … \"id\":\"redocly-cli\" … \"id\":\"redocly-lint-rules\" / https://redocly.com/mcp / Model Context Protocol server exposing the documentation tools and skills.", "ref": 27 }, { "label": "[28]", "url": "https://www.pangram.com/.well-known/agent-card.json", "claim": "Pangram, *Pangram Agent Card*, 2026-10-30", "date": "2026-10-30", "quote": "Pangram AI detection agent. Detects AI-generated text and images; live detection calls the Pangram APIs with a user-provided x-api-key / \"supportedInterfaces\":[{\"url\":\"https://www.pangram.com/a2a\",\"protocolBinding\":\"JSONRPC\",\"protocolVersion\":\"1.0\"}] / \"version\":\"1.0.0\" … \"streaming\":false,\"pushNotifications\":false,\"extendedAgentCard\":false / detect-ai-text / detect-ai-image", "ref": 28 }, { "label": "[29]", "url": "https://www.ticketfairy.com/.well-known/agent-card.json", "claim": "Ticket Fairy, *Ticket Fairy Agent Card*, 2026-10-30", "date": "2026-10-30", "quote": "Ticket Fairy events and ticket checkout / \"version\": \"1.0.0\" / https://www.ticketfairy.com/agentic/a2a / \"protocolBinding\": \"JSONRPC\" / \"protocolVersion\": \"1.0\" / search_events / Send SendMessage with role ROLE_USER / A2A-Version: 1.0 … UCP-Agent, Content-Digest and RFC 9421 HTTP Message Signatures / ticket-checkout / https://a2ui.org/a2a-extension/a2ui/v0.8 / https://ucp.dev/2026-08-25/specification/reference", "ref": 29 }, { "label": "[30]", "url": "https://www.wearewarp.com/.well-known/agent-card.json", "claim": "Warp, *Warp Freight Agent Card*, 2026-10-30", "date": "2026-10-30", "quote": "a2a-version: 1.0.0 / \"name\":\"Warp Freight\" / \"version\":\"0.23.0\" / https://www.wearewarp.com/api/a2a/jsonrpc / \"protocolBinding\":\"JSONRPC\" / \"protocolVersion\":\"1.0\" / warpApiKey / \"scheme\":\"bearer\" / \"id\":\"get_ltl_freight_quote\" … \"id\":\"get_ftl_freight_quote\" … \"id\":\"get_box_truck_quote\" … \"id\":\"get_cargo_van_quote\" … \"id\":\"track_shipment\" … \"id\":\"get_lane_rate_history\" … \"id\":\"book_shipment\"", "ref": 30 }, { "label": "[31]", "url": "https://aws.amazon.com/blogs/machine-learning/introducing-agent-to-agent-protocol-support-in-amazon-bedrock-agentcore-runtime/", "claim": "Madhur Prashant et al. (AWS Machine Learning Blog), *Introducing agent-to-agent protocol support in Amazon Bedrock AgentCore Runtime*, 2025-11-11", "date": "2025-11-11", "quote": "We recently announced the support for Agent-to-Agent (A2A) protocol on Amazon Bedrock AgentCore Runtime. / 11 NOV 2025 / JSON-RPC 2.0 / stateless HTTP server on port 9000 and supporting JSON-RPC messaging. The runtime acts as a transparent proxy, passing JSON-RPC requests and responses unchanged / Supports authenticated agent card at /.well-known/agent-card.json / Amazon Bedrock AgentCore Runtime supports secure authentication via AWS SigV4 and OAuth 2.0", "ref": 31 }, { "label": "[32]", "url": "https://architecture.learning.sap.com/news/2026/10/27/a2a-agent-gateway-interoperability", "claim": "PVN PavanKumar (SAP Architecture Center), *Third-party agents can now interoperate with SAP Agents via the Agent Gateway*, 2026-10-27", "date": "2026-10-27", "quote": "SAP announces the October 2026 general availability of inbound Agent2Agent (A2A) interoperability / 2026-10-27 / The Agent Gateway implements discovery based on the open Agentic Resource Discovery (ARD) specification / Customers can discover available SAP Agents and Assistants, each with its identifier, AgentCard URL, and metadata. / Creates a single-tenant OpenID Connect (OIDC) Agent Identity for the registered consumer. / Creates an access control list (ACL) specifying which SAP Agents the consumer is permitted to invoke", "ref": 32 }, { "label": "[33]", "url": "https://docs.cloud.google.com/gemini/enterprise/docs/release-notes", "claim": "Google Cloud, *Gemini Enterprise release notes*, A2A GA entry 2026-08-17", "date": null, "quote": "August 17, 2026 / General availability for registering A2UI and A2A agents with Gemini Enterprise, including A2UI version v0.9 support / The feature is generally available (GA) instead of Public Preview. / the Agent2Agent (A2A) Protocol for communication with Gemini Enterprise / v0.8", "ref": 33 }, { "label": "[34]", "url": "https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent", "claim": "Microsoft, *Connect to an A2A agent endpoint from Foundry Agent Service*, last updated 2026-10-28", "date": null, "quote": "Use the generally available a2a tool type for new integrations. The earlier a2a_preview tool type remains in preview for existing integrations. / a2a (A2ATool or A2AToolboxTool) 1.0 Generally available (GA) a2a_preview (A2APreviewTool or A2APreviewToolboxTool) 0.3 Preview / Foundry agent targets support generally available A2A protocol version 1.0 and preview version 0.3. Version 1.0 uses JSON-RPC. Only text modality is supported, and streaming responses aren't supported. / send_credentials_for_agent_card / When the target supports the agent identity acting with the user, use AgentOnBehalfOfUser. This authentication type is in preview. / Last updated on 2026-10-28 / Create an A2A server by using the official A2A SDK for your language (Python, .NET, or JavaScript). … Serve an agent card at /.well-known/agent-card.json that describes your agent's capabilities.", "ref": 34 }, { "label": "[35]", "url": "https://learn.microsoft.com/en-us/microsoft-copilot-studio/add-agent-agent-to-agent", "claim": "Microsoft, *Connect to an agent over the Agent2Agent (A2A) protocol*, last updated 2026-08-26", "date": null, "quote": "By using A2A, Copilot Studio can delegate tasks to another agent, not just call APIs. / Once you enter your endpoint URL, if your agent has a valid agent card on the standard .well-known URL, Copilot Studio automatically pulls the name and description for your agent from the card / You can also try to navigate to your agent's card in your browser (located at your agent's endpoint + /.well-known/agent.json). / \"method\": \"message/send\", \"params\": { \"message\": { \"contextId\": / copilotstudio.microsoft.com/a2a/chathistory / Last updated on 2026-08-26", "ref": 35 }, { "label": "[36]", "url": "https://architecture.learning.sap.com/docs/ref-arch/ae6821", "claim": "SAP Architecture Center, *Integrating AI Agents with Joule (Outbound A2A)*, last updated 2026-10-26", "date": null, "quote": "Within this scenario, you add a Joule Dialog Function with an action of type agent-request. / Joule acts as an A2A client. / It sends a request to your agent's A2A endpoint / the bidirectional communication with 3rd-party and self-hosted agents through Agent Gateway is not yet supported / Last updated on Oct 26, 2026 / not yet generally available (GA)", "ref": 36 }, { "label": "[37]", "url": "https://a2a-protocol.org/oauth/a2a-cli.json", "claim": "a2aproject, *A2A CLI OAuth Client ID Metadata Document*, fetched 2026-11-11", "date": null, "quote": "\"client_id\": \"https://a2a-protocol.org/oauth/a2a-cli.json\" / \"client_name\": \"A2A CLI\",\n \"client_uri\": \"https://github.com/a2aproject/a2a-cli\", / \"grant_types\": [\n \"authorization_code\",\n \"refresh_token\",\n \"urn:ietf:params:oauth:grant-type:device_code\"\n ] / \"token_endpoint_auth_method\": \"none\"", "ref": 37 }, { "label": "[38]", "url": "https://www.linuxfoundation.org/press/a2a-protocol-surpasses-150-organizations-lands-in-major-cloud-platforms-and-sees-enterprise-production-use-in-first-year", "claim": "The Linux Foundation, *A2A Protocol Surpasses 150 Organizations*, 2026-04-09", "date": "2026-04-09", "quote": "April 9, 2026 / expanded from a single Python implementation to five production-ready languages, including JavaScript, Java, Go, and .NET / more than 150 organizations supporting the standard / grown from more than 50 to over 150 / surpassed 22,000 GitHub stars", "ref": 38 }, { "label": "[39]", "url": "https://agentpeering.com/docs/faq", "claim": "AgentPeering, *Frequently Asked Questions*, checked 2026-11-06", "date": null, "quote": "agentpeering.com is a free, vendor-neutral registry / prove they own its domain / uptime monitoring, latency tracking and a trust score / speaks A2A v0.3 / message/send / still accepts v0.2 / tasks/send / no official affiliation with Google, the Linux Foundation", "ref": 39 } ], "form": "endpoint", "governance": "Agentic AI Foundation (AAIF) under the Linux Foundation (donated to the Linux Foundation on 2025-06-23; AAIF Growth Stage project approved by Technical Committee 2026-07-15 and Governing Board 2026-08-04, announced 2026-08-17); nine-seat Technical Steering Committee (Google, Microsoft, Cisco, Amazon Web Services, Salesforce, ServiceNow, SAP, IBM, and Bloomberg)", "group": null, "history": [ { "date": "2026-09-06", "note": "verified against a2a-protocol.org/latest/specification/, github.com/a2aproject/A2A README and agent-discovery.md, and the LF/A2A one-year press release (prnewswire)" }, { "date": "2026-10-16", "note": "A2A v1.0.1 released on 2026-05-28 (v1.0.0 on 2026-03-12); governance is the Linux Foundation with a Technical Steering Committee of AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP and ServiceNow" }, { "date": "2026-10-20", "note": "AAIF membership (17 August 2026) added beside the Linux Foundation TSC; probe accepts v1.0 supportedInterfaces cards and legacy v0.3 cards; four card-version censuses recorded with their frames" }, { "date": "2026-10-21", "note": "a2a-sdk 1.2.3 published 2026-10-19" }, { "date": "2026-10-28", "note": "Re-verified record against 24 sources on 2026-10-28: 5 live /.well-known/agent-card.json endpoints (Telnyx, Redocly, Pangram, Ticket Fairy, Warp Freight), 6 vendor implementations, and 3 press sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "a2a", "implementation": "multi-implementation", "last_verified": "2026-11-12", "name": "Agent2Agent Protocol (A2A)", "native_status": "Stable: v1.0 is the first stable specification (shipped March 2026); latest release 1.0.1 (2026-05-28)", "origin": { "date": "2025-04-09", "org": "Google" }, "part_of": null, "parties": [ "agent-agent" ], "phase": "stable", "probe": { "method": "GET", "on_absent": "404 or non-JSON response means no public Agent Card is hosted at this well-known path; the origin may still run A2A behind auth or a registry", "parse": "Accept either card shape and record which one was seen. A v1.0 card places url, protocolBinding, and protocolVersion inside supportedInterfaces[] (preferredTransport and additionalInterfaces fold into that array). A legacy v0.3 card carries a top-level url. name may be present on either shape.", "path": "{origin}/.well-known/agent-card.json" }, "question": "How do two independent agents, built on different frameworks, discover each other and delegate a task to completion?", "scope": "general", "spec_url": "https://a2a-protocol.org/latest/specification/", "step": "coordinate", "summary_md": "The **Agent2Agent Protocol** (**A2A**) is an open standard originated by Google on April 9, 2025 (`2025-04-09`) for capability discovery and task delegation between independent, opaque AI agent systems across different frameworks and vendor stacks without exposing internal memory, state, or tool implementations. An A2A client fetches the server's JSON Agent Card at `https://{server_domain}/.well-known/agent-card.json` (permanently registered with IANA on `2025-08-01`, renamed from `/.well-known/agent.json` in `0.3.0`) and invokes PascalCase operations (`SendMessage`, `SendStreamingMessage`, `GetTask`, `CancelTask`) over one of three core `supportedInterfaces` bindings: JSON-RPC 2.0 over HTTP(S) (`JSONRPC`) with Server-Sent Events (`text/event-stream`), gRPC (`GRPC`), or RESTful `HTTP+JSON` (`application/a2a+json`) carrying the `A2A-Version` header. Transferred to the Linux Foundation on June 23, 2025 (`2025-06-23`), A2A merged IBM's Agent Communication Protocol in August 2025, reached its first stable release (`1.0.0`) on March 12, 2026 (`2026-03-12`, followed by `1.0.1` on `2026-05-26`), and was approved as an Agentic AI Foundation (AAIF) Growth Stage project in August 2026 (`2026-08-17`). Release candidate v1.1.0-rc adds an IANA media-type registration template for `application/a2a-agent-card+json`, for inclusion in the 1.1 release (commit dated 2026-10-27). Inclusion of the template does not mean IANA registration is complete.", "track": "linux-foundation", "version": { "date": "2026-05-28", "label": "1.0.1" }, "watch": [ { "type": "page", "url": "https://a2a-protocol.org/latest/specification/", "selector": "main", "cadence": "weekly" }, { "type": "github", "repo": "a2aproject/A2A", "mode": "release" }, { "type": "pypi", "pkg": "a2a-sdk" } ], "use_cases": [ "agent-to-agent-messaging", "describe-agent-capabilities", "discover-my-api" ], "audience": [ "agent-builder", "platform", "standards-body" ], "pairs_with": [ "mcp", "agent-communication-protocol", "agent-connect-protocol", "ap2" ], "prerequisites": [], "hatnote_md": "This page covers the Agent2Agent Protocol (A2A), the open protocol for capability discovery via an Agent Card and inter-agent task delegation. It is distinct from Account-to-Account (A2A) bank payments. For host-to-tool context integration, see [Model Context Protocol](/protocols/mcp/); for agent payment authorization built on A2A, see [Agent Payments Protocol (AP2)](/protocols/ap2/).", "tier": "flagship", "lifecycle_status": "published_standard", "wire_archetype": "harnesses_rpc_ui", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This page covers the Agent2Agent Protocol (A2A), the open protocol for capability discovery via an Agent Card and inter-agent task delegation. It is distinct from Account-to-Account (A2A) bank payments. For host-to-tool context integration, see [Model Context Protocol](/protocols/mcp/); for agent payment authorization built on A2A, see [Agent Payments Protocol (AP2)](/protocols/ap2/). [1]", "v05_elevator_pitch_md": "A2A is a peer-to-peer interoperability standard that lets independent AI agents built on different frameworks or vendor stacks discover each other's skills and delegate multi-turn tasks without exposing their internal memory, prompts, or private tools. Instead of writing custom point-to-point glue code for every cross-vendor agent pairing, a client reads a remote agent's JSON Agent Card at `/.well-known/agent-card.json` and coordinates stateful work through standardized operations such as `SendMessage`, `SendStreamingMessage`, and `GetTask`. [1][2]", "v05_lead_md": "The **Agent2Agent Protocol** (**A2A**) is an open standard originated by Google on April 9, 2025 (`2025-04-09`) for capability discovery and task delegation between independent, opaque AI agent systems across different frameworks and vendor stacks without exposing internal memory, state, or tool implementations. [1][3] An A2A client fetches the server's JSON Agent Card at `https://{server_domain}/.well-known/agent-card.json` (permanently registered with IANA on `2025-08-01`, renamed from `/.well-known/agent.json` in `0.3.0`) and invokes PascalCase operations (`SendMessage`, `SendStreamingMessage`, `GetTask`, `CancelTask`) over one of three core `supportedInterfaces` bindings: JSON-RPC 2.0 over HTTP(S) (`JSONRPC`) with Server-Sent Events (`text/event-stream`), gRPC (`GRPC`), or RESTful `HTTP+JSON` (`application/a2a+json`) carrying the `A2A-Version` header. [4][5][6][7][8] Transferred to the Linux Foundation on June 23, 2025 (`2025-06-23`), A2A merged IBM's Agent Communication Protocol in August 2025, reached its first stable release (`1.0.0`) on March 12, 2026 (`2026-03-12`, followed by `1.0.1` on `2026-05-26`), and was approved as an Agentic AI Foundation (AAIF) Growth Stage project in August 2026 (`2026-08-17`). [7][9][10][11][12][13] Release candidate v1.1.0-rc adds an IANA media-type registration template for `application/a2a-agent-card+json`, for inclusion in the 1.1 release (commit dated 2026-10-27). Inclusion of the template does not mean IANA registration is complete. [14]", "v05_identity_sentence_md": "The **Agent2Agent Protocol** (**A2A**) is an open standard originated by Google on April 9, 2025 (`2025-04-09`) for capability discovery and task delegation between independent, opaque AI agent systems across different frameworks and vendor stacks without exposing internal memory, state, or tool implementations. [1][3]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Coordinate](/category/coordinate/) (`coordinate`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "Google (launched 2025-04-09) [3]" }, { "label": "Governed by", "value_md": "Agentic AI Foundation (AAIF) under the Linux Foundation (Linux Foundation project launched 2025-06-23; AAIF Growth Stage approved by Technical Committee 2026-07-15 and Governing Board 2026-08-04, announced 2026-08-17); nine-seat Technical Steering Committee [9][11][13][15]" }, { "label": "Track", "value_md": "Foundation / Consortium Specification (`linux-foundation`); AAIF Growth Stage hosted project [2][11]" }, { "label": "Status", "value_md": "Active open standard; v1.0 is the first stable specification (March 2026); latest release `1.0.1` (changelog `2026-05-26`, GitHub release `2026-05-28`) [11][16]" }, { "label": "Version", "value_md": "`1.0.1` (changelog `2026-05-26`; GitHub release `2026-05-28`); `1.0.0` (`2026-03-12`); `0.3.0` (`2025-07-30`); release candidate v1.1.0-rc in progress (commit 2026-10-27). The specification page header still lists `1.0.0` as Latest Released Version (previous: `0.3.0`, `0.2.6`, `0.1.0`). [1][7][14][16]" }, { "label": "Message format", "value_md": "JSON-RPC 2.0 over HTTP(S) (`JSONRPC`) with Server-Sent Events (`text/event-stream`); gRPC (`GRPC`, Protocol Buffers over HTTP/2); RESTful `HTTP+JSON` (`application/a2a+json` preferred in `1.0.1`) [1][7]" }, { "label": "Headers", "value_md": "`A2A-Version`, `A2A-Extensions` [1]" }, { "label": "IANA registration", "value_md": "`agent-card.json` in IANA Well-Known URIs (`permanent`, `2025-08-01`, change controller `Linux Foundation`; spec section 14.3 template names `A2A Protocol Working Group`). Section 14.1–14.2 provide registration templates for `application/a2a+json`, `A2A-Version`, and `A2A-Extensions`. Release candidate v1.1.0-rc adds a registration template for `application/a2a-agent-card+json` (commit 2026-10-27); inclusion of the template does not mean IANA registration is complete. [1][5][14]" }, { "label": "Specification", "value_md": "[Agent2Agent (A2A) Protocol Specification](https://a2a-protocol.org/latest/specification/) [1]" }, { "label": "Found at", "value_md": "`GET https://{server_domain}/.well-known/agent-card.json` (renamed from `/.well-known/agent.json` in `0.3.0` on `2025-07-30`), registry/catalog lookup, or direct configuration [1][7]" }, { "label": "Licence", "value_md": "Apache License, Version 2.0 [1]" } ], "v05_problem_md": "Before A2A, handing off work between agents built on different frameworks required custom integration code for every new pairing. Those agents might use different languages or come from different vendors, with no common interaction model to bridge disparate agentic systems. [1][2] An A2A server publishes an Agent Card whose `supportedInterfaces` entries each declare a `protocolBinding` and `protocolVersion`. Clients call `SendMessage` or `SendStreamingMessage` to initiate or continue work, and use `GetTask` and `CancelTask` against a stateful Task across states such as `TASK_STATE_SUBMITTED` and `TASK_STATE_WORKING`. [1] For long-running or disconnected work, the server can stream incremental updates with `text/event-stream` or deliver asynchronous updates by HTTP POST to a client-provided webhook. [1] Agents stay opaque: they collaborate from declared capabilities and exchanged information, without sharing internal thoughts, plans, tool implementations, state, or memory. MCP, not A2A, standardizes how an agent connects to tools, APIs, and other resources. [1]", "v05_mechanism_delta_md": "An A2A server publishes an Agent Card whose `supportedInterfaces` entries each declare a `protocolBinding` and `protocolVersion`. Clients call `SendMessage` or `SendStreamingMessage` to initiate or continue work, and use `GetTask` and `CancelTask` against a stateful Task across states such as `TASK_STATE_SUBMITTED` and `TASK_STATE_WORKING`. [1] For long-running or disconnected work, the server can stream incremental updates with `text/event-stream` or deliver asynchronous updates by HTTP POST to a client-provided webhook. [1]", "v05_scope_boundary_md": "Agents stay opaque: they collaborate from declared capabilities and exchanged information, without sharing internal thoughts, plans, tool implementations, state, or memory. MCP, not A2A, standardizes how an agent connects to tools, APIs, and other resources. [1]", "v05_fuzzy_additions": [ { "id": "discovery-and-the-well-known-agent-card", "heading": "Discovery and the well-known Agent Card", "body_md": "A2A standardizes self-description in an Agent Card, a JSON business card for the remote agent, and leaves discovery to the deployment. A client that knows the domain GETs `/.well-known/agent-card.json`, following RFC 8615. Curated registries and direct configuration are allowed, but the current A2A specification does not prescribe a standard API for curated registries. [1][17]", "bullets": [ { "label": "Supported interfaces", "text_md": "An Agent Card lists `name`, `description`, and `provider`, plus an ordered `supportedInterfaces` array. Each `AgentInterface` has `url`, `protocolBinding`, and `protocolVersion`; the first entry is preferred. v1.0 replaced `preferredTransport` and `additionalInterfaces` with `supportedInterfaces[]`, beside `streaming`, `pushNotifications`, `securitySchemes`, and `AgentSkill` entries. [1][8][17]" }, { "label": "No standard registry API", "text_md": "A curated registry is an intermediary catalog. Servers publish Agent Cards to it, and clients query by skills, tags, provider, or capabilities. The specification does not define that registry API. Direct configuration, including hardcoded URLs or proprietary APIs, also lacks a standard discovery method. [17]" }, { "label": "Well-known path rename", "text_md": "Issue #66 initially requested `.well-known/agent.json` (citing existing production deployments) with the Linux Foundation as change controller, then adopted `agent-card.json` after reviewers noted `agent.json` was too generic. PR #841, merged 2025-07-29, changed `/.well-known/agent.json` to `/.well-known/agent-card.json`. Changelog `0.3.0` (2025-07-30) records that break. The `v0.3.0` specification publishes `https://{server_domain}/.well-known/agent-card.json`, and IANA registered `agent-card.json` as permanent on 2025-08-01. [4][5][6][7][18]" }, { "label": "Extended Agent Cards", "text_md": "`securitySchemes` names the schemes used to authenticate to the agent. If `AgentCard.capabilities.extendedAgentCard` is true, `GetExtendedAgentCard` (which MUST require authentication) returns a more detailed card after authentication, and clients should replace the cached public card for that session. Agent Cards MAY also be signed using JSON Web Signatures (`JWS`, RFC 7515) over RFC 8785 `JCS` canonical JSON, and clients SHOULD verify `signatures` when present. Authenticated extended cards are recommended for sensitive skills, using out-of-band dynamic credentials rather than static secrets in the card. [1][17]" } ] }, { "id": "task-lifecycle-message-parts-and-transport-bindings", "heading": "Task lifecycle, message parts, and transport bindings", "body_md": "A Task is the stateful unit of work. Clients open it with `SendMessage` or `SendStreamingMessage`, read it with `GetTask`, and may cancel it with `CancelTask`. Content rides in typed `Part` containers, and outputs come back as `Artifact` objects. Live updates use Server-Sent Events or a webhook. The same operations bind to JSON-RPC 2.0, gRPC, and `HTTP+JSON`. [1]", "bullets": [ { "label": "Lifecycle operations", "text_md": "`SendMessage` returns a Task or a direct Message, and processing may continue afterward. States run through `TASK_STATE_SUBMITTED`, `TASK_STATE_WORKING`, interrupted `TASK_STATE_INPUT_REQUIRED` and `TASK_STATE_AUTH_REQUIRED`, and terminal `TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, and `TASK_STATE_REJECTED`. `SendStreamingMessage` emits `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` objects. `GetTask` reads status, artifacts, and optional history, while `ListTasks` lists tasks visible within the caller's authorization scope. `CancelTask` requests cancellation, which is not guaranteed, `SubscribeToTask` resubscribes to an active task stream, and `CreateTaskPushNotificationConfig`, `GetTaskPushNotificationConfig`, `ListTaskPushNotificationConfigs`, and `DeleteTaskPushNotificationConfig` manage webhook push configurations. [1]" }, { "label": "Message parts", "text_md": "A `Part` is the smallest unit of content in a Message or Artifact: a container for text, a file such as an image or video, or a structured JSON blob. An `Artifact` is task output, a document, image, or structured data, composed of Parts. [1]" }, { "label": "Streaming and webhooks", "text_md": "Streaming sends real-time updates for status changes and artifact chunks. The JSON-RPC binding uses Server-Sent Events (`text/event-stream`), delivers events in generation order, and may broadcast one task on multiple concurrent streams. Push notifications POST asynchronous updates to a client webhook for disconnected clients. `GetTask` reads the final state afterward. Under §13 Security Considerations, implementations MUST enforce authorization checks on every operation and scope `ListTasks`, `GetTask`, and task mutations to the caller's authorized access boundaries even when `contextId` or filter parameters are omitted (§13.1); webhook-calling agents MUST include `PushNotificationConfig.authentication` credentials and SHOULD validate webhook URLs against SSRF by rejecting private IP ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), localhost, and link-local addresses, while webhook-receiving clients MUST validate webhook authenticity and SHOULD process notifications idempotently (§13.2). An unrefereed arXiv preprint, A2ABreak (arXiv:2609.10871, last revised 24 Oct 2026, v3), models the `1.0.0` protocol as 37 states and 76 transitions and claims 11 new vulnerabilities, each exploitable by a specification-compliant adversary without requiring any implementation flaw. Those findings are preprint claims, not an established specification defect. [1][19][20]" }, { "label": "Three protocol bindings", "text_md": "`JSONRPC` is JSON-RPC 2.0 over HTTP(S), with PascalCase methods such as `SendMessage` and `GetTask` and streaming on `text/event-stream`. `GRPC` uses Protocol Buffers over HTTP/2 and the `A2AService` service. `HTTP+JSON` is REST with JSON payloads and prefers `application/a2a+json`. Clients select the first supported `supportedInterfaces` entry, including its `protocolBinding` and `protocolVersion`. [1]" } ] } ], "v05_diagram": { "title": "Discovery and task lifecycle", "heading": "Discovery and task lifecycle", "mermaid": "flowchart TD\n Client[\"A2A Client\"] -->|\"GET /.well-known/agent-card.json, registry, or direct config\"| Card[\"Agent Card\"]\n Card -->|\"First supported interface: JSONRPC, GRPC, or HTTP+JSON\"| Send[\"Send Message\"]\n Send --> Direct[\"Direct Message\"]\n Send --> Task[\"Task\"]\n Task --> Submitted[\"TASK_STATE_SUBMITTED\"]\n Submitted --> Working[\"TASK_STATE_WORKING\"]\n Working --> NeedInput[\"INPUT_REQUIRED or AUTH_REQUIRED\"]\n NeedInput --> Working\n Working --> Terminal[\"COMPLETED, FAILED, CANCELED, or REJECTED\"]\n Task -->|\"Poll, stream, or webhook\"| Client", "caption_md": "An A2A Client fetches `/.well-known/agent-card.json`, selects the first supported interface (`JSONRPC`, `GRPC`, or `HTTP+JSON`), and sends a message. The server returns either a direct message or a stateful task that moves through `TASK_STATE_SUBMITTED`, `TASK_STATE_WORKING`, `TASK_STATE_INPUT_REQUIRED` or `TASK_STATE_AUTH_REQUIRED`, and a terminal state (`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, or `TASK_STATE_REJECTED`), with updates by poll, stream, or webhook. [1]" }, "v05_wire_artifact": { "title": "Sample Agent Card", "heading": "Sample Agent Card", "lang": "json", "code": "{\n \"name\": \"GeoSpatial Route Planner Agent\",\n \"description\": \"Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.\",\n \"supportedInterfaces\": [\n {\"url\": \"https://georoute-agent.example.com/a2a/v1\", \"protocolBinding\": \"JSONRPC\", \"protocolVersion\": \"1.0\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/grpc\", \"protocolBinding\": \"GRPC\", \"protocolVersion\": \"1.0\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/json\", \"protocolBinding\": \"HTTP+JSON\", \"protocolVersion\": \"1.0\"}\n ],\n \"provider\": {\n \"organization\": \"Example Geo Services Inc.\",\n \"url\": \"https://www.examplegeoservices.com\"\n },\n \"iconUrl\": \"https://georoute-agent.example.com/icon.png\",\n \"version\": \"1.2.0\",\n \"documentationUrl\": \"https://docs.examplegeoservices.com/georoute-agent/api\",\n \"capabilities\": {\n \"streaming\": true,\n \"pushNotifications\": true,\n \"extendedAgentCard\": true\n },\n \"securitySchemes\": {\n \"google\": {\n \"openIdConnectSecurityScheme\": {\n \"openIdConnectUrl\": \"https://accounts.google.com/.well-known/openid-configuration\"\n }\n }\n },\n \"securityRequirements\": [{ \"schemes\": { \"google\": { \"list\": [\"openid\", \"profile\", \"email\"] } } }],\n \"defaultInputModes\": [\"application/json\", \"text/plain\"],\n \"defaultOutputModes\": [\"application/json\", \"image/png\"],\n \"skills\": [\n {\n \"id\": \"route-optimizer-traffic\",\n \"name\": \"Traffic-Aware Route Optimizer\",\n \"description\": \"Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).\",\n \"tags\": [\"maps\", \"routing\", \"navigation\", \"directions\", \"traffic\"],\n \"examples\": [\n \"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.\",\n \"{\\\"origin\\\": {\\\"lat\\\": 37.422, \\\"lng\\\": -122.084}, \\\"destination\\\": {\\\"lat\\\": 37.7749, \\\"lng\\\": -122.4194}, \\\"preferences\\\": [\\\"avoid_ferries\\\"]}\"\n ],\n \"inputModes\": [\"application/json\", \"text/plain\"],\n \"outputModes\": [\n \"application/json\",\n \"application/vnd.geo+json\",\n \"text/html\"\n ]\n },\n {\n \"id\": \"custom-map-generator\",\n \"name\": \"Personalized Map Generator\",\n \"description\": \"Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.\",\n \"tags\": [\"maps\", \"customization\", \"visualization\", \"cartography\"],\n \"examples\": [\n \"Generate a map of my upcoming road trip with all planned stops highlighted.\",\n \"Show me a map visualizing all coffee shops within a 1-mile radius of my current location.\"\n ],\n \"inputModes\": [\"application/json\"],\n \"outputModes\": [\n \"image/png\",\n \"image/jpeg\",\n \"application/json\",\n \"text/html\"\n ]\n }\n ],\n \"signatures\": [\n {\n \"protected\": \"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0\",\n \"signature\": \"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ\"\n }\n ]\n}", "caption_md": "Sample Agent Card for the GeoSpatial Route Planner Agent (§8.5 illustrative specification example). It declares `supportedInterfaces` for `JSONRPC`, `GRPC`, and `HTTP+JSON`, plus `capabilities`, `securitySchemes`, `skills`, and optional `signatures` (Agent Cards MAY be signed using JWS over RFC 8785 canonical JSON, and clients SHOULD verify signatures when present). [1]" }, "v05_counterparts": { "classic_analogues": [ { "name": "JSON-RPC 2.0 Specification", "spec_or_rfc": "JSON-RPC 2.0", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Profiles JSON-RPC 2.0 over HTTP(S) (`JSONRPC` binding) for task method calls (`SendMessage`, `GetTask`, `CancelTask`) paired with Server-Sent Events (`text/event-stream`) for streaming updates. [1]" }, { "name": "Well-Known URIs (RFC 8615)", "spec_or_rfc": "RFC 8615", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Registers the permanent IANA well-known URI suffix `agent-card.json` (2025-08-01), fetched via HTTP `GET` at `https://{server_domain}/.well-known/agent-card.json` for Agent Card discovery. [1][5]" } ], "agentic_peers": [ { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "MCP provides the vertical integration layer connecting an agent to external tools, APIs, and resources, whereas A2A provides the horizontal peer-to-peer protocol for capability discovery and task delegation between opaque agents. [1][2]" }, { "target_id": "agent-communication-protocol", "target_name": "Agent Communication Protocol", "relation_type": "supersedes", "relation_label": "Supersedes", "delta_md": "IBM's Agent Communication Protocol (ACP) for the BeeAI platform officially merged into A2A under the Linux Foundation in August 2025, winding down standalone ACP development in favor of A2A. [11][12]" }, { "target_id": "agent-connect-protocol", "target_name": "Agent Connect Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Within Cisco's AGNTCY stack (which deprecated standalone Agent Connect Protocol in favor of A2A), SLIM (Secure Low-Latency Interactive Messaging) carries A2A messages via the experimental SLIMRPC binding, using Messaging Layer Security (MLS, RFC 9420) by default for end-to-end session encryption. [13][21][22][23]" }, { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "AP2 extends A2A into agentic commerce by adding payment authorization while shopping and merchant agents communicate over A2A for discovery, pricing, and fulfillment. [11]" }, { "target_id": "agentproto", "target_name": "IETF agentproto WG", "relation_type": "complements", "relation_label": "Complements", "delta_md": "The IETF agentproto Working Group (Agent Communication Protocols) is Active in the Applications and Real-Time Area (art) under approved charter `charter-ietf-agentproto-01` (chairs Leslie Daigle and Orie Steele), which scopes the WG to dialog-context correlation and lifecycle management that complements rather than replaces application-layer agent communication protocols (explicitly naming MCP and A2A as capable of carrying dialog context) and defines no new transport protocol. Individual `draft-manyfolks-agentproto-arch-00` (30 October 2026) proposes an Agent Communications Protocol (ACP) architecture for communication among user agent clients, AI agents, and tools. [24][25]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (20 probed or cited examples across 4 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Public A2A agents & managed server runtimes", "col4_header": "Agent Card endpoint, transport & role", "note_md": null, "rows": [ { "actor": "Telnyx (Telnyx Assistant)", "role": "Public A2A agent", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-03", "col4_md": "Live Agent Card binding `JSONRPC` (`1.0` and `0.3`) at `https://api.telnyx.com/v2/support_agent/public/a2a` with `tasks/get` polling.", "source_md": "[Telnyx Assistant Agent Card](https://telnyx.com/.well-known/agent-card.json) [26]" }, { "actor": "Redocly", "role": "Public A2A agent", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Live Agent Card advertising `protocolVersion` `0.3.0` (`preferredTransport` `HTTP+JSON`) at `https://redocly.com/a2a` and MCP extension `https://redocly.com/mcp`.", "source_md": "[Redocly Agent Card](https://redocly.com/.well-known/agent-card.json) [27]" }, { "actor": "Pangram", "role": "Public A2A agent", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Live Agent Card binding `JSONRPC` (`protocolVersion` `1.0`) at `https://www.pangram.com/a2a` for `detect-ai-text` and `detect-ai-image` with `x-api-key`.", "source_md": "[Pangram Agent Card](https://www.pangram.com/.well-known/agent-card.json) [28]" }, { "actor": "Ticket Fairy", "role": "Public A2A agent", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Live Agent Card binding `JSONRPC` (`protocolVersion` `1.0`) at `https://www.ticketfairy.com/agentic/a2a` with `search_events`, `ticket-checkout`, A2UI `v0.8`, and UCP.", "source_md": "[Ticket Fairy Agent Card](https://www.ticketfairy.com/.well-known/agent-card.json) [29]" }, { "actor": "Warp (Warp Freight)", "role": "Public A2A agent", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Live Agent Card binding `JSONRPC` (`protocolVersion` `1.0`) at `https://www.wearewarp.com/api/a2a/jsonrpc` with `bearer` `warpApiKey` and freight skills.", "source_md": "[Warp Freight Agent Card](https://www.wearewarp.com/.well-known/agent-card.json) [30]" }, { "actor": "AWS (Bedrock AgentCore Runtime)", "role": "Managed agent runtime", "status": "Supported (release announcement)", "status_display": "Supported (release announcement) · as of 2025-11-11", "col4_md": "November 2025 blog announces container runtime (`port 9000`) proxying `JSON-RPC 2.0` and authenticated `/.well-known/agent-card.json`.", "source_md": "[AWS, AgentCore A2A support (11 NOV 2025)](https://aws.amazon.com/blogs/machine-learning/introducing-agent-to-agent-protocol-support-in-amazon-bedrock-agentcore-runtime/) [31]" }, { "actor": "SAP (Agent Gateway)", "role": "Enterprise agent gateway", "status": "Supported (release announcement)", "status_display": "Supported (release announcement) · as of 2026-10-27", "col4_md": "October 2026 announcement of inbound A2A gateway combining `AgentCard` URLs with Agentic Resource Discovery (`ARD`).", "source_md": "[SAP, Agent Gateway A2A (2026-10-27)](https://architecture.learning.sap.com/news/2026/10/27/a2a-agent-gateway-interoperability) [32]" } ] }, "side_b": { "visible": true, "heading": "Client orchestrators & enterprise host platforms", "col4_header": "Outbound client role & auth", "note_md": null, "rows": [ { "actor": "Google (Gemini Enterprise)", "role": "Client orchestrator", "status": "Supported (release announcement)", "status_display": "Supported (release announcement) · as of 2026-08-17", "col4_md": "August 2026 release note announces general availability for registering external `A2A` and `A2UI` (`v0.9`, `v0.8`) agents.", "source_md": "[Google Cloud, Gemini Enterprise release notes](https://docs.cloud.google.com/gemini/enterprise/docs/release-notes) [33]" }, { "actor": "Microsoft (Foundry Agent Service)", "role": "Client orchestrator & target", "status": "Partial", "status_display": "Partial · as of 2026-10-28", "col4_md": "GA `a2a` tool for `v1.0` `JSON-RPC` (text-only, no streaming) and preview `a2a_preview` tool for `v0.3`.", "source_md": "[Microsoft Learn, Foundry A2A tool](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent) [34]" }, { "actor": "Microsoft (Copilot Studio)", "role": "Client orchestrator", "status": "Partial", "status_display": "Partial · as of 2026-08-26", "col4_md": "Delegates tasks via `message/send` (`contextId`) and auto-reads metadata from the legacy pre-v0.3 `/.well-known/agent.json` card path.", "source_md": "[Microsoft Learn, Copilot Studio A2A](https://learn.microsoft.com/en-us/microsoft-copilot-studio/add-agent-agent-to-agent) [35]" }, { "actor": "SAP (Joule)", "role": "Outbound A2A client", "status": "Partial", "status_display": "Partial · as of 2026-10-26", "col4_md": "Outbound `agent-request` client with webhook push notifications; bidirectional third-party `Agent Gateway` communication not yet GA.", "source_md": "[SAP Architecture Center, Joule outbound A2A](https://architecture.learning.sap.com/docs/ref-arch/ae6821) [36]" }, { "actor": "A2A CLI", "role": "Official CLI client", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-11", "col4_md": "Live OAuth Client ID Metadata Document (HTTP 200) names client A2A CLI (`client_id` `https://a2a-protocol.org/oauth/a2a-cli.json`, `client_uri` `https://github.com/a2aproject/a2a-cli`) with grants `authorization_code`, `refresh_token`, and `urn:ietf:params:oauth:grant-type:device_code`, and `token_endpoint_auth_method` `none`.", "source_md": "[A2A CLI OAuth client metadata](https://a2a-protocol.org/oauth/a2a-cli.json) [37]" } ] }, "additional_tables": [ { "visible": true, "heading": "Official SDKs & agent frameworks", "col4_header": "Language / framework surface", "note_md": null, "rows": [ { "actor": "Official A2A SDKs", "role": "Official client & server SDKs", "status": "Supported", "status_display": "Supported · as of 2026-10-28", "col4_md": "Proto-generated official client and server SDKs across six languages: `Python`, `Go`, `Java`, `JS`, `.NET`, and `Rust`.", "source_md": "[A2A specification](https://a2a-protocol.org/latest/specification/) [1] · [Microsoft Learn, official A2A SDK](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent) [34] · [Linux Foundation one-year A2A release](https://www.linuxfoundation.org/press/a2a-protocol-surpasses-150-organizations-lands-in-major-cloud-platforms-and-sees-enterprise-production-use-in-first-year) [38]" }, { "actor": "Google ADK", "role": "Agent framework", "status": "Listed", "status_display": "Listed · as of 2026-08-04", "col4_md": "AAIF proposal lists native `Google ADK` client and server support across local runtimes and `Agent Platform Runtime`.", "source_md": "[AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] · [AAIF, A2A joins AAIF](https://aaif.io/blog/a2a-joins-aaif) [11]" }, { "actor": "IBM BeeAI", "role": "Agent framework", "status": "Listed", "status_display": "Listed · as of 2026-08-17", "col4_md": "Merged deprecated `ACP` into `A2A` (August 2025); `BeeAI Framework` ships native client and server adapters.", "source_md": "[BeeAI ACP README](https://raw.githubusercontent.com/i-am-bee/acp/main/README.md) [12] · [AAIF, A2A joins AAIF](https://aaif.io/blog/a2a-joins-aaif) [11] · [A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13]" }, { "actor": "LangGraph", "role": "Agent framework", "status": "Listed", "status_display": "Listed · as of 2026-08-27", "col4_md": "AAIF proposal lists hosted `/a2a/{assistant_id}` endpoints with auto-generated Agent Cards, `SSE` streaming, and `LangSmith` tracing.", "source_md": "[A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13]" }, { "actor": "CrewAI", "role": "Agent framework", "status": "Listed", "status_display": "Listed · as of 2026-08-27", "col4_md": "AAIF proposal lists `CrewAI AMP` production hosting across `REST`/`JSON-RPC`/`gRPC` transports with `OIDC`, `OAuth2`, and `mTLS`.", "source_md": "[A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13]" }, { "actor": "Pydantic AI", "role": "Agent framework", "status": "Listed", "status_display": "Listed · as of 2026-08-27", "col4_md": "AAIF proposal lists native `FastA2A` library integration exposing `Pydantic AI` agents as `ASGI` A2A applications.", "source_md": "[A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13]" }, { "actor": "AG2", "role": "Agent framework", "status": "Listed", "status_display": "Listed · as of 2026-08-27", "col4_md": "A2A blog and AAIF proposal list `AG2` (formerly `AutoGen`) agent swarm connections tagged with `a2a`.", "source_md": "[A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13]" } ] }, { "visible": true, "heading": "Public A2A registries & directories", "col4_header": "Verification & protocol surface", "note_md": null, "rows": [ { "actor": "AgentPeering", "role": "Independent public A2A registry", "status": "Supported", "status_display": "Supported · checked 2026-11-06", "col4_md": "Independent vendor-neutral A2A registry verifying domain ownership, monitoring uptime, and speaking `v0.3` `message/send` (plus `v0.2` `tasks/send`).", "source_md": "[AgentPeering FAQ](https://agentpeering.com/docs/faq) [39]" } ] } ], "censuses": [ { "label": "Google Developers Blog, Announcing A2A (2025-04-09)", "as_of": "2025-04-09", "value_md": "More than 50 technology and enterprise service partners (including Atlassian, Box, Cohere, Intuit, LangChain, MongoDB, PayPal, Salesforce, SAP, ServiceNow, UKG, Workday, Accenture, BCG, Capgemini, Cognizant, Deloitte, HCLTech, Infosys, KPMG, McKinsey, PwC, TCS, and Wipro) announced at A2A's initial launch on April 9, 2025. [3]" }, { "label": "Linux Foundation, A2A project launch (2025-06-23)", "as_of": "2025-06-23", "value_md": "More than 100 technology companies reported as supporting the Agent2Agent protocol when Google donated the specification, SDKs, and developer tooling to the Linux Foundation on June 23, 2025. [9]" }, { "label": "AAIF, A2A joins AAIF (2026-08-17)", "as_of": "2026-08-17", "value_md": "Over 150 partner organizations across cloud providers, enterprise SaaS platforms, and agent frameworks reported as backing A2A when it joined the Agentic AI Foundation (AAIF) as a Growth Stage project in August 2026. [2][11]" }, { "label": "Linux Foundation one-year A2A press release (9 April 2026)", "as_of": "2026-04-09", "value_md": "On April 9, 2026 the Linux Foundation reported that supporting organizations had grown from more than 50 to over 150, the core repository had surpassed 22,000 GitHub stars, and official SDKs had expanded from Python to five production-ready languages (Python, JavaScript, Java, Go, and .NET), later joined by Rust on the specification site. [1][38]" } ], "footer_md": null }, "v05_see_also": [ { "item_md": "**Depended on by:** [Ad Context Protocol (AdCP)](/protocols/adcp/)" }, { "item_md": "**Peer alternatives:** [Agent Interaction & Transaction Protocol (AITP)](/protocols/aitp/), [Agent Network Protocol](/protocols/anp/), [Agent Protocol](/protocols/agent-protocol-aief/), [Agora Protocol](/protocols/agora-protocol/), [Coral Protocol (CoralOS)](/protocols/coral-protocol/), [Eclipse LMOS (Language Model Operating System)](/protocols/lmos/), [ERC-8001: Agent Coordination Framework](/protocols/erc-8001/), [GB/Z 185 Artificial intelligence — Agent interconnection](/protocols/gbz-185-agent-interconnection/), [MCP Server Cards](/protocols/mcp-server-cards/), [Natural Language Interaction Protocol (NLIP)](/protocols/nlip/)" }, { "item_md": "**Complements:** [A2UI (Agent to UI) Protocol](/protocols/a2ui/), [Agent Client Protocol](/protocols/agent-client-protocol/), [Agent-User Interaction Protocol (AG-UI)](/protocols/ag-ui/), [ERC-8004: Trustless Agents](/protocols/erc-8004/), [Open Responses](/protocols/open-responses/), [Universal Commerce Protocol (UCP)](/protocols/ucp/), [Agent Directory Service](/protocols/ads/), [Agent Identity Protocol (AIP): Verifiable Delegation for AI Agent Systems](/protocols/aip-delegation-chain/), [Agent Name Service v2 (ANS)](/protocols/ans/), [Agent Registration and Discovery Protocol](/protocols/ardp/), and [16 more in the protocol directory](/protocols/)" }, { "item_md": "**[Coordinate protocols](/category/coordinate/)** — Category index for `coordinate` standards." } ], "v05_compiled_md": "---\nid: a2a\ntitle: \"Agent2Agent Protocol (A2A)\"\ntier: flagship\nlifecycle_status: published_standard\ncategory: coordinate\nform: endpoint\nwire_archetype: harnesses_rpc_ui\nspec_url: https://a2a-protocol.org/latest/specification/\nlast_checked: 2026-11-12\n---\n\n# Agent2Agent Protocol (A2A)\n\n**Category:** [Coordinate](/category/coordinate/) (`coordinate`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-12\n\n> *This page covers the Agent2Agent Protocol (A2A), the open protocol for capability discovery via an Agent Card and inter-agent task delegation. It is distinct from Account-to-Account (A2A) bank payments. For host-to-tool context integration, see [Model Context Protocol](/protocols/mcp/); for agent payment authorization built on A2A, see [Agent Payments Protocol (AP2)](/protocols/ap2/). [1]*\n\n> **In brief:** A2A is a peer-to-peer interoperability standard that lets independent AI agents built on different frameworks or vendor stacks discover each other's skills and delegate multi-turn tasks without exposing their internal memory, prompts, or private tools. Instead of writing custom point-to-point glue code for every cross-vendor agent pairing, a client reads a remote agent's JSON Agent Card at `/.well-known/agent-card.json` and coordinates stateful work through standardized operations such as `SendMessage`, `SendStreamingMessage`, and `GetTask`. [1][2]\n\nThe **Agent2Agent Protocol** (**A2A**) is an open standard originated by Google on April 9, 2025 (`2025-04-09`) for capability discovery and task delegation between independent, opaque AI agent systems across different frameworks and vendor stacks without exposing internal memory, state, or tool implementations. [1][3] An A2A client fetches the server's JSON Agent Card at `https://{server_domain}/.well-known/agent-card.json` (permanently registered with IANA on `2025-08-01`, renamed from `/.well-known/agent.json` in `0.3.0`) and invokes PascalCase operations (`SendMessage`, `SendStreamingMessage`, `GetTask`, `CancelTask`) over one of three core `supportedInterfaces` bindings: JSON-RPC 2.0 over HTTP(S) (`JSONRPC`) with Server-Sent Events (`text/event-stream`), gRPC (`GRPC`), or RESTful `HTTP+JSON` (`application/a2a+json`) carrying the `A2A-Version` header. [4][5][6][7][8] Transferred to the Linux Foundation on June 23, 2025 (`2025-06-23`), A2A merged IBM's Agent Communication Protocol in August 2025, reached its first stable release (`1.0.0`) on March 12, 2026 (`2026-03-12`, followed by `1.0.1` on `2026-05-26`), and was approved as an Agentic AI Foundation (AAIF) Growth Stage project in August 2026 (`2026-08-17`). [7][9][10][11][12][13] Release candidate v1.1.0-rc adds an IANA media-type registration template for `application/a2a-agent-card+json`, for inclusion in the 1.1 release (commit dated 2026-10-27). Inclusion of the template does not mean IANA registration is complete. [14]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Coordinate](/category/coordinate/) (`coordinate`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | Google (launched 2025-04-09) [3] |\n| **Governed by** | Agentic AI Foundation (AAIF) under the Linux Foundation (Linux Foundation project launched 2025-06-23; AAIF Growth Stage approved by Technical Committee 2026-07-15 and Governing Board 2026-08-04, announced 2026-08-17); nine-seat Technical Steering Committee [9][11][13][15] |\n| **Track** | Foundation / Consortium Specification (`linux-foundation`); AAIF Growth Stage hosted project [2][11] |\n| **Status** | Active open standard; v1.0 is the first stable specification (March 2026); latest release `1.0.1` (changelog `2026-05-26`, GitHub release `2026-05-28`) [11][16] |\n| **Version** | `1.0.1` (changelog `2026-05-26`; GitHub release `2026-05-28`); `1.0.0` (`2026-03-12`); `0.3.0` (`2025-07-30`); release candidate v1.1.0-rc in progress (commit 2026-10-27). The specification page header still lists `1.0.0` as Latest Released Version (previous: `0.3.0`, `0.2.6`, `0.1.0`). [1][7][14][16] |\n| **Message format** | JSON-RPC 2.0 over HTTP(S) (`JSONRPC`) with Server-Sent Events (`text/event-stream`); gRPC (`GRPC`, Protocol Buffers over HTTP/2); RESTful `HTTP+JSON` (`application/a2a+json` preferred in `1.0.1`) [1][7] |\n| **Headers** | `A2A-Version`, `A2A-Extensions` [1] |\n| **IANA registration** | `agent-card.json` in IANA Well-Known URIs (`permanent`, `2025-08-01`, change controller `Linux Foundation`; spec section 14.3 template names `A2A Protocol Working Group`). Section 14.1–14.2 provide registration templates for `application/a2a+json`, `A2A-Version`, and `A2A-Extensions`. Release candidate v1.1.0-rc adds a registration template for `application/a2a-agent-card+json` (commit 2026-10-27); inclusion of the template does not mean IANA registration is complete. [1][5][14] |\n| **Specification** | [Agent2Agent (A2A) Protocol Specification](https://a2a-protocol.org/latest/specification/) [1] |\n| **Found at** | `GET https://{server_domain}/.well-known/agent-card.json` (renamed from `/.well-known/agent.json` in `0.3.0` on `2025-07-30`), registry/catalog lookup, or direct configuration [1][7] |\n| **Licence** | Apache License, Version 2.0 [1] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Discovery and the well-known Agent Card](#discovery-and-the-well-known-agent-card)\n3. [Task lifecycle, message parts, and transport bindings](#task-lifecycle-message-parts-and-transport-bindings)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nBefore A2A, handing off work between agents built on different frameworks required custom integration code for every new pairing. Those agents might use different languages or come from different vendors, with no common interaction model to bridge disparate agentic systems. [1][2] An A2A server publishes an Agent Card whose `supportedInterfaces` entries each declare a `protocolBinding` and `protocolVersion`. Clients call `SendMessage` or `SendStreamingMessage` to initiate or continue work, and use `GetTask` and `CancelTask` against a stateful Task across states such as `TASK_STATE_SUBMITTED` and `TASK_STATE_WORKING`. [1] For long-running or disconnected work, the server can stream incremental updates with `text/event-stream` or deliver asynchronous updates by HTTP POST to a client-provided webhook. [1] Agents stay opaque: they collaborate from declared capabilities and exchanged information, without sharing internal thoughts, plans, tool implementations, state, or memory. MCP, not A2A, standardizes how an agent connects to tools, APIs, and other resources. [1]\n\n### Discovery and task lifecycle\n\n```mermaid\nflowchart TD\n Client[\"A2A Client\"] -->|\"GET /.well-known/agent-card.json, registry, or direct config\"| Card[\"Agent Card\"]\n Card -->|\"First supported interface: JSONRPC, GRPC, or HTTP+JSON\"| Send[\"Send Message\"]\n Send --> Direct[\"Direct Message\"]\n Send --> Task[\"Task\"]\n Task --> Submitted[\"TASK_STATE_SUBMITTED\"]\n Submitted --> Working[\"TASK_STATE_WORKING\"]\n Working --> NeedInput[\"INPUT_REQUIRED or AUTH_REQUIRED\"]\n NeedInput --> Working\n Working --> Terminal[\"COMPLETED, FAILED, CANCELED, or REJECTED\"]\n Task -->|\"Poll, stream, or webhook\"| Client\n```\n\n*An A2A Client fetches `/.well-known/agent-card.json`, selects the first supported interface (`JSONRPC`, `GRPC`, or `HTTP+JSON`), and sends a message. The server returns either a direct message or a stateful task that moves through `TASK_STATE_SUBMITTED`, `TASK_STATE_WORKING`, `TASK_STATE_INPUT_REQUIRED` or `TASK_STATE_AUTH_REQUIRED`, and a terminal state (`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, or `TASK_STATE_REJECTED`), with updates by poll, stream, or webhook. [1]*\n\n### Sample Agent Card\n\n```json\n{\n \"name\": \"GeoSpatial Route Planner Agent\",\n \"description\": \"Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.\",\n \"supportedInterfaces\": [\n {\"url\": \"https://georoute-agent.example.com/a2a/v1\", \"protocolBinding\": \"JSONRPC\", \"protocolVersion\": \"1.0\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/grpc\", \"protocolBinding\": \"GRPC\", \"protocolVersion\": \"1.0\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/json\", \"protocolBinding\": \"HTTP+JSON\", \"protocolVersion\": \"1.0\"}\n ],\n \"provider\": {\n \"organization\": \"Example Geo Services Inc.\",\n \"url\": \"https://www.examplegeoservices.com\"\n },\n \"iconUrl\": \"https://georoute-agent.example.com/icon.png\",\n \"version\": \"1.2.0\",\n \"documentationUrl\": \"https://docs.examplegeoservices.com/georoute-agent/api\",\n \"capabilities\": {\n \"streaming\": true,\n \"pushNotifications\": true,\n \"extendedAgentCard\": true\n },\n \"securitySchemes\": {\n \"google\": {\n \"openIdConnectSecurityScheme\": {\n \"openIdConnectUrl\": \"https://accounts.google.com/.well-known/openid-configuration\"\n }\n }\n },\n \"securityRequirements\": [{ \"schemes\": { \"google\": { \"list\": [\"openid\", \"profile\", \"email\"] } } }],\n \"defaultInputModes\": [\"application/json\", \"text/plain\"],\n \"defaultOutputModes\": [\"application/json\", \"image/png\"],\n \"skills\": [\n {\n \"id\": \"route-optimizer-traffic\",\n \"name\": \"Traffic-Aware Route Optimizer\",\n \"description\": \"Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).\",\n \"tags\": [\"maps\", \"routing\", \"navigation\", \"directions\", \"traffic\"],\n \"examples\": [\n \"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.\",\n \"{\\\"origin\\\": {\\\"lat\\\": 37.422, \\\"lng\\\": -122.084}, \\\"destination\\\": {\\\"lat\\\": 37.7749, \\\"lng\\\": -122.4194}, \\\"preferences\\\": [\\\"avoid_ferries\\\"]}\"\n ],\n \"inputModes\": [\"application/json\", \"text/plain\"],\n \"outputModes\": [\n \"application/json\",\n \"application/vnd.geo+json\",\n \"text/html\"\n ]\n },\n {\n \"id\": \"custom-map-generator\",\n \"name\": \"Personalized Map Generator\",\n \"description\": \"Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.\",\n \"tags\": [\"maps\", \"customization\", \"visualization\", \"cartography\"],\n \"examples\": [\n \"Generate a map of my upcoming road trip with all planned stops highlighted.\",\n \"Show me a map visualizing all coffee shops within a 1-mile radius of my current location.\"\n ],\n \"inputModes\": [\"application/json\"],\n \"outputModes\": [\n \"image/png\",\n \"image/jpeg\",\n \"application/json\",\n \"text/html\"\n ]\n }\n ],\n \"signatures\": [\n {\n \"protected\": \"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0\",\n \"signature\": \"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ\"\n }\n ]\n}\n```\n\n*Sample Agent Card for the GeoSpatial Route Planner Agent (§8.5 illustrative specification example). It declares `supportedInterfaces` for `JSONRPC`, `GRPC`, and `HTTP+JSON`, plus `capabilities`, `securitySchemes`, `skills`, and optional `signatures` (Agent Cards MAY be signed using JWS over RFC 8785 canonical JSON, and clients SHOULD verify signatures when present). [1]*\n\n---\n\n## Discovery and the well-known Agent Card\n\nA2A standardizes self-description in an Agent Card, a JSON business card for the remote agent, and leaves discovery to the deployment. A client that knows the domain GETs `/.well-known/agent-card.json`, following RFC 8615. Curated registries and direct configuration are allowed, but the current A2A specification does not prescribe a standard API for curated registries. [1][17]\n\n- **Supported interfaces:** An Agent Card lists `name`, `description`, and `provider`, plus an ordered `supportedInterfaces` array. Each `AgentInterface` has `url`, `protocolBinding`, and `protocolVersion`; the first entry is preferred. v1.0 replaced `preferredTransport` and `additionalInterfaces` with `supportedInterfaces[]`, beside `streaming`, `pushNotifications`, `securitySchemes`, and `AgentSkill` entries. [1][8][17]\n- **No standard registry API:** A curated registry is an intermediary catalog. Servers publish Agent Cards to it, and clients query by skills, tags, provider, or capabilities. The specification does not define that registry API. Direct configuration, including hardcoded URLs or proprietary APIs, also lacks a standard discovery method. [17]\n- **Well-known path rename:** Issue #66 initially requested `.well-known/agent.json` (citing existing production deployments) with the Linux Foundation as change controller, then adopted `agent-card.json` after reviewers noted `agent.json` was too generic. PR #841, merged 2025-07-29, changed `/.well-known/agent.json` to `/.well-known/agent-card.json`. Changelog `0.3.0` (2025-07-30) records that break. The `v0.3.0` specification publishes `https://{server_domain}/.well-known/agent-card.json`, and IANA registered `agent-card.json` as permanent on 2025-08-01. [4][5][6][7][18]\n- **Extended Agent Cards:** `securitySchemes` names the schemes used to authenticate to the agent. If `AgentCard.capabilities.extendedAgentCard` is true, `GetExtendedAgentCard` (which MUST require authentication) returns a more detailed card after authentication, and clients should replace the cached public card for that session. Agent Cards MAY also be signed using JSON Web Signatures (`JWS`, RFC 7515) over RFC 8785 `JCS` canonical JSON, and clients SHOULD verify `signatures` when present. Authenticated extended cards are recommended for sensitive skills, using out-of-band dynamic credentials rather than static secrets in the card. [1][17]\n\n---\n\n## Task lifecycle, message parts, and transport bindings\n\nA Task is the stateful unit of work. Clients open it with `SendMessage` or `SendStreamingMessage`, read it with `GetTask`, and may cancel it with `CancelTask`. Content rides in typed `Part` containers, and outputs come back as `Artifact` objects. Live updates use Server-Sent Events or a webhook. The same operations bind to JSON-RPC 2.0, gRPC, and `HTTP+JSON`. [1]\n\n- **Lifecycle operations:** `SendMessage` returns a Task or a direct Message, and processing may continue afterward. States run through `TASK_STATE_SUBMITTED`, `TASK_STATE_WORKING`, interrupted `TASK_STATE_INPUT_REQUIRED` and `TASK_STATE_AUTH_REQUIRED`, and terminal `TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, and `TASK_STATE_REJECTED`. `SendStreamingMessage` emits `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` objects. `GetTask` reads status, artifacts, and optional history, while `ListTasks` lists tasks visible within the caller's authorization scope. `CancelTask` requests cancellation, which is not guaranteed, `SubscribeToTask` resubscribes to an active task stream, and `CreateTaskPushNotificationConfig`, `GetTaskPushNotificationConfig`, `ListTaskPushNotificationConfigs`, and `DeleteTaskPushNotificationConfig` manage webhook push configurations. [1]\n- **Message parts:** A `Part` is the smallest unit of content in a Message or Artifact: a container for text, a file such as an image or video, or a structured JSON blob. An `Artifact` is task output, a document, image, or structured data, composed of Parts. [1]\n- **Streaming and webhooks:** Streaming sends real-time updates for status changes and artifact chunks. The JSON-RPC binding uses Server-Sent Events (`text/event-stream`), delivers events in generation order, and may broadcast one task on multiple concurrent streams. Push notifications POST asynchronous updates to a client webhook for disconnected clients. `GetTask` reads the final state afterward. Under §13 Security Considerations, implementations MUST enforce authorization checks on every operation and scope `ListTasks`, `GetTask`, and task mutations to the caller's authorized access boundaries even when `contextId` or filter parameters are omitted (§13.1); webhook-calling agents MUST include `PushNotificationConfig.authentication` credentials and SHOULD validate webhook URLs against SSRF by rejecting private IP ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), localhost, and link-local addresses, while webhook-receiving clients MUST validate webhook authenticity and SHOULD process notifications idempotently (§13.2). An unrefereed arXiv preprint, A2ABreak (arXiv:2609.10871, last revised 24 Oct 2026, v3), models the `1.0.0` protocol as 37 states and 76 transitions and claims 11 new vulnerabilities, each exploitable by a specification-compliant adversary without requiring any implementation flaw. Those findings are preprint claims, not an established specification defect. [1][19][20]\n- **Three protocol bindings:** `JSONRPC` is JSON-RPC 2.0 over HTTP(S), with PascalCase methods such as `SendMessage` and `GetTask` and streaming on `text/event-stream`. `GRPC` uses Protocol Buffers over HTTP/2 and the `A2AService` service. `HTTP+JSON` is REST with JSON payloads and prefers `application/a2a+json`. Clients select the first supported `supportedInterfaces` entry, including its `protocolBinding` and `protocolVersion`. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **JSON-RPC 2.0 Specification** | `JSON-RPC 2.0` | Profiles classic standard | Profiles JSON-RPC 2.0 over HTTP(S) (`JSONRPC` binding) for task method calls (`SendMessage`, `GetTask`, `CancelTask`) paired with Server-Sent Events (`text/event-stream`) for streaming updates. [1] |\n| **Well-Known URIs (RFC 8615)** | `RFC 8615` | Profiles classic standard | Registers the permanent IANA well-known URI suffix `agent-card.json` (2025-08-01), fetched via HTTP `GET` at `https://{server_domain}/.well-known/agent-card.json` for Agent Card discovery. [1][5] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | MCP provides the vertical integration layer connecting an agent to external tools, APIs, and resources, whereas A2A provides the horizontal peer-to-peer protocol for capability discovery and task delegation between opaque agents. [1][2] |\n| **[Agent Communication Protocol](/protocols/agent-communication-protocol/)** | Supersedes | IBM's Agent Communication Protocol (ACP) for the BeeAI platform officially merged into A2A under the Linux Foundation in August 2025, winding down standalone ACP development in favor of A2A. [11][12] |\n| **[Agent Connect Protocol](/protocols/agent-connect-protocol/)** | Complements | Within Cisco's AGNTCY stack (which deprecated standalone Agent Connect Protocol in favor of A2A), SLIM (Secure Low-Latency Interactive Messaging) carries A2A messages via the experimental SLIMRPC binding, using Messaging Layer Security (MLS, RFC 9420) by default for end-to-end session encryption. [13][21][22][23] |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Complements | AP2 extends A2A into agentic commerce by adding payment authorization while shopping and merchant agents communicate over A2A for discovery, pricing, and fulfillment. [11] |\n| **IETF agentproto WG** | Complements | The IETF agentproto Working Group (Agent Communication Protocols) is Active in the Applications and Real-Time Area (art) under approved charter `charter-ietf-agentproto-01` (chairs Leslie Daigle and Orie Steele), which scopes the WG to dialog-context correlation and lifecycle management that complements rather than replaces application-layer agent communication protocols (explicitly naming MCP and A2A as capable of carrying dialog context) and defines no new transport protocol. Individual `draft-manyfolks-agentproto-arch-00` (30 October 2026) proposes an Agent Communications Protocol (ACP) architecture for communication among user agent clients, AI agents, and tools. [24][25] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (20 probed or cited examples across 4 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Public A2A agents & managed server runtimes\n\n| Actor | Role | Status | Agent Card endpoint, transport & role | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Telnyx (Telnyx Assistant)** | Public A2A agent | Live (HTTP 200) · checked 2026-11-03 | Live Agent Card binding `JSONRPC` (`1.0` and `0.3`) at `https://api.telnyx.com/v2/support_agent/public/a2a` with `tasks/get` polling. | [Telnyx Assistant Agent Card](https://telnyx.com/.well-known/agent-card.json) [26] |\n| **Redocly** | Public A2A agent | Live (HTTP 200) · checked 2026-10-30 | Live Agent Card advertising `protocolVersion` `0.3.0` (`preferredTransport` `HTTP+JSON`) at `https://redocly.com/a2a` and MCP extension `https://redocly.com/mcp`. | [Redocly Agent Card](https://redocly.com/.well-known/agent-card.json) [27] |\n| **Pangram** | Public A2A agent | Live (HTTP 200) · checked 2026-10-30 | Live Agent Card binding `JSONRPC` (`protocolVersion` `1.0`) at `https://www.pangram.com/a2a` for `detect-ai-text` and `detect-ai-image` with `x-api-key`. | [Pangram Agent Card](https://www.pangram.com/.well-known/agent-card.json) [28] |\n| **Ticket Fairy** | Public A2A agent | Live (HTTP 200) · checked 2026-10-30 | Live Agent Card binding `JSONRPC` (`protocolVersion` `1.0`) at `https://www.ticketfairy.com/agentic/a2a` with `search_events`, `ticket-checkout`, A2UI `v0.8`, and UCP. | [Ticket Fairy Agent Card](https://www.ticketfairy.com/.well-known/agent-card.json) [29] |\n| **Warp (Warp Freight)** | Public A2A agent | Live (HTTP 200) · checked 2026-10-30 | Live Agent Card binding `JSONRPC` (`protocolVersion` `1.0`) at `https://www.wearewarp.com/api/a2a/jsonrpc` with `bearer` `warpApiKey` and freight skills. | [Warp Freight Agent Card](https://www.wearewarp.com/.well-known/agent-card.json) [30] |\n| **AWS (Bedrock AgentCore Runtime)** | Managed agent runtime | Supported (release announcement) · as of 2025-11-11 | November 2025 blog announces container runtime (`port 9000`) proxying `JSON-RPC 2.0` and authenticated `/.well-known/agent-card.json`. | [AWS, AgentCore A2A support (11 NOV 2025)](https://aws.amazon.com/blogs/machine-learning/introducing-agent-to-agent-protocol-support-in-amazon-bedrock-agentcore-runtime/) [31] |\n| **SAP (Agent Gateway)** | Enterprise agent gateway | Supported (release announcement) · as of 2026-10-27 | October 2026 announcement of inbound A2A gateway combining `AgentCard` URLs with Agentic Resource Discovery (`ARD`). | [SAP, Agent Gateway A2A (2026-10-27)](https://architecture.learning.sap.com/news/2026/10/27/a2a-agent-gateway-interoperability) [32] |\n\n### Client orchestrators & enterprise host platforms\n\n| Actor | Role | Status | Outbound client role & auth | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Google (Gemini Enterprise)** | Client orchestrator | Supported (release announcement) · as of 2026-08-17 | August 2026 release note announces general availability for registering external `A2A` and `A2UI` (`v0.9`, `v0.8`) agents. | [Google Cloud, Gemini Enterprise release notes](https://docs.cloud.google.com/gemini/enterprise/docs/release-notes) [33] |\n| **Microsoft (Foundry Agent Service)** | Client orchestrator & target | Partial · as of 2026-10-28 | GA `a2a` tool for `v1.0` `JSON-RPC` (text-only, no streaming) and preview `a2a_preview` tool for `v0.3`. | [Microsoft Learn, Foundry A2A tool](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent) [34] |\n| **Microsoft (Copilot Studio)** | Client orchestrator | Partial · as of 2026-08-26 | Delegates tasks via `message/send` (`contextId`) and auto-reads metadata from the legacy pre-v0.3 `/.well-known/agent.json` card path. | [Microsoft Learn, Copilot Studio A2A](https://learn.microsoft.com/en-us/microsoft-copilot-studio/add-agent-agent-to-agent) [35] |\n| **SAP (Joule)** | Outbound A2A client | Partial · as of 2026-10-26 | Outbound `agent-request` client with webhook push notifications; bidirectional third-party `Agent Gateway` communication not yet GA. | [SAP Architecture Center, Joule outbound A2A](https://architecture.learning.sap.com/docs/ref-arch/ae6821) [36] |\n| **A2A CLI** | Official CLI client | Live (HTTP 200) · checked 2026-11-11 | Live OAuth Client ID Metadata Document (HTTP 200) names client A2A CLI (`client_id` `https://a2a-protocol.org/oauth/a2a-cli.json`, `client_uri` `https://github.com/a2aproject/a2a-cli`) with grants `authorization_code`, `refresh_token`, and `urn:ietf:params:oauth:grant-type:device_code`, and `token_endpoint_auth_method` `none`. | [A2A CLI OAuth client metadata](https://a2a-protocol.org/oauth/a2a-cli.json) [37] |\n\n### Official SDKs & agent frameworks\n\n| Actor | Role | Status | Language / framework surface | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Official A2A SDKs** | Official client & server SDKs | Supported · as of 2026-10-28 | Proto-generated official client and server SDKs across six languages: `Python`, `Go`, `Java`, `JS`, `.NET`, and `Rust`. | [A2A specification](https://a2a-protocol.org/latest/specification/) [1] · [Microsoft Learn, official A2A SDK](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent) [34] · [Linux Foundation one-year A2A release](https://www.linuxfoundation.org/press/a2a-protocol-surpasses-150-organizations-lands-in-major-cloud-platforms-and-sees-enterprise-production-use-in-first-year) [38] |\n| **Google ADK** | Agent framework | Listed · as of 2026-08-04 | AAIF proposal lists native `Google ADK` client and server support across local runtimes and `Agent Platform Runtime`. | [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] · [AAIF, A2A joins AAIF](https://aaif.io/blog/a2a-joins-aaif) [11] |\n| **IBM BeeAI** | Agent framework | Listed · as of 2026-08-17 | Merged deprecated `ACP` into `A2A` (August 2025); `BeeAI Framework` ships native client and server adapters. | [BeeAI ACP README](https://raw.githubusercontent.com/i-am-bee/acp/main/README.md) [12] · [AAIF, A2A joins AAIF](https://aaif.io/blog/a2a-joins-aaif) [11] · [A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] |\n| **LangGraph** | Agent framework | Listed · as of 2026-08-27 | AAIF proposal lists hosted `/a2a/{assistant_id}` endpoints with auto-generated Agent Cards, `SSE` streaming, and `LangSmith` tracing. | [A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] |\n| **CrewAI** | Agent framework | Listed · as of 2026-08-27 | AAIF proposal lists `CrewAI AMP` production hosting across `REST`/`JSON-RPC`/`gRPC` transports with `OIDC`, `OAuth2`, and `mTLS`. | [A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] |\n| **Pydantic AI** | Agent framework | Listed · as of 2026-08-27 | AAIF proposal lists native `FastA2A` library integration exposing `Pydantic AI` agents as `ASGI` A2A applications. | [A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] |\n| **AG2** | Agent framework | Listed · as of 2026-08-27 | A2A blog and AAIF proposal list `AG2` (formerly `AutoGen`) agent swarm connections tagged with `a2a`. | [A2A, joining the Agentic AI Foundation](https://a2a-protocol.org/latest/blog/2026/08/27/a-new-chapter-for-a2a-joining-the-agentic-ai-foundation/) [2] · [AAIF project proposal #37](https://github.com/aaif/project-proposals/issues/37) [13] |\n\n### Public A2A registries & directories\n\n| Actor | Role | Status | Verification & protocol surface | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **AgentPeering** | Independent public A2A registry | Supported · checked 2026-11-06 | Independent vendor-neutral A2A registry verifying domain ownership, monitoring uptime, and speaking `v0.3` `message/send` (plus `v0.2` `tasks/send`). | [AgentPeering FAQ](https://agentpeering.com/docs/faq) [39] |\n\n### Ecosystem censuses\n\n- **Google Developers Blog, Announcing A2A (2025-04-09)** (*as of 2025-04-09*): More than 50 technology and enterprise service partners (including Atlassian, Box, Cohere, Intuit, LangChain, MongoDB, PayPal, Salesforce, SAP, ServiceNow, UKG, Workday, Accenture, BCG, Capgemini, Cognizant, Deloitte, HCLTech, Infosys, KPMG, McKinsey, PwC, TCS, and Wipro) announced at A2A's initial launch on April 9, 2025. [3]\n- **Linux Foundation, A2A project launch (2025-06-23)** (*as of 2025-06-23*): More than 100 technology companies reported as supporting the Agent2Agent protocol when Google donated the specification, SDKs, and developer tooling to the Linux Foundation on June 23, 2025. [9]\n- **AAIF, A2A joins AAIF (2026-08-17)** (*as of 2026-08-17*): Over 150 partner organizations across cloud providers, enterprise SaaS platforms, and agent frameworks reported as backing A2A when it joined the Agentic AI Foundation (AAIF) as a Growth Stage project in August 2026. [2][11]\n- **Linux Foundation one-year A2A press release (9 April 2026)** (*as of 2026-04-09*): On April 9, 2026 the Linux Foundation reported that supporting organizations had grown from more than 50 to over 150, the core repository had surpassed 22,000 GitHub stars, and official SDKs had expanded from Python to five production-ready languages (Python, JavaScript, Java, Go, and .NET), later joined by Rust on the specification site. [1][38]\n\n---\n\n## See also\n\n- **Depended on by:** [Ad Context Protocol (AdCP)](/protocols/adcp/)\n- **Peer alternatives:** [Agent Interaction & Transaction Protocol (AITP)](/protocols/aitp/), [Agent Network Protocol](/protocols/anp/), [Agent Protocol](/protocols/agent-protocol-aief/), [Agora Protocol](/protocols/agora-protocol/), [Coral Protocol (CoralOS)](/protocols/coral-protocol/), [Eclipse LMOS (Language Model Operating System)](/protocols/lmos/), [ERC-8001: Agent Coordination Framework](/protocols/erc-8001/), [GB/Z 185 Artificial intelligence — Agent interconnection](/protocols/gbz-185-agent-interconnection/), [MCP Server Cards](/protocols/mcp-server-cards/), [Natural Language Interaction Protocol (NLIP)](/protocols/nlip/)\n- **Complements:** [A2UI (Agent to UI) Protocol](/protocols/a2ui/), [Agent Client Protocol](/protocols/agent-client-protocol/), [Agent-User Interaction Protocol (AG-UI)](/protocols/ag-ui/), [ERC-8004: Trustless Agents](/protocols/erc-8004/), [Open Responses](/protocols/open-responses/), [Universal Commerce Protocol (UCP)](/protocols/ucp/), [Agent Directory Service](/protocols/ads/), [Agent Identity Protocol (AIP): Verifiable Delegation for AI Agent Systems](/protocols/aip-delegation-chain/), [Agent Name Service v2 (ANS)](/protocols/ans/), [Agent Registration and Discovery Protocol](/protocols/ardp/), and [16 more in the protocol directory](/protocols/)\n- **Category:** [Coordinate protocols](/category/coordinate/)\n\n---\n\n## References\n\n1. A2A Protocol (The Linux Foundation), *Agent2Agent (A2A) Protocol Specification* (latest released version 1.0.0; checked 2026-10-30) — \n2. A2A Protocol, *A New Chapter for A2A: Joining the Agentic AI Foundation* (2026-08-27) — \n3. Rao Surapaneni, Miku Jha, Michael Vakoc, and Todd Segal (Google), *Announcing the Agent2Agent Protocol (A2A)* (2025-04-09) — \n4. A2A Protocol, *Agent2Agent (A2A) Protocol Official Specification v0.3.0* (v0.3.0) — \n5. IANA, *Well-Known URIs* (agent-card.json registered 2025-08-01) — \n6. holtskinner (a2aproject/A2A), *Change Well-Known URI for Agent Card hosting from agent.json to agent-card.json (PR #841)* (merged 2025-07-29) — \n7. a2aproject, *A2A CHANGELOG.md* (1.0.1 (2026-05-26); 1.0.0 (2026-03-12); 0.3.0 (2025-07-30)) — \n8. A2A Protocol (The Linux Foundation), *What's New in v1.0* (checked 2026-10-30) — \n9. The Linux Foundation, *Linux Foundation Launches the Agent2Agent Protocol Project to Enable Secure, Intelligent Communication Between AI Agents* (2025-06-23) — \n10. Rao Surapaneni, Todd Segal, and Michael Vakoc (Google Cloud), *Google Cloud donates A2A to Linux Foundation* (2025-06-23) — \n11. Agentic AI Foundation, *A2A joins AAIF's open agentic stack* (published 2026-08-17; modified 2026-09-24) — \n12. IBM BeeAI (i-am-bee/acp), *Agent Communication Protocol (ACP) README* (checked 2026-10-31) — \n13. Agentic AI Foundation, *[Project Proposal] Agent2Agent Protocol (A2A) · Issue #37* (Technical Committee 2026-07-15; Governing Board 2026-08-04) — \n14. a2aproject, *Add Agent Card media type registration template (commit 40cffc57)* (2026-10-27) — \n15. a2aproject, *Agent2Agent (A2A) Governance (GOVERNANCE.md)* (checked 2026-10-30) — \n16. a2aproject, *Release v1.0.1* (2026-05-28 (changelog 2026-05-26)) — \n17. A2A Protocol, *Agent Discovery* (checked 2026-11-06) — \n18. protocol-registries/well-known-uris, *Well-Known URI registration for agent.json (issue 66)* (2025-06-11) — \n19. Alireza Lotfi, Mirza Masfiqur Rahman, Imtiaz Karim, and Elisa Bertino, *A2ABreak: Systematic Security Analysis of the A2A Protocol (arXiv:2609.10871)* (submitted 9 Sep 2026; last revised 24 Oct 2026 (v3); fetched 2026-11-11) — \n20. Alireza Lotfi, Mirza Masfiqur Rahman, Imtiaz Karim, and Elisa Bertino, *A2ABreak: Systematic Security Analysis of the A2A Protocol (v3 HTML)* (24 October 2026 (v3)) — \n21. AGNTCY SLIM Documentation, *A2A over SLIM* (fetched 2026-10-30) — \n22. a2aproject, *a2a-slimrpc: SLIMRPC transport binding for A2A* (fetched 2026-10-30) — \n23. IETF Datatracker, *Secure Low-Latency Interactive Messaging (SLIM) (draft-mpsb-agntcy-slim)* (fetched 2026-10-30) — \n24. IETF, *Agent Communication Protocols (agentproto) Working Group* (fetched 2026-11-11) — \n25. J. Rosenberg, Z. Sarker, T. Reddy, K. Yao, D. Liu, and S. Krishnan, *Architecture for AI Agent Communications on the Internet (draft-manyfolks-agentproto-arch-00)* (30 October 2026; fetched 2026-11-11) — \n26. Telnyx, *Telnyx Assistant Agent Card* (2026-11-03) — \n27. Redocly, *Redocly Agent Card* (2026-10-30) — \n28. Pangram, *Pangram Agent Card* (2026-10-30) — \n29. Ticket Fairy, *Ticket Fairy Agent Card* (2026-10-30) — \n30. Warp, *Warp Freight Agent Card* (2026-10-30) — \n31. Madhur Prashant et al. (AWS Machine Learning Blog), *Introducing agent-to-agent protocol support in Amazon Bedrock AgentCore Runtime* (2025-11-11) — \n32. PVN PavanKumar (SAP Architecture Center), *Third-party agents can now interoperate with SAP Agents via the Agent Gateway* (2026-10-27) — \n33. Google Cloud, *Gemini Enterprise release notes* (A2A GA entry 2026-08-17) — \n34. Microsoft, *Connect to an A2A agent endpoint from Foundry Agent Service* (last updated 2026-10-28) — \n35. Microsoft, *Connect to an agent over the Agent2Agent (A2A) protocol* (last updated 2026-08-26) — \n36. SAP Architecture Center, *Integrating AI Agents with Joule (Outbound A2A)* (last updated 2026-10-26) — \n37. a2aproject, *A2A CLI OAuth Client ID Metadata Document* (fetched 2026-11-11) — \n38. The Linux Foundation, *A2A Protocol Surpasses 150 Organizations* (2026-04-09) — \n39. AgentPeering, *Frequently Asked Questions* (checked 2026-11-06) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "ACP", "adoption": { "level": "observed", "by": "Google Gemini CLI, Block goose, GitHub Copilot CLI, AWS Kiro, Zed, JetBrains IDEs, CodeCompanion.nvim, Emacs agent-shell, and 3 other verified implementations", "probe_run": null }, "aliases": [], "analog": "Language Server Protocol", "collisions": [ "Agent Communication Protocol (IBM)", "Agentic Commerce Protocol (OpenAI/Stripe)", "Agent Connect Protocol (AGNTCY)" ], "discovery": { "mechanism": "Local agent launched by the client as a subprocess over stdin and stdout; curated ACP Registry index at https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json", "path": "No fixed URL on the agent; registry index at https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json (plus JetBrains-specific indices)" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://zed.dev/blog/bring-your-own-agent-to-zed", "claim": "Nathan Sobo (Zed Industries), *Bring Your Own Agent to Zed — Featuring Gemini CLI*, published 2025-08-27", "date": null, "quote": "You can now interact with third-party agents directly within Zed. To make this possible, we created the Agent Client Protocol (ACP) / Just as the Language Server Protocol unbundled language intelligence from monolithic IDEs, our goal with the Agent Client Protocol is to enable you to switch between multiple agents without switching your editor. / Nathan Sobo August 27th, 2025 / we created the Agent Client Protocol (ACP), and we've partnered with Google to integrate Gemini CLI as the initial reference implementation. / we've partnered with Google to integrate Gemini CLI as the initial reference implementation.", "ref": 1 }, { "label": "[2]", "url": "https://blog.jetbrains.com/ai/2025/10/jetbrains-zed-open-interoperability-for-ai-coding-agents-in-your-ide/", "claim": "Denis Shiryaev (JetBrains), *JetBrains × Zed: Open Interoperability for AI Coding Agents in Your IDE*, published 2025-10-06", "date": null, "quote": "an open protocol that lets AI coding agents work inside editors / an open protocol that lets AI coding agents work inside editors, including JetBrains IDEs, if both are ACP-compatible. / we're collaborating with Zed on the Agent Client Protocol (ACP) – an open protocol that lets AI coding agents work inside editors, including JetBrains IDEs, if both are ACP-compatible.", "ref": 2 }, { "label": "[3]", "url": "https://agentclientprotocol.com/get-started/introduction", "claim": "Agent Client Protocol, *Introduction*, checked 2026-10-30", "date": null, "quote": "The Agent Client Protocol (ACP) standardizes communication between code editors/IDEs and coding agents and is suitable for both local and remote scenarios. / Full support for remote agents is a work in progress. / AI coding agents and editors are tightly coupled but interoperability isn't the default. / Each editor must build custom integrations for every agent they want to support, and agents must implement editor-specific APIs to reach users. / Integration overhead: Every new agent-editor combination requires custom work / Limited compatibility: Agents work with only a subset of available editors / Developer lock-in: Choosing an agent often means accepting their available interfaces / The protocol re-uses the JSON representations used in MCP where possible, but includes custom types for useful agentic coding UX elements, like displaying diffs. / The Agent Client Protocol (ACP) standardizes communication between code editors/IDEs and coding agents / includes custom types for useful agentic coding UX elements, like displaying diffs.", "ref": 3 }, { "label": "[4]", "url": "https://agentclientprotocol.com/protocol/v1/overview", "claim": "Agent Client Protocol, *Overview (protocol v1)*, checked 2026-10-30", "date": null, "quote": "Client → Agent: session/prompt to send user message / initialize Negotiate versions and exchange capabilities. / Client → Agent: initialize to establish connection / Client → Agent: session/new to create a new session / Client → Agent: session/load to resume an existing session if supported / Agent → Client: session/update notifications for progress updates and user-facing notices / Agent → Client: File operations or permission requests as needed / the Agent sends the session/prompt response with a stop reason / The protocol follows the JSON-RPC 2.0 specification with two types of messages / Methods are request-response pairs that expect a result or error. Notifications are one-way messages that don't expect a response. / The protocol follows the JSON-RPC 2.0 specification with two types of messages: Methods are request-response pairs that expect a result or error. Notifications are one-way messages that don’t expect a response. / Client → Agent: `initialize` to establish connection / Client → Agent: `session/new` to create a new session / Client → Agent: `session/load` to resume an existing session if supported / Client → Agent: `session/prompt` to send user message / Agent → Client: `session/update` notifications for progress updates and user-facing notices / Agents are programs that use generative AI to autonomously modify code. They typically run as subprocesses of the Client. / Clients provide the interface between users and agents. They are typically code editors (IDEs, text editors) but can also be other UIs for interacting with agents. / The Agent Client Protocol allows Agents and Clients to communicate by exposing methods that each side can call and sending notifications to inform each other of events. / The protocol follows the JSON-RPC 2.0 specification with two types of messages: Methods are request-response pairs that expect a result or error. / Notifications are one-way messages that don't expect a response. / Client: completes an advertised authentication flow if required. For example, authenticate for an Agent-handled method or launch and reconnect for a terminal method / authenticate Authenticate with the Agent (if required). / logout End the current authenticated state (requires agentCapabilities.auth.logout capability). / terminal/create Create a new terminal (requires terminal capability). / Client → Agent: session/cancel to interrupt processing if needed / session/request_permission Request user authorization for tool calls. / fs/read_text_file Read file contents (requires fs.readTextFile capability). / fs/write_text_file Write file contents (requires fs.writeTextFile capability). / terminal/output Get terminal output and exit status (requires terminal capability). / terminal/release Release a terminal (requires terminal capability). / terminal/wait_for_exit Wait for terminal command to exit (requires terminal capability). / terminal/kill Kill terminal command without releasing (requires terminal capability). / fs/read_text_file Read file contents / terminal/create Create a new terminal / session/update Send session updates to inform the Client of changes", "ref": 4 }, { "label": "[5]", "url": "https://agentclientprotocol.com/community/governance", "claim": "Agent Client Protocol, *Governance*, checked 2026-10-30", "date": null, "quote": "ACP is jointly governed by Zed and JetBrains, who collaborate to ensure the protocol serves the broader ecosystem. We aim to operate transparently and make decisions in the best interests of ACP and its community, while working toward transitioning to an independent foundation. / The following is an interim governance model to provide clearer roles and responsibilities between the various parties collaborating on ACP. / ACP has two lead maintainers: Ben Brandt (Zed Industries) and Sergey Ignatov (JetBrains). / All repositories in the ACP organization should be licensed under the Apache 2.0 License. This project does not require a Contributor License Agreement (CLA).", "ref": 5 }, { "label": "[6]", "url": "https://agentclientprotocol.com/protocol/v1/transports", "claim": "Agent Client Protocol, *Transports (protocol v1)*, checked 2026-10-30", "date": null, "quote": "The client launches the agent as a subprocess. The agent reads JSON-RPC messages from its standard input (stdin) and sends messages to its standard output (stdout). / Messages are delimited by newlines (\\n), and MUST NOT contain embedded newlines. / JSON-RPC messages MUST be UTF-8 encoded. / stdio, communication over standard in and standard out. / The protocol currently defines one transport mechanism for agent-client communication: stdio, communication over standard in and standard out. A remote transport based on Streamable HTTP is being specified in the transport RFD. Agents and clients SHOULD support stdio whenever possible. / The protocol currently defines one transport mechanism for agent-client communication: stdio, communication over standard in and standard out. / A remote transport based on Streamable HTTP is being specified in the transport RFD. / ACP uses JSON-RPC to encode messages. JSON-RPC messages MUST be UTF-8 encoded. / The client launches the agent as a subprocess. / The agent reads JSON-RPC messages from its standard input (stdin) and sends messages to its standard output (stdout). / Agents and clients SHOULD support stdio whenever possible.", "ref": 6 }, { "label": "[7]", "url": "https://github.com/agentclientprotocol/agent-client-protocol", "claim": "agentclientprotocol, *Agent Client Protocol (ACP)*, repository created 2025-06-23; checked 2026-10-30", "date": null, "quote": "The current stable ACP protocol version is 1 / ACP wire compatibility is determined separately by the protocol version exchanged during initialize via protocolVersion. / \"created_at\": \"2025-06-23T17:39:36Z\" / The current stable ACP protocol version is … 1 / ACP wire compatibility is determined separately by the protocol version exchanged during … initialize … via … protocolVersion / \"name\": \"Apache License 2.0\", \"spdx_id\": \"Apache-2.0\" / to determine the ACP wire protocol shape and breaking-compatibility level. / Within a protocol version, use the exchanged capabilities to decide which optional ACP messages and features are supported. / Kotlin : acp-kotlin / Java : java-sdk / Python : python-sdk / Rust : agent-client-protocol / TypeScript : @agentclientprotocol/sdk", "ref": 7 }, { "label": "[8]", "url": "https://agentclientprotocol.com/protocol/v1/session-setup", "claim": "Agent Client Protocol, *Session Setup (protocol v1)*, checked 2026-10-30", "date": null, "quote": "\"protocolVersion\": 1, \"agentCapabilities\": { \"loadSession\": true } / When creating a session, Clients MAY include connection details for MCP servers that the Agent should connect to. / Clients create a new session by calling the session/new method with / \"sessionId\": \"sess_abc123def456\" / If loadSession is false or not present, the Agent does not support loading sessions and Clients MUST NOT attempt to call session/load. / If the Agent requires authentication, session/new may fail with an auth_required error until the Client completes the authentication flow. / The working directory for the session / A list of MCP servers the Agent should connect to / \"method\": \"session/new\", \"params\": { \"cwd\": \"/home/user/project\", \"mcpServers\" / The Agent MUST respond with a unique Session ID that identifies this conversation / To load an existing session, Clients MUST call the session/load method with / The Agent MUST replay the entire conversation to the Client in the form of session/update notifications", "ref": 8 }, { "label": "[9]", "url": "https://agentclientprotocol.com/updates", "claim": "Agent Client Protocol, *Updates*, checked 2026-10-30", "date": null, "quote": "June 25, 2026 SDKs Rust and TypeScript SDKs Reach 1.0 / both the Rust and TypeScript ACP SDKs reached version 1.0.0", "ref": 9 }, { "label": "[10]", "url": "https://agentclientprotocol.com/announcements/acp-v2-draft", "claim": "Agent Client Protocol, *ACP v2 is available in Draft*, published 2026-07-20", "date": null, "quote": "Published: July 20, 2026 Today is a day the ACP team has been working towards for months, and we are excited to share the first Draft of version 2 of the Agent Client Protocol.", "ref": 10 }, { "label": "[11]", "url": "https://github.com/agentclientprotocol/agent-client-protocol/releases", "claim": "Agent Client Protocol, *agentclientprotocol/agent-client-protocol releases*, checked 2026-11-09", "date": null, "quote": "\"tag_name\":\"v1.15.1\",\"target_commitish\":\"main\",\"name\":\"Rust Crate v1.15.1\",\"draft\":false,\"immutable\":false,\"prerelease\":false,\"created_at\":\"2026-11-02T10:51:44Z\",\"updated_at\":\"2026-11-02T10:51:45Z\" / \"tag_name\":\"schema-v1.29.1\",\"target_commitish\":\"main\",\"name\":\"Schema v1.29.1\",\"draft\":false,\"immutable\":false,\"prerelease\":false,\"created_at\":\"2026-11-02T10:51:46Z\" / \"tag_name\":\"schema-v2.0.0-alpha.13\",\"target_commitish\":\"main\",\"name\":\"Schema v2.0.0-alpha.13\",\"draft\":false,\"immutable\":false,\"prerelease\":true,\"created_at\":\"2026-11-02T10:51:48Z\" / \"tag_name\": \"v1.13.0\", \"target_commitish\": \"main\", \"name\": \"Rust Crate v1.13.0\", \"draft\": false, \"immutable\": false, \"prerelease\": false, \"created_at\": \"2026-10-27T21:56:48Z\", \"updated_at\": \"2026-10-27T21:56:49Z\", \"published_at\": \"2026-10-27T21:56:49Z\" / \"tag_name\": \"schema-v1.27.0\", \"target_commitish\": \"main\", \"name\": \"Schema v1.27.0\", \"draft\": false, \"immutable\": false, \"prerelease\": false, \"created_at\": \"2026-10-27T21:56:50Z\", \"updated_at\": \"2026-10-27T21:56:58Z\", \"published_at\": \"2026-10-27T21:56:51Z\" / \"tag_name\": \"schema-v2.0.0-alpha.10\", \"target_commitish\": \"main\", \"name\": \"Schema v2.0.0-alpha.10\", \"draft\": false, \"immutable\": false, \"prerelease\": true, \"created_at\": \"2026-10-27T21:56:51Z\", \"updated_at\": \"2026-10-27T21:57:01Z\", \"published_at\": \"2026-10-27T21:56:53Z\" / \"tag_name\": \"v1.0.0\" / \"tag_name\": \"v1.13.0\" / \"tag_name\": \"schema-v1.27.0\"", "ref": 11 }, { "label": "[12]", "url": "https://github.com/agentclientprotocol/agent-client-protocol/releases/tag/schema-v1.31.0", "claim": "agentclientprotocol (acp-release-bot), *Schema v1.31.0*, published 2026-11-10", "date": null, "quote": "schema-v1.31.0 … released this 10 Nov 20:46 … (unstable) add session/options and initial config option values ( #2792 )", "ref": 12 }, { "label": "[13]", "url": "https://agentclientprotocol.com/rfds/about", "claim": "Agent Client Protocol, *Requests for Dialog (RFDs)*, checked 2026-10-30", "date": null, "quote": "The project currently has a design team with the Zed team as the lead (BDFL).", "ref": 13 }, { "label": "[14]", "url": "https://agentclientprotocol.com/announcements/transports-working-group", "claim": "Agent Client Protocol, *Transports Working Group*, published 2026-04-22", "date": null, "quote": "We have started work on a Draft RFD for how this could work both via WebSockets and HTTP.", "ref": 14 }, { "label": "[15]", "url": "https://agentclientprotocol.com/protocol/v1/content", "claim": "Agent Client Protocol, *Content (protocol v1)*, checked 2026-10-30", "date": null, "quote": "ACP's ContentBlock is compatible with, and a superset of, the Model Context Protocol (MCP) 2025-06-18 ContentBlock / User prompts sent via session/prompt / Language model output streamed through session/update notifications / so Agents can forward content from MCP tool outputs unchanged. / All Agents MUST support text content blocks when included in prompts. / \"type\": \"text\" / \"type\": \"resource_link\" / All Agents MUST support resource links when included in prompts.", "ref": 15 }, { "label": "[16]", "url": "https://github.com/agentclientprotocol/registry", "claim": "agentclientprotocol, *ACP Registry*, checked 2026-10-30", "date": null, "quote": "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json / JetBrains IDEs use a dedicated index, plus an opt-in preview channel / https://cdn.agentclientprotocol.com/registry/v1/latest/registry-for-jetbrains.json / https://cdn.agentclientprotocol.com/registry/v1/latest/registry-for-jetbrains-preview.json / https://cdn.agentclientprotocol.com/registry/v1/latest/registry-for-jetbrains-air.json / All agents are verified via CI to ensure they return valid authMethods in the ACP handshake. / Agent versions are automatically updated via a cron job that runs hourly. It checks for new releases across all supported distribution types (npm, PyPI, GitHub releases) and commits updates directly to main", "ref": 16 }, { "label": "[17]", "url": "https://agentclientprotocol.com/rfds/mcp-over-acp", "claim": "Agent Client Protocol, *MCP-over-ACP: Stateless MCP Requests over ACP*, checked 2026-10-30", "date": null, "quote": "Let an ACP client or proxy supply tools to an agent using the ACP connection it already has. / Declare an MCP server with \"type\": \"acp\", then send independent MCP requests to its serverId. / Results, request-scoped notifications, and cancellation travel over ACP without a second process or network endpoint. / This draft targets MCP 2026-07-28 only. / ACP initialization and sessions remain unchanged, but there is no MCP initialization handshake", "ref": 17 }, { "label": "[18]", "url": "https://agentclientprotocol.com/announcements/client-system-prompt-stabilized", "claim": "Agent Client Protocol, *Client-provided system prompts are stabilized*, published 2026-11-06", "date": null, "quote": "Clients can send system-level instructions on session setup in the stable ACP protocol surfaces. … Published: November 6, 2026 … Completed, stabilizing the `systemPrompt` field on session setup requests and the `systemPrompt` session capability.", "ref": 18 }, { "label": "[19]", "url": "https://agentclientprotocol.com/announcements/acp-agent-registry-stabilized", "claim": "Agent Client Protocol, *ACP Registry is stabilized*, published 2026-03-09", "date": null, "quote": "The registry gives ACP clients a standard way to discover, install, and configure compatible agents. / Published: March 9, 2026 The ACP Registry RFD has moved to Completed and the initial version of the registry is stabilized. / It introduces a curated catalog and a shared manifest format so editors and other clients do not need to invent their own integration metadata.", "ref": 19 }, { "label": "[20]", "url": "https://goose-docs.ai/docs/gdk/acp/", "claim": "goose, *Build an app with goose (ACP)*, checked 2026-10-30", "date": null, "quote": "Permission callbacks are not a sandbox: goose's configured mode determines when approval is requested, and its tools run with the backend's access to the machine. / Connect over stdio Launch goose acp as a subprocess. Its stdin and stdout carry ACP messages / goose serve exposes ACP over HTTP and WebSocket. / http://127.0.0.1:3284/acp / This is also how goose Desktop talks to its backend.", "ref": 20 }, { "label": "[21]", "url": "https://zed.dev/docs/ai/sandboxing", "claim": "Zed, *Sandboxing*, checked 2026-11-08", "date": null, "quote": "Sandboxing applies only to Zed Agent. It does not sandbox Zed itself, language servers, extensions, tasks, your normal terminal tabs, External Agents, or Terminal Threads.", "ref": 21 }, { "label": "[22]", "url": "https://agentclientprotocol.com/get-started/registry", "claim": "Agent Client Protocol, *ACP Registry*, checked 2026-10-30", "date": null, "quote": "curl https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json / The registry JSON contains all agent metadata including distribution information for automatic installation. / Claude Agent ACP wrapper for Anthropic's Claude / Codex ACP adapter for OpenAI's coding assistant / This is a curated set of agents, including only the ones that support authentication. / Clients can fetch the registry programmatically / https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json", "ref": 22 }, { "label": "[23]", "url": "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json", "claim": "Agent Client Protocol, *ACP registry.json (v1 latest)*, checked 2026-11-06", "date": null, "quote": "\"version\": \"1.0.0\", \"agents\" / \"distribution\": { \"npx\": { \"package\" / \"binary\": { \"darwin-aarch64\" / \"version\": \"1.0.0\" / \"agents\"", "ref": 23 }, { "label": "[24]", "url": "https://zed.dev/blog/acp-registry", "claim": "Ben Brandt (Zed Industries), *The ACP Registry is Live*, published 2026-01-28", "date": null, "quote": "Zed and JetBrains IDEs now have built-in registry support so users can easily install / Zed and JetBrains IDEs now have built-in registry support", "ref": 24 }, { "label": "[25]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification (2026-07-28)*, version 2026-07-28", "date": null, "quote": "The protocol uses JSON-RPC 2.0 messages to establish communication between: Hosts : LLM applications that initiate connections Clients : Connectors within the host application Servers : Services that provide context and capabilities / Servers offer any of the following features to clients: Resources : Context and data, for the user or the AI model to use Prompts : Templated messages and workflows for users Tools : Functions for the AI model to execute", "ref": 25 }, { "label": "[26]", "url": "https://a2a-protocol.org/latest/specification/", "claim": "A2A Protocol, *Agent2Agent (A2A) Protocol Specification*, checked 2026-10-30", "date": null, "quote": "GET /.well-known/agent-card.json / JSON-RPC Protocol Binding … gRPC Protocol Binding … HTTP+JSON/REST Protocol Binding", "ref": 26 }, { "label": "[27]", "url": "https://docs.ag-ui.com/spec/1.0/index", "claim": "Agent User Interaction Protocol, *Specification 1.0*, modified 2026-09-17", "date": null, "quote": "Run input - the one message that travels from application to agent. / Transports - HTTP + SSE, HTTP + Protobuf", "ref": 27 }, { "label": "[28]", "url": "https://www.copilotkit.ai/blog/introducing-ag-ui-the-protocol-where-agents-meet-users", "claim": "CopilotKit, *Introducing AG-UI: The Protocol Where Agents Meet Users*, checked 2026-10-30", "date": null, "quote": "Your client makes a single POST to the agent endpoint, then listens to a unified event stream.", "ref": 28 }, { "label": "[29]", "url": "https://agents.md/", "claim": "AGENTS.md, *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project. / Create an AGENTS.md file at the root of the repository.", "ref": 29 }, { "label": "[30]", "url": "https://geminicli.com/docs/cli/acp-mode/", "claim": "Google (Gemini CLI), *ACP Mode*, checked 2026-10-30", "date": null, "quote": "ACP (Agent Client Protocol) mode is a special operational mode of Gemini CLI designed for programmatic control, primarily for IDE and other developer tool integrations. / The entire communication happens over standard input/output (stdio) using the JSON-RPC 2.0 protocol. / gemini --acp / Gemini CLI is an ACP-compatible agent and can be found in this registry.", "ref": 30 }, { "label": "[31]", "url": "https://docs.github.com/en/copilot/reference/copilot-cli-reference/acp-server", "claim": "GitHub, *Copilot CLI ACP server*, checked 2026-10-30", "date": null, "quote": "ACP support in GitHub Copilot CLI is in public preview and subject to change. / Use the --acp option of the copilot command to start the CLI's ACP server. / You can specify the transport mode with either the --stdio or --port options. / --available-tools=TOOL... / --excluded-tools=TOOL... / --effort=LEVEL, --reasoning-effort=LEVEL", "ref": 31 }, { "label": "[32]", "url": "https://github.blog/changelog/2026-01-28-acp-support-in-copilot-cli-is-now-in-public-preview/", "claim": "Allison (GitHub Changelog), *ACP support in Copilot CLI is now in public preview*, published 2026-01-28", "date": null, "quote": "2026-01-28", "ref": 32 }, { "label": "[33]", "url": "https://thenewstack.io/kiro-agent-client-protocol/", "claim": "Janakiram MSV (The New Stack), *Free agents: How AWS Kiro could untie agents from editors*, published 2026-08-06", "date": null, "quote": "AWS chose the Agent Client Protocol (ACP) as the interface between Kiro's clients and Kiro's own agent. / The team introduced more than 20 agent-callable methods, 15 client-callable methods, and 20 notification types, all namespaced under _kiro/. It also implemented a WebSocket transport for web and iOS clients while continuing to use ACP's standard stdio transport for local execution.", "ref": 33 }, { "label": "[34]", "url": "https://zed.dev/docs/ai/external-agents", "claim": "Zed, *External Agents*, checked 2026-10-30", "date": null, "quote": "External Agents are agents that integrate with Zed through the Agent Client Protocol (ACP). / Zed hosts the thread in the Agent Panel and Threads Sidebar / Open the registry with zed: acp registry / \"agent_servers\": {", "ref": 34 }, { "label": "[35]", "url": "https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/", "claim": "Jan-Niklas Wortmann (JetBrains), *ACP Agent Registry Is Live: Find and Connect AI Coding Agents in Your JetBrains IDE*, published 2026-01-28", "date": null, "quote": "The ACP Registry is available now in JetBrains IDE versions 2025.3 and later.", "ref": 35 }, { "label": "[36]", "url": "https://codecompanion.olimorris.dev/agent-client-protocol", "claim": "CodeCompanion.nvim, *Agent Client Protocol (ACP)*, checked 2026-10-30", "date": null, "quote": "CodeCompanion implements it so you can work with agents like Claude Code and Codex from the chat buffer. / JSON-RPC 2.0, streaming responses, message buffering / Create, list and load sessions / readTextFile / writeTextFile / Show an agent's execution plan / Give the agent a Neovim terminal", "ref": 36 }, { "label": "[37]", "url": "https://github.com/olimorris/codecompanion.nvim/blob/main/CHANGELOG.md", "claim": "olimorris (CodeCompanion.nvim), *CHANGELOG.md*, 17.18.0 dated 2025-08-27; page checked 2026-10-30", "date": null, "quote": "17.18.0 (2025-08-27) / add support for Agent Client Protocol", "ref": 37 }, { "label": "[38]", "url": "https://xenodium.com/introducing-agent-shell", "claim": "Álvaro Ramírez (xenodium), *Introducing Emacs agent-shell (powered by ACP)*, published 2025-09-25", "date": null, "quote": "September 25, 2025 Introducing Emacs agent-shell (powered by ACP) / I introduced acp.el, an Emacs lisp implementation of ACP (Agent Client Protocol) / agent-shell is a native Emacs shell, powered by comint-mode / Today, I have an initial version of agent-shell I can share.", "ref": 38 }, { "label": "[39]", "url": "https://github.com/agentclientprotocol/claude-agent-acp", "claim": "agentclientprotocol, *claude-agent-acp*, checked 2026-10-30", "date": null, "quote": "npm install @agentclientprotocol/claude-agent-acp@preview / This tool implements an ACP agent by using the official Claude Agent SDK / Context @-mentions / Interactive (and background) terminals / /mcp in the chat", "ref": 39 }, { "label": "[40]", "url": "https://github.com/agentclientprotocol/codex-acp", "claim": "agentclientprotocol, *codex-acp*, checked 2026-10-30", "date": null, "quote": "npx -y @agentclientprotocol/codex-acp / codex-acp is a stdio ACP agent server. It starts the Codex App Server, translates ACP requests into Codex operations, and maps Codex events back into the client. / Native ACP subagent sessions (after capability negotiation) / Mid-turn input through the _session/steering extension", "ref": 40 } ], "form": "endpoint", "governance": "Jointly governed by Zed and JetBrains under an interim governance model while working toward transitioning to an independent foundation; lead maintainers Ben Brandt (Zed Industries) and Sergey Ignatov (JetBrains) hold final decision authority alongside the ACP steering group and public Requests for Dialog (RFD) process", "group": "Protocols called ACP", "history": [ { "date": "2026-09-06", "note": "verified against agentclientprotocol.com/get-started/introduction, agentclientprotocol.com/updates, agentclientprotocol.com/rfds/about" }, { "date": "2026-09-06", "note": "collisions updated to add Agent Connect Protocol (Cisco/AGNTCY), verified against github.com/agntcy/acp-spec, spec.acp.agntcy.org" }, { "date": "2026-10-16", "note": "Agent Client Protocol v1.11.0 (schema v1.25.0) released on 2026-10-09; v2 is unstable" }, { "date": "2026-10-28", "note": "Verified specification record (v1.13.0 / schema v1.27.0 / schema v2.0.0-alpha.10, 40 primary/secondary sources)" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "agent-client-protocol", "implementation": "multi-implementation", "last_verified": "2026-11-12", "name": "Agent Client Protocol", "native_status": "Active open protocol. Protocol version 1 is stable; version 2 published in Draft on 2026-07-20; full support for remote agents is a work in progress.", "origin": { "date": "2025-08-27", "org": "Zed Industries" }, "part_of": null, "parties": [ "agent-site" ], "phase": "stable", "probe": { "method": "stdio", "on_absent": "process exits, writes non-JSON-RPC output, or times out: the binary does not speak ACP", "parse": "response result containing protocolVersion and agentCapabilities confirms an ACP-speaking agent", "path": "spawn {agent-binary} and send a JSON-RPC 2.0 initialize request per the ACP schema over stdin/stdout" }, "question": "How does a code editor invoke and converse with an interchangeable coding agent it did not build?", "scope": "coding-tools", "spec_url": "https://agentclientprotocol.com/protocol/v1/overview", "step": "act", "summary_md": "The **Agent Client Protocol** (**ACP**) is an open protocol that standardizes communication between code editors or IDEs and AI coding agents across local and remote environments. Launched by Zed Industries on August 27, 2025 with Google's Gemini CLI as its initial reference implementation, ACP is jointly governed by Zed and JetBrains while transitioning toward an independent foundation. On the baseline `stdio` transport, the editor launches the agent as a subprocess exchanging newline-delimited `UTF-8` JSON-RPC 2.0 messages over `stdin` and `stdout`. The client calls `initialize`, `session/new` (or `session/load`), and `session/prompt`, while the agent streams `session/update` notifications and requests file or permission operations before returning a stop reason. Stable wire version `1` (`protocolVersion` in `initialize`) reached `1.0.0` Rust and TypeScript SDKs on June 25, 2026, followed by Draft v2 on July 20, 2026 and the `v1.15.1` crate, `schema-v1.29.1`, and `schema-v2.0.0-alpha.13` releases on November 2, 2026. Schema `schema-v1.31.0`, released November 10, 2026, adds unstable `session/options` and initial config option values.", "track": "vendor-consortium", "version": { "label": "1 (JSON Schema schema-v1.31.0; Rust crate v1.15.1; v2 Draft schema-v2.0.0-alpha.13)", "date": "2026-11-10" }, "watch": [ { "type": "page", "url": "https://agentclientprotocol.com/get-started/introduction", "selector": "main", "cadence": "weekly" }, { "type": "github", "repo": "agentclientprotocol/agent-client-protocol", "mode": "release", "version": false } ], "use_cases": [ "describe-agent-capabilities", "render-agent-ui", "agent-to-agent-messaging" ], "audience": [ "agent-builder", "platform" ], "pairs_with": [ "mcp", "a2a", "ag-ui", "agents-md" ], "prerequisites": [], "hatnote_md": "This article covers the Agent Client Protocol (ACP) for editor-to-coding-agent sessions. It is distinct from OpenAI and Stripe's [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), IBM's [Agent Communication Protocol](/protocols/agent-communication-protocol/) (merged into [A2A](/protocols/a2a/)), and AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/). For host-to-tool context integration, see [Model Context Protocol](/protocols/mcp/).", "tier": "flagship", "lifecycle_status": "published_standard", "wire_archetype": "harnesses_rpc_ui", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This article covers the Agent Client Protocol (ACP) for editor-to-coding-agent sessions. It is distinct from OpenAI and Stripe's [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), IBM's [Agent Communication Protocol](/protocols/agent-communication-protocol/) (merged into [A2A](/protocols/a2a/)), and AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/). For host-to-tool context integration, see [Model Context Protocol](/protocols/mcp/). [1][2]", "v05_elevator_pitch_md": "ACP is an editor-to-agent interoperability standard—analogous to the Language Server Protocol—that lets code editors and IDEs (such as Zed and JetBrains IDEs) run any compatible AI coding agent (such as Gemini CLI). Instead of writing bespoke plugins that lock each coding agent to a single editor UI, the editor communicates with the agent over `stdio` using JSON-RPC methods (`initialize`, `session/new`, `session/prompt`, and `session/update`) to stream prompts, diffs, and tool approvals. [1][3][4]", "v05_lead_md": "The **Agent Client Protocol** (**ACP**) is an open protocol that standardizes communication between code editors or IDEs and AI coding agents across local and remote environments. [2][3] Launched by Zed Industries on August 27, 2025 with Google's Gemini CLI as its initial reference implementation, ACP is jointly governed by Zed and JetBrains while transitioning toward an independent foundation. [1][5] On the baseline `stdio` transport, the editor launches the agent as a subprocess exchanging newline-delimited `UTF-8` JSON-RPC 2.0 messages over `stdin` and `stdout`. [6] The client calls `initialize`, `session/new` (or `session/load`), and `session/prompt`, while the agent streams `session/update` notifications and requests file or permission operations before returning a stop reason. [4] Stable wire version `1` (`protocolVersion` in `initialize`) reached `1.0.0` Rust and TypeScript SDKs on June 25, 2026, followed by Draft v2 on July 20, 2026 and the `v1.15.1` crate, `schema-v1.29.1`, and `schema-v2.0.0-alpha.13` releases on November 2, 2026. [7][8][9][10][11] Schema `schema-v1.31.0`, released November 10, 2026, adds unstable `session/options` and initial config option values. [12]", "v05_identity_sentence_md": "The **Agent Client Protocol** (**ACP**) is an open protocol that standardizes communication between code editors or IDEs and AI coding agents across local and remote environments. [2][3] Launched by Zed Industries on August 27, 2025 with Google's Gemini CLI as its initial reference implementation, ACP is jointly governed by Zed and JetBrains while transitioning toward an independent foundation. [1][5]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Act](/category/act/) (`act`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "Zed Industries (Nathan Sobo), announced 2025-08-27 with Google's Gemini CLI as initial reference implementation (GitHub repo created 2025-06-23) [1][7]" }, { "label": "Governed by", "value_md": "Zed and JetBrains under an interim governance model while working toward an independent foundation; lead maintainers: Ben Brandt (Zed Industries) and Sergey Ignatov (JetBrains) [5]" }, { "label": "Track", "value_md": "Vendor / Spec-Site Standard (`vendor-consortium`); specification changes advance via public Requests for Dialog (RFDs) [13]" }, { "label": "Status", "value_md": "Active open standard; protocol version `1` is stable, version `2` was published in Draft on 2026-07-20, and remote-agent support is a work in progress [3][7][10]" }, { "label": "Version", "value_md": "Protocol version `1` (wire `protocolVersion` negotiated during `initialize`); latest schema `schema-v1.31.0`, published 2026-11-10, adds unstable `session/options` and initial config option values (after Rust crate `v1.15.1`, `schema-v1.29.1`, and prerelease `schema-v2.0.0-alpha.13` on 2026-11-02, following `v1.13.0`, `schema-v1.27.0`, and `schema-v2.0.0-alpha.10` on 2026-10-27) [7][11][12]" }, { "label": "Transports", "value_md": "`stdio` (newline-delimited UTF-8 JSON-RPC over subprocess `stdin`/`stdout`); remote transport based on Streamable HTTP and WebSockets in RFD specification [6][14]" }, { "label": "Message format", "value_md": "JSON-RPC 2.0 request-response methods and one-way notifications; `ContentBlock` is a superset of the MCP `2025-06-18` `ContentBlock` [4][15]" }, { "label": "Specification", "value_md": "[Protocol overview (v1)](https://agentclientprotocol.com/protocol/v1/overview) [4]" }, { "label": "Found at", "value_md": "No fixed agent URL (client spawns subprocess over `stdin`/`stdout`); ACP Registry index at `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json` [6][16]" }, { "label": "Licence", "value_md": "Apache License 2.0 (no Contributor License Agreement required) [5][7]" } ], "v05_problem_md": "Without a shared editor-agent protocol, AI coding agents and editors are tightly coupled: each editor must build custom integrations for every agent it supports, and agents must implement editor-specific APIs to reach users, resulting in integration overhead, limited editor compatibility, and developer lock-in. [3] Just as the Language Server Protocol unbundled language intelligence from monolithic IDEs, ACP decouples coding agents from editor UIs so developers can switch agents without switching editors. It reuses Model Context Protocol (MCP) JSON representations where possible while adding coding-specific UX types (such as diffs) and allowing clients to pass MCP server connection configurations at session creation. [1][3][8] ACP v1 standardizes only the local `stdio` subprocess transport; remote transports over Streamable HTTP and WebSockets and stateless tool tunneling (`MCP-over-ACP`) remain under active specification in Working Group draft RFDs. [6][14][17]", "v05_mechanism_delta_md": "Just as the Language Server Protocol unbundled language intelligence from monolithic IDEs, ACP decouples coding agents from editor UIs so developers can switch agents without switching editors. It reuses Model Context Protocol (MCP) JSON representations where possible while adding coding-specific UX types (such as diffs) and allowing clients to pass MCP server connection configurations at session creation. [1][3][8]", "v05_scope_boundary_md": "ACP v1 standardizes only the local `stdio` subprocess transport; remote transports over Streamable HTTP and WebSockets and stateless tool tunneling (`MCP-over-ACP`) remain under active specification in Working Group draft RFDs. [6][14][17]", "v05_fuzzy_additions": [ { "id": "json-rpc-session-lifecycle-and-transport-framing", "heading": "JSON-RPC session lifecycle and transport framing", "body_md": "The protocol allows agents and clients to communicate by exposing methods that each side can call and by sending notifications to inform each other of events. It follows the JSON-RPC 2.0 specification: methods are request-response pairs that expect a result or error, and notifications are one-way messages that do not expect a response. [4]", "bullets": [ { "label": "Version negotiation", "text_md": "Clients call `initialize` to establish the connection, negotiate versions, and exchange capabilities. The result carries `protocolVersion` and `agentCapabilities`, including `loadSession`. If `loadSession` is false or not present, clients MUST NOT call `session/load`. Negotiated `protocolVersion` fixes the wire shape, and exchanged capabilities select optional messages. [4][7][8]" }, { "label": "Optional authenticate", "text_md": "If the agent requires it, the client completes an advertised authentication flow before creating a session, such as `authenticate` or a terminal launch-and-reconnect. Until that flow finishes, `session/new` may fail with `auth_required`. `logout` ends the authenticated state when `agentCapabilities.auth.logout` is advertised. [4][8]" }, { "label": "Session ids and MCP servers", "text_md": "`session/new` sends the working directory and `mcpServers`, the MCP servers the agent should connect to, and the agent MUST respond with a unique `sessionId`. `session/load` is allowed only after `loadSession` is advertised, and it sends `sessionId`, `cwd`, and `mcpServers` again so the agent can replay the conversation as `session/update` notifications. The Client-Provided System Prompt RFD moved to Completed on November 6, 2026, stabilizing client `systemPrompt` on session setup requests and the `systemPrompt` session capability in the stable ACP protocol surfaces, including v1 session setup. [8][18]" }, { "label": "stdio versus remote drafts", "text_md": "All ACP JSON-RPC 2.0 messages MUST be `UTF-8` encoded; on `stdio` (which agents and clients SHOULD support whenever possible), the client spawns the agent as a subprocess and frames `stdin` and `stdout` messages with newline delimiters (`\\n`) and no embedded newlines. For remote agents, the Transports Working Group is specifying a Streamable HTTP transport RFD alongside a Draft RFD covering both WebSockets and HTTP. [6][14]" } ] }, { "id": "prompt-turns-client-callbacks-and-the-acp-registry", "heading": "Prompt turns, client callbacks, and the ACP Registry", "body_md": "Each user turn is a prompt: the client sends content blocks, the agent streams updates, and the agent calls back into the editor for permissions, files, and terminals. The stabilized ACP Agent Registry is the catalog clients use to discover and install agents. [4][19]", "bullets": [ { "label": "Prompt turns", "text_md": "`session/prompt` sends user content blocks, and model output streams through `session/update` notifications. `ContentBlock` is a superset of the MCP `2025-06-18` `ContentBlock`, so agents can forward MCP tool output unchanged. As a baseline, all agents must support both `text` and `resource_link` content blocks when included in prompts. The turn ends with a `session/prompt` stop reason, or the client sends `session/cancel`. [4][15]" }, { "label": "Client callbacks", "text_md": "The agent requests tool authorization with `session/request_permission`. File reads and writes use `fs/read_text_file` and `fs/write_text_file` when the client advertised `fs.readTextFile` and `fs.writeTextFile`. Terminal management uses the `terminal/create`, `terminal/output`, `terminal/wait_for_exit`, `terminal/kill`, and `terminal/release` methods, each requiring the `terminal` capability. Because ACP agents run as local subprocesses with the host user's access to the machine, `session/request_permission` and client capability callbacks are cooperative rather than an OS sandbox: `goose` documentation states that permission callbacks are not a sandbox and tools run with the backend's access to the machine, and Zed's sandboxing documentation states that Zed Agent sandboxing does not sandbox `External Agents`. [4][20][21]" }, { "label": "MCP-over-ACP", "text_md": "The `MCP-over-ACP` draft lets a client or proxy supply tools on the ACP connection it already has, by declaring an MCP server of type `acp` and sending requests to its `serverId`. Results and cancellation travel over ACP with no second process or network endpoint. It targets MCP `2026-07-28` only, and ACP initialization and sessions remain unchanged. [17]" }, { "label": "Registry manifest", "text_md": "On March 9, 2026 the registry stabilized, with a curated catalog and a shared manifest format for discovery, install, and configuration. Clients fetch `registry.json`, where top-level `version` is `1.0.0` and each agent can include `distribution` data such as an `npx` package or a `binary` archive. Zed and JetBrains IDEs ship built-in registry support. [19][22][23][24]" } ] } ], "v05_diagram": { "title": "Client and agent session flow", "heading": "Client and agent session flow", "mermaid": "sequenceDiagram\n participant Client as Editor Client\n participant Agent as Coding Agent\n Client->>Agent: initialize\n Agent-->>Client: protocolVersion and agentCapabilities\n opt Authentication required\n Client->>Agent: authenticate\n Agent-->>Client: authenticated\n end\n Client->>Agent: session/new or session/load\n Agent-->>Client: sessionId\n Client->>Agent: session/prompt\n Agent-->>Client: session/update notifications\n opt Workspace callbacks or cancellation\n Agent->>Client: file ops or session/request_permission\n Client-->>Agent: callback result or session/cancel\n end\n Agent-->>Client: session/prompt response with stop reason", "caption_md": "An editor `Client` initializes a session with an `Agent` (`initialize`, optional `authenticate`, and `session/new` or `session/load`), then sends user turns via `session/prompt`; the agent streams `session/update` notifications and invokes editor file or permission callbacks before returning a final stop reason (unless interrupted by `session/cancel`). [4]" }, "v05_wire_artifact": { "title": "session/new request", "heading": "session/new request", "lang": "json", "code": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"session/new\",\n \"params\": {\n \"cwd\": \"/home/user/project\",\n \"mcpServers\": [\n {\n \"name\": \"filesystem\",\n \"command\": \"/path/to/mcp-server\",\n \"args\": [\n \"--stdio\"\n ],\n \"env\": []\n }\n ]\n }\n}", "caption_md": "A `session/new` JSON-RPC 2.0 request supplies the workspace path (`cwd`) and MCP server launch configurations (`mcpServers`); the agent responds on the matching `id` with a unique `sessionId` (for example, `\"sess_abc123def456\"`). [8]" }, "v05_counterparts": { "classic_analogues": [ { "name": "JSON-RPC 2.0 Specification", "spec_or_rfc": "JSON-RPC 2.0", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Profiles JSON-RPC 2.0 bidirectional request-response methods and one-way `session/update` notifications for multi-turn coding sessions, adding reverse agent-to-editor callbacks (`session/request_permission`, `fs/read_text_file`, `fs/write_text_file`, and `terminal/create`). [4]" }, { "name": "Language Server Protocol (LSP)", "spec_or_rfc": "LSP", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Whereas the Language Server Protocol (LSP) unbundled static language intelligence (autocomplete, diagnostics, go-to-definition) from monolithic IDEs, ACP applies the same client-server decoupling to multi-turn AI coding agents so developers can switch agents without switching editors. [1]" } ], "agentic_peers": [ { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "MCP uses JSON-RPC 2.0 between a host, the host's client, and a server that can offer resources, prompts, and tools. ACP is the editor-to-coding-agent session; when an ACP client creates a session, it may include connection details for MCP servers the agent should connect to. [3][8][25]" }, { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "A2A coordinates task delegation between opaque remote agents discovered via `GET /.well-known/agent-card.json` over HTTP or gRPC, whereas ACP couples an interactive code editor UI to a coding agent with workspace diff, file, and terminal callbacks. [3][26]" }, { "target_id": "ag-ui", "target_name": "Agent-User Interaction Protocol (AG-UI)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "AG-UI streams frontend UI state events from a backend agent after an HTTP `POST` (`HTTP + SSE` or `HTTP + Protobuf`), whereas ACP mediates an IDE coding session in which the agent also calls back into the editor for file reads/writes, terminals, and tool permissions. [4][27][28]" }, { "target_id": "agents-md", "target_name": "AGENTS.md", "relation_type": "complements", "relation_label": "Complements", "delta_md": "`AGENTS.md` is a static repository-root Markdown file providing project instructions and conventions, whereas ACP defines the live bidirectional session wire protocol between the code editor and the coding agent. [3][29]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (11 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Native ACP coding agents", "col4_header": "Transport, capabilities & scope", "note_md": null, "rows": [ { "actor": "Google Gemini CLI", "role": "Native CLI coding agent (reference implementation)", "status": "Supported", "status_display": "Supported · as of 2025-08-27", "col4_md": "Native `gemini --acp` mode speaking `JSON-RPC 2.0` over `stdio`; initial ACP reference implementation with Zed.", "source_md": "[Gemini CLI ACP mode](https://geminicli.com/docs/cli/acp-mode/) [30] · [Bring Your Own Agent to Zed](https://zed.dev/blog/bring-your-own-agent-to-zed) [1]" }, { "actor": "Block goose", "role": "Native CLI coding agent & desktop client", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Native `goose acp` subprocess over `stdio` and `goose serve` daemon at `http://127.0.0.1:3284/acp`.", "source_md": "[goose ACP guide](https://goose-docs.ai/docs/gdk/acp/) [20]" }, { "actor": "GitHub Copilot CLI", "role": "Native CLI coding agent", "status": "Supported (preview)", "status_display": "Supported (preview) · as of 2026-01-28", "col4_md": "Public preview `--acp` server on `copilot` over `--stdio` (default) or `--port` TCP, launched 2026-01-28.", "source_md": "[Copilot CLI ACP server](https://docs.github.com/en/copilot/reference/copilot-cli-reference/acp-server) [31] · [Copilot CLI ACP public preview](https://github.blog/changelog/2026-01-28-acp-support-in-copilot-cli-is-now-in-public-preview/) [32]" }, { "actor": "AWS Kiro", "role": "Standalone coding agent & client harness", "status": "Supported (release announcement)", "status_display": "Supported (release announcement) · as of 2026-08-06", "col4_md": "Uses ACP over local `stdio` and `WebSocket` between Kiro clients and agent with `_kiro/` extensions.", "source_md": "[AWS Kiro on ACP (The New Stack)](https://thenewstack.io/kiro-agent-client-protocol/) [33]" } ] }, "side_b": { "visible": true, "heading": "Editors & IDE host clients", "col4_header": "Host surface & transport", "note_md": null, "rows": [ { "actor": "Zed", "role": "Native code editor client (co-steward)", "status": "Supported", "status_display": "Supported · as of 2026-01-28", "col4_md": "Native ACP client hosting `External Agents` in the `Agent Panel` with built-in `zed: acp registry`.", "source_md": "[Zed External Agents](https://zed.dev/docs/ai/external-agents) [34] · [The ACP Registry is Live](https://zed.dev/blog/acp-registry) [24]" }, { "actor": "JetBrains IDEs", "role": "Native IDE client (co-steward)", "status": "Supported", "status_display": "Supported · as of 2026-01-28", "col4_md": "Built-in ACP client and `ACP Registry` in JetBrains IDEs `2025.3`+ consuming `registry-for-jetbrains.json`.", "source_md": "[JetBrains and Zed on ACP](https://blog.jetbrains.com/ai/2025/10/jetbrains-zed-open-interoperability-for-ai-coding-agents-in-your-ide/) [2] · [ACP Agent Registry in JetBrains IDEs](https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/) [35] · [ACP Registry repository](https://github.com/agentclientprotocol/registry) [16]" }, { "actor": "CodeCompanion.nvim", "role": "Community Neovim client plugin", "status": "Partial", "status_display": "Partial · as of 2025-08-27", "col4_md": "Neovim plugin supporting `JSON-RPC 2.0` sessions, `readTextFile`, and `writeTextFile`; omits agent plans and terminals.", "source_md": "[CodeCompanion ACP](https://codecompanion.olimorris.dev/agent-client-protocol) [36] · [CodeCompanion changelog](https://github.com/olimorris/codecompanion.nvim/blob/main/CHANGELOG.md) [37]" }, { "actor": "Emacs agent-shell", "role": "Community Emacs client package", "status": "Development", "status_display": "Development · as of 2025-09-25", "col4_md": "Initial native Emacs shell on `comint-mode` built on the `acp.el` Emacs Lisp ACP client.", "source_md": "[Introducing Emacs agent-shell](https://xenodium.com/introducing-agent-shell) [38]" } ] }, "additional_tables": [ { "visible": true, "heading": "External bridge adapters & official SDKs", "col4_header": "Target runtime / SDK languages", "note_md": null, "rows": [ { "actor": "Claude Agent (claude-agent-acp)", "role": "External ACP adapter (Claude Agent SDK)", "status": "Listed integration", "status_display": "Listed integration · checked 2026-10-30", "col4_md": "External adapter (`@agentclientprotocol/claude-agent-acp`) wrapping the `Claude Agent SDK` with `@-mentions`, terminals, subagents, and `/mcp`.", "source_md": "[claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) [39] · [ACP Registry](https://agentclientprotocol.com/get-started/registry) [22]" }, { "actor": "OpenAI Codex (codex-acp)", "role": "External ACP adapter (Codex App Server)", "status": "Listed integration", "status_display": "Listed integration · checked 2026-10-30", "col4_md": "External `stdio` adapter (`@agentclientprotocol/codex-acp`) translating ACP requests into `Codex App Server` operations.", "source_md": "[codex-acp](https://github.com/agentclientprotocol/codex-acp) [40] · [ACP Registry](https://agentclientprotocol.com/get-started/registry) [22]" }, { "actor": "Official ACP SDKs", "role": "Official client & agent SDKs", "status": "Supported", "status_display": "Supported · as of 2026-11-02", "col4_md": "Official client and agent SDKs: Rust `agent-client-protocol` (`v1.15.1`), TypeScript `@agentclientprotocol/sdk`, Python `python-sdk`, Kotlin `acp-kotlin`, Java `java-sdk`.", "source_md": "[ACP repository](https://github.com/agentclientprotocol/agent-client-protocol) [7] · [ACP updates](https://agentclientprotocol.com/updates) [9] · [ACP releases](https://github.com/agentclientprotocol/agent-client-protocol/releases) [11]" } ] } ], "censuses": [ { "label": "Official ACP Registry (Available Agents index)", "as_of": "2026-10-30", "value_md": "43 authenticated coding agents and external ACP adapters—including Gemini CLI, goose, GitHub Copilot, Junie, Kimi CLI, Mistral Vibe, OpenCode, OpenCode V2, Qwen Code, Claude Agent, and Codex—are listed in the curated Available Agents directory and verified in CI to return valid `authMethods` during the ACP handshake, with package versions synced hourly across npm, PyPI, and GitHub releases. [16][22]" }, { "label": "cdn.agentclientprotocol.com registry.json (version 1.0.0)", "as_of": "2026-11-06", "value_md": "45 agent manifest entries appear in the top-level `agents` array of `registry.json` (`version` `1.0.0`) at `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. [23]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "open-responses", "target_name": "Open Responses", "relation_label": "Peer alternative", "delta": "ACP is JSON-RPC 2.0 over a local agent subprocess. Open Responses is HTTP `/v1/responses`, with an optional 2026-04-24 WebSocket.", "item_md": "**[Open Responses](/protocols/open-responses/)** (Peer alternative) — ACP is JSON-RPC 2.0 over a local agent subprocess. Open Responses is HTTP `/v1/responses`, with an optional 2026-04-24 WebSocket." }, { "item_md": "**[Act protocols](/category/act/)** — Category index for `act` standards." } ], "v05_compiled_md": "---\nid: agent-client-protocol\ntitle: \"Agent Client Protocol\"\ntier: flagship\nlifecycle_status: published_standard\ncategory: act\nform: endpoint\nwire_archetype: harnesses_rpc_ui\nspec_url: https://agentclientprotocol.com/protocol/v1/overview\nlast_checked: 2026-11-12\n---\n\n# Agent Client Protocol\n\n**Category:** [Act](/category/act/) (`act`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-12\n\n> *This article covers the Agent Client Protocol (ACP) for editor-to-coding-agent sessions. It is distinct from OpenAI and Stripe's [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), IBM's [Agent Communication Protocol](/protocols/agent-communication-protocol/) (merged into [A2A](/protocols/a2a/)), and AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/). For host-to-tool context integration, see [Model Context Protocol](/protocols/mcp/). [1][2]*\n\n> **In brief:** ACP is an editor-to-agent interoperability standard—analogous to the Language Server Protocol—that lets code editors and IDEs (such as Zed and JetBrains IDEs) run any compatible AI coding agent (such as Gemini CLI). Instead of writing bespoke plugins that lock each coding agent to a single editor UI, the editor communicates with the agent over `stdio` using JSON-RPC methods (`initialize`, `session/new`, `session/prompt`, and `session/update`) to stream prompts, diffs, and tool approvals. [1][3][4]\n\nThe **Agent Client Protocol** (**ACP**) is an open protocol that standardizes communication between code editors or IDEs and AI coding agents across local and remote environments. [2][3] Launched by Zed Industries on August 27, 2025 with Google's Gemini CLI as its initial reference implementation, ACP is jointly governed by Zed and JetBrains while transitioning toward an independent foundation. [1][5] On the baseline `stdio` transport, the editor launches the agent as a subprocess exchanging newline-delimited `UTF-8` JSON-RPC 2.0 messages over `stdin` and `stdout`. [6] The client calls `initialize`, `session/new` (or `session/load`), and `session/prompt`, while the agent streams `session/update` notifications and requests file or permission operations before returning a stop reason. [4] Stable wire version `1` (`protocolVersion` in `initialize`) reached `1.0.0` Rust and TypeScript SDKs on June 25, 2026, followed by Draft v2 on July 20, 2026 and the `v1.15.1` crate, `schema-v1.29.1`, and `schema-v2.0.0-alpha.13` releases on November 2, 2026. [7][8][9][10][11] Schema `schema-v1.31.0`, released November 10, 2026, adds unstable `session/options` and initial config option values. [12]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Act](/category/act/) (`act`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | Zed Industries (Nathan Sobo), announced 2025-08-27 with Google's Gemini CLI as initial reference implementation (GitHub repo created 2025-06-23) [1][7] |\n| **Governed by** | Zed and JetBrains under an interim governance model while working toward an independent foundation; lead maintainers: Ben Brandt (Zed Industries) and Sergey Ignatov (JetBrains) [5] |\n| **Track** | Vendor / Spec-Site Standard (`vendor-consortium`); specification changes advance via public Requests for Dialog (RFDs) [13] |\n| **Status** | Active open standard; protocol version `1` is stable, version `2` was published in Draft on 2026-07-20, and remote-agent support is a work in progress [3][7][10] |\n| **Version** | Protocol version `1` (wire `protocolVersion` negotiated during `initialize`); latest schema `schema-v1.31.0`, published 2026-11-10, adds unstable `session/options` and initial config option values (after Rust crate `v1.15.1`, `schema-v1.29.1`, and prerelease `schema-v2.0.0-alpha.13` on 2026-11-02, following `v1.13.0`, `schema-v1.27.0`, and `schema-v2.0.0-alpha.10` on 2026-10-27) [7][11][12] |\n| **Transports** | `stdio` (newline-delimited UTF-8 JSON-RPC over subprocess `stdin`/`stdout`); remote transport based on Streamable HTTP and WebSockets in RFD specification [6][14] |\n| **Message format** | JSON-RPC 2.0 request-response methods and one-way notifications; `ContentBlock` is a superset of the MCP `2025-06-18` `ContentBlock` [4][15] |\n| **Specification** | [Protocol overview (v1)](https://agentclientprotocol.com/protocol/v1/overview) [4] |\n| **Found at** | No fixed agent URL (client spawns subprocess over `stdin`/`stdout`); ACP Registry index at `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json` [6][16] |\n| **Licence** | Apache License 2.0 (no Contributor License Agreement required) [5][7] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [JSON-RPC session lifecycle and transport framing](#json-rpc-session-lifecycle-and-transport-framing)\n3. [Prompt turns, client callbacks, and the ACP Registry](#prompt-turns-client-callbacks-and-the-acp-registry)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nWithout a shared editor-agent protocol, AI coding agents and editors are tightly coupled: each editor must build custom integrations for every agent it supports, and agents must implement editor-specific APIs to reach users, resulting in integration overhead, limited editor compatibility, and developer lock-in. [3] Just as the Language Server Protocol unbundled language intelligence from monolithic IDEs, ACP decouples coding agents from editor UIs so developers can switch agents without switching editors. It reuses Model Context Protocol (MCP) JSON representations where possible while adding coding-specific UX types (such as diffs) and allowing clients to pass MCP server connection configurations at session creation. [1][3][8] ACP v1 standardizes only the local `stdio` subprocess transport; remote transports over Streamable HTTP and WebSockets and stateless tool tunneling (`MCP-over-ACP`) remain under active specification in Working Group draft RFDs. [6][14][17]\n\n### Client and agent session flow\n\n```mermaid\nsequenceDiagram\n participant Client as Editor Client\n participant Agent as Coding Agent\n Client->>Agent: initialize\n Agent-->>Client: protocolVersion and agentCapabilities\n opt Authentication required\n Client->>Agent: authenticate\n Agent-->>Client: authenticated\n end\n Client->>Agent: session/new or session/load\n Agent-->>Client: sessionId\n Client->>Agent: session/prompt\n Agent-->>Client: session/update notifications\n opt Workspace callbacks or cancellation\n Agent->>Client: file ops or session/request_permission\n Client-->>Agent: callback result or session/cancel\n end\n Agent-->>Client: session/prompt response with stop reason\n```\n\n*An editor `Client` initializes a session with an `Agent` (`initialize`, optional `authenticate`, and `session/new` or `session/load`), then sends user turns via `session/prompt`; the agent streams `session/update` notifications and invokes editor file or permission callbacks before returning a final stop reason (unless interrupted by `session/cancel`). [4]*\n\n### session/new request\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"session/new\",\n \"params\": {\n \"cwd\": \"/home/user/project\",\n \"mcpServers\": [\n {\n \"name\": \"filesystem\",\n \"command\": \"/path/to/mcp-server\",\n \"args\": [\n \"--stdio\"\n ],\n \"env\": []\n }\n ]\n }\n}\n```\n\n*A `session/new` JSON-RPC 2.0 request supplies the workspace path (`cwd`) and MCP server launch configurations (`mcpServers`); the agent responds on the matching `id` with a unique `sessionId` (for example, `\"sess_abc123def456\"`). [8]*\n\n---\n\n## JSON-RPC session lifecycle and transport framing\n\nThe protocol allows agents and clients to communicate by exposing methods that each side can call and by sending notifications to inform each other of events. It follows the JSON-RPC 2.0 specification: methods are request-response pairs that expect a result or error, and notifications are one-way messages that do not expect a response. [4]\n\n- **Version negotiation:** Clients call `initialize` to establish the connection, negotiate versions, and exchange capabilities. The result carries `protocolVersion` and `agentCapabilities`, including `loadSession`. If `loadSession` is false or not present, clients MUST NOT call `session/load`. Negotiated `protocolVersion` fixes the wire shape, and exchanged capabilities select optional messages. [4][7][8]\n- **Optional authenticate:** If the agent requires it, the client completes an advertised authentication flow before creating a session, such as `authenticate` or a terminal launch-and-reconnect. Until that flow finishes, `session/new` may fail with `auth_required`. `logout` ends the authenticated state when `agentCapabilities.auth.logout` is advertised. [4][8]\n- **Session ids and MCP servers:** `session/new` sends the working directory and `mcpServers`, the MCP servers the agent should connect to, and the agent MUST respond with a unique `sessionId`. `session/load` is allowed only after `loadSession` is advertised, and it sends `sessionId`, `cwd`, and `mcpServers` again so the agent can replay the conversation as `session/update` notifications. The Client-Provided System Prompt RFD moved to Completed on November 6, 2026, stabilizing client `systemPrompt` on session setup requests and the `systemPrompt` session capability in the stable ACP protocol surfaces, including v1 session setup. [8][18]\n- **stdio versus remote drafts:** All ACP JSON-RPC 2.0 messages MUST be `UTF-8` encoded; on `stdio` (which agents and clients SHOULD support whenever possible), the client spawns the agent as a subprocess and frames `stdin` and `stdout` messages with newline delimiters (`\\n`) and no embedded newlines. For remote agents, the Transports Working Group is specifying a Streamable HTTP transport RFD alongside a Draft RFD covering both WebSockets and HTTP. [6][14]\n\n---\n\n## Prompt turns, client callbacks, and the ACP Registry\n\nEach user turn is a prompt: the client sends content blocks, the agent streams updates, and the agent calls back into the editor for permissions, files, and terminals. The stabilized ACP Agent Registry is the catalog clients use to discover and install agents. [4][19]\n\n- **Prompt turns:** `session/prompt` sends user content blocks, and model output streams through `session/update` notifications. `ContentBlock` is a superset of the MCP `2025-06-18` `ContentBlock`, so agents can forward MCP tool output unchanged. As a baseline, all agents must support both `text` and `resource_link` content blocks when included in prompts. The turn ends with a `session/prompt` stop reason, or the client sends `session/cancel`. [4][15]\n- **Client callbacks:** The agent requests tool authorization with `session/request_permission`. File reads and writes use `fs/read_text_file` and `fs/write_text_file` when the client advertised `fs.readTextFile` and `fs.writeTextFile`. Terminal management uses the `terminal/create`, `terminal/output`, `terminal/wait_for_exit`, `terminal/kill`, and `terminal/release` methods, each requiring the `terminal` capability. Because ACP agents run as local subprocesses with the host user's access to the machine, `session/request_permission` and client capability callbacks are cooperative rather than an OS sandbox: `goose` documentation states that permission callbacks are not a sandbox and tools run with the backend's access to the machine, and Zed's sandboxing documentation states that Zed Agent sandboxing does not sandbox `External Agents`. [4][20][21]\n- **MCP-over-ACP:** The `MCP-over-ACP` draft lets a client or proxy supply tools on the ACP connection it already has, by declaring an MCP server of type `acp` and sending requests to its `serverId`. Results and cancellation travel over ACP with no second process or network endpoint. It targets MCP `2026-07-28` only, and ACP initialization and sessions remain unchanged. [17]\n- **Registry manifest:** On March 9, 2026 the registry stabilized, with a curated catalog and a shared manifest format for discovery, install, and configuration. Clients fetch `registry.json`, where top-level `version` is `1.0.0` and each agent can include `distribution` data such as an `npx` package or a `binary` archive. Zed and JetBrains IDEs ship built-in registry support. [19][22][23][24]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **JSON-RPC 2.0 Specification** | `JSON-RPC 2.0` | Profiles classic standard | Profiles JSON-RPC 2.0 bidirectional request-response methods and one-way `session/update` notifications for multi-turn coding sessions, adding reverse agent-to-editor callbacks (`session/request_permission`, `fs/read_text_file`, `fs/write_text_file`, and `terminal/create`). [4] |\n| **Language Server Protocol (LSP)** | `LSP` | Analogous to classic standard | Whereas the Language Server Protocol (LSP) unbundled static language intelligence (autocomplete, diagnostics, go-to-definition) from monolithic IDEs, ACP applies the same client-server decoupling to multi-turn AI coding agents so developers can switch agents without switching editors. [1] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | MCP uses JSON-RPC 2.0 between a host, the host's client, and a server that can offer resources, prompts, and tools. ACP is the editor-to-coding-agent session; when an ACP client creates a session, it may include connection details for MCP servers the agent should connect to. [3][8][25] |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Complements | A2A coordinates task delegation between opaque remote agents discovered via `GET /.well-known/agent-card.json` over HTTP or gRPC, whereas ACP couples an interactive code editor UI to a coding agent with workspace diff, file, and terminal callbacks. [3][26] |\n| **[Agent-User Interaction Protocol (AG-UI)](/protocols/ag-ui/)** | Peer alternative | AG-UI streams frontend UI state events from a backend agent after an HTTP `POST` (`HTTP + SSE` or `HTTP + Protobuf`), whereas ACP mediates an IDE coding session in which the agent also calls back into the editor for file reads/writes, terminals, and tool permissions. [4][27][28] |\n| **[AGENTS.md](/protocols/agents-md/)** | Complements | `AGENTS.md` is a static repository-root Markdown file providing project instructions and conventions, whereas ACP defines the live bidirectional session wire protocol between the code editor and the coding agent. [3][29] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (11 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Native ACP coding agents\n\n| Actor | Role | Status | Transport, capabilities & scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Google Gemini CLI** | Native CLI coding agent (reference implementation) | Supported · as of 2025-08-27 | Native `gemini --acp` mode speaking `JSON-RPC 2.0` over `stdio`; initial ACP reference implementation with Zed. | [Gemini CLI ACP mode](https://geminicli.com/docs/cli/acp-mode/) [30] · [Bring Your Own Agent to Zed](https://zed.dev/blog/bring-your-own-agent-to-zed) [1] |\n| **Block goose** | Native CLI coding agent & desktop client | Supported · checked 2026-10-30 | Native `goose acp` subprocess over `stdio` and `goose serve` daemon at `http://127.0.0.1:3284/acp`. | [goose ACP guide](https://goose-docs.ai/docs/gdk/acp/) [20] |\n| **GitHub Copilot CLI** | Native CLI coding agent | Supported (preview) · as of 2026-01-28 | Public preview `--acp` server on `copilot` over `--stdio` (default) or `--port` TCP, launched 2026-01-28. | [Copilot CLI ACP server](https://docs.github.com/en/copilot/reference/copilot-cli-reference/acp-server) [31] · [Copilot CLI ACP public preview](https://github.blog/changelog/2026-01-28-acp-support-in-copilot-cli-is-now-in-public-preview/) [32] |\n| **AWS Kiro** | Standalone coding agent & client harness | Supported (release announcement) · as of 2026-08-06 | Uses ACP over local `stdio` and `WebSocket` between Kiro clients and agent with `_kiro/` extensions. | [AWS Kiro on ACP (The New Stack)](https://thenewstack.io/kiro-agent-client-protocol/) [33] |\n\n### Editors & IDE host clients\n\n| Actor | Role | Status | Host surface & transport | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Zed** | Native code editor client (co-steward) | Supported · as of 2026-01-28 | Native ACP client hosting `External Agents` in the `Agent Panel` with built-in `zed: acp registry`. | [Zed External Agents](https://zed.dev/docs/ai/external-agents) [34] · [The ACP Registry is Live](https://zed.dev/blog/acp-registry) [24] |\n| **JetBrains IDEs** | Native IDE client (co-steward) | Supported · as of 2026-01-28 | Built-in ACP client and `ACP Registry` in JetBrains IDEs `2025.3`+ consuming `registry-for-jetbrains.json`. | [JetBrains and Zed on ACP](https://blog.jetbrains.com/ai/2025/10/jetbrains-zed-open-interoperability-for-ai-coding-agents-in-your-ide/) [2] · [ACP Agent Registry in JetBrains IDEs](https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/) [35] · [ACP Registry repository](https://github.com/agentclientprotocol/registry) [16] |\n| **CodeCompanion.nvim** | Community Neovim client plugin | Partial · as of 2025-08-27 | Neovim plugin supporting `JSON-RPC 2.0` sessions, `readTextFile`, and `writeTextFile`; omits agent plans and terminals. | [CodeCompanion ACP](https://codecompanion.olimorris.dev/agent-client-protocol) [36] · [CodeCompanion changelog](https://github.com/olimorris/codecompanion.nvim/blob/main/CHANGELOG.md) [37] |\n| **Emacs agent-shell** | Community Emacs client package | Development · as of 2025-09-25 | Initial native Emacs shell on `comint-mode` built on the `acp.el` Emacs Lisp ACP client. | [Introducing Emacs agent-shell](https://xenodium.com/introducing-agent-shell) [38] |\n\n### External bridge adapters & official SDKs\n\n| Actor | Role | Status | Target runtime / SDK languages | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Claude Agent (claude-agent-acp)** | External ACP adapter (Claude Agent SDK) | Listed integration · checked 2026-10-30 | External adapter (`@agentclientprotocol/claude-agent-acp`) wrapping the `Claude Agent SDK` with `@-mentions`, terminals, subagents, and `/mcp`. | [claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) [39] · [ACP Registry](https://agentclientprotocol.com/get-started/registry) [22] |\n| **OpenAI Codex (codex-acp)** | External ACP adapter (Codex App Server) | Listed integration · checked 2026-10-30 | External `stdio` adapter (`@agentclientprotocol/codex-acp`) translating ACP requests into `Codex App Server` operations. | [codex-acp](https://github.com/agentclientprotocol/codex-acp) [40] · [ACP Registry](https://agentclientprotocol.com/get-started/registry) [22] |\n| **Official ACP SDKs** | Official client & agent SDKs | Supported · as of 2026-11-02 | Official client and agent SDKs: Rust `agent-client-protocol` (`v1.15.1`), TypeScript `@agentclientprotocol/sdk`, Python `python-sdk`, Kotlin `acp-kotlin`, Java `java-sdk`. | [ACP repository](https://github.com/agentclientprotocol/agent-client-protocol) [7] · [ACP updates](https://agentclientprotocol.com/updates) [9] · [ACP releases](https://github.com/agentclientprotocol/agent-client-protocol/releases) [11] |\n\n### Ecosystem censuses\n\n- **Official ACP Registry (Available Agents index)** (*as of 2026-10-30*): 43 authenticated coding agents and external ACP adapters—including Gemini CLI, goose, GitHub Copilot, Junie, Kimi CLI, Mistral Vibe, OpenCode, OpenCode V2, Qwen Code, Claude Agent, and Codex—are listed in the curated Available Agents directory and verified in CI to return valid `authMethods` during the ACP handshake, with package versions synced hourly across npm, PyPI, and GitHub releases. [16][22]\n- **cdn.agentclientprotocol.com registry.json (version 1.0.0)** (*as of 2026-11-06*): 45 agent manifest entries appear in the top-level `agents` array of `registry.json` (`version` `1.0.0`) at `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. [23]\n\n---\n\n## See also\n\n- **[Open Responses](/protocols/open-responses/)** *(Peer alternative)* — ACP is JSON-RPC 2.0 over a local agent subprocess. Open Responses is HTTP `/v1/responses`, with an optional 2026-04-24 WebSocket.\n- **Category:** [Act protocols](/category/act/)\n\n---\n\n## References\n\n1. Nathan Sobo (Zed Industries), *Bring Your Own Agent to Zed — Featuring Gemini CLI* (published 2025-08-27) — \n2. Denis Shiryaev (JetBrains), *JetBrains × Zed: Open Interoperability for AI Coding Agents in Your IDE* (published 2025-10-06) — \n3. Agent Client Protocol, *Introduction* (checked 2026-10-30) — \n4. Agent Client Protocol, *Overview (protocol v1)* (checked 2026-10-30) — \n5. Agent Client Protocol, *Governance* (checked 2026-10-30) — \n6. Agent Client Protocol, *Transports (protocol v1)* (checked 2026-10-30) — \n7. agentclientprotocol, *Agent Client Protocol (ACP)* (repository created 2025-06-23; checked 2026-10-30) — \n8. Agent Client Protocol, *Session Setup (protocol v1)* (checked 2026-10-30) — \n9. Agent Client Protocol, *Updates* (checked 2026-10-30) — \n10. Agent Client Protocol, *ACP v2 is available in Draft* (published 2026-07-20) — \n11. Agent Client Protocol, *agentclientprotocol/agent-client-protocol releases* (checked 2026-11-09) — \n12. agentclientprotocol (acp-release-bot), *Schema v1.31.0* (published 2026-11-10) — \n13. Agent Client Protocol, *Requests for Dialog (RFDs)* (checked 2026-10-30) — \n14. Agent Client Protocol, *Transports Working Group* (published 2026-04-22) — \n15. Agent Client Protocol, *Content (protocol v1)* (checked 2026-10-30) — \n16. agentclientprotocol, *ACP Registry* (checked 2026-10-30) — \n17. Agent Client Protocol, *MCP-over-ACP: Stateless MCP Requests over ACP* (checked 2026-10-30) — \n18. Agent Client Protocol, *Client-provided system prompts are stabilized* (published 2026-11-06) — \n19. Agent Client Protocol, *ACP Registry is stabilized* (published 2026-03-09) — \n20. goose, *Build an app with goose (ACP)* (checked 2026-10-30) — \n21. Zed, *Sandboxing* (checked 2026-11-08) — \n22. Agent Client Protocol, *ACP Registry* (checked 2026-10-30) — \n23. Agent Client Protocol, *ACP registry.json (v1 latest)* (checked 2026-11-06) — \n24. Ben Brandt (Zed Industries), *The ACP Registry is Live* (published 2026-01-28) — \n25. Model Context Protocol, *Specification (2026-07-28)* (version 2026-07-28) — \n26. A2A Protocol, *Agent2Agent (A2A) Protocol Specification* (checked 2026-10-30) — \n27. Agent User Interaction Protocol, *Specification 1.0* (modified 2026-09-17) — \n28. CopilotKit, *Introducing AG-UI: The Protocol Where Agents Meet Users* (checked 2026-10-30) — \n29. AGENTS.md, *AGENTS.md* (checked 2026-10-30) — \n30. Google (Gemini CLI), *ACP Mode* (checked 2026-10-30) — \n31. GitHub, *Copilot CLI ACP server* (checked 2026-10-30) — \n32. Allison (GitHub Changelog), *ACP support in Copilot CLI is now in public preview* (published 2026-01-28) — \n33. Janakiram MSV (The New Stack), *Free agents: How AWS Kiro could untie agents from editors* (published 2026-08-06) — \n34. Zed, *External Agents* (checked 2026-10-30) — \n35. Jan-Niklas Wortmann (JetBrains), *ACP Agent Registry Is Live: Find and Connect AI Coding Agents in Your JetBrains IDE* (published 2026-01-28) — \n36. CodeCompanion.nvim, *Agent Client Protocol (ACP)* (checked 2026-10-30) — \n37. olimorris (CodeCompanion.nvim), *CHANGELOG.md* (17.18.0 dated 2025-08-27; page checked 2026-10-30) — \n38. Álvaro Ramírez (xenodium), *Introducing Emacs agent-shell (powered by ACP)* (published 2025-09-25) — \n39. agentclientprotocol, *claude-agent-acp* (checked 2026-10-30) — \n40. agentclientprotocol, *codex-acp* (checked 2026-10-30) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "ACP", "adoption": { "level": "unmeasured", "by": null, "probe_run": null }, "aliases": [ "Agent Communication Protocol", "ACP" ], "analog": "none", "collisions": [ "Agent Client Protocol (Zed)", "Agentic Commerce Protocol (OpenAI/Stripe)", "Agent Connect Protocol (AGNTCY)" ], "discovery": { "mechanism": "GET /agents (Agent Discovery endpoint)", "path": "/agents" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://github.com/i-am-bee/acp", "claim": "BeeAI project (i-am-bee), *i-am-bee/acp*, archived Aug 27, 2025; fetched 2026-10-31", "date": null, "quote": "This repository was archived by the owner on Aug 27, 2025. It is now read-only. ... ACP is now part of A2A under the Linux Foundation / \"full_name\": \"i-am-bee/acp\" ... \"created_at\": \"2025-04-03T08:40:43Z\" / \"pushed_at\": \"2025-08-25T18:42:36Z\" ... \"archived\": true / This repository was archived by the owner on Aug 27, 2025. It is now read-only. / 100%;\\\"\\u003e\\u003c/a\\u003e\\n\\u003ca href=\\\"https://github.com/i-am-bee/beeai-framework?tab=Apache-2.0-1-ov-file#readme\\\"\\u003e\\u003cimg / \"url\": \"https://api.github.com/users/i-am-bee\", / \"full_name\": \"i-am-bee/acp\" / 🛠️ \\u003ca href=\\\"https://github.com/i-am-bee/beeai-platform/blob/main/docs/community-and-support/acp-a2a-migration-guide.mdx\\\"\\u003eMigration / data-snippet-clipboard-copy-content=\\\"curl -X POST http://localhost:8000/runs \\\\\\n -H \\u0026quot;Content-Type: application/json\\u0026quot; \\\\\\n -d '{\\n \\u0026quot;agent_name\\u0026quot;:", "ref": 1 }, { "label": "[2]", "url": "https://raw.githubusercontent.com/i-am-bee/acp/main/README.md", "claim": "BeeAI project (i-am-bee), *Agent Communication Protocol README*, fetched 2026-10-31", "date": null, "quote": "ACP is an open protocol for communication between AI agents, applications, and humans. / ACP enables agents to: - Send and receive rich messages - like text, code, files, or media - Respond in real time, in the background, or as a stream - Let others discover what they can do - Collaborate on long-running tasks - Share state with each other when needed / Developed by contributors to the BeeAI project, this initiative is part of the Linux Foundation AI & Data program. / ACP is now part of A2A under the Linux Foundation! / Modern AI agents are often built in isolation, across different frameworks, teams, and infrastructures. This fragmentation slows innovation and makes it harder for agents to work together effectively. / ACP solves this by enabling agents to communicate and coordinate using multimodal messages. ... A single agent execution with specific inputs. Supports sync or streaming, with intermediate and final output. ... Let agents pause to request information from the client and resume, enabling interactive exchanges where the agent can wait for external input (data, actions, etc.) before continuing. / A model describing an agent's capabilities-its name, description, and optional metadata and status-for discovery and composition without exposing implementation details.", "ref": 2 }, { "label": "[3]", "url": "https://raw.githubusercontent.com/i-am-bee/acp/main/docs/spec/openapi.yaml", "claim": "BeeAI project (i-am-bee), *ACP OpenAPI specification 0.2.0*, version 0.2.0; fetched 2026-10-31", "date": null, "quote": "The Agent Communication Protocol (ACP) provides a standardized RESTful API for managing, orchestrating, and executing AI agents. It supports synchronous, asynchronous, and streamed agent interactions, with both stateless and stateful execution modes. ... version: 0.2.0 / Returns a ping. ... summary: Agent Discovery description: Returns a list of agents. ... Returns a manifest of the specified agent. ... Create and start a new run for the specified agent. ... Resume a paused or awaiting run. ... Cancel the specified run. / license: name: Apache 2.0 ... version: 0.2.0 / openapi: 3.1.1 info: title: ACP - Agent Communication Protocol description: >- The Agent Communication / immediate) content: application/json: schema: $ref: \"#/components/schemas/Run\" text/event-stream: schema: $ref: \"#/components/schemas/Event\" \"202\": description: Run accepted / responses: \"200\":description: Ping successful content: application/json: schema: type: object default: $ref: \"#/components/responses/Error\" /agents: get: / license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html / enum: - created - in-progress - awaiting - cancelling - cancelled - completed - failed description: Status of the run RunMode: type: string enum: [sync, async, stream] description: Mode of the request / A part of a message, containing a specific `content_type` and either inline `content` or `content_url`, or neither. Only one of `content` or `content_url` can be provided. / history: type: array items: type: string format: uri state: type: string format: uri required: - id - history / enum: - server_error - invalid_input - not_found / openapi: 3.1.1 info: title: ACP - Agent Communication Protocol", "ref": 3 }, { "label": "[4]", "url": "https://github.com/i-am-bee/acp/releases/tag/v1.0.3", "claim": "BeeAI project (i-am-bee), *Release v1.0.3*, published 2025-08-21; fetched 2026-10-31", "date": null, "quote": "\"tag_name\": \"v1.0.3\" ... \"published_at\": \"2025-08-21T05:31:04Z\" ... fix(python): revert cachetools version bump to avoid conflicts", "ref": 4 }, { "label": "[5]", "url": "https://spec.openapis.org/oas/v3.1.0.html", "claim": "OpenAPI Initiative, *OpenAPI Specification v3.1.0*, 2021-02-15", "date": "2021-02-15", "quote": "OpenAPI Specification v3.1.0 Version 3.1.0", "ref": 5 }, { "label": "[6]", "url": "https://aaif.io/blog/a2a-joins-aaif", "claim": "Agentic AI Foundation, *A2A joins AAIF's open agentic stack*, published 2026-08-17; modified 2026-09-24", "date": null, "quote": "A2A v1.0, the first stable specification, shipped in March 2026.", "ref": 6 }, { "label": "[7]", "url": "https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Versioning — Model Context Protocol Documentation*, 2026-07-28", "date": "2026-07-28", "quote": "Current : the current protocol version, which is ready for use and may continue to receive backwards compatible changes.", "ref": 7 }, { "label": "[8]", "url": "https://github.com/agntcy/oasf/releases", "claim": "AGNTCY, *agntcy/oasf releases*, checked 2026-10-31", "date": null, "quote": "\"html_url\": \"https://github.com/agntcy/oasf/releases/tag/v1.1.0\", \"id\": 352159727, \"author\": { \"login\": \"github-actions[bot]\", \"id\": 41898282, \"node_id\": \"MDM6Qm90NDE4OTgyODI=\", \"avatar_url\":", "ref": 8 } ], "form": "endpoint", "governance": "Formerly IBM BeeAI; archived, functionality merged into A2A under the Linux Foundation", "group": "Protocols called ACP", "history": [ { "date": "2026-09-06", "note": "verified against github.com/i-am-bee/acp (archived banner, archive date) and its OpenAPI spec; set phase withdrawn as merged into A2A" }, { "date": "2026-09-06", "note": "collisions updated to add Agent Connect Protocol (Cisco/AGNTCY), verified against github.com/agntcy/acp-spec, spec.acp.agntcy.org" }, { "date": "2026-10-16", "note": "IBM's Agent Communication Protocol is deprecated (merged into A2A)" }, { "date": "2026-10-16", "note": "version v1.0.3" }, { "date": "2026-10-16", "note": "No push since 2025-08-25 (over 180 days)" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "agent-communication-protocol", "implementation": "none-found", "last_verified": "2026-11-12", "name": "Agent Communication Protocol", "native_status": "\"ACP is now part of A2A under the Linux Foundation\" (repository banner)", "origin": { "date": "2025", "org": "IBM (BeeAI)" }, "part_of": null, "parties": [ "agent-agent", "agent-human" ], "phase": "replaced", "probe": { "method": "GET", "on_absent": "Expected: the protocol was retired in August 2025 and superseded by A2A, so absence is the normal case", "parse": "JSON array of agent objects would confirm a live ACP server; in practice the repository is archived and this is not expected to resolve on new deployments", "path": "{origin}/agents" }, "question": "How did agents, applications, and people exchange multimodal REST messages before merging into A2A?", "scope": "general", "spec_url": "https://github.com/i-am-bee/acp", "step": "coordinate", "summary_md": "**Agent Communication Protocol** (`ACP`) is an open protocol for communication between AI agents, applications, and humans. It enables agents to send and receive rich messages such as text, code, files, or media, to respond in real time, in the background, or as a stream, to let others discover what they can do, to collaborate on long-running tasks, and to share state with each other when needed. The `i-am-bee/acp` repository was created on 2025-04-03. Contributors to the BeeAI project developed the initiative as part of the Linux Foundation AI & Data program. The README states that ACP is now part of A2A under the Linux Foundation. OpenAPI version `0.2.0` describes a standardized RESTful API for managing, orchestrating, and executing AI agents. It supports synchronous, asynchronous, and streamed agent interactions, with both stateless and stateful execution modes. `/ping` returns a ping, `/agents` returns a list of agents, and `/agents/{name}` returns a manifest of the specified agent. `/runs` creates and starts a new run for the specified agent. A paused or awaiting run is resumed at `/runs/{run_id}`, and the specified run is cancelled at `/runs/{run_id}/cancel`. The OpenAPI license name is Apache 2.0 and the info `version` is `0.2.0`. Release `v1.0.3` was published on 2025-08-21, and the release body is `fix(python): revert cachetools version bump to avoid conflicts`. The `i-am-bee/acp` repository received its final push on `2025-08-25` and was archived by its owner as read-only on Aug 27, 2025.", "track": "linux-foundation", "version": { "label": "v1.0.3", "date": "2025-08-21" }, "watch": [ { "type": "github", "repo": "i-am-bee/acp", "mode": "release" } ], "use_cases": [ "agent-to-agent-messaging", "describe-agent-capabilities" ], "audience": [ "agent-builder", "platform" ], "pairs_with": [ "a2a", "mcp", "oasf" ], "prerequisites": [], "hatnote_md": "*This page is about IBM and BeeAI's Agent Communication Protocol (`i-am-bee/acp`), an OpenAPI 3.1.1 REST and SSE specification (`/agents`, `/runs`) whose repository was archived into A2A under the Linux Foundation in August 2025. It is not AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/) or Zed's [Agent Client Protocol](/protocols/agent-client-protocol/).*", "tier": "spec_brief", "lifecycle_status": "superseded", "wire_archetype": "harnesses_rpc_ui", "status_notice_md": "**Status notice (Merged & Archived):** The IBM / BeeAI Agent Communication Protocol (`ACP`) repository was archived read-only on `2025-08-27` after merging into [Agent2Agent (A2A)](/protocols/a2a/) under the Linux Foundation.", "superseded_by": [ { "doc": "Agent2Agent (A2A)", "protocol_id": "a2a", "url": "https://agenticweb.wiki/protocols/a2a/" } ], "replaced_by": { "doc": "Agent2Agent (A2A)", "page": "/protocols/a2a/" }, "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "**Status notice (Merged & Archived):** The IBM / BeeAI Agent Communication Protocol (`ACP`) repository was archived read-only on `2025-08-27` after merging into [Agent2Agent (A2A)](/protocols/a2a/) under the Linux Foundation. This page is about IBM and BeeAI's Agent Communication Protocol (`i-am-bee/acp`), an OpenAPI 3.1.1 REST and SSE specification (`/agents`, `/runs`) whose repository was archived into A2A under the Linux Foundation in August 2025. It is not AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/) or Zed's [Agent Client Protocol](/protocols/agent-client-protocol/). [1]", "v05_elevator_pitch_md": null, "v05_lead_md": "**Agent Communication Protocol** (`ACP`) is an open protocol for communication between AI agents, applications, and humans. It enables agents to send and receive rich messages such as text, code, files, or media, to respond in real time, in the background, or as a stream, to let others discover what they can do, to collaborate on long-running tasks, and to share state with each other when needed. [2] The `i-am-bee/acp` repository was created on 2025-04-03. [1] Contributors to the BeeAI project developed the initiative as part of the Linux Foundation AI & Data program. The README states that ACP is now part of A2A under the Linux Foundation. [2] OpenAPI version `0.2.0` describes a standardized RESTful API for managing, orchestrating, and executing AI agents. It supports synchronous, asynchronous, and streamed agent interactions, with both stateless and stateful execution modes. [3] `/ping` returns a ping, `/agents` returns a list of agents, and `/agents/{name}` returns a manifest of the specified agent. `/runs` creates and starts a new run for the specified agent. A paused or awaiting run is resumed at `/runs/{run_id}`, and the specified run is cancelled at `/runs/{run_id}/cancel`. [3] The OpenAPI license name is Apache 2.0 and the info `version` is `0.2.0`. Release `v1.0.3` was published on 2025-08-21, and the release body is `fix(python): revert cachetools version bump to avoid conflicts`. [3][4] The `i-am-bee/acp` repository received its final push on `2025-08-25` and was archived by its owner as read-only on Aug 27, 2025. [1]", "v05_identity_sentence_md": "**Agent Communication Protocol** (`ACP`) is an open protocol for communication between AI agents, applications, and humans. It enables agents to send and receive rich messages such as text, code, files, or media, to respond in real time, in the background, or as a stream, to let others discover what they can do, to collaborate on long-running tasks, and to share state with each other when needed. [2] The `i-am-bee/acp` repository was created on 2025-04-03. [1] Contributors to the BeeAI project developed the initiative as part of the Linux Foundation AI & Data program. The README states that ACP is now part of A2A under the Linux Foundation. [2]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Coordinate](/category/coordinate/) (`coordinate`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "IBM / BeeAI Project (`i-am-bee`) [1]" }, { "label": "Governed by", "value_md": "IBM BeeAI Project (`i-am-bee`), archived 2025-08-27 and merged into A2A under the Linux Foundation [1][2]" }, { "label": "Track", "value_md": "Open-source project specification (`i-am-bee/acp`, archived and merged into A2A under the Linux Foundation) [1][2]" }, { "label": "Status", "value_md": "Archived (`2025-08-27`, read-only); README states \"ACP is now part of A2A under the Linux Foundation\" [1][2]" }, { "label": "Version", "value_md": "OpenAPI Spec `0.2.0`; final SDK/repo release `v1.0.3` (2025-08-21, archived) [1][3][4]" }, { "label": "Wire format", "value_md": "HTTP/1.1 or HTTP/2 REST (`application/json`) and Server-Sent Events (`text/event-stream`) defined in OpenAPI 3.1.1 [3]" }, { "label": "Specification", "value_md": "https://github.com/i-am-bee/acp [1]" }, { "label": "Found at", "value_md": "`GET /agents`, `GET /agents/{name}`, `GET /ping`, `Content-Type: application/json` [1][3]" }, { "label": "Licence", "value_md": "Apache License 2.0 (`i-am-bee/acp`) [1][3]" } ], "v05_problem_md": "Modern AI agents are often built in isolation, across different frameworks, teams, and infrastructures. This fragmentation slows innovation and makes it harder for agents to work together effectively. [2] ACP solves this by enabling agents to communicate and coordinate using multimodal messages. A run is a single agent execution with specific inputs and supports sync or streaming, with intermediate and final output. Await lets an agent pause to request information from the client and resume, so the agent can wait for external input before continuing. [2] Run mode is `sync`, `async`, or `stream`. Run status is `created`, `in-progress`, `awaiting`, `cancelling`, `cancelled`, `completed`, or `failed`. [3] An agent manifest describes the agent's name, description, and optional metadata and status for discovery and composition without exposing implementation details. [2] A message part contains a specific `content_type` and either inline `content` or `content_url`, or neither, and only one of `content` or `content_url` can be provided. [3] Session `history` is an array of URI strings and `state` is a URI, and the required session fields are `id` and `history`. [3] An error `code` is `server_error`, `invalid_input`, or `not_found`. [3]", "v05_mechanism_delta_md": "ACP solves this by enabling agents to communicate and coordinate using multimodal messages. A run is a single agent execution with specific inputs and supports sync or streaming, with intermediate and final output. Await lets an agent pause to request information from the client and resume, so the agent can wait for external input before continuing. [2] Run mode is `sync`, `async`, or `stream`. Run status is `created`, `in-progress`, `awaiting`, `cancelling`, `cancelled`, `completed`, or `failed`. [3]", "v05_scope_boundary_md": "An agent manifest describes the agent's name, description, and optional metadata and status for discovery and composition without exposing implementation details. [2] A message part contains a specific `content_type` and either inline `content` or `content_url`, or neither, and only one of `content` or `content_url` can be provided. [3] Session `history` is an array of URI strings and `state` is a URI, and the required session fields are `id` and `history`. [3] An error `code` is `server_error`, `invalid_input`, or `not_found`. [3]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "OpenAPI Specification 3.1", "spec_or_rfc": "OpenAPI 3.1.1", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "IBM ACP's last published OpenAPI document, v0.2.0, exposed GET /ping, GET /agents with limit and offset, and a /runs family including POST /runs, and the repository was archived on 27 August 2025 with the banner that ACP is now part of A2A. [1][3][5]" } ], "agentic_peers": [ { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "superseded_by", "relation_label": "Superseded by", "delta_md": "IBM ACP is superseded by A2A at the governance level: its repository was archived on 27 August 2025 with the banner that ACP is now part of A2A under the Linux Foundation, while its wire surface remained an OpenAPI REST API at GET /ping, GET /agents, and POST /runs rather than A2A's JSON-RPC 2.0 and /.well-known/agent-card.json surface. [1][6]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "IBM ACP addressed remote agents with GET /agents and POST /runs on its archived OpenAPI surface, while MCP addresses tools, resources, and prompt templates over JSON-RPC 2.0 on stdio or Streamable HTTP. [1][7]" }, { "target_id": "oasf", "target_name": "Open Agentic Schema Framework", "relation_type": "complements", "relation_label": "Complements", "delta_md": "OASF is the AGNTCY schema for agent skills, domains, and modules, and IBM ACP's /agents path is not described as using that schema. [1][8]" } ] }, "v05_adoption": { "visible": false, "empty_state_note_md": null, "scope_note_md": null, "side_a": null, "side_b": null, "additional_tables": null, "censuses": [], "footer_md": null }, "v05_see_also": [ { "target_id": "nlip", "target_name": "Natural Language Interaction Protocol (NLIP)", "relation_label": "Peer alternative", "delta": "ACP's repository was archived by the owner on 27 August 2025 and states that ACP is now part of A2A under the Linux Foundation. Its OpenAPI document exposes GET /agents and POST /runs. NLIP's HTTP binding accepts an ECMA-430 JSON message with POST at the path /nlip.", "item_md": "**[Natural Language Interaction Protocol (NLIP)](/protocols/nlip/)** (Peer alternative) — ACP's repository was archived by the owner on 27 August 2025 and states that ACP is now part of A2A under the Linux Foundation. Its OpenAPI document exposes GET /agents and POST /runs. NLIP's HTTP binding accepts an ECMA-430 JSON message with POST at the path /nlip." }, { "target_id": "agtp", "target_name": "Agent Transfer Protocol", "relation_label": "Complements", "delta": "AGTP draft-10 frames ACP as an AGMP layer above AGTP's transport-level semantic methods and agent identity, while IBM ACP's archived OpenAPI surface was GET /agents and POST /runs before the repository was archived into A2A on 2025-08-27.", "item_md": "**[Agent Transfer Protocol](/protocols/agtp/)** (Complements) — AGTP draft-10 frames ACP as an AGMP layer above AGTP's transport-level semantic methods and agent identity, while IBM ACP's archived OpenAPI surface was GET /agents and POST /runs before the repository was archived into A2A on 2025-08-27." }, { "item_md": "**[Coordinate protocols](/category/coordinate/)** — Category index for `coordinate` standards." } ], "v05_compiled_md": "---\nid: agent-communication-protocol\ntitle: \"Agent Communication Protocol\"\ntier: spec_brief\nlifecycle_status: superseded\ncategory: coordinate\nform: endpoint\nwire_archetype: harnesses_rpc_ui\nspec_url: https://github.com/i-am-bee/acp\nlast_checked: 2026-11-12\n---\n\n# Agent Communication Protocol\n\n**Category:** [Coordinate](/category/coordinate/) (`coordinate`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-12\n\n> ***Status notice (Merged & Archived):** The IBM / BeeAI Agent Communication Protocol (`ACP`) repository was archived read-only on `2025-08-27` after merging into [Agent2Agent (A2A)](/protocols/a2a/) under the Linux Foundation. This page is about IBM and BeeAI's Agent Communication Protocol (`i-am-bee/acp`), an OpenAPI 3.1.1 REST and SSE specification (`/agents`, `/runs`) whose repository was archived into A2A under the Linux Foundation in August 2025. It is not AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/) or Zed's [Agent Client Protocol](/protocols/agent-client-protocol/). [1]*\n\n**Agent Communication Protocol** (`ACP`) is an open protocol for communication between AI agents, applications, and humans. It enables agents to send and receive rich messages such as text, code, files, or media, to respond in real time, in the background, or as a stream, to let others discover what they can do, to collaborate on long-running tasks, and to share state with each other when needed. [2] The `i-am-bee/acp` repository was created on 2025-04-03. [1] Contributors to the BeeAI project developed the initiative as part of the Linux Foundation AI & Data program. The README states that ACP is now part of A2A under the Linux Foundation. [2] OpenAPI version `0.2.0` describes a standardized RESTful API for managing, orchestrating, and executing AI agents. It supports synchronous, asynchronous, and streamed agent interactions, with both stateless and stateful execution modes. [3] `/ping` returns a ping, `/agents` returns a list of agents, and `/agents/{name}` returns a manifest of the specified agent. `/runs` creates and starts a new run for the specified agent. A paused or awaiting run is resumed at `/runs/{run_id}`, and the specified run is cancelled at `/runs/{run_id}/cancel`. [3] The OpenAPI license name is Apache 2.0 and the info `version` is `0.2.0`. Release `v1.0.3` was published on 2025-08-21, and the release body is `fix(python): revert cachetools version bump to avoid conflicts`. [3][4] The `i-am-bee/acp` repository received its final push on `2025-08-25` and was archived by its owner as read-only on Aug 27, 2025. [1]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Coordinate](/category/coordinate/) (`coordinate`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | IBM / BeeAI Project (`i-am-bee`) [1] |\n| **Governed by** | IBM BeeAI Project (`i-am-bee`), archived 2025-08-27 and merged into A2A under the Linux Foundation [1][2] |\n| **Track** | Open-source project specification (`i-am-bee/acp`, archived and merged into A2A under the Linux Foundation) [1][2] |\n| **Status** | Archived (`2025-08-27`, read-only); README states \"ACP is now part of A2A under the Linux Foundation\" [1][2] |\n| **Version** | OpenAPI Spec `0.2.0`; final SDK/repo release `v1.0.3` (2025-08-21, archived) [1][3][4] |\n| **Wire format** | HTTP/1.1 or HTTP/2 REST (`application/json`) and Server-Sent Events (`text/event-stream`) defined in OpenAPI 3.1.1 [3] |\n| **Specification** | https://github.com/i-am-bee/acp [1] |\n| **Found at** | `GET /agents`, `GET /agents/{name}`, `GET /ping`, `Content-Type: application/json` [1][3] |\n| **Licence** | Apache License 2.0 (`i-am-bee/acp`) [1][3] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [See also](#see-also)\n4. [References](#references)\n\n---\n\n## Problem and scope\n\nModern AI agents are often built in isolation, across different frameworks, teams, and infrastructures. This fragmentation slows innovation and makes it harder for agents to work together effectively. [2] ACP solves this by enabling agents to communicate and coordinate using multimodal messages. A run is a single agent execution with specific inputs and supports sync or streaming, with intermediate and final output. Await lets an agent pause to request information from the client and resume, so the agent can wait for external input before continuing. [2] Run mode is `sync`, `async`, or `stream`. Run status is `created`, `in-progress`, `awaiting`, `cancelling`, `cancelled`, `completed`, or `failed`. [3] An agent manifest describes the agent's name, description, and optional metadata and status for discovery and composition without exposing implementation details. [2] A message part contains a specific `content_type` and either inline `content` or `content_url`, or neither, and only one of `content` or `content_url` can be provided. [3] Session `history` is an array of URI strings and `state` is a URI, and the required session fields are `id` and `history`. [3] An error `code` is `server_error`, `invalid_input`, or `not_found`. [3]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **OpenAPI Specification 3.1** | `OpenAPI 3.1.1` | Profiles classic standard | IBM ACP's last published OpenAPI document, v0.2.0, exposed GET /ping, GET /agents with limit and offset, and a /runs family including POST /runs, and the repository was archived on 27 August 2025 with the banner that ACP is now part of A2A. [1][3][5] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Superseded by | IBM ACP is superseded by A2A at the governance level: its repository was archived on 27 August 2025 with the banner that ACP is now part of A2A under the Linux Foundation, while its wire surface remained an OpenAPI REST API at GET /ping, GET /agents, and POST /runs rather than A2A's JSON-RPC 2.0 and /.well-known/agent-card.json surface. [1][6] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | IBM ACP addressed remote agents with GET /agents and POST /runs on its archived OpenAPI surface, while MCP addresses tools, resources, and prompt templates over JSON-RPC 2.0 on stdio or Streamable HTTP. [1][7] |\n| **[Open Agentic Schema Framework](/protocols/oasf/)** | Complements | OASF is the AGNTCY schema for agent skills, domains, and modules, and IBM ACP's /agents path is not described as using that schema. [1][8] |\n\n---\n\n## See also\n\n- **[Natural Language Interaction Protocol (NLIP)](/protocols/nlip/)** *(Peer alternative)* — ACP's repository was archived by the owner on 27 August 2025 and states that ACP is now part of A2A under the Linux Foundation. Its OpenAPI document exposes GET /agents and POST /runs. NLIP's HTTP binding accepts an ECMA-430 JSON message with POST at the path /nlip.\n- **[Agent Transfer Protocol](/protocols/agtp/)** *(Complements)* — AGTP draft-10 frames ACP as an AGMP layer above AGTP's transport-level semantic methods and agent identity, while IBM ACP's archived OpenAPI surface was GET /agents and POST /runs before the repository was archived into A2A on 2025-08-27.\n- **Category:** [Coordinate protocols](/category/coordinate/)\n\n---\n\n## References\n\n1. BeeAI project (i-am-bee), *i-am-bee/acp* (archived Aug 27, 2025; fetched 2026-10-31) — \n2. BeeAI project (i-am-bee), *Agent Communication Protocol README* (fetched 2026-10-31) — \n3. BeeAI project (i-am-bee), *ACP OpenAPI specification 0.2.0* (version 0.2.0; fetched 2026-10-31) — \n4. BeeAI project (i-am-bee), *Release v1.0.3* (published 2025-08-21; fetched 2026-10-31) — \n5. OpenAPI Initiative, *OpenAPI Specification v3.1.0* (2021-02-15) — \n6. Agentic AI Foundation, *A2A joins AAIF's open agentic stack* (published 2026-08-17; modified 2026-09-24) — \n7. Model Context Protocol (AAIF / Linux Foundation), *Versioning — Model Context Protocol Documentation* (2026-07-28) — \n8. AGNTCY, *agntcy/oasf releases* (checked 2026-10-31) — \n" }, { "acronym": "ACP", "adoption": { "level": "observed", "by": "Etsy, Shopify, Walmart, Salesforce (Agentforce Commerce), commercetools, OpenAI (ChatGPT Instant Checkout), Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair, Stripe, and 3 other verified implementations", "probe_run": null }, "aliases": [ "ACP", "Agentic Commerce Protocol" ], "analog": "Checkout API", "collisions": [ "Agent Client Protocol (Zed)", "Agent Communication Protocol (IBM)", "ERC-8183 (also informally called Agentic Commerce Protocol)", "Agent Connect Protocol (AGNTCY)" ], "discovery": { "mechanism": "well-known", "path": "GET https://{domain}/.well-known/acp.json, the discovery document added in version 2026-04-17. No site was found serving it: the path returned HTTP 404 on www.etsy.com, www.shopify.com, www.urbanoutfitters.com, www.target.com, www.sephora.com, www.walmart.com, www.nordstrom.com, www.wayfair.com and www.agenticcommerce.dev (checked 2026-10-28)" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://web.archive.org/web/20261022061422/https://openai.com/index/buy-it-in-chatgpt/", "claim": "OpenAI, *Buy it in ChatGPT: Instant Checkout and the Agentic Commerce Protocol*, 2025-09-29 (Wayback snapshot 2026-10-22)", "date": null, "quote": "September 29, 2025 / Instant Checkout, powered by the Agentic Commerce Protocol, built with Stripe / built with Stripe / accept agentic payments either by using Stripe's new Shared Payment Token API / or adopting the Delegated Payments Spec in the Agentic Commerce Protocol / without changing their existing payment processor. / U.S. ChatGPT Plus, Pro, and Free users can now buy directly from U.S. Etsy sellers / Today, Instant Checkout supports single-item purchases. / over a million Shopify merchants, like Glossier, SKIMS, Spanx and Vuori, coming soon.", "ref": 1 }, { "label": "[2]", "url": "https://lfaidata.foundation/communityblog/2025/08/29/acp-joins-forces-with-a2a-under-the-linux-foundations-lf-ai-data/", "claim": "Kate Blair and Todd Segal, LF AI & Data, *ACP Joins Forces with A2A*, 2025-08-29", "date": "2025-08-29", "quote": "August 29, 2025 / IBM Research launched the Agent Communication Protocol (ACP) in March 2025 to power its BeeAI platform / ACP is officially merging with the A2A under the Linux Foundation", "ref": 2 }, { "label": "[3]", "url": "https://zed.dev/blog/bring-your-own-agent-to-zed", "claim": "Nathan Sobo, Zed, *Bring Your Own Agent to Zed — Featuring Gemini CLI*, 2025-08-27", "date": "2025-08-27", "quote": "August 27th, 2025 / we created the Agent Client Protocol (ACP) / interact with third-party agents directly within Zed", "ref": 3 }, { "label": "[4]", "url": "https://github.com/agntcy/acp-spec", "claim": "AGNTCY, *Agent Connect Protocol specification*, checked 2026-10-28", "date": null, "quote": "Agent Connect Protocol / defines a standard interface to invoke and configure remote agents over an API", "ref": 4 }, { "label": "[5]", "url": "https://eips.ethereum.org/EIPS/eip-8183", "claim": "Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce*, created 2026-02-25", "date": null, "quote": "Created 2026-02-25 / This specification defines the Agentic Commerce Protocol: a job with escrowed budget", "ref": 5 }, { "label": "[6]", "url": "https://ap2-protocol.org/ap2/specification/", "claim": "Google, *Agent Payments Protocol specification*, v0.2; checked 2026-10-30", "date": null, "quote": "Checkout Mandate / Payment Mandate / creating a user-signed mandate / Agentic Payment Protocol (v0.2) / The Trusted Surface role is a UI surface that is trusted to get informed user consent for an intent before creating a user-signed mandate.", "ref": 6 }, { "label": "[7]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/README.md", "claim": "OpenAI and Stripe, *Agentic Commerce Protocol README*, checked 2026-10-28", "date": null, "quote": "The Agentic Commerce Protocol (ACP) is an interaction model and open standard for connecting buyers, their AI agents, and businesses to complete purchases seamlessly. / The specification is maintained by OpenAI and Stripe and is currently in beta. / 2026-04-17/ # Cart, feed, orders, authentication, and MCP / All contributors must sign a CLA before contributions can be accepted. / ACP uses date-based versioning in YYYY-MM-DD format. / 2026-01-30/ # Extensions, discounts, payment handlers", "ref": 7 }, { "label": "[8]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.agentic_checkout.md", "claim": "OpenAI and Stripe, *RFC: Agentic Checkout — Merchant REST API*, Status Draft; Version 2026-01-16; checked 2026-10-28", "date": null, "quote": "1. Create - POST /checkout_sessions initializes a session from items and optional buyer/address. / Orders are processed entirely on the merchant's existing commerce stack. / POST /checkout_sessions/{checkout_session_id} → 200 OK / GET /checkout_sessions/{checkout_session_id} → 200 OK (or 404 if not found) / 4. Complete - POST /checkout_sessions/{id}/complete finalizes with a payment method and MUST create an order. / POST /checkout_sessions/{checkout_session_id}/cancel → 200 OK when canceled, 405 if already completed or canceled. / Clients MUST include an Idempotency-Key header on every POST request (create, update, complete, cancel). / Status: Draft / Version: 2026-01-16 / Authorization: Bearer (REQUIRED) / Content-Type: application/json (REQUIRED on requests with body) / Idempotency-Key: (REQUIRED on all POST requests; opaque string, max 255 characters, UUID v4 recommended) / Request-Id: (RECOMMENDED) / API-Version: 2026-01-16 (REQUIRED) / This RFC defines the Agentic Checkout Specification (ACS), a standardized REST API contract that merchants SHOULD implement to support experiences across agent platforms. / 2. Update - POST /checkout_sessions/{id} applies changes (items, address, fulfillment option). / 3. Retrieve - GET /checkout_sessions/{id} returns latest authoritative state. / 4. Complete - POST /checkout_sessions/{id}/complete finalizes with a payment method and must create an order. / 5. Cancel - POST /checkout_sessions/{id}/cancel / RFC: Agentic Checkout / The merchant remains the system of record for all orders, payments, taxes, and compliance. / Keep payments on merchant rails; optional delegated payments are covered separately. / Out of scope: PSP authorization/capture semantics, returns/exchanges workflows, tax configuration, fraud modeling details. / 1. **Create** — `POST /checkout_sessions` initializes a session from items and optional buyer/address. / 2. **Update** — `POST /checkout_sessions/{id}` applies changes (items, address, fulfillment option). / 3. **Retrieve** — `GET /checkout_sessions/{id}` returns latest authoritative state. / 4. **Complete** — `POST /checkout_sessions/{id}/complete` finalizes with a payment method and **MUST** create an order. / 5. **Cancel** — `POST /checkout_sessions/{id}/cancel` cancels if the session is not yet completed/canceled. / Keep **payments on merchant rails**; optional delegated payments are covered separately. / Scope: Checkout session lifecycle and webhook integration / Provide a stable, versioned API surface (API-Version: 2026-01-16) that ChatGPT calls to create, update, retrieve, complete, and cancel checkout sessions. / Ensure ChatGPT renders an authoritative cart state on every response. / Signature: (RECOMMENDED) / Timestamp: (RECOMMENDED) / Server SHOULD publish acceptable signature algorithms out‑of‑band; client SHOULD sign requests (Signature) over canonical JSON with an accompanying Timestamp (RFC 3339). / Order lifecycle updates (order_create, order_update) MUST be emitted to the application's webhook receiver (see Agentic Checkout Webhooks API RFC/OAS). / POST /checkout_sessions → 201 Created / status: not_ready_for_payment | ready_for_payment | completed | canceled | in_progress / line_items[] with base_amount, discount, subtotal, tax, total (all integers) / Response returns full authoritative state as in Create. / Response MUST include status: completed and an order with id, checkout_session_id, and permalink_url. / Server MUST set session.status to authentication_required when authentication (e.g., 3DS) is required. / When status is authentication_required, the session response MUST include authentication_metadata. / the client MUST attempt authentication using the provided metadata and MUST return the authentication_result / The key is an opaque string, max 255 characters; UUID v4 is RECOMMENDED. / \"code\": \"idempotency_key_required\" / The replayed response SHOULD include the header Idempotent-Replayed: true. / Same key + identical body → server MUST return the original response with the same HTTP status code. / Servers MUST retain idempotency key → response mappings for at least 24 hours. / Webhooks: Verify HMAC (Merchant-Signature) on webhook calls (see separate Webhooks RFC/OAS). / PCI/PII: Do not log full PAN/CVC; redact addresses as required by policy. TLS 1.3 MUST be used.", "ref": 8 }, { "label": "[9]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.delegate_payment.md", "claim": "OpenAI and Stripe, *RFC: Delegate Payment API*, Status Draft; Version 2025-09-29; checked 2026-10-28", "date": null, "quote": "The token may then be used by the merchant's existing PSP only within explicit Allowance constraints. / POST /agentic_commerce/delegate_payment / This RFC defines a single, MUST-implement HTTP endpoint that issues a delegated vault token for a payment credential. / Status: Draft / Version: 2025-09-29 / RFC: Agentic Commerce - Delegate Payment API / This RFC defines a **single, MUST-implement** HTTP endpoint that issues a **delegated vault token** for a payment credential. / allowance | Allowance | ✅ | Constraints on how the token may be used. / reason: MUST be one_time / max_amount: integer, minor units (e.g., $20 → 2000) / currency: string, lowercase ISO-4217 (e.g., usd) / checkout_session_id: string / merchant_id: string (≤256) / expires_at: RFC 3339 timestamp / The token MUST become invalid at or after allowance.expires_at. / The returned token MUST ONLY be usable within the provided Allowance (reason, max_amount, currency, expiry). / Out of scope: PSP-specific authorization/capture, multi-use tokens beyond allowance, refund semantics. / Payments, settlement, and compliance remain on the merchant's rails. / PII/PCI: Card data handling MUST follow applicable PCI DSS requirements; logs MUST NOT contain full PAN or CVC. / Transport: All requests MUST use HTTPS/TLS 1.3. / issues a delegated vault token for a payment credential. / delegated vault token for a payment credential / issues a delegated vault token for a payment credential", "ref": 9 }, { "label": "[10]", "url": "https://stripe.com/blog/developing-an-open-standard-for-agentic-commerce", "claim": "Jeff Weinstein and Steve Kaliski, Stripe, *Developing an open standard for agentic commerce*, 2025-09-29", "date": "2025-09-29", "quote": "codeveloped by Stripe and OpenAI / Developing an open standard for agentic commerce September 29, 2025 / September 29, 2025 / Jeff Weinstein / Steve Kaliski / ACP is open source, Apache 2.0 licensed, and community-designed.", "ref": 10 }, { "label": "[11]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/docs/governance.md", "claim": "OpenAI and Stripe, *ACP governance*, checked 2026-10-28", "date": null, "quote": "The TSC has up to 7 seats. / The TSC has up to 7 seats. Each seat is held by one organization, including OpenAI and Stripe. / TSC seats are appointed by the Founding Maintainers (OpenAI and Stripe) / the Founding Maintainers (OpenAI and Stripe) reserve a limited veto authority over TSC decisions. / the Founding Maintainers' veto authority may be exercised as a last resort. / The veto can only be used to block a change, never to override the TSC and force one through. / | 1 | OpenAI | aravindrao-openai | / | 2 | Stripe | prasad-stripe | / | 3 | Meta | lhwa |", "ref": 11 }, { "label": "[12]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.discovery.md", "claim": "OpenAI and Stripe, *RFC: ACP discovery document*, Status Proposal; version unreleased; checked 2026-10-28", "date": null, "quote": "This RFC introduces a well-known discovery document (/.well-known/acp.json) for the Agentic Commerce Protocol (ACP). / Status: Proposal / Version: unreleased / without requiring authentication. / The document allows agents to determine whether a seller supports ACP, which protocol version is available, what transports are offered, and what capabilities the seller provides, all before creating a checkout session and without requiring authentication. / /.well-known/acp.json", "ref": 12 }, { "label": "[13]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/changelog/2026-04-17.md", "claim": "OpenAI and Stripe, *Changelog 2026-04-17*, 2026-04-17; checked 2026-10-28", "date": null, "quote": "API Version: 2026-04-17 / Previous version 2026-01-30 deprecated / Added -- pre-checkout cart management for incremental basket building. / transports field advertises available transport bindings (rest, mcp) / an unreleased Feed API surface / Added -- discovery document at /.well-known/acp.json for pre-session capability checks. / Header value is t=,v1=<64_hex> / Signed payload is timestamp + \".\" + raw_body; HMAC-SHA256 with shared secret. / Recommended tolerance 300 seconds. / Specifies the Merchant-Signature header format for agentic checkout webhooks and adds replay protection. / POST /feeds for merchants to create feed metadata on an Agent-hosted feed service / This RFC defines a standardized REST API contract for delegated consumer authentication. / Automatically includes newly added schemas like schema.discount.json and schema.extension.json / OrderConfirmation: Added optional order_notes to echo order notes on confirmation. / This release promotes the accumulated unreleased ACP changes since 2026-01-30. / POST /carts -- Create a new cart with line items and optional buyer information. / GET /carts/{id} -- Retrieve the current state of a cart. / PUT /carts/{id} -- Update a cart (full replacement of line items). / POST /carts/{id}/cancel -- Cancel a cart and return its final state. / Carts have no status lifecycle - they either exist or return 404. / Carts have no payment data - payment is a checkout concern. / Totals on carts are estimates (e.g., tax may be omitted if address is unknown). / \"carts\" added to the capabilities.services enum in the discovery document (/.well-known/acp.json). / PATCH /feeds/{id}/products for merchants to partially upsert products by Product.id into the Agent-hosted feed / The Feed API is a push model: merchants push product catalog metadata and product records to Agents, rather than Agents pulling catalog data from merchant-hosted endpoints. / This RFC defines a standardized REST API contract for delegated consumer authentication. It enables agents to execute 3DS2 browser-based authentication directly with merchant specified authentication providers. / Established a session-based authentication lifecycle (Create → Authenticate → Retrieve) to manage 3DS2 states across asynchronous browser actions. / Added support for asynchronous notifications, including Fingerprint completion, Challenge results, and an optional RReq webhook to prevent browser-to-backend race conditions. / Cart-to-checkout conversion (via cart_id) and extension support (e.g., discounts) are deferred to follow-up SEPs. / Added optional order_notes (string, maxLength 5000) to CheckoutSessionCreateRequest, CheckoutSessionUpdateRequest, and CheckoutSessionCompleteRequest for delivery instructions, gift messages, and customer comments. / Added optional client_reference_id: reference provided by the client (agent/platform) when completing checkout; the merchant stores it on the order and returns it so the platform can reconcile its transaction / The Feed API is a push model: merchants push product catalog metadata and product records to Agents / pre-checkout cart management for incremental basket building", "ref": 13 }, { "label": "[14]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.product_feeds.md", "claim": "OpenAI and Stripe, *RFC: Product Feeds*, Status Proposal; version unreleased; checked 2026-10-28", "date": null, "quote": "Status: Proposal / Version: unreleased", "ref": 14 }, { "label": "[15]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol", "claim": "OpenAI and Stripe, *agentic-commerce-protocol repository*, created 2025-09-29; checked 2026-10-28", "date": null, "quote": "\"created_at\": \"2025-09-29T04:09:29Z\" / The specification is currently maintained by OpenAI and Stripe. / The Agentic Commerce Protocol (ACP) is an interaction model and open standard for connecting buyers, their AI agents, and businesses to complete purchases seamlessly. / \"spdx_id\": \"Apache-2.0\"", "ref": 15 }, { "label": "[16]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/commits/HEAD/docs/governance.md", "claim": "GitHub API, *Commit history of docs/governance.md*, checked 2026-10-28", "date": null, "quote": "\"date\": \"2025-12-02T00:44:03Z\" / Add Governance, Principles & process docs (#43) / \"date\": \"2026-03-10T17:28:47Z\" / ADMIN: Revised governance model (#173) / \"date\": \"2026-04-24T16:44:27Z\" / ADMIN: Add Meta as TSC member (#236)", "ref": 16 }, { "label": "[17]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/MAINTAINERS.md", "claim": "OpenAI and Stripe, *MAINTAINERS.md*, checked 2026-10-28", "date": null, "quote": "OpenAI / Stripe / Meta", "ref": 17 }, { "label": "[18]", "url": "https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/", "claim": "OpenAI, *Powering Product Discovery in ChatGPT*, 2026-03-24 (Wayback snapshot 2026-10-12)", "date": null, "quote": "March 24, 2026 / allowing merchants to use their own checkout experiences / focus our efforts on product discovery / We’ve found that the initial version of Instant Checkout did not offer the level of flexibility that we aspire to provide, so we’re allowing merchants to use their own checkout experiences while we focus our efforts on product discovery. / Walmart is introducing an in-ChatGPT app experience that takes users from discovery in ChatGPT into a tailored Walmart environment that supports account linking, loyalty and Walmart payments. / Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair have integrated into ACP for discovery. / Through ACP, merchants share product feeds and promotions", "ref": 18 }, { "label": "[19]", "url": "https://developers.openai.com/commerce", "claim": "OpenAI, *Agentic Commerce Protocol*, checked 2026-11-11", "date": null, "quote": "Agentic Commerce Protocol (ACP) is an open standard that serves as the connective layer between merchants and ChatGPT users. It enables ChatGPT to ingest structured catalog data, understand merchant inventory, and surface relevant products in context. / Agentic Commerce Protocol (ACP) is an open standard that serves as the connective layer between merchants and ChatGPT users.", "ref": 19 }, { "label": "[20]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/changelog/2025-09-29.md", "claim": "OpenAI and Stripe, *Changelog 2025-09-29*, 2025-09-29; checked 2026-10-28", "date": null, "quote": "Initial release of the Agentic Commerce Protocol specification.", "ref": 20 }, { "label": "[21]", "url": "https://www.agenticcommerce.dev/", "claim": "Agentic Commerce Protocol, *Agentic Commerce Protocol*, checked 2026-10-29", "date": null, "quote": "Publish your checkout configuration with a traditional API or MCP. / ACP is open source and community-designed under the Apache 2.0 license. / As transactions move from websites to AI workflows, the internet needs a new set of standards for open and secure commerce. / Let your users discover and transact directly with businesses in your application, without being the merchant of record. / while using your existing commerce infrastructure. / Create and control agent-facing endpoints that integrate with your existing commerce backend and payment processor. / Stripe is the first compatible PSP with its Shared Payment Token.", "ref": 21 }, { "label": "[22]", "url": "https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens", "claim": "Stripe, *Shared payment tokens*, checked 2026-10-28", "date": null, "quote": "Public preview / Shared payment tokens (SPTs) grant sellers scoped access to customers' payment methods for agent-initiated purchases. / After you receive a granted SharedPaymentToken, you can process the payment with Stripe or use the SPT with a third-party processor. / payment_method_data[shared_payment_granted_token]=spt_123 / usage_limits[currency]=usd / usage_limits[max_amount]=1000 / usage_limits[expires_at]=1798761600 / SPTs are available to agents, customers, and sellers in the US, Canada, and select European countries.", "ref": 22 }, { "label": "[23]", "url": "https://www.shopify.com/news/agentic-commerce-momentum", "claim": "Shopify, *Millions of merchants can sell in AI chats*, 2026-03-24", "date": "2026-03-24", "quote": "Crucially, merchants remain the merchant of record, retaining ownership of customer relationships and data. / March 24, 2026 / complete purchases via an in-app browser. / On desktop, ChatGPT links out directly to the merchant's store in a separate browser tab. / merchants remain the merchant of record", "ref": 23 }, { "label": "[24]", "url": "https://ucp.dev/latest/specification/overview/", "claim": "Universal Commerce Protocol, *Overview*, checked 2026-10-30", "date": null, "quote": "fetch business profile from /.well-known/ucp / URI advertised in UCP-Agent / REST transport (core) … Model Context Protocol (MCP) … Agent-to-Agent Protocol (A2A) … Embedded Protocol (EP)", "ref": 24 }, { "label": "[25]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "claim": "x402 Foundation, *X402 Protocol Specification*, Protocol Version 2; checked 2026-10-30", "date": null, "quote": "X402 Protocol Specification / Protocol Version: 2 / base64-encoded PAYMENT-REQUIRED response header / PAYMENT-SIGNATURE header is required / Facilitator interface: standard APIs for payment verification and settlement", "ref": 25 }, { "label": "[26]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification*, 2026-07-28", "date": "2026-07-28", "quote": "The protocol uses JSON-RPC 2.0 messages to establish communication between / prompts … resources … tools", "ref": 26 }, { "label": "[27]", "url": "https://developer.visa.com/docs/trusted-agent-protocol/trusted-agent-protocol-specifications", "claim": "Visa, *Trusted Agent Protocol specifications*, checked 2026-10-30", "date": null, "quote": "HTTP message signatures defined by RCF 9421 / This proves the agent's participation in the payment scheme specific program.", "ref": 27 }, { "label": "[28]", "url": "https://web.archive.org/web/20251220210109/https://www.etsy.com/news/meeting-buyers-where-they-are-etsy-partners-with-openai-to-enable-ai-powered-shopping", "claim": "Rafe Colburn, Etsy, *Meeting Buyers Where They Are: Etsy partners with OpenAI to enable AI-powered shopping*, 2025-09-29 (Wayback snapshot 2025-12-20)", "date": null, "quote": "Sep 29, 2025 / Starting today, ChatGPT users in the U.S. can discover, browse, and purchase items on Etsy directly through ChatGPT.", "ref": 28 }, { "label": "[29]", "url": "https://chatgpt.com/merchants/", "claim": "OpenAI, *ChatGPT merchants*, checked 2026-10-29", "date": null, "quote": "If you sell through Shopify or Etsy, your catalog is already integrated / purchases are completed on merchant-owned websites or apps.", "ref": 29 }, { "label": "[30]", "url": "https://www.shopify.com/news/shopify-open-ai-commerce", "claim": "Shopify, *Shopify and OpenAI bring commerce to ChatGPT*, 2025-09-29", "date": "2025-09-29", "quote": "September 29, 2025 / Shopify merchants will be able to sell directly through ChatGPT conversations", "ref": 30 }, { "label": "[31]", "url": "https://web.archive.org/web/20260302064248/https://help.openai.com/en/articles/6825453-chatgpt-release-notes/", "claim": "OpenAI Help Center, *ChatGPT release notes*, entry 2025-11-20; Wayback snapshot 2026-03-02", "date": null, "quote": "November 20, 2025 / Instant Checkout now rolling out to Shopify merchants / You can now find and buy from Shopify merchants starting with Spanx, Skims, and Glossier / You can now find and buy from Shopify merchants starting with Spanx, Skims, and Glossier through Instant Checkout in ChatGPT.", "ref": 31 }, { "label": "[32]", "url": "https://corporate.walmart.com/news/2025/10/14/walmart-partners-with-openai-to-create-ai-first-shopping-experiences", "claim": "Walmart, *Walmart Partners with OpenAI to Create AI-First Shopping Experiences*, 2025-10-14", "date": "2025-10-14", "quote": "Oct. 14, 2025 / allowing customers and members to soon shop Walmart through ChatGPT using Instant Checkout.", "ref": 32 }, { "label": "[33]", "url": "https://www.salesforce.com/news/press-releases/2025/10/14/stripe-openai-agentic-commerce-protocol-announcement/?bc=OTH", "claim": "Salesforce, *Salesforce Announces Support for Agentic Commerce Protocol with Stripe*, 2025-10-14", "date": "2025-10-14", "quote": "October 14, 2025 / today announced a collaboration with Stripe and OpenAI to build an Instant Checkout integration guided by the new Agentic Commerce Protocol (ACP).", "ref": 33 }, { "label": "[34]", "url": "https://commercetools.com/press-releases/commercetools-partners-with-stripe-to-launch-acp", "claim": "commercetools, *commercetools partners with Stripe in its launch of the ACP*, 2025-09-30", "date": "2025-09-30", "quote": "September 30, 2025 / joined Stripe and OpenAI as a launch partner of the Agentic Commerce Protocol (ACP).", "ref": 34 }, { "label": "[35]", "url": "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/agentic-payments-acp", "claim": "Adyen, *Agentic Payments integration with ACP checkout flow*, checked 2026-10-29", "date": null, "quote": "Learn to delegate payments to Adyen from your agent platform in the ACP checkout flow. / The merchant uses the token to process the payment with Adyen.", "ref": 35 }, { "label": "[36]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/changelog/2026-01-16.md", "claim": "OpenAI and Stripe, *Changelog 2026-01-16*, 2026-01-16; checked 2026-10-28", "date": null, "quote": "Added adyen to the provider enum for both PaymentProvider and AuthenticationProvider", "ref": 36 }, { "label": "[37]", "url": "https://developer.paypal.com/agent-ready/agentic-commerce-protocol", "claim": "PayPal Developer, *Agentic Commerce Protocol integration*, last updated 2026-10-29", "date": null, "quote": "Last updated: October 29, 2026 / Use this guide to build a custom ChatGPT app that accepts payments using the Agentic Commerce Protocol (ACP) and the ChatGPT Apps SDK. / configuring Braintree as your payment provider, processing delegated payment tokens", "ref": 37 }, { "label": "[38]", "url": "https://www.checkout.com/newsroom/checkout-adopts-acp-backed-by-openai-to-power-agentic-commerce-for-enterprise-merchants", "claim": "Checkout.com, *Checkout adopts ACP, backed by OpenAI, to power agentic commerce for enterprise merchants*, 2025-11-25", "date": "2025-11-25", "quote": "November 25, 2025 / today announced its support for the Agentic Commerce Protocol (ACP)", "ref": 38 } ], "form": "endpoint", "governance": "A Technical Steering Committee (TSC) of up to 7 seats, one per organization, appointed by the Founding Maintainers, OpenAI and Stripe, who keep a veto \"as a last resort\". Seats held on 2026-10-28: OpenAI, Stripe and Meta; the commit adding Meta is dated 2026-04-24. The governance document was first added on 2025-12-02 and replaced by a revised model on 2026-03-10. Apache-2.0 licence; contributors must sign a CLA", "group": "Protocols called ACP", "history": [ { "date": "2026-09-06", "note": "verified against agentic-commerce-protocol GitHub repo (README, docs/governance.md, MAINTAINERS.md, spec/2026-04-17), developers.openai.com/commerce, docs.stripe.com/agentic-commerce" }, { "date": "2026-09-06", "note": "collisions updated to add Agent Connect Protocol (Cisco/AGNTCY), verified against github.com/agntcy/acp-spec, spec.acp.agntcy.org" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "agentic-commerce-protocol", "implementation": "multi-implementation", "last_verified": "2026-11-11", "name": "Agentic Commerce Protocol", "native_status": "Beta. The checkout and delegate-payment RFCs are marked Draft, the product-feeds and discovery RFCs Proposal. On 2026-03-24 OpenAI let merchants use their own checkouts in ChatGPT and shifted its ACP use towards product discovery. OpenAI's commerce documentation describes ACP as an open standard that serves as the connective layer between merchants and ChatGPT users, enabling ChatGPT to ingest structured catalog data, understand merchant inventory, and surface relevant products in context.", "origin": { "org": "OpenAI and Stripe", "date": "2025-09-29" }, "part_of": null, "parties": [ "agent-site" ], "phase": "living", "probe": { "method": "POST", "on_absent": "Absence proves nothing generalizable: ACP endpoints and auth are negotiated per integration and not advertised at a fixed public path, so a failed probe only shows this origin/path pair is not configured, not that ACP is unsupported.", "parse": "Response includes an API-Version response/negotiation and a CheckoutSession object per the 2026-04-17 OpenAPI schema", "path": "{origin}/checkout_sessions" }, "question": "How do a buyer's agent and a merchant complete a deterministic, programmatic checkout without the agent becoming the merchant of record?", "scope": "commerce", "spec_url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol", "step": "pay", "summary_md": "**Agentic Commerce Protocol** (`ACP`) is an open standard codeveloped by OpenAI and Stripe (announced September 29, 2025) for connecting buyers, AI agents, and businesses to complete purchases on the merchant's existing commerce stack. OpenAI and Stripe maintain the beta specification alongside a Technical Steering Committee of up to 7 seats. The buyer's agent drives five merchant REST operations on `checkout_sessions` (create `POST /checkout_sessions`, update `POST /checkout_sessions/{checkout_session_id}`, retrieve `GET /checkout_sessions/{checkout_session_id}`, complete `POST /checkout_sessions/{id}/complete`, and cancel `POST /checkout_sessions/{checkout_session_id}/cancel`, abbreviated `{id}` in RFC summaries) with a mandatory `Idempotency-Key` header on every POST. Delegated payment uses `POST /agentic_commerce/delegate_payment` to issue a scoped vault token, and agents read `/.well-known/acp.json` before creating a session. Dated snapshot `2026-04-17` (deprecating `2026-01-30`) ships normative OpenAPI and JSON Schema artifacts in `spec/2026-04-17/` for pre-checkout cart management, feed, order confirmation, delegated authentication, discovery (`transports` advertising `rest` and `mcp`), and MCP, whereas the prose RFC Markdown files `rfcs/rfc.product_feeds.md` and `rfcs/rfc.discovery.md` on `main` still carry `Status: Proposal` (`Version: unreleased`).", "track": "vendor-consortium", "version": { "label": "2026-04-17", "date": "2026-04-17" }, "watch": [ { "type": "github", "repo": "agentic-commerce-protocol/agentic-commerce-protocol", "mode": "tag" } ], "use_cases": [ "agent-checkout", "accept-agent-payments" ], "audience": [ "platform", "agent-builder" ], "pairs_with": [ "ucp", "ap2", "x402", "mcp", "tap" ], "prerequisites": [], "hatnote_md": "This page is about the Agentic Commerce Protocol (ACP), the open checkout protocol that OpenAI and Stripe announced on 2025-09-29 with Instant Checkout in ChatGPT. It is not the Agent Communication Protocol (ACP) that IBM Research launched for its BeeAI Platform in March 2025 and that an LF AI & Data post of 2025-08-29 says is officially merging with A2A under the Linux Foundation (see [Agent Communication Protocol](/protocols/agent-communication-protocol/) and [Agent2Agent Protocol (A2A)](/protocols/a2a/)). It is not the Agent Client Protocol (ACP) that Zed created, in a post dated 2025-08-27, so third-party agents can be used inside the editor (see [Agent Client Protocol](/protocols/agent-client-protocol/)). It is not AGNTCY's Agent Connect Protocol (ACP), which defines a standard interface to invoke and configure remote agents over an API (see [Agent Connect Protocol](/protocols/agent-connect-protocol/)), nor ERC-8183, created 2026-02-25, whose specification also calls itself the Agentic Commerce Protocol and describes a job with an escrowed budget. For a user-signed Checkout Mandate and Payment Mandate, see [Agent Payments Protocol (AP2)](/protocols/ap2/).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-11", "v05_hatnote_html_md": "This page is about the Agentic Commerce Protocol (ACP), the open checkout protocol that OpenAI and Stripe announced on 2025-09-29 with Instant Checkout in ChatGPT. It is not the Agent Communication Protocol (ACP) that IBM Research launched for its BeeAI Platform in March 2025 and that an LF AI & Data post of 2025-08-29 says is officially merging with A2A under the Linux Foundation (see [Agent Communication Protocol](/protocols/agent-communication-protocol/) and [Agent2Agent Protocol (A2A)](/protocols/a2a/)). It is not the Agent Client Protocol (ACP) that Zed created, in a post dated 2025-08-27, so third-party agents can be used inside the editor (see [Agent Client Protocol](/protocols/agent-client-protocol/)). It is not AGNTCY's Agent Connect Protocol (ACP), which defines a standard interface to invoke and configure remote agents over an API (see [Agent Connect Protocol](/protocols/agent-connect-protocol/)), nor ERC-8183, created 2026-02-25, whose specification also calls itself the Agentic Commerce Protocol and describes a job with an escrowed budget. For a user-signed Checkout Mandate and Payment Mandate, see [Agent Payments Protocol (AP2)](/protocols/ap2/). [1][2][3][4][5][6]", "v05_elevator_pitch_md": "ACP (Agentic Commerce Protocol) lets AI assistants purchase goods directly from online retailers on a buyer's behalf while keeping the seller as the merchant of record. Instead of forcing AI platforms to act as marketplace resellers or scrape web checkout forms, businesses expose standardized `POST /checkout_sessions` REST endpoints and accept scoped vault tokens issued via `POST /agentic_commerce/delegate_payment` on their existing payment rails. [7][8][9]", "v05_lead_md": "**Agentic Commerce Protocol** (`ACP`) is an open standard codeveloped by OpenAI and Stripe (announced September 29, 2025) for connecting buyers, AI agents, and businesses to complete purchases on the merchant's existing commerce stack. OpenAI and Stripe maintain the beta specification alongside a Technical Steering Committee of up to 7 seats. [7][8][10][11] The buyer's agent drives five merchant REST operations on `checkout_sessions` (create `POST /checkout_sessions`, update `POST /checkout_sessions/{checkout_session_id}`, retrieve `GET /checkout_sessions/{checkout_session_id}`, complete `POST /checkout_sessions/{id}/complete`, and cancel `POST /checkout_sessions/{checkout_session_id}/cancel`, abbreviated `{id}` in RFC summaries) with a mandatory `Idempotency-Key` header on every POST. Delegated payment uses `POST /agentic_commerce/delegate_payment` to issue a scoped vault token, and agents read `/.well-known/acp.json` before creating a session. [8][9][12] Dated snapshot `2026-04-17` (deprecating `2026-01-30`) ships normative OpenAPI and JSON Schema artifacts in `spec/2026-04-17/` for pre-checkout cart management, feed, order confirmation, delegated authentication, discovery (`transports` advertising `rest` and `mcp`), and MCP, whereas the prose RFC Markdown files `rfcs/rfc.product_feeds.md` and `rfcs/rfc.discovery.md` on `main` still carry `Status: Proposal` (`Version: unreleased`). [7][12][13][14]", "v05_identity_sentence_md": "**Agentic Commerce Protocol** (`ACP`) is an open standard codeveloped by OpenAI and Stripe (announced September 29, 2025) for connecting buyers, AI agents, and businesses to complete purchases on the merchant's existing commerce stack. OpenAI and Stripe maintain the beta specification alongside a Technical Steering Committee of up to 7 seats. [7][8][10][11]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "OpenAI and Stripe, announced September 29, 2025 (repository created September 29, 2025; codeveloped by Stripe and OpenAI with Jeff Weinstein and Steve Kaliski at Stripe). [1][10][15]" }, { "label": "Governed by", "value_md": "Up to 7 TSC seats (OpenAI `aravindrao-openai`, Stripe `prasad-stripe`, Meta `lhwa`), appointed by founding maintainers with a last-resort veto that can only be used to block a change, never to override the TSC and force one through. CLA required. [7][11][16][17]" }, { "label": "Track", "value_md": "Vendor consortium (`vendor-consortium`). OpenAI and Stripe maintain the specification and appoint the Technical Steering Committee. [7][11]" }, { "label": "Status", "value_md": "Beta spec: checkout and delegate-payment RFCs are Draft; feeds and discovery RFCs are unreleased Proposals. On March 24, 2026 OpenAI focused its ChatGPT shopping efforts on product discovery and merchant checkout experiences. OpenAI's commerce docs call ACP an open standard that serves as the connective layer between merchants and ChatGPT users, enabling ChatGPT to ingest structured catalog data, understand merchant inventory, and surface relevant products in context. [7][8][9][12][14][18][19]" }, { "label": "Version", "value_md": "Latest stable snapshot `2026-04-17` (deprecates `2026-01-30`); checkout RFC Markdown on `main` remains titled Version `2026-01-16` (Delegate Payment RFC `2025-09-29`). [7][8][9][13][20]" }, { "label": "Headers", "value_md": "`Authorization: Bearer` (required), `Content-Type: application/json` (required with body), `Idempotency-Key` (required on all `POST`), `Request-Id` (recommended), and `API-Version` (required `YYYY-MM-DD` release snapshot selector—latest stable `2026-04-17`, illustrated as `2026-01-16` in `rfcs/rfc.agentic_checkout.md`). [7][8][13]" }, { "label": "Message format", "value_md": "Merchant REST checkout. Requests that carry a body use `Content-Type: application/json`. Session operations are create, update, retrieve, complete, and cancel. [8]" }, { "label": "Transports", "value_md": "Changelog 2026-04-17: discovery `transports` advertises `rest` and `mcp`. Checkout configuration can be published via API or MCP. [13][21]" }, { "label": "Token format", "value_md": "Delegate Payment issues a delegated vault token under an allowance. Stripe shared payment tokens (public preview) scope agent-initiated purchases. [9][22]" }, { "label": "Specification", "value_md": "[Agentic Commerce Protocol repository](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol), including the [Agentic Checkout RFC](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.agentic_checkout.md) and the [Delegate Payment RFC](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.delegate_payment.md). OpenAI's [commerce documentation](https://developers.openai.com/commerce) calls ACP an open standard connective layer between merchants and ChatGPT users. [8][9][15][19]" }, { "label": "Found at", "value_md": "`GET /.well-known/acp.json` (added in the 2026-04-17 changelog for pre-session capability checks; the discovery RFC is Status Proposal, version unreleased). [12][13]" }, { "label": "Licence", "value_md": "Apache-2.0 (repository and RFC specifications; contributors must sign a CLA). [7][10][15][21]" } ], "v05_problem_md": "As transactions move from websites to AI workflows, agent checkout has no common standard. An application that lets its users buy from a business would otherwise have to be the merchant of record. A business would otherwise leave its existing commerce infrastructure instead of publishing agent-facing endpoints on its current backend and payment processor. [21] The merchant remains the system of record for orders, payments, taxes, and compliance, and payments stay on merchant rails. A delegated vault token may be used by the merchant's existing PSP only within explicit allowance constraints. Stripe shared payment tokens grant sellers scoped access to customers' payment methods for agent-initiated purchases. [8][9][22] The checkout RFC leaves PSP authorization and capture semantics, returns and exchanges, tax configuration, and fraud modeling out of scope. A merchant accepts the agent payment either by using Stripe's Shared Payment Token API or by adopting the Delegated Payments Spec, without changing its existing payment processor. [1][8]", "v05_mechanism_delta_md": "The merchant remains the system of record for orders, payments, taxes, and compliance, and payments stay on merchant rails. A delegated vault token may be used by the merchant's existing PSP only within explicit allowance constraints. Stripe shared payment tokens grant sellers scoped access to customers' payment methods for agent-initiated purchases. [8][9][22]", "v05_scope_boundary_md": "The checkout RFC leaves PSP authorization and capture semantics, returns and exchanges, tax configuration, and fraud modeling out of scope. A merchant accepts the agent payment either by using Stripe's Shared Payment Token API or by adopting the Delegated Payments Spec, without changing its existing payment processor. [1][8]", "v05_fuzzy_additions": [ { "id": "checkout-session-lifecycle-headers-and-webhook-events", "heading": "Checkout session lifecycle, headers, and webhook events", "body_md": "Agentic Checkout is the merchant REST session for the checkout session lifecycle and webhook integration, versioned via the required `API-Version` (`YYYY-MM-DD`) header (latest stable snapshot `2026-04-17`; `rfcs/rfc.agentic_checkout.md` on `main` illustrates `API-Version: 2026-01-16`). Every response returns the authoritative cart state. `API-Version` and `Authorization: Bearer` are required on each call, `Idempotency-Key` is required on every POST, and `Signature` (`RECOMMENDED`, where the server `SHOULD` publish acceptable signature algorithms out-of-band and the client `SHOULD` sign requests) covers the canonical JSON with an accompanying `Timestamp` (`RECOMMENDED`). [7][8][13]", "bullets": [ { "label": "Create and update", "text_md": "`POST /checkout_sessions` creates a session from items and an optional buyer or address and returns 201 Created, with `status`, a `line_items` array whose amount fields (`base_amount`, `discount`, `subtotal`, `tax`, and `total`) are integers, fulfillment options, totals, and messages. `POST /checkout_sessions/{checkout_session_id}` (abbreviated `{id}` in RFC summaries) updates items, address, or fulfillment option and returns 200 OK with the full authoritative cart. [8]" }, { "label": "Retrieve, complete, and cancel", "text_md": "`GET /checkout_sessions/{checkout_session_id}` (`{id}`) returns the latest authoritative state, or 404 if missing. `POST /checkout_sessions/{checkout_session_id}/complete` (`POST /checkout_sessions/{id}/complete`) finalizes with a payment method, MUST create an order, sets `status` to `completed`, and returns `order` fields `id`, `checkout_session_id`, and `permalink_url`. `POST /checkout_sessions/{checkout_session_id}/cancel` returns 200 when canceled and 405 if already completed or canceled. [8]" }, { "label": "Status and headers", "text_md": "`status` is `not_ready_for_payment`, `ready_for_payment`, `authentication_required`, `completed`, `canceled`, or `in_progress`. When authentication such as 3-D Secure is required, the server sets `authentication_required` and includes `authentication_metadata` in the session response, while the client must send `authentication_result` on `POST /checkout_sessions/{id}/complete`. Required POST headers are `API-Version` (selecting the dated `YYYY-MM-DD` release snapshot—latest stable `2026-04-17`, shown as `2026-01-16` in `rfc.agentic_checkout.md`) and `Idempotency-Key` (opaque, at most 255 characters). `Signature` and `Timestamp` are recommended. A missing key returns HTTP 400 `idempotency_key_required`. Replay returns the original response, should include `Idempotent-Replayed: true`, and servers must retain idempotency mappings for at least 24 hours. [7][8][13]" }, { "label": "Merchant order webhooks", "text_md": "The merchant MUST emit `order_create` and `order_update` to the application webhook receiver. Receivers check HMAC `Merchant-Signature`. Version `2026-04-17` sets that header to `t=,v1=<64_hex>`, signs timestamp, a period, and the raw body with HMAC-SHA256, and rejects timestamps outside a 300-second window. [8][13]" } ] }, { "id": "delegated-payment-allowance-shared-payment-tokens-and-2026-04-17-extensions", "heading": "Delegated payment allowance, Shared Payment Tokens, and 2026-04-17 extensions", "body_md": "`POST /agentic_commerce/delegate_payment` issues a delegated vault token the merchant's PSP may use only inside `allowance`. A granted `SharedPaymentToken` is charged on Stripe or sent to a third-party processor. Snapshot `2026-04-17` ships OpenAPI and JSON Schema artifacts under `spec/2026-04-17/` for cart, feed, orders, delegated authentication, discovery, and the extensions schema, while the prose RFC documents for product feeds and discovery on `main` remain marked `Proposal` (`unreleased`). [7][9][12][13][14][22]", "bullets": [ { "label": "Allowance constraints", "text_md": "`allowance` is required. `reason` MUST be `one_time`. `max_amount` is minor units (20 dollars is 2000). `currency` is lowercase ISO-4217 such as `usd`. `checkout_session_id` and `merchant_id` (at most 256 characters) bind the grant. `expires_at` is RFC 3339, and the token is invalid at or after `allowance.expires_at`. [9]" }, { "label": "SharedPaymentToken and vaulting", "text_md": "A `SharedPaymentToken` grants the seller scoped access to the customer's payment method for an agent-initiated purchase. The seller processes it on Stripe or with a third-party processor by setting `payment_method_data[shared_payment_granted_token]` on a PaymentIntent. Sandbox limits are `usage_limits[currency]`, `usage_limits[max_amount]`, and `usage_limits[expires_at]`. The vault token keeps settlement on the merchant's rails without changing the existing payment processor. [1][9][22]" }, { "label": "Cart, feed, and delegated authentication", "text_md": "`2026-04-17` promotes changes since `2026-01-30` into `spec/2026-04-17/` OpenAPI and JSON Schema artifacts covering cart, feed, orders, authentication, discovery, and MCP, even though `rfcs/rfc.product_feeds.md` and `rfcs/rfc.discovery.md` on `main` still carry `Status: Proposal` (`unreleased`). `POST /carts`, `GET /carts/{id}`, `PUT /carts/{id}`, and `POST /carts/{id}/cancel` manage a cart with no status lifecycle, no payment data, and estimated totals. Agents check `carts` on `/.well-known/acp.json`. The push-model Agent-hosted Feed API uses `POST /feeds` and `PATCH /feeds/{id}/products`. Delegate Authentication runs 3DS2 through Create, Authenticate, and Retrieve, plus fingerprint and challenge webhooks. [7][12][13][14]" }, { "label": "Extensions, confirmation, security, and merchant liability", "text_md": "`2026-01-30` holds extensions, discounts, and payment handlers, and `2026-04-17` still ships `schema.extension.json` beside `schema.discount.json`. `cart_id` checkout conversion and discount extensions are deferred. Confirmation adds `order_notes` on `OrderConfirmation` and `client_reference_id` so the platform can reconcile its transaction with the merchant order. Both checkout and delegated-payment endpoints require `TLS 1.3`, card data handling must follow applicable `PCI DSS` requirements, logs must not contain full `PAN` or `CVC` (with addresses redacted as required by policy), and merchants remain the system and merchant of record for all orders, payments, taxes, compliance, and customer relationships. [7][8][9][13][23]" } ] } ], "v05_diagram": { "title": "Checkout session operations", "heading": "Checkout session operations", "mermaid": "sequenceDiagram\n participant Client as Client (ChatGPT)\n participant Merchant as Merchant server\n Client->>Merchant: POST /checkout_sessions\n Merchant-->>Client: 201 Created, authoritative cart\n opt Update\n Client->>Merchant: POST /checkout_sessions/{id}\n Merchant-->>Client: 200 OK, authoritative state\n end\n opt Retrieve\n Client->>Merchant: GET /checkout_sessions/{id}\n Merchant-->>Client: 200 OK, or 404 if not found\n end\n alt Complete\n Client->>Merchant: POST /checkout_sessions/{id}/complete\n Merchant-->>Client: 200 OK, status completed, and order\n else Cancel\n Client->>Merchant: POST /checkout_sessions/{id}/cancel\n Merchant-->>Client: 200 OK, or 405 if already completed or canceled\n end", "caption_md": "Merchant server checkout operations: `POST /checkout_sessions`, `POST /checkout_sessions/{id}`, `GET /checkout_sessions/{id}`, `POST /checkout_sessions/{id}/complete`, and `POST /checkout_sessions/{id}/cancel`. [8]" }, "v05_wire_artifact": { "title": "POST /agentic_commerce/delegate_payment 201 delegated vault token", "heading": "POST /agentic_commerce/delegate_payment 201 delegated vault token", "lang": "json", "code": "{\n \"id\": \"vt_01J8Z3WXYZ9ABC\",\n \"created\": \"2025-09-29T11:00:00Z\",\n \"metadata\": {\n \"source\": \"agent_checkout\",\n \"merchant_id\": \"acme\",\n \"idempotency_key\": \"idem_abc123\"\n }\n}", "caption_md": "`POST /agentic_commerce/delegate_payment` returns a delegated vault token. The success `id` in this example is `vt_01J8Z3WXYZ9ABC`. [9]" }, "v05_counterparts": { "classic_analogues": [ { "name": "Well-Known URIs (RFC 8615)", "spec_or_rfc": "RFC 8615", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "ACP's discovery RFC introduces `/.well-known/acp.json` so an agent can check ACP support, protocol version, transports, and seller capabilities before creating a checkout session, without authentication. [12]" }, { "name": "W3C Payment Request API", "spec_or_rfc": "Payment Request API", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "ACP checkout RFC defines create, update, retrieve, complete, and cancel on `/checkout_sessions`, paid by a delegated vault token or Stripe shared payment token: the merchant REST counterpart of Payment Request. [8][9][22]" } ], "agentic_peers": [ { "target_id": "ucp", "target_name": "Universal Commerce Protocol (UCP)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "UCP clients fetch `/.well-known/ucp` and `UCP-Agent` profile, with REST, MCP, A2A, and embedded transports. ACP discovers via `/.well-known/acp.json` and pays with a delegated vault token or Stripe shared payment token. [9][12][22][24]" }, { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "AP2 v0.2 defines Checkout and Payment Mandates after a trusted surface obtains informed user consent for an intent before creating a user-signed mandate. ACP keeps the merchant as system of record and pays via a delegated vault token or Stripe SPT. [6][8][9][22]" }, { "target_id": "x402", "target_name": "x402", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "x402 v2 puts requirements in base64 `PAYMENT-REQUIRED`, requires `PAYMENT-SIGNATURE`, and settles via a facilitator. ACP is the merchant session API (create, update, complete, cancel) paid by a delegated vault token. [8][9][25]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "MCP uses JSON-RPC 2.0 among hosts, clients, and servers for prompts, resources, and tools. ACP 2026-04-17 advertises `rest` and `mcp`, a Feed API (prose RFC marked unreleased), and cart; Delegate Payment issues delegated vault tokens. [9][13][14][26]" }, { "target_id": "tap", "target_name": "Trusted Agent Protocol (TAP)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "TAP signs with HTTP message signatures to prove agent's payment-scheme participation. ACP Delegate Payment issues a delegated vault token; Stripe shared payment tokens grant scoped access for agent-initiated purchases. [9][22][27]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (11 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Merchants & commerce platforms", "col4_header": "Checkout surface & merchant rollout", "note_md": null, "rows": [ { "actor": "Etsy", "role": "Marketplace", "status": "Supported", "status_display": "Supported · as of 2026-03-24", "col4_md": "Launched in-ChatGPT Instant Checkout for U.S. Etsy items on 2025-09-29; following OpenAI's 2026-03-24 shift, Etsy catalogs remain integrated while purchases complete on merchant-owned websites or apps.", "source_md": "[Etsy News (Sep 29, 2025)](https://web.archive.org/web/20251220210109/https://www.etsy.com/news/meeting-buyers-where-they-are-etsy-partners-with-openai-to-enable-ai-powered-shopping) [28] · [ChatGPT merchants](https://chatgpt.com/merchants/) [29] · [OpenAI (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18]" }, { "actor": "Shopify", "role": "Platform", "status": "Supported", "status_display": "Supported · as of 2026-03-24", "col4_md": "Instant Checkout for Shopify merchants (rolling out from November 20, 2025); on March 24, 2026 OpenAI shifted to merchant checkout experiences while focusing on product discovery, and Shopify states buyers finish in-app on mobile or in a separate browser tab on desktop while merchants stay merchant of record.", "source_md": "[Shopify News (September 29, 2025)](https://www.shopify.com/news/shopify-open-ai-commerce) [30] · [ChatGPT release notes (November 20, 2025)](https://web.archive.org/web/20260302064248/https://help.openai.com/en/articles/6825453-chatgpt-release-notes/) [31] · [Shopify News (March 24, 2026)](https://www.shopify.com/news/agentic-commerce-momentum) [23] · [OpenAI (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18]" }, { "actor": "Walmart", "role": "Enterprise retailer", "status": "Supported", "status_display": "Supported · as of 2026-03-24", "col4_md": "Announced ChatGPT Instant Checkout partnership on October 14, 2025; introduced tailored in-ChatGPT app with account linking, loyalty, and Walmart payments on March 24, 2026.", "source_md": "[Walmart News (October 14, 2025)](https://corporate.walmart.com/news/2025/10/14/walmart-partners-with-openai-to-create-ai-first-shopping-experiences) [32] · [OpenAI (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18]" }, { "actor": "Salesforce (Agentforce Commerce)", "role": "Commerce platform", "status": "Supported", "status_display": "Supported · as of 2025-10-14", "col4_md": "Collaborated with Stripe and OpenAI to build an Instant Checkout integration guided by ACP (announced October 14, 2025).", "source_md": "[Salesforce Press Release (October 14, 2025)](https://www.salesforce.com/news/press-releases/2025/10/14/stripe-openai-agentic-commerce-protocol-announcement/?bc=OTH) [33]" }, { "actor": "commercetools", "role": "Commerce platform", "status": "Supported", "status_display": "Supported · as of 2025-09-30", "col4_md": "Joined Stripe and OpenAI as an ACP launch partner for enterprise merchants (announced September 30, 2025).", "source_md": "[commercetools Press Release (September 30, 2025)](https://commercetools.com/press-releases/commercetools-partners-with-stripe-to-launch-acp) [34]" }, { "actor": "Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair", "role": "Merchant cohort", "status": "Partial", "status_display": "Partial · as of 2026-03-24", "col4_md": "Discovery only, not checkout, for Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair.", "source_md": "[OpenAI, Powering Product Discovery in ChatGPT (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18]" } ] }, "side_b": { "visible": true, "heading": "Buying agents & AI checkout surfaces", "col4_header": "Checkout flow & credential orchestration", "note_md": null, "rows": [ { "actor": "OpenAI (ChatGPT Instant Checkout)", "role": "Buying agent / AI surface (Co-author)", "status": "Partial", "status_display": "Partial · as of 2026-03-24", "col4_md": "U.S. Plus, Pro, and Free users: single-item Etsy checkout, then merchant checkout and discovery.", "source_md": "[OpenAI, Buy it in ChatGPT (September 29, 2025)](https://web.archive.org/web/20261022061422/https://openai.com/index/buy-it-in-chatgpt/) [1] · [OpenAI, Powering Product Discovery in ChatGPT (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18] · [ChatGPT merchants](https://chatgpt.com/merchants/) [29]" } ] }, "additional_tables": [ { "visible": true, "heading": "Payment processors & delegated token rails", "col4_header": "Shared Payment Token (SPT) / rail role", "note_md": null, "rows": [ { "actor": "Stripe", "role": "Payment rail (Co-author)", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Codeveloped ACP; public-preview Shared Payment Tokens in the US, Canada, and select European countries.", "source_md": "[Stripe Blog (September 29, 2025)](https://stripe.com/blog/developing-an-open-standard-for-agentic-commerce) [10] · [Stripe shared payment tokens](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) [22] · [Agentic Commerce Protocol](https://www.agenticcommerce.dev/) [21]" }, { "actor": "Adyen", "role": "Payment rail", "status": "Supported", "status_display": "Supported · as of 2026-01-16", "col4_md": "ACP checkout delegates the payment token to Adyen (`adyen` provider enum, 2026-01-16).", "source_md": "[Adyen ACP checkout docs](https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/agentic-payments-acp) [35] · [ACP changelog 2026-01-16](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/changelog/2026-01-16.md) [36]" }, { "actor": "PayPal (Braintree)", "role": "Payment rail", "status": "Supported", "status_display": "Supported · as of 2026-10-29", "col4_md": "ChatGPT app accepts ACP payments via Braintree delegated payment tokens (guide updated 2026-10-29).", "source_md": "[PayPal Developer guide (last updated October 29, 2026)](https://developer.paypal.com/agent-ready/agentic-commerce-protocol) [37]" }, { "actor": "Checkout.com", "role": "Payment rail", "status": "Supported", "status_display": "Supported · as of 2025-11-25", "col4_md": "Adopted ACP to power agentic commerce payments for enterprise merchants (announced November 25, 2025).", "source_md": "[Checkout.com Newsroom (November 25, 2025)](https://www.checkout.com/newsroom/checkout-adopts-acp-backed-by-openai-to-power-agentic-commerce-for-enterprise-merchants) [38]" } ] } ], "censuses": [ { "label": "OpenAI (September 29, 2025) & ChatGPT release notes (November 20, 2025)", "as_of": "2025-11-20", "value_md": "Instant Checkout launched on September 29, 2025 for U.S. ChatGPT Plus, Pro, and Free users purchasing from U.S. Etsy sellers, with over a million Shopify merchants (including Glossier, SKIMS, Spanx, and Vuori) announced at launch and rolling out in ChatGPT starting November 20, 2025. [1][31]" }, { "label": "Stripe SPT documentation & enterprise partner announcements (Sept–Nov 2025)", "as_of": "2025-11-25", "value_md": "Stripe launched public-preview Shared Payment Tokens (SPTs) across the US, Canada, and select European countries alongside Day-1 and Q4 2025 platform integrations across Etsy, Shopify, commercetools, Salesforce Agentforce Commerce, Walmart, and Checkout.com. [21][22][33][34][38]" }, { "label": "OpenAI & Shopify announcements (March 24, 2026)", "as_of": "2026-03-24", "value_md": "On March 24, 2026, OpenAI shifted ChatGPT physical-goods shopping from standalone in-chat Instant Checkout to merchant-owned checkout experiences (in-app browser on mobile and direct store tab on desktop for Shopify and Etsy catalogs) while expanding ACP catalog discovery to Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair. [18][23]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "mpp", "target_name": "Machine Payments Protocol (MPP)", "relation_label": "Complements", "delta": "ACP, maintained by OpenAI and Stripe, connects buyers, agents, and businesses for checkout; MPP pays for one HTTP resource.", "item_md": "**[Machine Payments Protocol (MPP)](/protocols/mpp/)** (Complements) — ACP, maintained by OpenAI and Stripe, connects buyers, agents, and businesses for checkout; MPP pays for one HTTP resource." }, { "target_id": "agtp", "target_name": "Agent Transfer Protocol", "relation_label": "Complements", "delta": "AGTP draft-10 defines governance and authority headers alongside its eight Tier 1 Core Methods (such as BOOK and DELEGATE), while the Agentic Commerce Protocol is the separate OpenAI and Stripe checkout protocol.", "item_md": "**[Agent Transfer Protocol](/protocols/agtp/)** (Complements) — AGTP draft-10 defines governance and authority headers alongside its eight Tier 1 Core Methods (such as BOOK and DELEGATE), while the Agentic Commerce Protocol is the separate OpenAI and Stripe checkout protocol." }, { "target_id": "vi", "target_name": "Verifiable Intent", "relation_label": "Complements", "delta": "The Agentic Commerce Protocol moves the order with the merchant, and Verifiable Intent supplies the SD-JWT (RFC 9901) L1, L2, and L3 mandate chain for that order.", "item_md": "**[Verifiable Intent](/protocols/vi/)** (Complements) — The Agentic Commerce Protocol moves the order with the merchant, and Verifiable Intent supplies the SD-JWT (RFC 9901) L1, L2, and L3 mandate chain for that order." }, { "target_id": "agent-attribution-protocol", "target_name": "Agent Attribution Protocol", "relation_label": "Complements", "delta": "The Agentic Commerce Protocol completes the merchant order, while AAP uses checkout() to route the user to checkout and matches merchant conversions reported via the conversions API back to the Rako-signed AAP Code from recommend().", "item_md": "**[Agent Attribution Protocol](/protocols/agent-attribution-protocol/)** (Complements) — The Agentic Commerce Protocol completes the merchant order, while AAP uses checkout() to route the user to checkout and matches merchant conversions reported via the conversions API back to the Rako-signed AAP Code from recommend()." }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: agentic-commerce-protocol\ntitle: \"Agentic Commerce Protocol\"\ntier: flagship\nlifecycle_status: active\ncategory: pay\nform: endpoint\nwire_archetype: payments_onchain\nspec_url: https://github.com/agentic-commerce-protocol/agentic-commerce-protocol\nlast_checked: 2026-11-11\n---\n\n# Agentic Commerce Protocol\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-11\n\n> *This page is about the Agentic Commerce Protocol (ACP), the open checkout protocol that OpenAI and Stripe announced on 2025-09-29 with Instant Checkout in ChatGPT. It is not the Agent Communication Protocol (ACP) that IBM Research launched for its BeeAI Platform in March 2025 and that an LF AI & Data post of 2025-08-29 says is officially merging with A2A under the Linux Foundation (see [Agent Communication Protocol](/protocols/agent-communication-protocol/) and [Agent2Agent Protocol (A2A)](/protocols/a2a/)). It is not the Agent Client Protocol (ACP) that Zed created, in a post dated 2025-08-27, so third-party agents can be used inside the editor (see [Agent Client Protocol](/protocols/agent-client-protocol/)). It is not AGNTCY's Agent Connect Protocol (ACP), which defines a standard interface to invoke and configure remote agents over an API (see [Agent Connect Protocol](/protocols/agent-connect-protocol/)), nor ERC-8183, created 2026-02-25, whose specification also calls itself the Agentic Commerce Protocol and describes a job with an escrowed budget. For a user-signed Checkout Mandate and Payment Mandate, see [Agent Payments Protocol (AP2)](/protocols/ap2/). [1][2][3][4][5][6]*\n\n> **In brief:** ACP (Agentic Commerce Protocol) lets AI assistants purchase goods directly from online retailers on a buyer's behalf while keeping the seller as the merchant of record. Instead of forcing AI platforms to act as marketplace resellers or scrape web checkout forms, businesses expose standardized `POST /checkout_sessions` REST endpoints and accept scoped vault tokens issued via `POST /agentic_commerce/delegate_payment` on their existing payment rails. [7][8][9]\n\n**Agentic Commerce Protocol** (`ACP`) is an open standard codeveloped by OpenAI and Stripe (announced September 29, 2025) for connecting buyers, AI agents, and businesses to complete purchases on the merchant's existing commerce stack. OpenAI and Stripe maintain the beta specification alongside a Technical Steering Committee of up to 7 seats. [7][8][10][11] The buyer's agent drives five merchant REST operations on `checkout_sessions` (create `POST /checkout_sessions`, update `POST /checkout_sessions/{checkout_session_id}`, retrieve `GET /checkout_sessions/{checkout_session_id}`, complete `POST /checkout_sessions/{id}/complete`, and cancel `POST /checkout_sessions/{checkout_session_id}/cancel`, abbreviated `{id}` in RFC summaries) with a mandatory `Idempotency-Key` header on every POST. Delegated payment uses `POST /agentic_commerce/delegate_payment` to issue a scoped vault token, and agents read `/.well-known/acp.json` before creating a session. [8][9][12] Dated snapshot `2026-04-17` (deprecating `2026-01-30`) ships normative OpenAPI and JSON Schema artifacts in `spec/2026-04-17/` for pre-checkout cart management, feed, order confirmation, delegated authentication, discovery (`transports` advertising `rest` and `mcp`), and MCP, whereas the prose RFC Markdown files `rfcs/rfc.product_feeds.md` and `rfcs/rfc.discovery.md` on `main` still carry `Status: Proposal` (`Version: unreleased`). [7][12][13][14]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | OpenAI and Stripe, announced September 29, 2025 (repository created September 29, 2025; codeveloped by Stripe and OpenAI with Jeff Weinstein and Steve Kaliski at Stripe). [1][10][15] |\n| **Governed by** | Up to 7 TSC seats (OpenAI `aravindrao-openai`, Stripe `prasad-stripe`, Meta `lhwa`), appointed by founding maintainers with a last-resort veto that can only be used to block a change, never to override the TSC and force one through. CLA required. [7][11][16][17] |\n| **Track** | Vendor consortium (`vendor-consortium`). OpenAI and Stripe maintain the specification and appoint the Technical Steering Committee. [7][11] |\n| **Status** | Beta spec: checkout and delegate-payment RFCs are Draft; feeds and discovery RFCs are unreleased Proposals. On March 24, 2026 OpenAI focused its ChatGPT shopping efforts on product discovery and merchant checkout experiences. OpenAI's commerce docs call ACP an open standard that serves as the connective layer between merchants and ChatGPT users, enabling ChatGPT to ingest structured catalog data, understand merchant inventory, and surface relevant products in context. [7][8][9][12][14][18][19] |\n| **Version** | Latest stable snapshot `2026-04-17` (deprecates `2026-01-30`); checkout RFC Markdown on `main` remains titled Version `2026-01-16` (Delegate Payment RFC `2025-09-29`). [7][8][9][13][20] |\n| **Headers** | `Authorization: Bearer` (required), `Content-Type: application/json` (required with body), `Idempotency-Key` (required on all `POST`), `Request-Id` (recommended), and `API-Version` (required `YYYY-MM-DD` release snapshot selector—latest stable `2026-04-17`, illustrated as `2026-01-16` in `rfcs/rfc.agentic_checkout.md`). [7][8][13] |\n| **Message format** | Merchant REST checkout. Requests that carry a body use `Content-Type: application/json`. Session operations are create, update, retrieve, complete, and cancel. [8] |\n| **Transports** | Changelog 2026-04-17: discovery `transports` advertises `rest` and `mcp`. Checkout configuration can be published via API or MCP. [13][21] |\n| **Token format** | Delegate Payment issues a delegated vault token under an allowance. Stripe shared payment tokens (public preview) scope agent-initiated purchases. [9][22] |\n| **Specification** | [Agentic Commerce Protocol repository](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol), including the [Agentic Checkout RFC](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.agentic_checkout.md) and the [Delegate Payment RFC](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/rfcs/rfc.delegate_payment.md). OpenAI's [commerce documentation](https://developers.openai.com/commerce) calls ACP an open standard connective layer between merchants and ChatGPT users. [8][9][15][19] |\n| **Found at** | `GET /.well-known/acp.json` (added in the 2026-04-17 changelog for pre-session capability checks; the discovery RFC is Status Proposal, version unreleased). [12][13] |\n| **Licence** | Apache-2.0 (repository and RFC specifications; contributors must sign a CLA). [7][10][15][21] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Checkout session lifecycle, headers, and webhook events](#checkout-session-lifecycle-headers-and-webhook-events)\n3. [Delegated payment allowance, Shared Payment Tokens, and 2026-04-17 extensions](#delegated-payment-allowance-shared-payment-tokens-and-2026-04-17-extensions)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nAs transactions move from websites to AI workflows, agent checkout has no common standard. An application that lets its users buy from a business would otherwise have to be the merchant of record. A business would otherwise leave its existing commerce infrastructure instead of publishing agent-facing endpoints on its current backend and payment processor. [21] The merchant remains the system of record for orders, payments, taxes, and compliance, and payments stay on merchant rails. A delegated vault token may be used by the merchant's existing PSP only within explicit allowance constraints. Stripe shared payment tokens grant sellers scoped access to customers' payment methods for agent-initiated purchases. [8][9][22] The checkout RFC leaves PSP authorization and capture semantics, returns and exchanges, tax configuration, and fraud modeling out of scope. A merchant accepts the agent payment either by using Stripe's Shared Payment Token API or by adopting the Delegated Payments Spec, without changing its existing payment processor. [1][8]\n\n### Checkout session operations\n\n```mermaid\nsequenceDiagram\n participant Client as Client (ChatGPT)\n participant Merchant as Merchant server\n Client->>Merchant: POST /checkout_sessions\n Merchant-->>Client: 201 Created, authoritative cart\n opt Update\n Client->>Merchant: POST /checkout_sessions/{id}\n Merchant-->>Client: 200 OK, authoritative state\n end\n opt Retrieve\n Client->>Merchant: GET /checkout_sessions/{id}\n Merchant-->>Client: 200 OK, or 404 if not found\n end\n alt Complete\n Client->>Merchant: POST /checkout_sessions/{id}/complete\n Merchant-->>Client: 200 OK, status completed, and order\n else Cancel\n Client->>Merchant: POST /checkout_sessions/{id}/cancel\n Merchant-->>Client: 200 OK, or 405 if already completed or canceled\n end\n```\n\n*Merchant server checkout operations: `POST /checkout_sessions`, `POST /checkout_sessions/{id}`, `GET /checkout_sessions/{id}`, `POST /checkout_sessions/{id}/complete`, and `POST /checkout_sessions/{id}/cancel`. [8]*\n\n### POST /agentic_commerce/delegate_payment 201 delegated vault token\n\n```json\n{\n \"id\": \"vt_01J8Z3WXYZ9ABC\",\n \"created\": \"2025-09-29T11:00:00Z\",\n \"metadata\": {\n \"source\": \"agent_checkout\",\n \"merchant_id\": \"acme\",\n \"idempotency_key\": \"idem_abc123\"\n }\n}\n```\n\n*`POST /agentic_commerce/delegate_payment` returns a delegated vault token. The success `id` in this example is `vt_01J8Z3WXYZ9ABC`. [9]*\n\n---\n\n## Checkout session lifecycle, headers, and webhook events\n\nAgentic Checkout is the merchant REST session for the checkout session lifecycle and webhook integration, versioned via the required `API-Version` (`YYYY-MM-DD`) header (latest stable snapshot `2026-04-17`; `rfcs/rfc.agentic_checkout.md` on `main` illustrates `API-Version: 2026-01-16`). Every response returns the authoritative cart state. `API-Version` and `Authorization: Bearer` are required on each call, `Idempotency-Key` is required on every POST, and `Signature` (`RECOMMENDED`, where the server `SHOULD` publish acceptable signature algorithms out-of-band and the client `SHOULD` sign requests) covers the canonical JSON with an accompanying `Timestamp` (`RECOMMENDED`). [7][8][13]\n\n- **Create and update:** `POST /checkout_sessions` creates a session from items and an optional buyer or address and returns 201 Created, with `status`, a `line_items` array whose amount fields (`base_amount`, `discount`, `subtotal`, `tax`, and `total`) are integers, fulfillment options, totals, and messages. `POST /checkout_sessions/{checkout_session_id}` (abbreviated `{id}` in RFC summaries) updates items, address, or fulfillment option and returns 200 OK with the full authoritative cart. [8]\n- **Retrieve, complete, and cancel:** `GET /checkout_sessions/{checkout_session_id}` (`{id}`) returns the latest authoritative state, or 404 if missing. `POST /checkout_sessions/{checkout_session_id}/complete` (`POST /checkout_sessions/{id}/complete`) finalizes with a payment method, MUST create an order, sets `status` to `completed`, and returns `order` fields `id`, `checkout_session_id`, and `permalink_url`. `POST /checkout_sessions/{checkout_session_id}/cancel` returns 200 when canceled and 405 if already completed or canceled. [8]\n- **Status and headers:** `status` is `not_ready_for_payment`, `ready_for_payment`, `authentication_required`, `completed`, `canceled`, or `in_progress`. When authentication such as 3-D Secure is required, the server sets `authentication_required` and includes `authentication_metadata` in the session response, while the client must send `authentication_result` on `POST /checkout_sessions/{id}/complete`. Required POST headers are `API-Version` (selecting the dated `YYYY-MM-DD` release snapshot—latest stable `2026-04-17`, shown as `2026-01-16` in `rfc.agentic_checkout.md`) and `Idempotency-Key` (opaque, at most 255 characters). `Signature` and `Timestamp` are recommended. A missing key returns HTTP 400 `idempotency_key_required`. Replay returns the original response, should include `Idempotent-Replayed: true`, and servers must retain idempotency mappings for at least 24 hours. [7][8][13]\n- **Merchant order webhooks:** The merchant MUST emit `order_create` and `order_update` to the application webhook receiver. Receivers check HMAC `Merchant-Signature`. Version `2026-04-17` sets that header to `t=,v1=<64_hex>`, signs timestamp, a period, and the raw body with HMAC-SHA256, and rejects timestamps outside a 300-second window. [8][13]\n\n---\n\n## Delegated payment allowance, Shared Payment Tokens, and 2026-04-17 extensions\n\n`POST /agentic_commerce/delegate_payment` issues a delegated vault token the merchant's PSP may use only inside `allowance`. A granted `SharedPaymentToken` is charged on Stripe or sent to a third-party processor. Snapshot `2026-04-17` ships OpenAPI and JSON Schema artifacts under `spec/2026-04-17/` for cart, feed, orders, delegated authentication, discovery, and the extensions schema, while the prose RFC documents for product feeds and discovery on `main` remain marked `Proposal` (`unreleased`). [7][9][12][13][14][22]\n\n- **Allowance constraints:** `allowance` is required. `reason` MUST be `one_time`. `max_amount` is minor units (20 dollars is 2000). `currency` is lowercase ISO-4217 such as `usd`. `checkout_session_id` and `merchant_id` (at most 256 characters) bind the grant. `expires_at` is RFC 3339, and the token is invalid at or after `allowance.expires_at`. [9]\n- **SharedPaymentToken and vaulting:** A `SharedPaymentToken` grants the seller scoped access to the customer's payment method for an agent-initiated purchase. The seller processes it on Stripe or with a third-party processor by setting `payment_method_data[shared_payment_granted_token]` on a PaymentIntent. Sandbox limits are `usage_limits[currency]`, `usage_limits[max_amount]`, and `usage_limits[expires_at]`. The vault token keeps settlement on the merchant's rails without changing the existing payment processor. [1][9][22]\n- **Cart, feed, and delegated authentication:** `2026-04-17` promotes changes since `2026-01-30` into `spec/2026-04-17/` OpenAPI and JSON Schema artifacts covering cart, feed, orders, authentication, discovery, and MCP, even though `rfcs/rfc.product_feeds.md` and `rfcs/rfc.discovery.md` on `main` still carry `Status: Proposal` (`unreleased`). `POST /carts`, `GET /carts/{id}`, `PUT /carts/{id}`, and `POST /carts/{id}/cancel` manage a cart with no status lifecycle, no payment data, and estimated totals. Agents check `carts` on `/.well-known/acp.json`. The push-model Agent-hosted Feed API uses `POST /feeds` and `PATCH /feeds/{id}/products`. Delegate Authentication runs 3DS2 through Create, Authenticate, and Retrieve, plus fingerprint and challenge webhooks. [7][12][13][14]\n- **Extensions, confirmation, security, and merchant liability:** `2026-01-30` holds extensions, discounts, and payment handlers, and `2026-04-17` still ships `schema.extension.json` beside `schema.discount.json`. `cart_id` checkout conversion and discount extensions are deferred. Confirmation adds `order_notes` on `OrderConfirmation` and `client_reference_id` so the platform can reconcile its transaction with the merchant order. Both checkout and delegated-payment endpoints require `TLS 1.3`, card data handling must follow applicable `PCI DSS` requirements, logs must not contain full `PAN` or `CVC` (with addresses redacted as required by policy), and merchants remain the system and merchant of record for all orders, payments, taxes, compliance, and customer relationships. [7][8][9][13][23]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Well-Known URIs (RFC 8615)** | `RFC 8615` | Profiles classic standard | ACP's discovery RFC introduces `/.well-known/acp.json` so an agent can check ACP support, protocol version, transports, and seller capabilities before creating a checkout session, without authentication. [12] |\n| **W3C Payment Request API** | `Payment Request API` | Analogous to classic standard | ACP checkout RFC defines create, update, retrieve, complete, and cancel on `/checkout_sessions`, paid by a delegated vault token or Stripe shared payment token: the merchant REST counterpart of Payment Request. [8][9][22] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Universal Commerce Protocol (UCP)](/protocols/ucp/)** | Peer alternative | UCP clients fetch `/.well-known/ucp` and `UCP-Agent` profile, with REST, MCP, A2A, and embedded transports. ACP discovers via `/.well-known/acp.json` and pays with a delegated vault token or Stripe shared payment token. [9][12][22][24] |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Complements | AP2 v0.2 defines Checkout and Payment Mandates after a trusted surface obtains informed user consent for an intent before creating a user-signed mandate. ACP keeps the merchant as system of record and pays via a delegated vault token or Stripe SPT. [6][8][9][22] |\n| **[x402](/protocols/x402/)** | Peer alternative | x402 v2 puts requirements in base64 `PAYMENT-REQUIRED`, requires `PAYMENT-SIGNATURE`, and settles via a facilitator. ACP is the merchant session API (create, update, complete, cancel) paid by a delegated vault token. [8][9][25] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | MCP uses JSON-RPC 2.0 among hosts, clients, and servers for prompts, resources, and tools. ACP 2026-04-17 advertises `rest` and `mcp`, a Feed API (prose RFC marked unreleased), and cart; Delegate Payment issues delegated vault tokens. [9][13][14][26] |\n| **[Trusted Agent Protocol (TAP)](/protocols/tap/)** | Complements | TAP signs with HTTP message signatures to prove agent's payment-scheme participation. ACP Delegate Payment issues a delegated vault token; Stripe shared payment tokens grant scoped access for agent-initiated purchases. [9][22][27] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (11 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Merchants & commerce platforms\n\n| Actor | Role | Status | Checkout surface & merchant rollout | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Etsy** | Marketplace | Supported · as of 2026-03-24 | Launched in-ChatGPT Instant Checkout for U.S. Etsy items on 2025-09-29; following OpenAI's 2026-03-24 shift, Etsy catalogs remain integrated while purchases complete on merchant-owned websites or apps. | [Etsy News (Sep 29, 2025)](https://web.archive.org/web/20251220210109/https://www.etsy.com/news/meeting-buyers-where-they-are-etsy-partners-with-openai-to-enable-ai-powered-shopping) [28] · [ChatGPT merchants](https://chatgpt.com/merchants/) [29] · [OpenAI (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18] |\n| **Shopify** | Platform | Supported · as of 2026-03-24 | Instant Checkout for Shopify merchants (rolling out from November 20, 2025); on March 24, 2026 OpenAI shifted to merchant checkout experiences while focusing on product discovery, and Shopify states buyers finish in-app on mobile or in a separate browser tab on desktop while merchants stay merchant of record. | [Shopify News (September 29, 2025)](https://www.shopify.com/news/shopify-open-ai-commerce) [30] · [ChatGPT release notes (November 20, 2025)](https://web.archive.org/web/20260302064248/https://help.openai.com/en/articles/6825453-chatgpt-release-notes/) [31] · [Shopify News (March 24, 2026)](https://www.shopify.com/news/agentic-commerce-momentum) [23] · [OpenAI (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18] |\n| **Walmart** | Enterprise retailer | Supported · as of 2026-03-24 | Announced ChatGPT Instant Checkout partnership on October 14, 2025; introduced tailored in-ChatGPT app with account linking, loyalty, and Walmart payments on March 24, 2026. | [Walmart News (October 14, 2025)](https://corporate.walmart.com/news/2025/10/14/walmart-partners-with-openai-to-create-ai-first-shopping-experiences) [32] · [OpenAI (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18] |\n| **Salesforce (Agentforce Commerce)** | Commerce platform | Supported · as of 2025-10-14 | Collaborated with Stripe and OpenAI to build an Instant Checkout integration guided by ACP (announced October 14, 2025). | [Salesforce Press Release (October 14, 2025)](https://www.salesforce.com/news/press-releases/2025/10/14/stripe-openai-agentic-commerce-protocol-announcement/?bc=OTH) [33] |\n| **commercetools** | Commerce platform | Supported · as of 2025-09-30 | Joined Stripe and OpenAI as an ACP launch partner for enterprise merchants (announced September 30, 2025). | [commercetools Press Release (September 30, 2025)](https://commercetools.com/press-releases/commercetools-partners-with-stripe-to-launch-acp) [34] |\n| **Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair** | Merchant cohort | Partial · as of 2026-03-24 | Discovery only, not checkout, for Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair. | [OpenAI, Powering Product Discovery in ChatGPT (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18] |\n\n### Buying agents & AI checkout surfaces\n\n| Actor | Role | Status | Checkout flow & credential orchestration | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **OpenAI (ChatGPT Instant Checkout)** | Buying agent / AI surface (Co-author) | Partial · as of 2026-03-24 | U.S. Plus, Pro, and Free users: single-item Etsy checkout, then merchant checkout and discovery. | [OpenAI, Buy it in ChatGPT (September 29, 2025)](https://web.archive.org/web/20261022061422/https://openai.com/index/buy-it-in-chatgpt/) [1] · [OpenAI, Powering Product Discovery in ChatGPT (March 24, 2026)](https://web.archive.org/web/20261012013103/https://openai.com/index/powering-product-discovery-in-chatgpt/) [18] · [ChatGPT merchants](https://chatgpt.com/merchants/) [29] |\n\n### Payment processors & delegated token rails\n\n| Actor | Role | Status | Shared Payment Token (SPT) / rail role | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Stripe** | Payment rail (Co-author) | Supported · checked 2026-10-30 | Codeveloped ACP; public-preview Shared Payment Tokens in the US, Canada, and select European countries. | [Stripe Blog (September 29, 2025)](https://stripe.com/blog/developing-an-open-standard-for-agentic-commerce) [10] · [Stripe shared payment tokens](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) [22] · [Agentic Commerce Protocol](https://www.agenticcommerce.dev/) [21] |\n| **Adyen** | Payment rail | Supported · as of 2026-01-16 | ACP checkout delegates the payment token to Adyen (`adyen` provider enum, 2026-01-16). | [Adyen ACP checkout docs](https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/agentic-payments-acp) [35] · [ACP changelog 2026-01-16](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/blob/main/changelog/2026-01-16.md) [36] |\n| **PayPal (Braintree)** | Payment rail | Supported · as of 2026-10-29 | ChatGPT app accepts ACP payments via Braintree delegated payment tokens (guide updated 2026-10-29). | [PayPal Developer guide (last updated October 29, 2026)](https://developer.paypal.com/agent-ready/agentic-commerce-protocol) [37] |\n| **Checkout.com** | Payment rail | Supported · as of 2025-11-25 | Adopted ACP to power agentic commerce payments for enterprise merchants (announced November 25, 2025). | [Checkout.com Newsroom (November 25, 2025)](https://www.checkout.com/newsroom/checkout-adopts-acp-backed-by-openai-to-power-agentic-commerce-for-enterprise-merchants) [38] |\n\n### Ecosystem censuses\n\n- **OpenAI (September 29, 2025) & ChatGPT release notes (November 20, 2025)** (*as of 2025-11-20*): Instant Checkout launched on September 29, 2025 for U.S. ChatGPT Plus, Pro, and Free users purchasing from U.S. Etsy sellers, with over a million Shopify merchants (including Glossier, SKIMS, Spanx, and Vuori) announced at launch and rolling out in ChatGPT starting November 20, 2025. [1][31]\n- **Stripe SPT documentation & enterprise partner announcements (Sept–Nov 2025)** (*as of 2025-11-25*): Stripe launched public-preview Shared Payment Tokens (SPTs) across the US, Canada, and select European countries alongside Day-1 and Q4 2025 platform integrations across Etsy, Shopify, commercetools, Salesforce Agentforce Commerce, Walmart, and Checkout.com. [21][22][33][34][38]\n- **OpenAI & Shopify announcements (March 24, 2026)** (*as of 2026-03-24*): On March 24, 2026, OpenAI shifted ChatGPT physical-goods shopping from standalone in-chat Instant Checkout to merchant-owned checkout experiences (in-app browser on mobile and direct store tab on desktop for Shopify and Etsy catalogs) while expanding ACP catalog discovery to Target, Sephora, Nordstrom, Lowe's, Best Buy, The Home Depot, and Wayfair. [18][23]\n\n---\n\n## See also\n\n- **[Machine Payments Protocol (MPP)](/protocols/mpp/)** *(Complements)* — ACP, maintained by OpenAI and Stripe, connects buyers, agents, and businesses for checkout; MPP pays for one HTTP resource.\n- **[Agent Transfer Protocol](/protocols/agtp/)** *(Complements)* — AGTP draft-10 defines governance and authority headers alongside its eight Tier 1 Core Methods (such as BOOK and DELEGATE), while the Agentic Commerce Protocol is the separate OpenAI and Stripe checkout protocol.\n- **[Verifiable Intent](/protocols/vi/)** *(Complements)* — The Agentic Commerce Protocol moves the order with the merchant, and Verifiable Intent supplies the SD-JWT (RFC 9901) L1, L2, and L3 mandate chain for that order.\n- **[Agent Attribution Protocol](/protocols/agent-attribution-protocol/)** *(Complements)* — The Agentic Commerce Protocol completes the merchant order, while AAP uses checkout() to route the user to checkout and matches merchant conversions reported via the conversions API back to the Rako-signed AAP Code from recommend().\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. OpenAI, *Buy it in ChatGPT: Instant Checkout and the Agentic Commerce Protocol* (2025-09-29 (Wayback snapshot 2026-10-22)) — \n2. Kate Blair and Todd Segal, LF AI & Data, *ACP Joins Forces with A2A* (2025-08-29) — \n3. Nathan Sobo, Zed, *Bring Your Own Agent to Zed — Featuring Gemini CLI* (2025-08-27) — \n4. AGNTCY, *Agent Connect Protocol specification* (checked 2026-10-28) — \n5. Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce* (created 2026-02-25) — \n6. Google, *Agent Payments Protocol specification* (v0.2; checked 2026-10-30) — \n7. OpenAI and Stripe, *Agentic Commerce Protocol README* (checked 2026-10-28) — \n8. OpenAI and Stripe, *RFC: Agentic Checkout — Merchant REST API* (Status Draft; Version 2026-01-16; checked 2026-10-28) — \n9. OpenAI and Stripe, *RFC: Delegate Payment API* (Status Draft; Version 2025-09-29; checked 2026-10-28) — \n10. Jeff Weinstein and Steve Kaliski, Stripe, *Developing an open standard for agentic commerce* (2025-09-29) — \n11. OpenAI and Stripe, *ACP governance* (checked 2026-10-28) — \n12. OpenAI and Stripe, *RFC: ACP discovery document* (Status Proposal; version unreleased; checked 2026-10-28) — \n13. OpenAI and Stripe, *Changelog 2026-04-17* (2026-04-17; checked 2026-10-28) — \n14. OpenAI and Stripe, *RFC: Product Feeds* (Status Proposal; version unreleased; checked 2026-10-28) — \n15. OpenAI and Stripe, *agentic-commerce-protocol repository* (created 2025-09-29; checked 2026-10-28) — \n16. GitHub API, *Commit history of docs/governance.md* (checked 2026-10-28) — \n17. OpenAI and Stripe, *MAINTAINERS.md* (checked 2026-10-28) — \n18. OpenAI, *Powering Product Discovery in ChatGPT* (2026-03-24 (Wayback snapshot 2026-10-12)) — \n19. OpenAI, *Agentic Commerce Protocol* (checked 2026-11-11) — \n20. OpenAI and Stripe, *Changelog 2025-09-29* (2025-09-29; checked 2026-10-28) — \n21. Agentic Commerce Protocol, *Agentic Commerce Protocol* (checked 2026-10-29) — \n22. Stripe, *Shared payment tokens* (checked 2026-10-28) — \n23. Shopify, *Millions of merchants can sell in AI chats* (2026-03-24) — \n24. Universal Commerce Protocol, *Overview* (checked 2026-10-30) — \n25. x402 Foundation, *X402 Protocol Specification* (Protocol Version 2; checked 2026-10-30) — \n26. Model Context Protocol, *Specification* (2026-07-28) — \n27. Visa, *Trusted Agent Protocol specifications* (checked 2026-10-30) — \n28. Rafe Colburn, Etsy, *Meeting Buyers Where They Are: Etsy partners with OpenAI to enable AI-powered shopping* (2025-09-29 (Wayback snapshot 2025-12-20)) — \n29. OpenAI, *ChatGPT merchants* (checked 2026-10-29) — \n30. Shopify, *Shopify and OpenAI bring commerce to ChatGPT* (2025-09-29) — \n31. OpenAI Help Center, *ChatGPT release notes* (entry 2025-11-20; Wayback snapshot 2026-03-02) — \n32. Walmart, *Walmart Partners with OpenAI to Create AI-First Shopping Experiences* (2025-10-14) — \n33. Salesforce, *Salesforce Announces Support for Agentic Commerce Protocol with Stripe* (2025-10-14) — \n34. commercetools, *commercetools partners with Stripe in its launch of the ACP* (2025-09-30) — \n35. Adyen, *Agentic Payments integration with ACP checkout flow* (checked 2026-10-29) — \n36. OpenAI and Stripe, *Changelog 2026-01-16* (2026-01-16; checked 2026-10-28) — \n37. PayPal Developer, *Agentic Commerce Protocol integration* (last updated 2026-10-29) — \n38. Checkout.com, *Checkout adopts ACP, backed by OpenAI, to power agentic commerce for enterprise merchants* (2025-11-25) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "UCP", "adoption": { "level": "observed", "by": "Shopify, Allbirds, Glossier, Monos, Steve Madden, Google (AI Mode in Search & Gemini app), Google Pay, Universal-Commerce-Protocol Official SDKs, and 12 other verified implementations", "probe_run": null }, "aliases": [ "Universal Commerce Protocol" ], "analog": "Machine-readable commerce capability profile at /.well-known/ucp for checkout, cart, order, and identity linking", "audience": [ "platform", "site-owner", "agent-builder" ], "collisions": [ "Universal Computer Protocol (SMSC protocol)", "Oracle Universal Connection Pool" ], "discovery": { "mechanism": "GET /.well-known/ucp on the business's own domain", "path": "GET /.well-known/ucp on the business's own domain: \"Businesses publish their profile at /.well-known/ucp; platforms publish their profile at the URI advertised in UCP-Agent.\"" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://developers.googleblog.com/en/under-the-hood-universal-commerce-protocol-ucp/", "claim": "Amit Handa and Ashish Gupta (Google Developers Blog), *Under the Hood: Universal Commerce Protocol (UCP)*, published 2026-01-11", "date": null, "quote": "The Universal Commerce Protocol (UCP) is a new, open-source standard for agentic commerce, co-developed by Google and industry leaders.", "ref": 1 }, { "label": "[2]", "url": "https://shopify.engineering/ucp", "claim": "Shopify Engineering, *Building the Universal Commerce Protocol*, published 2026-01-11", "date": null, "quote": "We co-developed UCP with Google to create an open standard for AI agents to connect and transact with any merchant. / 2026-01-11T14:17:01Z / We co-developed UCP with Google / Co-developed with Google. Supported by Etsy, Target, Walmart, Wayfair, and millions of Shopify merchants.", "ref": 2 }, { "label": "[3]", "url": "https://www.shopify.com/news/ai-commerce-at-scale", "claim": "Shopify, *The agentic commerce platform: Shopify connects any merchant to every AI conversation*, published 2026-01-11", "date": null, "quote": "January 11, 2026 / \"datePublished\":\"2026-01-11T14:58:43Z\"", "ref": 3 }, { "label": "[4]", "url": "https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/", "claim": "Vidhya Srinivasan (Google), *New tech and tools for retailers to succeed in an agentic shopping era*, published 2026-01-11", "date": null, "quote": "\"datePublished\": \"2026-01-11T15:00:00+00:00\" / UCP was co-developed with industry leaders including Shopify, Etsy, Wayfair, Target and Walmart / endorsed by more than 20 others across the ecosystem like Adyen, American Express, Best Buy, Flipkart, Macy's Inc., Mastercard, Stripe, The Home Depot, Visa and Zalando.", "ref": 4 }, { "label": "[5]", "url": "https://ucp.dev/latest/specification/overview/", "claim": "Universal Commerce Protocol, *Overview*, specification version aliased latest; fetched 2026-10-30", "date": null, "quote": "A profile document is a JSON object with a required ucp member. / Businesses publish their profile at /.well-known/ucp; platforms publish their profile at the URI advertised in UCP-Agent. / The ucp member contains protocol metadata: protocol version, services, optional capabilities, and payment handlers. / Platforms MUST include their profile URI in every request using the transport-appropriate mechanism. / HTTP Transport: Platforms MUST use Dictionary Structured Field syntax (RFC 8941) in the UCP-Agent header: / Platforms MAY fetch the business profile from /.well-known/ucp before initiating requests. / UCP supports HTTP/1.1 (or higher) using RESTful patterns. / UCP supports MCP protocol, which operates over JSON-RPC. / A business MAY expose an A2A agent that supports UCP as an A2A Extension / A business MAY embed an interface onto an eligible host / UCP uses date-based versioning in the format YYYY-MM-DD. / Platforms MUST use Dictionary Structured Field syntax (RFC 8941) in the UCP-Agent header / Requests and responses MUST use application/json. / endpoint SHOULD NOT have a trailing slash / Content-Type: application/json / UCP supports multiple transport protocols. / UCP separates protocol version selection from capability negotiation. A Business advertises its current protocol version and links to profiles for older supported versions. / Businesses MUST compute the intersection of platform and business capabilities. / Businesses MUST include the ucp field in every response containing: version: The UCP version used to process the request capabilities: Array of active capabilities for this response / Businesses publish their profile at /.well-known/ucp. An example: / Platforms MUST use Dictionary Structured Field syntax (RFC 8941) in the UCP-Agent header: / All capability and service names MUST use the format: {reverse-domain}.{service}.{capability} / {reverse-domain} - Authority identifier derived from domain ownership / dev.ucp.shopping.checkout ucp.dev shopping checkout / Protocol version selection chooses one complete Business profile first. Capability negotiation then selects active capabilities and extensions by exact version intersection within that profile. / select the highest version (latest date) / Extensions use the extends field to declare their parent(s): / Extensions MAY extend multiple parent capabilities by using an array: / For single-parent extensions (extends: \"string\"): parent must be present / at least one parent must be present / how it modifies base types using allOf composition. / Platforms MUST resolve schemas client-side by fetching and composing base schemas with active extension schemas. / separates Payment Instruments (what is accepted) from Payment Handlers (the specifications for how instruments are processed) / Payment Handlers are specifications (not entities) / com.google.pay, dev.shopify.shop_pay / entity like Google Pay, Shop Pay / Businesses MUST filter the handlers list based on the context of the cart / Businesses publish their profile at /.well-known/ucp / MCP requests use the tools/call method", "ref": 5 }, { "label": "[6]", "url": "https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/README.md", "claim": "OpenAI and Stripe, *Agentic Commerce Protocol (ACP) README*, fetched 2026-10-30", "date": null, "quote": "The specification is maintained by OpenAI and Stripe and is currently in beta. / The Agentic Commerce Protocol (ACP) is an interaction model and open standard for connecting buyers, their AI agents, and businesses to complete purchases seamlessly.", "ref": 6 }, { "label": "[7]", "url": "https://ucp.dev/documentation/ucp-and-ap2/", "claim": "Universal Commerce Protocol, *UCP and AP2*, fetched 2026-10-30", "date": null, "quote": "UCP is fully compatible with Agent Payments Protocol (AP2).", "ref": 7 }, { "label": "[8]", "url": "https://ucp.dev/latest/specification/payment/extensions/ap2-mandates/", "claim": "Universal Commerce Protocol, *AP2 Mandates Extension*, fetched 2026-10-30", "date": null, "quote": "user intents and authorizations using Verifiable Digital Credentials / the secure exchange of user intents and authorizations using Verifiable Digital Credentials. / Businesses MUST embed a cryptographic signature in checkout responses / Platforms MUST provide cryptographically signed proofs (Mandates) during the complete operation / the session is Security Locked. / dev.ucp.common.payment.ap2_mandate to their capabilities list in /.well-known/ucp. / \"version\": \"2026-08-25\"", "ref": 8 }, { "label": "[9]", "url": "https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/", "claim": "Suresh Ganapathy (Google), *Google's new Universal Cart launches today in the U.S.*, published 2026-10-15", "date": null, "quote": "checkout powered by the Universal Commerce Protocol (UCP) / merchants like Nike, Sephora, Target, Ulta Beauty, Walmart, Wayfair, and many Shopify merchants / \"datePublished\": \"2026-10-15T13:00:00+00:00\" / Today, Universal Cart is rolling out in the U.S. across Google Search and in the Gemini app. / You can securely check out with Google Pay in just a few taps", "ref": 9 }, { "label": "[10]", "url": "https://wiki.wireshark.org/UCP", "claim": "Wireshark Wiki, *Universal Computer Protocol (UCP)*, fetched 2026-10-30", "date": null, "quote": "Universal Computer Protocol (UCP) / transferring Short Messages between a Short Message Service Centre (SMSC)", "ref": 10 }, { "label": "[11]", "url": "https://docs.oracle.com/en/database/oracle/oracle-database/26/jjucp/intro.html", "claim": "Oracle, *Introduction to UCP (Universal Connection Pool)*, fetched 2026-10-30", "date": null, "quote": "Overview of Universal Connection Pool / A connection pool is a cache of database connection objects.", "ref": 11 }, { "label": "[12]", "url": "https://ucp.dev/documentation/core-concepts/", "claim": "Universal Commerce Protocol, *Core Concepts*, fetched 2026-10-30", "date": null, "quote": "The Universal Commerce Protocol (UCP) is an open standard for interoperability between commerce entities. / Each capability is identified by a reverse-domain name (e.g., dev.ucp.shopping.checkout) and carries a date-based version. / A Business declares which transport bindings it supports within each service; Platforms pick whichever fits their context - an AI agent may prefer MCP, a traditional web app may use REST. / Capability negotiation follows a server-selects architecture. / The business determines the active capabilities by computing the intersection of its own declared capabilities with those in the platform's profile / Select the highest (latest date). If no mutual version exists, exclude the capability. / Capabilities are declared in the Business's UCP profile at /.well-known/ucp, negotiated by exact version, and confirmed in every response so that the Platform always knows the active feature set for a given interaction. / In transactional contexts, the business typically acts as the Merchant of Record (MoR), retaining financial liability and ownership of the transaction - though UCP's capability model is not limited to transactional use cases. / Capabilities are declared in the Business's UCP profile at /.well-known/ucp / The business determines the active capabilities by computing the intersection / A single service can be accessed via multiple transport bindings: / REST OpenAPI 3.1.0 Standard server-to-server integrations MCP OpenRPC / Every UCP-defined service declares an explicit version equal to the selected ucp.version / Transport bindings have no separate version. / UCP defines the interactions between four distinct actors, each playing a specific role in the interaction lifecycle. / The platform is any entity that consumes capabilities exposed by a business / The entity exposing capabilities. / particularly payment instruments / The financial infrastructure provider that processes payments on behalf of businesses. / \"Payment Credential Provider\" refers to the CP and/or PSP roles defined above; depending on the payment handler, they may be the same entity or distinct. / Discovering business capabilities via profiles / acting on behalf of its principal within the bounds of negotiated capabilities. / Publishing a UCP profile, declaring supported services, capabilities and extensions / typically acts as the Merchant of Record (MoR), retaining financial liability and ownership of the transaction", "ref": 12 }, { "label": "[13]", "url": "https://raw.githubusercontent.com/Universal-Commerce-Protocol/.github/main/GOVERNANCE.md", "claim": "UCP Authors, *GOVERNANCE.md*, fetched 2026-10-30", "date": null, "quote": "GC serves as the ultimate owner of all UCP assets. / Google acts as the custodian of the UCP.dev domain, holding and managing it to foster adoption of UCP. / Includes a total of 5 members. / Includes 1 permanent member from each founding organization (Google & Shopify) each having 1 vote (total 2 votes). / Includes 3 elected members from any organization / Google holds proxy vote for all open seats until Dec 2028 / May choose to review and veto a DTC decision or recommendation. / needs to sign a contributor license", "ref": 13 }, { "label": "[14]", "url": "https://ucp.dev/latest/specification/embedded-protocol/", "claim": "Universal Commerce Protocol, *Embedded protocol*, fetched 2026-10-30", "date": null, "quote": "The Embedded Protocol (EP) is a UCP transport binding that enables a host to embed a business's interface in an iframe or webview and exchange structured messages over that channel. / The Embedded Protocol (EP) is a UCP transport binding that enables a host to embed a business's interface in an iframe or webview / All EP messages MUST use JSON-RPC 2.0 format (RFC 7159). / in an iframe or webview / embed a business's interface in an iframe or webview", "ref": 14 }, { "label": "[15]", "url": "https://ucp.dev/versions.json", "claim": "Universal Commerce Protocol, *versions.json*, last-modified 2026-10-29; fetched 2026-10-30", "date": null, "quote": "\"version\": \"2026-08-25\" / \"aliases\": [ \"latest\" ] / { \"version\": \"draft\", \"title\": \"draft\", \"aliases\": [] } / \"version\": \"2026-04-08\" / \"version\": \"2026-01-23\" / \"version\": \"2026-01-11\" / \"version\": \"draft\" / { \"version\": \"2026-08-25\", \"title\": \"2026-08-25\", \"aliases\": [ \"latest\" ] }", "ref": 15 }, { "label": "[16]", "url": "https://github.com/Universal-Commerce-Protocol/ucp/releases", "claim": "Universal-Commerce-Protocol, *Releases, Universal-Commerce-Protocol/ucp*, fetched 2026-10-30", "date": null, "quote": "\"tag_name\": \"v2026-08-25\", \"target_commitish\": \"release/2026-08-25\", \"name\": \"Release v2026-08-25\", \"draft\": false, \"immutable\": false, \"prerelease\": false, \"created_at\": \"2026-08-25T13:47:10Z\", \"updated_at\": \"2026-10-23T12:05:14Z\", \"published_at\": \"2026-08-25T13:53:03Z\" / \"tag_name\": \"v2026-04-08\", \"target_commitish\": \"release/2026-04-08\", \"name\": \"Release v2026-04-08\", \"draft\": false, \"immutable\": false, \"prerelease\": false, \"created_at\": \"2026-04-13T14:51:29Z\", \"updated_at\": \"2026-10-23T12:04:19Z\", \"published_at\": \"2026-04-09T01:48:20Z\" / \"tag_name\": \"v2026-01-23\", \"target_commitish\": \"release/2026-01-23\", \"name\": \"Release v2026-01-23\", \"draft\": false, \"immutable\": false, \"prerelease\": false, \"created_at\": \"2026-01-23T22:46:40Z\", \"updated_at\": \"2026-01-23T22:48:51Z\", \"published_at\": \"2026-01-23T22:48:51Z\" / \"tag_name\": \"v2026-01-11\", \"target_commitish\": \"release/2026-01-11\", \"name\": \"Release v2026-01-11\", \"draft\": false, \"immutable\": false, \"prerelease\": false, \"created_at\": \"2026-01-23T17:55:22Z\", \"updated_at\": \"2026-01-23T17:58:21Z\", \"published_at\": \"2026-01-23T17:58:21Z\" / Release v2026-08-25", "ref": 16 }, { "label": "[17]", "url": "https://ucp.dev/documentation/announcements/", "claim": "Universal Commerce Protocol, *Announcements*, fetched 2026-10-30", "date": null, "quote": "August 25, 2026: Protocol Release v2026-08-25 / April 8, 2026: Protocol Release v2026-04-08 / January 11, 2026: Protocol Release v2026-01-11 / April 28, 2026: Stripe Joins the Governing Council / Stripe has joined the UCP Governing Council as a new member, joining existing permanent members Google and Shopify. / July 16, 2026: Food Technical Council (Food TC) Formed / Initial members include Block (Square), DoorDash, Google, Toast, and Uber Eats. / August 11, 2026: Lodging Technical Council (Lodging TC) Formed / inaugural members Amadeus, Booking.com, Expedia, Google, Hilton, Marriott, and Trip.com / We are excited to welcome inaugural members Adyen NV, Ant International, Coinbase, Global Payments, Google, PayPal, Shopify, and Stripe to the Payments TC. / We have released version v2026-08-25 of the protocol. / September 25, 2026: UCP Lodging: Booking Capability Draft Spec Release / the initial draft version of the Lodging Booking capability (dev.ucp.lodging.booking) / September 2, 2026: Payments Technical Council (Payments TC) Formed / Stripe has joined the UCP Governing Council as a new member", "ref": 17 }, { "label": "[18]", "url": "https://github.com/Universal-Commerce-Protocol/ucp", "claim": "Universal-Commerce-Protocol, *ucp: Specification and documentation for the Universal Commerce Protocol*, repository created 2025-12-31; fetched 2026-10-30", "date": null, "quote": "\"createdAt\":\"2025-12-31T02:17:21.000Z\" / \"homepage\": \"https://ucp.dev\" / spdxId\":\"Apache-2.0\"", "ref": 18 }, { "label": "[19]", "url": "https://raw.githubusercontent.com/Universal-Commerce-Protocol/.github/main/MAINTAINERS.md", "claim": "UCP Authors, *UCP Maintainers*, fetched 2026-10-30", "date": null, "quote": "Shopping Tech Council / The Governance Council is responsible for the overall adoption and health of the protocol. / Amit Handa / Ilya Grigorik / Twum Djin / Stripe / to be elected / | Twum Djin | Stripe | / Jose Mendez | Adyen NV", "ref": 19 }, { "label": "[20]", "url": "https://ucp.dev/draft/specification/lodging/booking/", "claim": "Universal Commerce Protocol, *Lodging Booking capability (draft)*, fetched 2026-10-30", "date": null, "quote": "Capability Name: dev.ucp.lodging.booking", "ref": 20 }, { "label": "[21]", "url": "https://raw.githubusercontent.com/Universal-Commerce-Protocol/ucp/main/README.md", "claim": "Universal Commerce Protocol, *Universal Commerce Protocol (UCP) README*, fetched 2026-10-30", "date": null, "quote": "skip release branches and only build the current draft / Businesses can offer Capabilities via REST APIs, MCP (Model Context Protocol), or A2A, depending on their infrastructure. / Checkout: Facilitates checkout sessions including cart management and tax calculation / Identity Linking: Enables platforms to obtain authorization to perform actions on a user's behalf via OAuth 2.0. / Order: Webhook-based updates for order lifecycle events / Payment Token Exchange: Protocols for PSPs and Credential Providers to securely exchange payment tokens and credentials. / UCP is an open-source project under the Apache License 2.0 / As commerce becomes increasingly agentic and distributed, the ability for different systems to interoperate without custom, one-off integrations is vital.", "ref": 21 }, { "label": "[22]", "url": "https://ucp.dev/latest/specification/shopping/checkout/a2a/", "claim": "Universal Commerce Protocol, *Checkout A2A binding*, fetched 2026-10-30", "date": null, "quote": "Businesses supporting UCP must advertise the extension and any optional capabilities in their A2A Agent Card", "ref": 22 }, { "label": "[23]", "url": "https://www.iana.org/assignments/well-known-uris", "claim": "IANA, *Well-Known URIs Registry*, updated 2026-10-26", "date": null, "quote": "ucp https://ucp.dev/latest/specification/overview/#profile-structure provisional Ilya Grigorik 2026-10-26", "ref": 23 }, { "label": "[24]", "url": "https://blog.google/products-and-platforms/platforms/google-pay/agent-payments-protocol-fido-alliance/", "claim": "Google, *Google donates Agent Payments Protocol to FIDO Alliance*, 2026-04-28", "date": "2026-04-28", "quote": "Google donates the Agent Payments Protocol (AP2) to the FIDO Alliance / \"datePublished\": \"2026-04-28T13:00:00+00:00\"", "ref": 24 }, { "label": "[25]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/specification.md", "claim": "Agent Payments Protocol (google-agentic-commerce), *Agentic Payment Protocol (v0.2)*, fetched 2026-10-30", "date": null, "quote": "AP2 operates as a security feature within a Commerce Protocol. / AP2 is designed explicitly to be compatible with the Universal Commerce Protocol (UCP) and integrates seamlessly.", "ref": 25 }, { "label": "[26]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification, 2026-07-28*, specification date 2026-07-28; fetched 2026-10-30", "date": null, "quote": "The protocol uses JSON-RPC 2.0 messages", "ref": 26 }, { "label": "[27]", "url": "https://ucp.dev/latest/specification/shopping/checkout/mcp/", "claim": "Universal Commerce Protocol, *Checkout MCP binding*, fetched 2026-10-30", "date": null, "quote": "Businesses advertise MCP transport availability through their UCP profile at /.well-known/ucp.", "ref": 27 }, { "label": "[28]", "url": "https://a2a-protocol.org/latest/specification/", "claim": "A2A Protocol, *Overview*, fetched 2026-10-30", "date": null, "quote": "JSON-RPC Protocol Binding / Agent Card", "ref": 28 }, { "label": "[29]", "url": "https://www.rfc-editor.org/info/rfc9421/", "claim": "A. Backman, J. Richer, and M. Sporny, *RFC 9421: HTTP Message Signatures*, fetched 2026-10-30", "date": null, "quote": "RFC 9421: HTTP Message Signatures", "ref": 29 }, { "label": "[30]", "url": "https://ucp.dev/latest/specification/signatures/", "claim": "Universal Commerce Protocol, *Signatures*, fetched 2026-10-30", "date": null, "quote": "This specification defines how to sign and verify UCP messages using RFC 9421 HTTP Message Signatures. / EdDSA is an additive option that unlocks Web Bot Auth (WBA) interop.", "ref": 30 }, { "label": "[31]", "url": "https://www.shopify.com/news/agentic-commerce-momentum", "claim": "Shopify, *Millions of merchants can sell in AI chats*, published 2026-03-24", "date": null, "quote": "select brands have started selling in AI Mode in Google Search and the Gemini app, powered by the Universal Commerce Protocol (UCP) / the open standard we co-developed with Google / \"datePublished\":\"2026-03-24T16:00:15Z\"", "ref": 31 }, { "label": "[32]", "url": "https://www.allbirds.com/.well-known/ucp", "claim": "Allbirds, *UCP profile at /.well-known/ucp*, fetched 2026-10-30", "date": null, "quote": "\"version\":\"2026-08-25\" / weareallbirds.myshopify.com / \"transport\":\"mcp\" / \"transport\":\"embedded\" / com.google.pay / dev.shopify.card / dev.shopify.shop_pay / dev.ucp.shopping.checkout / dev.ucp.common.identity_linking / \"dev.ucp.common\":", "ref": 32 }, { "label": "[33]", "url": "https://www.glossier.com/.well-known/ucp", "claim": "Glossier, *UCP profile at /.well-known/ucp*, fetched 2026-10-30", "date": null, "quote": "\"version\":\"2026-08-25\" / glossier-admin.myshopify.com / \"transport\":\"mcp\" / \"transport\":\"embedded\" / com.google.pay / dev.shopify.card / dev.shopify.shop_pay / dev.ucp.shopping.checkout / dev.ucp.common.identity_linking / \"dev.ucp.common\":", "ref": 33 }, { "label": "[34]", "url": "https://www.monos.com/.well-known/ucp", "claim": "Monos, *UCP profile at /.well-known/ucp*, fetched 2026-10-30", "date": null, "quote": "\"version\":\"2026-08-25\" / monostravel.myshopify.com / \"transport\":\"mcp\" / \"transport\":\"embedded\" / com.google.pay / dev.shopify.card / dev.shopify.shop_pay / dev.ucp.shopping.checkout / dev.ucp.common.identity_linking / \"dev.ucp.common\":", "ref": 34 }, { "label": "[35]", "url": "https://www.stevemadden.com/.well-known/ucp", "claim": "Steve Madden, *UCP profile at /.well-known/ucp*, fetched 2026-10-30", "date": null, "quote": "\"version\":\"2026-08-25\" / stevemadden.myshopify.com / \"transport\":\"mcp\" / \"transport\":\"embedded\" / com.google.pay / dev.shopify.card / dev.shopify.shop_pay / dev.ucp.shopping.checkout / dev.ucp.common.identity_linking", "ref": 35 }, { "label": "[36]", "url": "https://fentybeauty.com/.well-known/ucp", "claim": "Fenty Beauty, *UCP profile at /.well-known/ucp*, fetched 2026-10-30", "date": null, "quote": "\"version\":\"2026-08-25\" / fentybeautyshop.myshopify.com / \"transport\":\"mcp\" / \"transport\":\"embedded\" / com.google.pay / dev.shopify.card / dev.shopify.shop_pay / dev.ucp.shopping.checkout / dev.ucp.common.identity_linking", "ref": 36 }, { "label": "[37]", "url": "https://www.ikea.com/.well-known/ucp", "claim": "IKEA, *UCP profile at /.well-known/ucp*, fetched 2026-10-30", "date": null, "quote": "\"version\": \"2026-04-08\" / \"2026-08-25\": \"https://ucp.checkout.ingka.com/.well-known/ucp/2026-08-25\" / \"environment\": \"TEST\" / com.google.pay / \"endpoint\": \"https://ucp.checkout.ingka.com/api/us/mcp/messages\" / \"endpoint\": \"https://ucp.checkout.ingka.com/api/us/2026-04-08/rest\" / \"transport\": \"rest\" / dev.ucp.shopping.checkout / dev.ucp.shopping.fulfillment / \"alg\": \"ES256\" / \"version\": \"2026-01-23\"", "ref": 37 }, { "label": "[38]", "url": "https://docs.stripe.com/agentic-commerce/protocols/ucp", "claim": "Stripe, *Universal Commerce Protocol*, fetched 2026-10-30", "date": null, "quote": "with support for checkout, identity linking, order tracking, and secure payment token exchange (Stripe is a member of the UCP Tech Council).", "ref": 38 }, { "label": "[39]", "url": "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp", "claim": "Adyen, *AI agent API integration with UCP*, fetched 2026-10-30", "date": null, "quote": "Integrate with the Adyen Agentic API to enable your AI agent platform to make transactions with Adyen merchants using the Universal Commerce Protocol (UCP). / Session operations also require UCP HTTP Message Signatures (RFC 9421) for request integrity and origin verification.", "ref": 39 }, { "label": "[40]", "url": "https://corporate.target.com/press/fact-sheet/2026/06/conversational-ai", "claim": "Target, *How Target is Shaping Shopping Experiences in Conversational AI*, updated 2026-06-18", "date": null, "quote": "Shoppers can now browse product listings and buy items directly from Target in Google Search, including AI Mode, and the Gemini app. / The capability comes thanks to the Universal Commerce Protocol (UCP) / Updated 6:00am CT | Jun 18, 2026", "ref": 40 }, { "label": "[41]", "url": "https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/", "claim": "Vidhya Srinivasan (Google), *What to expect in digital advertising and commerce in 2026*, published 2026-02-11", "date": null, "quote": "UCP-powered checkout is rolling out now, letting US shoppers buy items from Etsy and Wayfair, right in AI Mode in Search and the Gemini app (with Shopify, Target, and Walmart coming soon). / \"datePublished\": \"2026-02-11T16:00:00+00:00\"", "ref": 41 }, { "label": "[42]", "url": "https://www.digitalcommerce360.com/2026/10/12/newegg-adds-google-ucp-checkout-integration/", "claim": "Brian Warmoth (Digital Commerce 360), *Newegg adds Google UCP checkout integration*, published 2026-10-12", "date": null, "quote": "\"datePublished\":\"2026-10-12T22:15:02+00:00\" / announcing that it has integrated Google's Universal Commerce Protocol (UCP) for online checkout. / Newegg remains the merchant of record", "ref": 42 }, { "label": "[43]", "url": "https://developers.google.com/merchant/ucp/faq", "claim": "Google for Developers, *Google Universal Commerce Protocol (UCP) Guide, FAQ*, fetched 2026-10-30", "date": null, "quote": "At launch, your UCP integration will power experiences on AI Mode in Google Search, as well as both the Gemini web application and the Gemini mobile app.", "ref": 43 }, { "label": "[44]", "url": "https://developers.google.com/pay/api/universal-commerce-protocol/google-pay-payment-handler", "claim": "Google for Developers, *Google Pay payment handler for Universal Commerce Protocol*, fetched 2026-10-30", "date": null, "quote": "Google Pay payment handler for Universal Commerce Protocol (UCP) enables users and merchants to use Google Pay as a credential provider on Google AI surfaces like Gemini and AI Mode. / Google Pay payment handler is identified by the name com.google.pay inside the payment_handlers object.", "ref": 44 }, { "label": "[45]", "url": "https://github.com/orgs/Universal-Commerce-Protocol/repositories", "claim": "GitHub API, Universal-Commerce-Protocol, *Organization repositories*, fetched 2026-10-30", "date": null, "quote": "\"name\": \"python-sdk\" / The official Python SDK for UCP / \"name\": \"js-sdk\" / The official JavaScript SDK for UCP / \"name\": \"conformance\" / Conformance Tests for UCP", "ref": 45 }, { "label": "[46]", "url": "https://ucpregistry.com/", "claim": "UCP Registry, *The Universal Commerce Protocol Registry*, checked 2026-11-06", "date": null, "quote": "Free Chrome extension that detects UCP manifests on any store you visit. Shows capabilities, payment handlers, transports, AI bot policies, and spec version in one click. / Works on Chrome, Edge, and Brave. / Buy now, pay later platform enabling merchants to offer flexible installment payment options at checkout. / Global payment processing platform providing online payment solutions, fraud detection, and multi-currency support for merchants worldwide. / Vintage-Racewear.com offers a curated collection of vintage motorsport racing jackets and apparel with UCP-enabled order, checkout, discount, and fulfillment. / Verified 204 days ago", "ref": 46 }, { "label": "[47]", "url": "https://ucp.dev/", "claim": "Universal Commerce Protocol, *Universal Commerce Protocol*, checked 2026-11-06", "date": null, "quote": "Co-developed by industry leaders / Expedia Group / Booking.com / Uber Eats / DoorDash / Salesforce", "ref": 47 } ], "form": "well-known-file", "governance": "A Governing Council (GC) of five seats: one permanent seat each for the founding organizations, Google and Shopify, and three elected seats. On 2026-10-28 the seats were held by Google, Shopify and Stripe, with two open; Stripe joined on 2026-04-28. GOVERNANCE.md says \"GC serves as the ultimate owner of all UCP assets. Google acts as the custodian of the UCP.dev domain, holding and managing it to foster adoption of UCP.\" and \"Google holds proxy vote for all open seats until Dec 2028 to facilitate rapid early stage growth & adoption of the protocol.\". Four Domain Tech Councils write the specification: Shopping, Food (formed 2026-07-16; initial members Block (Square), DoorDash, Google, Toast and Uber Eats), Lodging (formed 2026-08-11; inaugural members Amadeus, Booking.com, Expedia, Google, Hilton, Marriott and Trip.com) and Payments (formed 2026-09-02; inaugural members Adyen NV, Ant International, Coinbase, Global Payments, Google, PayPal, Shopify and Stripe); of the GC, GOVERNANCE.md says \"May choose to review and veto a DTC decision or recommendation.\". Apache-2.0 licence; contributors sign a CLA", "group": null, "hatnote_md": "This page is about the Universal Commerce Protocol (UCP) co-developed by Google and Shopify. It is not the [Agentic Commerce Protocol](https://agenticweb.wiki/protocols/agentic-commerce-protocol/) (ACP) maintained by OpenAI and Stripe, nor the [Agent Payments Protocol (AP2)](https://agenticweb.wiki/protocols/ap2/) (which integrates with UCP via the AP2 Mandates extension). It is also distinct from Google's UCP-powered Universal Cart consumer feature, the SMSC Universal Computer Protocol, and Oracle's Universal Connection Pool.", "history": [ { "date": "2026-10-28", "note": "Verified record against 41 primary and secondary sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "ucp", "implementation": "multi-implementation", "last_verified": "2026-11-06", "name": "Universal Commerce Protocol (UCP)", "native_status": "Live. Dated releases since 2026-01-11; ucp.dev also publishes a \"draft\" version, which on 2026-10-28 held the Lodging Booking capability (dev.ucp.lodging.booking), announced as a draft on 2026-09-25", "origin": { "date": "2026-01-11", "org": "Google and Shopify" }, "pairs_with": [ "agentic-commerce-protocol", "ap2", "mcp", "a2a", "http-message-signatures" ], "part_of": null, "parties": [ "agent-site" ], "phase": "living", "prerequisites": [], "probe": { "method": "GET", "on_absent": "A missing or non-JSON response at /.well-known/ucp means the origin does not declare UCP capabilities.", "parse": "200 response with a UCP profile JSON document declaring supported Capabilities and Services", "path": "{origin}/.well-known/ucp" }, "question": "Can an agent discover a business's commerce capabilities, build a cart, and check out interoperably across shopping, lodging, and food ordering?", "scope": "commerce", "spec_url": "https://ucp.dev/latest/specification/overview/", "step": "pay", "summary_md": "**Universal Commerce Protocol** (`UCP`) is an open standard co-developed by Google and Shopify (announced 2026-01-11 and governed by a five-seat Governing Council) that enables AI agents, platforms, and merchants to interoperate across commerce workflows. Each participant publishes a JSON profile document containing a required `ucp` object that declares the protocol version, supported services, optional capabilities, and payment handlers. Businesses publish their profile at `/.well-known/ucp`, while platforms advertise their profile URI in every request via the `UCP-Agent` header (formatted over HTTP using RFC 8941 Dictionary Structured Field syntax). Services declared in a business profile can bind to REST over HTTP/1.1+, Model Context Protocol (`MCP`) over JSON-RPC, Agent2Agent (`A2A`) extensions, or the iframe-based Embedded Protocol (`EP`). UCP uses date-based versioning (`YYYY-MM-DD`), with `2026-08-25` designated as `latest` alongside prior releases (`2026-04-08`, `2026-01-23`, and `2026-01-11`) and an active `draft` specification track.", "track": "vendor-consortium", "use_cases": [ "agent-checkout", "delegate-user-authority", "audit-agent-actions" ], "version": { "date": "2026-08-25", "label": "2026-08-25, marked \"latest\" on ucp.dev. Releases on GitHub: v2026-08-25 (published 2026-08-25), v2026-04-08 (published 2026-04-09 UTC), v2026-01-23 (published 2026-01-23) and v2026-01-11 (published on GitHub on 2026-01-23; the announcements page dates the release 2026-01-11)" }, "watch": [ { "cadence": "weekly", "selector": "main", "type": "page", "url": "https://ucp.dev/documentation/core-concepts/" }, { "repo": "Universal-Commerce-Protocol/ucp", "type": "github" } ], "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-06", "v05_hatnote_html_md": "This page is about the Universal Commerce Protocol (UCP) co-developed by Google and Shopify. It is not the [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/) (ACP) maintained by OpenAI and Stripe, nor the [Agent Payments Protocol (AP2)](/protocols/ap2/) (which integrates with UCP via the AP2 Mandates extension). It is also distinct from Google's UCP-powered Universal Cart consumer feature, the SMSC Universal Computer Protocol, and Oracle's Universal Connection Pool. [1][2][3][4][5][6][7][8][9][10][11]", "v05_elevator_pitch_md": "UCP (Universal Commerce Protocol) is a cross-platform discovery and capability-negotiation standard that allows AI shopping platforms, consumer agents, and online merchants to transact across REST, MCP, and A2A transports while the seller remains the merchant of record. Instead of building custom point-to-point integrations for every retail platform, a business publishes its supported services and payment handlers at `/.well-known/ucp` and computes the active capability intersection (such as `dev.ucp.shopping.checkout`) against the caller's `UCP-Agent` profile header. [5][12]", "v05_lead_md": "**Universal Commerce Protocol** (`UCP`) is an open standard co-developed by Google and Shopify (announced 2026-01-11 and governed by a five-seat Governing Council) that enables AI agents, platforms, and merchants to interoperate across commerce workflows. Each participant publishes a JSON profile document containing a required `ucp` object that declares the protocol version, supported services, optional capabilities, and payment handlers. [2][3][4][5][12][13] Businesses publish their profile at `/.well-known/ucp`, while platforms advertise their profile URI in every request via the `UCP-Agent` header (formatted over HTTP using RFC 8941 Dictionary Structured Field syntax). Services declared in a business profile can bind to REST over HTTP/1.1+, Model Context Protocol (`MCP`) over JSON-RPC, Agent2Agent (`A2A`) extensions, or the iframe-based Embedded Protocol (`EP`). [5][12][14] UCP uses date-based versioning (`YYYY-MM-DD`), with `2026-08-25` designated as `latest` alongside prior releases (`2026-04-08`, `2026-01-23`, and `2026-01-11`) and an active `draft` specification track. [5][15][16][17]", "v05_identity_sentence_md": "**Universal Commerce Protocol** (`UCP`) is an open standard co-developed by Google and Shopify (announced 2026-01-11 and governed by a five-seat Governing Council) that enables AI agents, platforms, and merchants to interoperate across commerce workflows. Each participant publishes a JSON profile document containing a required `ucp` object that declares the protocol version, supported services, optional capabilities, and payment handlers. [2][3][4][5][12][13]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "Well-known file (`well-known-file`)" }, { "label": "Originated by", "value_md": "Google and Shopify, announced 2026-01-11; GitHub repository created 2025-12-31. [2][3][4][18]" }, { "label": "Governed by", "value_md": "Five-seat Governing Council (permanent founding seats for Google and Shopify, plus Stripe as elected member; Google holds proxy votes for open seats until Dec 2028). [13][17][19]" }, { "label": "Track", "value_md": "Vendor consortium (`vendor-consortium`), co-developed by founding members Google and Shopify. [2][13]" }, { "label": "Status", "value_md": "Released `2026-08-25` (`latest` alias); `draft` track includes the `dev.ucp.lodging.booking` capability. [15][17][20]" }, { "label": "Version", "value_md": "Release `2026-08-25` (aliased as `latest`), alongside an active `draft` build branch. [15][16][21]" }, { "label": "Found at", "value_md": "Businesses publish profiles at `/.well-known/ucp`; platforms publish profiles at the URI advertised in `UCP-Agent`. [5]" }, { "label": "Headers", "value_md": "`UCP-Agent` (required RFC 8941 Dictionary Structured Field on REST requests) and `Content-Type: application/json` (required on requests and responses; endpoint URIs should omit trailing slashes). [5]" }, { "label": "Transports", "value_md": "REST over HTTP/1.1+, Model Context Protocol (MCP) over JSON-RPC, optional Agent2Agent (A2A) extension, and the Embedded Protocol (EP) iframe or webview binding. [5][14][21][22]" }, { "label": "Message format", "value_md": "JSON profile object with a required `ucp` member declaring protocol version, services, optional capabilities, and payment handlers. [5][21]" }, { "label": "Specification", "value_md": "[Overview](https://ucp.dev/latest/specification/overview/) (`latest` = `2026-08-25`). [12][15][18]" }, { "label": "Licence", "value_md": "Apache License 2.0 (contributors sign a contributor license agreement). [13][18][21]" }, { "label": "IANA registration", "value_md": "Provisional well-known URI suffix `ucp` (`/.well-known/ucp`), registered `2026-10-26` (contact: Ilya Grigorik). [23]" } ], "v05_problem_md": "As commerce becomes increasingly agentic and distributed, the ability for different systems to interoperate without custom, one-off integrations is vital. [21] Capability negotiation follows a server-selects architecture: a business computes the intersection between its own `/.well-known/ucp` profile and the caller's platform profile across reverse-domain capabilities (such as `dev.ucp.shopping.checkout`), selecting the latest mutually supported date version and confirming the active feature set in every response. [12] In transactional contexts, the business typically acts as the Merchant of Record (MoR), retaining financial liability and ownership of the transaction, though UCP's capability model is not limited to transactional use cases. [12]", "v05_mechanism_delta_md": "Capability negotiation follows a server-selects architecture: a business computes the intersection between its own `/.well-known/ucp` profile and the caller's platform profile across reverse-domain capabilities (such as `dev.ucp.shopping.checkout`), selecting the latest mutually supported date version and confirming the active feature set in every response. [12]", "v05_scope_boundary_md": "In transactional contexts, the business typically acts as the Merchant of Record (MoR), retaining financial liability and ownership of the transaction, though UCP's capability model is not limited to transactional use cases. [12]", "v05_fuzzy_additions": [ { "id": "well-known-profile-discovery-capability-intersection-and-transport-bindings", "heading": "Well-known profile discovery, capability intersection, and transport bindings", "body_md": "Before initiating a request, a platform may fetch a merchant's `/.well-known/ucp` document and must include its own profile URI in every request via the transport-appropriate `UCP-Agent` mechanism. After computing the capability intersection between the two profiles, the business must return a `ucp` object in every response containing the active `version` and `capabilities` array. [5]", "bullets": [ { "label": "Reverse-domain capability names", "text_md": "All capability and service identifiers must follow the `{reverse-domain}.{service}.{capability}` grammar, where `{reverse-domain}` is an authority identifier derived from domain ownership; for example, `dev.ucp.shopping.checkout` pairs authority `ucp.dev` with service `shopping` in the profile at `/.well-known/ucp`. [5][12]" }, { "label": "Date-based version intersection", "text_md": "Negotiation proceeds in two phases using `YYYY-MM-DD` date strings: protocol version selection first chooses one complete business profile, and capability negotiation then selects active capabilities and extensions by exact version intersection within that profile, picking the highest (latest date) match. [5][12]" }, { "label": "Extensions and schema composition", "text_md": "Extensions declare parent capabilities via the `extends` field (as a single string or an array of parent names, at least one of which must be present in the active intersection) and modify base JSON Schemas using `allOf` composition, which platforms must resolve and compose client-side. [5]" }, { "label": "REST, MCP, A2A, and Embedded bindings", "text_md": "A single service entry inherits `ucp.version` and can expose multiple transport bindings—REST (OpenAPI 3.1.0), MCP (OpenRPC), A2A extensions, and Embedded Protocol (`EP`)—without separate per-binding versions; `EP` embeds a merchant interface inside an iframe or webview and exchanges JSON-RPC 2.0 messages. [5][12][14]" } ] }, { "id": "payment-handlers-ap2-mandates-and-ecosystem-governance", "heading": "Payment handlers, AP2 mandates, and ecosystem governance", "body_md": "UCP models transactions across four distinct actor roles: the platform (which consumes business capabilities), the business (which exposes them), the credential provider (CP, which manages sensitive payment instruments), and the payment service provider (PSP, which processes payments on behalf of businesses; CP and PSP are collectively termed the Payment Credential Provider). [12]", "bullets": [ { "label": "Actor duties and Domain Technical Councils", "text_md": "In an interaction, the platform discovers business profiles and invokes capabilities on behalf of its principal within negotiated bounds, while the business publishes its profile and declares supported services, capabilities, and extensions. Specification work is divided across four Domain Tech Councils: Shopping, Food (formed July 16, 2026), Lodging (formed August 11, 2026), and Payments (formed September 2, 2026). [12][13][17][19]" }, { "label": "Instruments versus payment handlers", "text_md": "UCP separates Payment Instruments (what payment methods are accepted) from Payment Handlers (the specifications for how instruments are processed, which are specifications rather than legal entities). Reverse-domain handler identifiers such as `com.google.pay` and `dev.shopify.shop_pay` correspond to Google Pay and Shop Pay, and businesses must filter advertised handlers based on the cart context. [5]" }, { "label": "AP2 mandates and the FIDO donation", "text_md": "The AP2 Mandates extension (`dev.ucp.common.payment.ap2_mandate` in `/.well-known/ucp`, version `2026-08-25`) exchanges user intents and authorizations as Verifiable Digital Credentials: when a session is Security Locked, businesses must embed a cryptographic signature in checkout responses and platforms must supply signed mandates during completion. Google donated AP2 to the FIDO Alliance on 2026-04-28. [8][24]" }, { "label": "Dated releases through 2026-08-25", "text_md": "Following the initial `2026-01-11` launch and `2026-01-23` update, UCP published `v2026-04-08` (tagged 2026-04-09 on GitHub) and `v2026-08-25` (`latest`), alongside an active `draft` track. Ultimate ownership of all UCP assets rests with the Governing Council, where Stripe joined founding members Google and Shopify on April 28, 2026. [13][15][16][17]" } ] } ], "v05_diagram": { "title": "Discovery and capability intersection", "heading": "Discovery and capability intersection", "mermaid": "sequenceDiagram\n participant Platform\n participant Business\n opt Discovery\n Platform->>Business: fetch /.well-known/ucp\n Business-->>Platform: business profile\n end\n Platform->>Business: UCP-Agent profile URI\n Note over Business: fetch platform profile, capability intersection\n Business-->>Platform: ucp version and capabilities", "caption_md": "The platform may fetch `/.well-known/ucp`, then sends its profile URI in `UCP-Agent`. The business returns `version` and `capabilities`. [5]" }, "v05_wire_artifact": { "title": "Business profile at `/.well-known/ucp`", "heading": "Business profile at `/.well-known/ucp`", "lang": "json", "code": "{\n \"ucp\": {\n \"version\": \"2026-08-25\",\n \"services\": {\n \"dev.ucp.shopping\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"rest\",\n \"endpoint\": \"https://business.example.com/ucp/v1\",\n \"schema\": \"https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json\"\n },\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"mcp\",\n \"endpoint\": \"https://business.example.com/ucp/mcp\",\n \"schema\": \"https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json\"\n },\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"a2a\",\n \"endpoint\": \"https://business.example.com/.well-known/agent-card.json\"\n },\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"embedded\",\n \"schema\": \"https://ucp.dev/2026-08-25/services/shopping/embedded.openrpc.json\"\n }\n ]\n },\n \"capabilities\": {\n \"dev.ucp.shopping.checkout\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/shopping/checkout\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/shopping/checkout.json\"\n }\n ],\n \"dev.ucp.shopping.fulfillment\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/shopping/extensions/fulfillment\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/shopping/fulfillment.json\",\n \"extends\": \"dev.ucp.shopping.checkout\"\n }\n ],\n \"dev.ucp.shopping.discount\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/shopping/extensions/discount\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/shopping/discount.json\",\n \"extends\": \"dev.ucp.shopping.checkout\"\n }\n ],\n \"dev.ucp.common.identity_linking\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/common/identity-linking/\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/common/identity_linking.json\",\n \"config\": {\n \"providers\": {\n \"com.example.idp\": [\n { \"type\": \"oauth2\", \"auth_url\": \"https://accounts.example.com/\" }\n ]\n },\n \"scopes\": {\n \"dev.ucp.shopping.order:read\": {},\n \"dev.ucp.shopping.order:manage\": {}\n }\n }\n }\n ]\n },\n \"payment_handlers\": {\n \"com.example.processor_tokenizer\": [\n {\n \"id\": \"processor_tokenizer\",\n \"version\": \"2026-08-25\",\n \"spec\": \"https://example.com/specs/payments/processor_tokenizer\",\n \"schema\": \"https://example.com/specs/payments/merchant_tokenizer.json\",\n \"available_instruments\": [\n {\n \"type\": \"card\",\n \"constraints\": {\n \"properties\": { \"brand\": { \"enum\": [\"visa\", \"mastercard\", \"amex\"] } }\n }\n }\n ],\n \"config\": {\n \"type\": \"CARD\",\n \"tokenization_specification\": {\n \"type\": \"PUSH\",\n \"parameters\": {\n \"token_retrieval_url\": \"https://api.psp.example.com/v1/tokens\"\n }\n }\n }\n }\n ]\n }\n },\n \"keys\": [\n {\n \"kid\": \"poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U\",\n \"kty\": \"OKP\",\n \"crv\": \"Ed25519\",\n \"x\": \"JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs\",\n \"use\": \"sig\",\n \"alg\": \"EdDSA\"\n },\n {\n \"kid\": \"business_2025\",\n \"kty\": \"EC\",\n \"crv\": \"P-256\",\n \"x\": \"qIVYZVLCrPZHGHjP17CTW0_-D9Lfw0EkjqF7xB4FivA\",\n \"y\": \"Mc4nN9LTDOBhfoUeg8Ye9WedFRhnZXZJA12Qp0zZ6F0\",\n \"use\": \"sig\",\n \"alg\": \"ES256\"\n }\n ]\n}", "caption_md": "Business profile published at `/.well-known/ucp`, with `version` `2026-08-25`, `services`, `capabilities`, `payment_handlers`, and `keys`. [5]" }, "v05_counterparts": { "classic_analogues": [ { "name": "Well-Known URIs (RFC 8615)", "spec_or_rfc": "RFC 8615", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Business profile at /.well-known/ucp; platform profile URI is advertised in UCP-Agent. [5]" }, { "name": "W3C Payment Request API & Web Checkout", "spec_or_rfc": "W3C Payment Request", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "UCP lists payment handlers on /.well-known/ucp; Payment Request is the browser checkout API. [5][14]" } ], "agentic_peers": [ { "target_id": "agentic-commerce-protocol", "target_name": "Agentic Commerce Protocol", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "ACP (OpenAI and Stripe, beta) uses its own checkout; UCP publishes /.well-known/ucp payment handlers. [5][6]" }, { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "depended_on_by", "relation_label": "Depended on by", "delta_md": "AP2 is a compatible security feature; UCP's AP2 Mandates extension carries verifiable credentials. [7][8][25]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "MCP is JSON-RPC 2.0; UCP checkout advertises MCP and calls tools/call. [5][26][27]" }, { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "A2A is Agent Card JSON-RPC; UCP checkout must be advertised on that card. [22][28]" }, { "target_id": "http-message-signatures", "target_name": "HTTP Message Signatures", "relation_type": "complements", "relation_label": "Complements", "delta_md": "RFC 9421 signs HTTP messages; UCP signs its messages and adds EdDSA for Web Bot Auth. [29][30]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (20 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Merchants, platforms & payment processors", "col4_header": "`/.well-known/ucp` profile capabilities, transport & payment handlers", "note_md": null, "rows": [ { "actor": "Shopify", "role": "Platform (Co-author)", "status": "Supported", "status_display": "Supported · as of 2026-03-24", "col4_md": "Select brands sell in AI Mode and Gemini on co-developed UCP.", "source_md": "[Shopify News (datePublished 2026-03-24)](https://www.shopify.com/news/agentic-commerce-momentum) [31] · [Shopify Engineering, UCP](https://shopify.engineering/ucp) [2]" }, { "actor": "Allbirds", "role": "Seller (Shopify merchant)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "`2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`.", "source_md": "[Allbirds UCP profile](https://www.allbirds.com/.well-known/ucp) [32]" }, { "actor": "Glossier", "role": "Seller (Shopify merchant)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "`2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`.", "source_md": "[Glossier UCP profile](https://www.glossier.com/.well-known/ucp) [33]" }, { "actor": "Monos", "role": "Seller (Shopify merchant)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "`2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`.", "source_md": "[Monos UCP profile](https://www.monos.com/.well-known/ucp) [34]" }, { "actor": "Steve Madden", "role": "Seller (Shopify merchant)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "`2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`.", "source_md": "[Steve Madden UCP profile](https://www.stevemadden.com/.well-known/ucp) [35]" }, { "actor": "Fenty Beauty", "role": "Seller (Shopify merchant)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "`2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`.", "source_md": "[Fenty Beauty UCP profile](https://fentybeauty.com/.well-known/ucp) [36]" }, { "actor": "IKEA (Ingka)", "role": "Retailer (Custom UCP endpoint)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Active `2026-04-08` on `mcp` and `rest`; `com.google.pay` environment is `TEST`.", "source_md": "[IKEA UCP profile](https://www.ikea.com/.well-known/ucp) [37]" }, { "actor": "Stripe", "role": "Payment processor (Governing Council)", "status": "Supported", "status_display": "Supported · as of 2026-09-02", "col4_md": "Checkout, identity linking, order tracking, and payment-token exchange.", "source_md": "[Stripe UCP docs (checked 2026-10-30)](https://docs.stripe.com/agentic-commerce/protocols/ucp) [38] · [UCP announcements](https://ucp.dev/documentation/announcements/) [17] · [UCP MAINTAINERS.md](https://raw.githubusercontent.com/Universal-Commerce-Protocol/.github/main/MAINTAINERS.md) [19]" }, { "actor": "Adyen", "role": "Payment processor", "status": "Supported", "status_display": "Supported · as of 2026-09-02", "col4_md": "Agentic API transacts with Adyen merchants; sessions require RFC 9421.", "source_md": "[Adyen UCP docs (checked 2026-10-30)](https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp) [39] · [UCP announcements](https://ucp.dev/documentation/announcements/) [17] · [UCP MAINTAINERS.md](https://raw.githubusercontent.com/Universal-Commerce-Protocol/.github/main/MAINTAINERS.md) [19]" }, { "actor": "Visa", "role": "Payment network (endorser)", "status": "Listed", "status_display": "Listed · as of 2026-01-11", "col4_md": "Named among more than 20 launch endorsers on 2026-01-11.", "source_md": "[Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4]" }, { "actor": "Mastercard", "role": "Payment network (endorser)", "status": "Listed", "status_display": "Listed · as of 2026-01-11", "col4_md": "Launch-post endorser on 2026-01-11; no handler id in that sentence.", "source_md": "[Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4]" }, { "actor": "Target", "role": "Retailer (co-developer)", "status": "Supported", "status_display": "Supported · as of 2026-10-15", "col4_md": "Buy in Google Search AI Mode and Gemini via UCP; Universal Cart merchant.", "source_md": "[Target fact sheet (updated Jun 18, 2026)](https://corporate.target.com/press/fact-sheet/2026/06/conversational-ai) [40] · [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9]" }, { "actor": "Wayfair", "role": "Retailer (co-developer)", "status": "Supported", "status_display": "Supported · as of 2026-10-15", "col4_md": "Co-developer; 2026-02-11 UCP checkout rollout; Universal Cart merchant.", "source_md": "[Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, advertising and commerce (2026-02-11)](https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/) [41] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9]" }, { "actor": "Walmart", "role": "Retailer (co-developer)", "status": "Supported", "status_display": "Supported · as of 2026-10-15", "col4_md": "Co-developer; coming soon on 2026-02-11; listed on Universal Cart.", "source_md": "[Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, advertising and commerce (2026-02-11)](https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/) [41] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9]" }, { "actor": "Etsy", "role": "Retailer (co-developer)", "status": "Supported", "status_display": "Supported · as of 2026-02-11", "col4_md": "Co-developer; 2026-02-11 UCP checkout for US shoppers in AI Mode.", "source_md": "[Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, advertising and commerce (2026-02-11)](https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/) [41] · [Shopify Engineering, UCP](https://shopify.engineering/ucp) [2]" }, { "actor": "Newegg", "role": "Retailer", "status": "Supported", "status_display": "Supported · as of 2026-10-12", "col4_md": "Integrated UCP for online checkout (2026-10-12) as merchant of record.", "source_md": "[Digital Commerce 360, Newegg UCP checkout (2026-10-12)](https://www.digitalcommerce360.com/2026/10/12/newegg-adds-google-ucp-checkout-integration/) [42]" }, { "actor": "PayPal", "role": "Payment processor (Payments TC)", "status": "Listed", "status_display": "Listed · as of 2026-09-02", "col4_md": "Inaugural member of the UCP Payments Technical Council (formed September 2, 2026).", "source_md": "[UCP announcements](https://ucp.dev/documentation/announcements/) [17]" } ] }, "side_b": { "visible": true, "heading": "Buying agents, wallets & client SDKs", "col4_header": "Supported capabilities, payment handler & conformance", "note_md": null, "rows": [ { "actor": "Google (AI Mode in Search & Gemini app)", "role": "Buying agent / AI surface (Co-author)", "status": "Supported", "status_display": "Supported · as of 2026-10-15", "col4_md": "U.S. Universal Cart on Search and Gemini; checkout powered by UCP.", "source_md": "[Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9] · [Google Merchant UCP FAQ](https://developers.google.com/merchant/ucp/faq) [43]" }, { "actor": "Google Pay", "role": "Wallet", "status": "Supported", "status_display": "Supported · as of 2026-10-15", "col4_md": "`com.google.pay` on Gemini and AI Mode; checkout in Universal Cart.", "source_md": "[Google Pay UCP handler (checked 2026-10-30)](https://developers.google.com/pay/api/universal-commerce-protocol/google-pay-payment-handler) [44] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9]" }, { "actor": "Universal-Commerce-Protocol Official SDKs", "role": "Client SDK & conformance suite", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "Official `python-sdk`, `js-sdk`, and `conformance` repositories.", "source_md": "[GitHub org repos (checked 2026-10-30)](https://github.com/orgs/Universal-Commerce-Protocol/repositories) [45]" } ] }, "additional_tables": null, "censuses": [ { "label": "Shopify merchant /.well-known/ucp profiles", "as_of": "2026-10-30", "value_md": "Five probed Shopify storefronts (Allbirds, Glossier, Monos, Steve Madden, and Fenty Beauty) each declare ucp version 2026-08-25. [32][33][34][35][36]" }, { "label": "Google, UCP launch", "as_of": "2026-01-11", "value_md": "The launch post says UCP was endorsed by more than 20 others across the ecosystem, and names Adyen, American Express, Best Buy, Flipkart, Macy's Inc., Mastercard, Stripe, The Home Depot, Visa and Zalando. [4]" }, { "label": "ucp.dev versions.json", "as_of": "2026-08-25", "value_md": "ucp.dev versions.json aliases latest to version 2026-08-25 and lists a separate draft entry with an empty aliases array. [15]" }, { "label": "UCP Registry", "as_of": "2026-11-06", "value_md": "The UCP Registry lists the UCP Checker Extension, a Chrome, Edge, and Brave scanner that shows capabilities, payment handlers, transports, AI bot policies, and spec version. Verified entries on the same directory include Affirm, Checkout.com, and vintage-racewear.com (Shopify; UCP-enabled order, checkout, discount, and fulfillment; 133ms). [46]" }, { "label": "ucp.dev homepage", "as_of": "2026-11-06", "value_md": "The UCP homepage co-developer roster names Google, Shopify, Etsy, Wayfair, Target, Walmart, Amazon, Microsoft, Meta, Salesforce, Stripe, Amadeus, Booking.com, Expedia Group, Hilton, Marriott, Trip.com, DoorDash, Square, Toast, and Uber Eats. [47]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "ap2-checkout-mandate", "target_name": "AP2 Checkout Mandate", "relation_label": "Depended on by", "delta": "AP2 v0.2 Checkout Mandate rides on UCP's profile and optional AP2 Mandates extension.", "item_md": "**[AP2 Checkout Mandate](/protocols/ap2-checkout-mandate/)** (Depended on by) — AP2 v0.2 Checkout Mandate rides on UCP's profile and optional AP2 Mandates extension." }, { "target_id": "emv-agentic-payments", "target_name": "EMV® Agentic Payments – Framework for Specifications", "relation_label": "Complements", "delta": "UCP is a /.well-known/ucp profile with payment handlers; EMV is a card-scheme draft framework.", "item_md": "**[EMV® Agentic Payments – Framework for Specifications](/protocols/emv-agentic-payments/)** (Complements) — UCP is a /.well-known/ucp profile with payment handlers; EMV is a card-scheme draft framework." }, { "target_id": "amp-ant", "target_name": "Agentic Mobile Protocol (AMP)", "relation_label": "Complements", "delta": "UCP publishes /.well-known/ucp handlers; AMP uses Agent ID, mandates, and a CGCP token.", "item_md": "**[Agentic Mobile Protocol (AMP)](/protocols/amp-ant/)** (Complements) — UCP publishes /.well-known/ucp handlers; AMP uses Agent ID, mandates, and a CGCP token." }, { "target_id": "vi", "target_name": "Verifiable Intent", "relation_label": "Complements", "delta": "UCP is the checkout surface; Verifiable Intent adds an SD-JWT consent chain.", "item_md": "**[Verifiable Intent](/protocols/vi/)** (Complements) — UCP is the checkout surface; Verifiable Intent adds an SD-JWT consent chain." }, { "target_id": "agent-attribution-protocol", "target_name": "Agent Attribution Protocol", "relation_label": "Complements", "delta": "UCP is the commerce surface; an AAP Code attributes a recommend() offer.", "item_md": "**[Agent Attribution Protocol](/protocols/agent-attribution-protocol/)** (Complements) — UCP is the commerce surface; an AAP Code attributes a recommend() offer." }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: ucp\ntitle: \"Universal Commerce Protocol (UCP)\"\ntier: flagship\nlifecycle_status: active\ncategory: pay\nform: well-known-file\nwire_archetype: payments_onchain\nspec_url: https://ucp.dev/latest/specification/overview/\nlast_checked: 2026-11-06\n---\n\n# Universal Commerce Protocol (UCP)\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** Well-known file (`well-known-file`) · **Last checked:** 2026-11-06\n\n> *This page is about the Universal Commerce Protocol (UCP) co-developed by Google and Shopify. It is not the [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/) (ACP) maintained by OpenAI and Stripe, nor the [Agent Payments Protocol (AP2)](/protocols/ap2/) (which integrates with UCP via the AP2 Mandates extension). It is also distinct from Google's UCP-powered Universal Cart consumer feature, the SMSC Universal Computer Protocol, and Oracle's Universal Connection Pool. [1][2][3][4][5][6][7][8][9][10][11]*\n\n> **In brief:** UCP (Universal Commerce Protocol) is a cross-platform discovery and capability-negotiation standard that allows AI shopping platforms, consumer agents, and online merchants to transact across REST, MCP, and A2A transports while the seller remains the merchant of record. Instead of building custom point-to-point integrations for every retail platform, a business publishes its supported services and payment handlers at `/.well-known/ucp` and computes the active capability intersection (such as `dev.ucp.shopping.checkout`) against the caller's `UCP-Agent` profile header. [5][12]\n\n**Universal Commerce Protocol** (`UCP`) is an open standard co-developed by Google and Shopify (announced 2026-01-11 and governed by a five-seat Governing Council) that enables AI agents, platforms, and merchants to interoperate across commerce workflows. Each participant publishes a JSON profile document containing a required `ucp` object that declares the protocol version, supported services, optional capabilities, and payment handlers. [2][3][4][5][12][13] Businesses publish their profile at `/.well-known/ucp`, while platforms advertise their profile URI in every request via the `UCP-Agent` header (formatted over HTTP using RFC 8941 Dictionary Structured Field syntax). Services declared in a business profile can bind to REST over HTTP/1.1+, Model Context Protocol (`MCP`) over JSON-RPC, Agent2Agent (`A2A`) extensions, or the iframe-based Embedded Protocol (`EP`). [5][12][14] UCP uses date-based versioning (`YYYY-MM-DD`), with `2026-08-25` designated as `latest` alongside prior releases (`2026-04-08`, `2026-01-23`, and `2026-01-11`) and an active `draft` specification track. [5][15][16][17]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | Well-known file (`well-known-file`) |\n| **Originated by** | Google and Shopify, announced 2026-01-11; GitHub repository created 2025-12-31. [2][3][4][18] |\n| **Governed by** | Five-seat Governing Council (permanent founding seats for Google and Shopify, plus Stripe as elected member; Google holds proxy votes for open seats until Dec 2028). [13][17][19] |\n| **Track** | Vendor consortium (`vendor-consortium`), co-developed by founding members Google and Shopify. [2][13] |\n| **Status** | Released `2026-08-25` (`latest` alias); `draft` track includes the `dev.ucp.lodging.booking` capability. [15][17][20] |\n| **Version** | Release `2026-08-25` (aliased as `latest`), alongside an active `draft` build branch. [15][16][21] |\n| **Found at** | Businesses publish profiles at `/.well-known/ucp`; platforms publish profiles at the URI advertised in `UCP-Agent`. [5] |\n| **Headers** | `UCP-Agent` (required RFC 8941 Dictionary Structured Field on REST requests) and `Content-Type: application/json` (required on requests and responses; endpoint URIs should omit trailing slashes). [5] |\n| **Transports** | REST over HTTP/1.1+, Model Context Protocol (MCP) over JSON-RPC, optional Agent2Agent (A2A) extension, and the Embedded Protocol (EP) iframe or webview binding. [5][14][21][22] |\n| **Message format** | JSON profile object with a required `ucp` member declaring protocol version, services, optional capabilities, and payment handlers. [5][21] |\n| **Specification** | [Overview](https://ucp.dev/latest/specification/overview/) (`latest` = `2026-08-25`). [12][15][18] |\n| **Licence** | Apache License 2.0 (contributors sign a contributor license agreement). [13][18][21] |\n| **IANA registration** | Provisional well-known URI suffix `ucp` (`/.well-known/ucp`), registered `2026-10-26` (contact: Ilya Grigorik). [23] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Well-known profile discovery, capability intersection, and transport bindings](#well-known-profile-discovery-capability-intersection-and-transport-bindings)\n3. [Payment handlers, AP2 mandates, and ecosystem governance](#payment-handlers-ap2-mandates-and-ecosystem-governance)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nAs commerce becomes increasingly agentic and distributed, the ability for different systems to interoperate without custom, one-off integrations is vital. [21] Capability negotiation follows a server-selects architecture: a business computes the intersection between its own `/.well-known/ucp` profile and the caller's platform profile across reverse-domain capabilities (such as `dev.ucp.shopping.checkout`), selecting the latest mutually supported date version and confirming the active feature set in every response. [12] In transactional contexts, the business typically acts as the Merchant of Record (MoR), retaining financial liability and ownership of the transaction, though UCP's capability model is not limited to transactional use cases. [12]\n\n### Discovery and capability intersection\n\n```mermaid\nsequenceDiagram\n participant Platform\n participant Business\n opt Discovery\n Platform->>Business: fetch /.well-known/ucp\n Business-->>Platform: business profile\n end\n Platform->>Business: UCP-Agent profile URI\n Note over Business: fetch platform profile, capability intersection\n Business-->>Platform: ucp version and capabilities\n```\n\n*The platform may fetch `/.well-known/ucp`, then sends its profile URI in `UCP-Agent`. The business returns `version` and `capabilities`. [5]*\n\n### Business profile at `/.well-known/ucp`\n\n```json\n{\n \"ucp\": {\n \"version\": \"2026-08-25\",\n \"services\": {\n \"dev.ucp.shopping\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"rest\",\n \"endpoint\": \"https://business.example.com/ucp/v1\",\n \"schema\": \"https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json\"\n },\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"mcp\",\n \"endpoint\": \"https://business.example.com/ucp/mcp\",\n \"schema\": \"https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json\"\n },\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"a2a\",\n \"endpoint\": \"https://business.example.com/.well-known/agent-card.json\"\n },\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/overview/\",\n \"transport\": \"embedded\",\n \"schema\": \"https://ucp.dev/2026-08-25/services/shopping/embedded.openrpc.json\"\n }\n ]\n },\n \"capabilities\": {\n \"dev.ucp.shopping.checkout\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/shopping/checkout\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/shopping/checkout.json\"\n }\n ],\n \"dev.ucp.shopping.fulfillment\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/shopping/extensions/fulfillment\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/shopping/fulfillment.json\",\n \"extends\": \"dev.ucp.shopping.checkout\"\n }\n ],\n \"dev.ucp.shopping.discount\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/shopping/extensions/discount\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/shopping/discount.json\",\n \"extends\": \"dev.ucp.shopping.checkout\"\n }\n ],\n \"dev.ucp.common.identity_linking\": [\n {\n \"version\": \"2026-08-25\",\n \"spec\": \"https://ucp.dev/2026-08-25/specification/common/identity-linking/\",\n \"schema\": \"https://ucp.dev/2026-08-25/schemas/common/identity_linking.json\",\n \"config\": {\n \"providers\": {\n \"com.example.idp\": [\n { \"type\": \"oauth2\", \"auth_url\": \"https://accounts.example.com/\" }\n ]\n },\n \"scopes\": {\n \"dev.ucp.shopping.order:read\": {},\n \"dev.ucp.shopping.order:manage\": {}\n }\n }\n }\n ]\n },\n \"payment_handlers\": {\n \"com.example.processor_tokenizer\": [\n {\n \"id\": \"processor_tokenizer\",\n \"version\": \"2026-08-25\",\n \"spec\": \"https://example.com/specs/payments/processor_tokenizer\",\n \"schema\": \"https://example.com/specs/payments/merchant_tokenizer.json\",\n \"available_instruments\": [\n {\n \"type\": \"card\",\n \"constraints\": {\n \"properties\": { \"brand\": { \"enum\": [\"visa\", \"mastercard\", \"amex\"] } }\n }\n }\n ],\n \"config\": {\n \"type\": \"CARD\",\n \"tokenization_specification\": {\n \"type\": \"PUSH\",\n \"parameters\": {\n \"token_retrieval_url\": \"https://api.psp.example.com/v1/tokens\"\n }\n }\n }\n }\n ]\n }\n },\n \"keys\": [\n {\n \"kid\": \"poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U\",\n \"kty\": \"OKP\",\n \"crv\": \"Ed25519\",\n \"x\": \"JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs\",\n \"use\": \"sig\",\n \"alg\": \"EdDSA\"\n },\n {\n \"kid\": \"business_2025\",\n \"kty\": \"EC\",\n \"crv\": \"P-256\",\n \"x\": \"qIVYZVLCrPZHGHjP17CTW0_-D9Lfw0EkjqF7xB4FivA\",\n \"y\": \"Mc4nN9LTDOBhfoUeg8Ye9WedFRhnZXZJA12Qp0zZ6F0\",\n \"use\": \"sig\",\n \"alg\": \"ES256\"\n }\n ]\n}\n```\n\n*Business profile published at `/.well-known/ucp`, with `version` `2026-08-25`, `services`, `capabilities`, `payment_handlers`, and `keys`. [5]*\n\n---\n\n## Well-known profile discovery, capability intersection, and transport bindings\n\nBefore initiating a request, a platform may fetch a merchant's `/.well-known/ucp` document and must include its own profile URI in every request via the transport-appropriate `UCP-Agent` mechanism. After computing the capability intersection between the two profiles, the business must return a `ucp` object in every response containing the active `version` and `capabilities` array. [5]\n\n- **Reverse-domain capability names:** All capability and service identifiers must follow the `{reverse-domain}.{service}.{capability}` grammar, where `{reverse-domain}` is an authority identifier derived from domain ownership; for example, `dev.ucp.shopping.checkout` pairs authority `ucp.dev` with service `shopping` in the profile at `/.well-known/ucp`. [5][12]\n- **Date-based version intersection:** Negotiation proceeds in two phases using `YYYY-MM-DD` date strings: protocol version selection first chooses one complete business profile, and capability negotiation then selects active capabilities and extensions by exact version intersection within that profile, picking the highest (latest date) match. [5][12]\n- **Extensions and schema composition:** Extensions declare parent capabilities via the `extends` field (as a single string or an array of parent names, at least one of which must be present in the active intersection) and modify base JSON Schemas using `allOf` composition, which platforms must resolve and compose client-side. [5]\n- **REST, MCP, A2A, and Embedded bindings:** A single service entry inherits `ucp.version` and can expose multiple transport bindings—REST (OpenAPI 3.1.0), MCP (OpenRPC), A2A extensions, and Embedded Protocol (`EP`)—without separate per-binding versions; `EP` embeds a merchant interface inside an iframe or webview and exchanges JSON-RPC 2.0 messages. [5][12][14]\n\n---\n\n## Payment handlers, AP2 mandates, and ecosystem governance\n\nUCP models transactions across four distinct actor roles: the platform (which consumes business capabilities), the business (which exposes them), the credential provider (CP, which manages sensitive payment instruments), and the payment service provider (PSP, which processes payments on behalf of businesses; CP and PSP are collectively termed the Payment Credential Provider). [12]\n\n- **Actor duties and Domain Technical Councils:** In an interaction, the platform discovers business profiles and invokes capabilities on behalf of its principal within negotiated bounds, while the business publishes its profile and declares supported services, capabilities, and extensions. Specification work is divided across four Domain Tech Councils: Shopping, Food (formed July 16, 2026), Lodging (formed August 11, 2026), and Payments (formed September 2, 2026). [12][13][17][19]\n- **Instruments versus payment handlers:** UCP separates Payment Instruments (what payment methods are accepted) from Payment Handlers (the specifications for how instruments are processed, which are specifications rather than legal entities). Reverse-domain handler identifiers such as `com.google.pay` and `dev.shopify.shop_pay` correspond to Google Pay and Shop Pay, and businesses must filter advertised handlers based on the cart context. [5]\n- **AP2 mandates and the FIDO donation:** The AP2 Mandates extension (`dev.ucp.common.payment.ap2_mandate` in `/.well-known/ucp`, version `2026-08-25`) exchanges user intents and authorizations as Verifiable Digital Credentials: when a session is Security Locked, businesses must embed a cryptographic signature in checkout responses and platforms must supply signed mandates during completion. Google donated AP2 to the FIDO Alliance on 2026-04-28. [8][24]\n- **Dated releases through 2026-08-25:** Following the initial `2026-01-11` launch and `2026-01-23` update, UCP published `v2026-04-08` (tagged 2026-04-09 on GitHub) and `v2026-08-25` (`latest`), alongside an active `draft` track. Ultimate ownership of all UCP assets rests with the Governing Council, where Stripe joined founding members Google and Shopify on April 28, 2026. [13][15][16][17]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Well-Known URIs (RFC 8615)** | `RFC 8615` | Profiles classic standard | Business profile at /.well-known/ucp; platform profile URI is advertised in UCP-Agent. [5] |\n| **W3C Payment Request API & Web Checkout** | `W3C Payment Request` | Analogous to classic standard | UCP lists payment handlers on /.well-known/ucp; Payment Request is the browser checkout API. [5][14] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/)** | Peer alternative | ACP (OpenAI and Stripe, beta) uses its own checkout; UCP publishes /.well-known/ucp payment handlers. [5][6] |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Depended on by | AP2 is a compatible security feature; UCP's AP2 Mandates extension carries verifiable credentials. [7][8][25] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | MCP is JSON-RPC 2.0; UCP checkout advertises MCP and calls tools/call. [5][26][27] |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Complements | A2A is Agent Card JSON-RPC; UCP checkout must be advertised on that card. [22][28] |\n| **[HTTP Message Signatures](/protocols/http-message-signatures/)** | Complements | RFC 9421 signs HTTP messages; UCP signs its messages and adds EdDSA for Web Bot Auth. [29][30] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (20 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Merchants, platforms & payment processors\n\n| Actor | Role | Status | `/.well-known/ucp` profile capabilities, transport & payment handlers | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Shopify** | Platform (Co-author) | Supported · as of 2026-03-24 | Select brands sell in AI Mode and Gemini on co-developed UCP. | [Shopify News (datePublished 2026-03-24)](https://www.shopify.com/news/agentic-commerce-momentum) [31] · [Shopify Engineering, UCP](https://shopify.engineering/ucp) [2] |\n| **Allbirds** | Seller (Shopify merchant) | Live (HTTP 200) · checked 2026-10-30 | `2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`. | [Allbirds UCP profile](https://www.allbirds.com/.well-known/ucp) [32] |\n| **Glossier** | Seller (Shopify merchant) | Live (HTTP 200) · checked 2026-10-30 | `2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`. | [Glossier UCP profile](https://www.glossier.com/.well-known/ucp) [33] |\n| **Monos** | Seller (Shopify merchant) | Live (HTTP 200) · checked 2026-10-30 | `2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`. | [Monos UCP profile](https://www.monos.com/.well-known/ucp) [34] |\n| **Steve Madden** | Seller (Shopify merchant) | Live (HTTP 200) · checked 2026-10-30 | `2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`. | [Steve Madden UCP profile](https://www.stevemadden.com/.well-known/ucp) [35] |\n| **Fenty Beauty** | Seller (Shopify merchant) | Live (HTTP 200) · checked 2026-10-30 | `2026-08-25` via `mcp` and `embedded`; `com.google.pay`, `dev.shopify.card`, `dev.shopify.shop_pay`. | [Fenty Beauty UCP profile](https://fentybeauty.com/.well-known/ucp) [36] |\n| **IKEA (Ingka)** | Retailer (Custom UCP endpoint) | Live (HTTP 200) · checked 2026-10-30 | Active `2026-04-08` on `mcp` and `rest`; `com.google.pay` environment is `TEST`. | [IKEA UCP profile](https://www.ikea.com/.well-known/ucp) [37] |\n| **Stripe** | Payment processor (Governing Council) | Supported · as of 2026-09-02 | Checkout, identity linking, order tracking, and payment-token exchange. | [Stripe UCP docs (checked 2026-10-30)](https://docs.stripe.com/agentic-commerce/protocols/ucp) [38] · [UCP announcements](https://ucp.dev/documentation/announcements/) [17] · [UCP MAINTAINERS.md](https://raw.githubusercontent.com/Universal-Commerce-Protocol/.github/main/MAINTAINERS.md) [19] |\n| **Adyen** | Payment processor | Supported · as of 2026-09-02 | Agentic API transacts with Adyen merchants; sessions require RFC 9421. | [Adyen UCP docs (checked 2026-10-30)](https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp) [39] · [UCP announcements](https://ucp.dev/documentation/announcements/) [17] · [UCP MAINTAINERS.md](https://raw.githubusercontent.com/Universal-Commerce-Protocol/.github/main/MAINTAINERS.md) [19] |\n| **Visa** | Payment network (endorser) | Listed · as of 2026-01-11 | Named among more than 20 launch endorsers on 2026-01-11. | [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] |\n| **Mastercard** | Payment network (endorser) | Listed · as of 2026-01-11 | Launch-post endorser on 2026-01-11; no handler id in that sentence. | [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] |\n| **Target** | Retailer (co-developer) | Supported · as of 2026-10-15 | Buy in Google Search AI Mode and Gemini via UCP; Universal Cart merchant. | [Target fact sheet (updated Jun 18, 2026)](https://corporate.target.com/press/fact-sheet/2026/06/conversational-ai) [40] · [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9] |\n| **Wayfair** | Retailer (co-developer) | Supported · as of 2026-10-15 | Co-developer; 2026-02-11 UCP checkout rollout; Universal Cart merchant. | [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, advertising and commerce (2026-02-11)](https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/) [41] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9] |\n| **Walmart** | Retailer (co-developer) | Supported · as of 2026-10-15 | Co-developer; coming soon on 2026-02-11; listed on Universal Cart. | [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, advertising and commerce (2026-02-11)](https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/) [41] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9] |\n| **Etsy** | Retailer (co-developer) | Supported · as of 2026-02-11 | Co-developer; 2026-02-11 UCP checkout for US shoppers in AI Mode. | [Google, UCP launch (2026-01-11)](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/) [4] · [Google, advertising and commerce (2026-02-11)](https://blog.google/products/ads-commerce/digital-advertising-commerce-2026/) [41] · [Shopify Engineering, UCP](https://shopify.engineering/ucp) [2] |\n| **Newegg** | Retailer | Supported · as of 2026-10-12 | Integrated UCP for online checkout (2026-10-12) as merchant of record. | [Digital Commerce 360, Newegg UCP checkout (2026-10-12)](https://www.digitalcommerce360.com/2026/10/12/newegg-adds-google-ucp-checkout-integration/) [42] |\n| **PayPal** | Payment processor (Payments TC) | Listed · as of 2026-09-02 | Inaugural member of the UCP Payments Technical Council (formed September 2, 2026). | [UCP announcements](https://ucp.dev/documentation/announcements/) [17] |\n\n### Buying agents, wallets & client SDKs\n\n| Actor | Role | Status | Supported capabilities, payment handler & conformance | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Google (AI Mode in Search & Gemini app)** | Buying agent / AI surface (Co-author) | Supported · as of 2026-10-15 | U.S. Universal Cart on Search and Gemini; checkout powered by UCP. | [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9] · [Google Merchant UCP FAQ](https://developers.google.com/merchant/ucp/faq) [43] |\n| **Google Pay** | Wallet | Supported · as of 2026-10-15 | `com.google.pay` on Gemini and AI Mode; checkout in Universal Cart. | [Google Pay UCP handler (checked 2026-10-30)](https://developers.google.com/pay/api/universal-commerce-protocol/google-pay-payment-handler) [44] · [Google, Universal Cart (2026-10-15)](https://blog.google/products-and-platforms/products/shopping/universal-cart-launch/) [9] |\n| **Universal-Commerce-Protocol Official SDKs** | Client SDK & conformance suite | Supported · as of 2026-10-30 | Official `python-sdk`, `js-sdk`, and `conformance` repositories. | [GitHub org repos (checked 2026-10-30)](https://github.com/orgs/Universal-Commerce-Protocol/repositories) [45] |\n\n### Ecosystem censuses\n\n- **Shopify merchant /.well-known/ucp profiles** (*as of 2026-10-30*): Five probed Shopify storefronts (Allbirds, Glossier, Monos, Steve Madden, and Fenty Beauty) each declare ucp version 2026-08-25. [32][33][34][35][36]\n- **Google, UCP launch** (*as of 2026-01-11*): The launch post says UCP was endorsed by more than 20 others across the ecosystem, and names Adyen, American Express, Best Buy, Flipkart, Macy's Inc., Mastercard, Stripe, The Home Depot, Visa and Zalando. [4]\n- **ucp.dev versions.json** (*as of 2026-08-25*): ucp.dev versions.json aliases latest to version 2026-08-25 and lists a separate draft entry with an empty aliases array. [15]\n- **UCP Registry** (*as of 2026-11-06*): The UCP Registry lists the UCP Checker Extension, a Chrome, Edge, and Brave scanner that shows capabilities, payment handlers, transports, AI bot policies, and spec version. Verified entries on the same directory include Affirm, Checkout.com, and vintage-racewear.com (Shopify; UCP-enabled order, checkout, discount, and fulfillment; 133ms). [46]\n- **ucp.dev homepage** (*as of 2026-11-06*): The UCP homepage co-developer roster names Google, Shopify, Etsy, Wayfair, Target, Walmart, Amazon, Microsoft, Meta, Salesforce, Stripe, Amadeus, Booking.com, Expedia Group, Hilton, Marriott, Trip.com, DoorDash, Square, Toast, and Uber Eats. [47]\n\n---\n\n## See also\n\n- **[AP2 Checkout Mandate](/protocols/ap2-checkout-mandate/)** *(Depended on by)* — AP2 v0.2 Checkout Mandate rides on UCP's profile and optional AP2 Mandates extension.\n- **[EMV® Agentic Payments – Framework for Specifications](/protocols/emv-agentic-payments/)** *(Complements)* — UCP is a /.well-known/ucp profile with payment handlers; EMV is a card-scheme draft framework.\n- **[Agentic Mobile Protocol (AMP)](/protocols/amp-ant/)** *(Complements)* — UCP publishes /.well-known/ucp handlers; AMP uses Agent ID, mandates, and a CGCP token.\n- **[Verifiable Intent](/protocols/vi/)** *(Complements)* — UCP is the checkout surface; Verifiable Intent adds an SD-JWT consent chain.\n- **[Agent Attribution Protocol](/protocols/agent-attribution-protocol/)** *(Complements)* — UCP is the commerce surface; an AAP Code attributes a recommend() offer.\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. Amit Handa and Ashish Gupta (Google Developers Blog), *Under the Hood: Universal Commerce Protocol (UCP)* (published 2026-01-11) — \n2. Shopify Engineering, *Building the Universal Commerce Protocol* (published 2026-01-11) — \n3. Shopify, *The agentic commerce platform: Shopify connects any merchant to every AI conversation* (published 2026-01-11) — \n4. Vidhya Srinivasan (Google), *New tech and tools for retailers to succeed in an agentic shopping era* (published 2026-01-11) — \n5. Universal Commerce Protocol, *Overview* (specification version aliased latest; fetched 2026-10-30) — \n6. OpenAI and Stripe, *Agentic Commerce Protocol (ACP) README* (fetched 2026-10-30) — \n7. Universal Commerce Protocol, *UCP and AP2* (fetched 2026-10-30) — \n8. Universal Commerce Protocol, *AP2 Mandates Extension* (fetched 2026-10-30) — \n9. Suresh Ganapathy (Google), *Google's new Universal Cart launches today in the U.S.* (published 2026-10-15) — \n10. Wireshark Wiki, *Universal Computer Protocol (UCP)* (fetched 2026-10-30) — \n11. Oracle, *Introduction to UCP (Universal Connection Pool)* (fetched 2026-10-30) — \n12. Universal Commerce Protocol, *Core Concepts* (fetched 2026-10-30) — \n13. UCP Authors, *GOVERNANCE.md* (fetched 2026-10-30) — \n14. Universal Commerce Protocol, *Embedded protocol* (fetched 2026-10-30) — \n15. Universal Commerce Protocol, *versions.json* (last-modified 2026-10-29; fetched 2026-10-30) — \n16. Universal-Commerce-Protocol, *Releases, Universal-Commerce-Protocol/ucp* (fetched 2026-10-30) — \n17. Universal Commerce Protocol, *Announcements* (fetched 2026-10-30) — \n18. Universal-Commerce-Protocol, *ucp: Specification and documentation for the Universal Commerce Protocol* (repository created 2025-12-31; fetched 2026-10-30) — \n19. UCP Authors, *UCP Maintainers* (fetched 2026-10-30) — \n20. Universal Commerce Protocol, *Lodging Booking capability (draft)* (fetched 2026-10-30) — \n21. Universal Commerce Protocol, *Universal Commerce Protocol (UCP) README* (fetched 2026-10-30) — \n22. Universal Commerce Protocol, *Checkout A2A binding* (fetched 2026-10-30) — \n23. IANA, *Well-Known URIs Registry* (updated 2026-10-26) — \n24. Google, *Google donates Agent Payments Protocol to FIDO Alliance* (2026-04-28) — \n25. Agent Payments Protocol (google-agentic-commerce), *Agentic Payment Protocol (v0.2)* (fetched 2026-10-30) — \n26. Model Context Protocol, *Specification, 2026-07-28* (specification date 2026-07-28; fetched 2026-10-30) — \n27. Universal Commerce Protocol, *Checkout MCP binding* (fetched 2026-10-30) — \n28. A2A Protocol, *Overview* (fetched 2026-10-30) — \n29. A. Backman, J. Richer, and M. Sporny, *RFC 9421: HTTP Message Signatures* (fetched 2026-10-30) — \n30. Universal Commerce Protocol, *Signatures* (fetched 2026-10-30) — \n31. Shopify, *Millions of merchants can sell in AI chats* (published 2026-03-24) — \n32. Allbirds, *UCP profile at /.well-known/ucp* (fetched 2026-10-30) — \n33. Glossier, *UCP profile at /.well-known/ucp* (fetched 2026-10-30) — \n34. Monos, *UCP profile at /.well-known/ucp* (fetched 2026-10-30) — \n35. Steve Madden, *UCP profile at /.well-known/ucp* (fetched 2026-10-30) — \n36. Fenty Beauty, *UCP profile at /.well-known/ucp* (fetched 2026-10-30) — \n37. IKEA, *UCP profile at /.well-known/ucp* (fetched 2026-10-30) — \n38. Stripe, *Universal Commerce Protocol* (fetched 2026-10-30) — \n39. Adyen, *AI agent API integration with UCP* (fetched 2026-10-30) — \n40. Target, *How Target is Shaping Shopping Experiences in Conversational AI* (updated 2026-06-18) — \n41. Vidhya Srinivasan (Google), *What to expect in digital advertising and commerce in 2026* (published 2026-02-11) — \n42. Brian Warmoth (Digital Commerce 360), *Newegg adds Google UCP checkout integration* (published 2026-10-12) — \n43. Google for Developers, *Google Universal Commerce Protocol (UCP) Guide, FAQ* (fetched 2026-10-30) — \n44. Google for Developers, *Google Pay payment handler for Universal Commerce Protocol* (fetched 2026-10-30) — \n45. GitHub API, Universal-Commerce-Protocol, *Organization repositories* (fetched 2026-10-30) — \n46. UCP Registry, *The Universal Commerce Protocol Registry* (checked 2026-11-06) — \n47. Universal Commerce Protocol, *Universal Commerce Protocol* (checked 2026-11-06) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "AP2", "adoption": { "level": "observed", "by": "Google, Adyen, Mastercard, PayPal, Coinbase, Salesforce, ServiceNow, and 56 named launch partners in v0.1.0; donated to FIDO Alliance", "probe_run": null }, "aliases": [], "analog": "Signed payment authorization / purchase order", "collisions": [], "discovery": { "mechanism": "A2A Agent Card extension", "path": "No well-known file. Under the v0.1 A2A extension an agent lists AP2 in its A2A Agent Card extensions with the URI https://github.com/google-agentic-commerce/ap2/tree/v0.1. That URI is an identifier: fetched as a web page it returned HTTP 404 on 2026-10-28. No v0.2 discovery URI was found" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://cloud.google.com/blog/products/ai-machine-learning/announcing-agents-to-payments-ap2-protocol", "claim": "Stavan Parikh and Rao Surapaneni (Google Cloud), *Announcing Agent Payments Protocol (AP2)*, published 2025-09-16", "date": null, "quote": "Today, Google announced the Agent Payments Protocol (AP2) / \"datePublished\":\"2025-09-16\" / we have extended the core constructs of AP2 and launched the A2A x402 extension, a production-ready solution for agent-based crypto payments. / Today, Google announced the Agent Payments Protocol (AP2), an open protocol developed with leading payments and technology companies / September 16, 2025 / Stavan Parikh / Rao Surapaneni / The protocol can be used as an extension of the Agent2Agent (A2A) protocol and Model Context Protocol (MCP). / AP2 builds trust by using Mandates-tamper-proof, cryptographically-signed digital contracts that serve as verifiable proof of a user's instructions. / including Adyen, American Express, Ant International, Coinbase, Etsy, Forter, Intuit, JCB, Mastercard, Mysten Labs, Paypal, Revolut, Salesforce, ServiceNow, UnionPay International, Worldpay, and more. / launched the A2A x402 extension, a production-ready solution for agent-based crypto payments.", "ref": 1 }, { "label": "[2]", "url": "https://blog.google/products-and-platforms/platforms/google-pay/agent-payments-protocol-fido-alliance/", "claim": "Stavan Parikh (Google), *Google donates Agent Payments Protocol to FIDO Alliance*, published 2026-04-28", "date": null, "quote": "we're donating the Agent Payments Protocol (AP2) to the FIDO Alliance / \"datePublished\": \"2026-04-28T13:00:00+00:00\" / We're donating Agent Payments Protocol to the FIDO Alliance to support the future of secure, agentic payments. / We're donating Agent Payments Protocol to the FIDO Alliance to support the future of secure, agentic payments.\", \"datePublished\": \"2026-04-28T13:00:00+00:00\" / we're donating the Agent Payments Protocol (AP2) to the FIDO Alliance, a renowned industry association focused on creating open standards. / Today on GitHub, we're also releasing AP2 v.0.2", "ref": 2 }, { "label": "[3]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol", "claim": "OpenAI and Stripe, *Agentic Commerce Protocol*, fetched 2026-10-30", "date": null, "quote": "The specification is currently maintained by OpenAI and Stripe. / The Agentic Commerce Protocol (ACP) is an interaction model and open standard for connecting buyers, their AI agents, and businesses to complete purchases seamlessly.", "ref": 3 }, { "label": "[4]", "url": "https://web.archive.org/web/20261022061422/https://openai.com/index/buy-it-in-chatgpt/", "claim": "OpenAI, *Buy it in ChatGPT: Instant Checkout and the Agentic Commerce Protocol*, archived 2026-10-22", "date": null, "quote": "powered by the Agentic Commerce Protocol, built with Stripe.", "ref": 4 }, { "label": "[5]", "url": "https://github.com/visa/trusted-agent-protocol", "claim": "Visa, *Trusted Agent Protocol*, fetched 2026-10-30", "date": null, "quote": "Visa's Trusted Agent Protocol provides a standardized, cryptographic method for an AI agent to prove its identity and associated authorization directly to merchants.", "ref": 5 }, { "label": "[6]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "claim": "x402, *X402 Protocol Specification*, protocol version 2; fetched 2026-10-30", "date": null, "quote": "This specification defines the core x402 protocol for internet-native payments. / PAYMENT-SIGNATURE header is required", "ref": 6 }, { "label": "[7]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/specification.md", "claim": "Google (google-agentic-commerce), *Agentic Payment Protocol (v0.2)*, fetched 2026-10-30", "date": null, "quote": "AP2 is designed explicitly to be compatible with the Universal Commerce Protocol (UCP) and integrates seamlessly. / The Agentic Payment Protocol (AP2) provides a protocol to secure Agent-performed payment transactions. ... A Checkout Mandate and Receipt for securing *what* is being purchased. - A linked Payment Mandate and Receipt for the *payment* of the Checkout. / The Agentic Payment Protocol (AP2) provides a protocol to secure Agent-performed payment transactions. / When a Shopping Agent has a Checkout JWT for the closed Checkout from the Merchant, they construct the Checkout and Payment Mandate Content and pass it to a Trusted Surface for display to the user and signing. / Human Not Present (Autonomous): The User sees and approves a set of constraints over what closed Checkout and Payment would meet their intent. The Shopping Agent then assembles and approves a closed Checkout and Payment Mandate on their behalf using these open Mandates. ... In the Autonomous case, the closed Mandates are signed by an Agent key. / Agentic Payment Protocol (v0.2) / AP2 specifies the use of SD-JWTs for securing the Payment and Checkout Mandates. / Mandates are the core means that AP2 uses to authorize agents. ... AP2 defines two Mandate types: Checkout Mandate and Payment Mandate. / AP2 operates as a security feature within a Commerce Protocol. The exact details of the Commerce Protocol (e.g., catalog APIs, checkout updates, and specific APIs for communication between the different roles) are outside the scope of AP2. / AP2 defines two Mandate types: Checkout Mandate and Payment Mandate. / Verifiers of Mandates always receive a closed Payment and Checkout Mandate, regardless of the mode. / AP2 defines two Mandate types: Checkout Mandate and Payment Mandate. ... Verifiers of Mandates *always* receive a closed Payment and Checkout Mandate, regardless of the mode. / In the Autonomous case, the closed Mandates are signed by an Agent key. Trust in this key is provided by open Mandates that are signed by the User or a trust list of Agent Providers. / as a schema version number (e.g. `mandate.payment.1`, `mandate.checkout.open.1`). Implementations MUST match the exact `vct` / The Payment Mandate is bound to a particular Checkout using the cryptographic hash of the Checkout JWT. To prevent rainbow table attacks, the Checkout JWT MUST be signed using a digital signature scheme (e.g., ECDSA) and not a deterministic signature (e.g., Ed25519). / Only constraints relevant to the closed Mandates are shared with the verifier. / Once the Merchant Payment Processor has accepted or rejected the Payment Mandate, a signed Payment Receipt MUST be returned to the Shopping Agent, Credential Provider, and possibly Networks. / AP2 considers five roles, who have different responsibilities from a processing and verification perspective. ... Shopping Agent (SA) ... Credential Provider (CP) ... Merchant (M) ... Merchant Payment Processor (MPP) ... Trusted Surface (TS) ... The following role MUST be non-agentic: - Trusted Surface / The following role MUST be non-agentic: - Trusted Surface ... When this document refers to validation or processing for a particular role, it MUST happen in deterministic code regardless of whether the role is agentic or not.", "ref": 7 }, { "label": "[8]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/checkout_mandate.md", "claim": "Google (google-agentic-commerce), *Checkout Mandate*, fetched 2026-10-30", "date": null, "quote": "\"alg\": \"ES256\", \"typ\": \"kb+sd-jwt\" ... \"vct\": \"mandate.checkout.1\" / Closed Checkout Mandate SD-JWT plus disclosures / A closed Checkout Mandate MUST use the value mandate.checkout.1 for the vct claim and an open Checkout Mandate MUST use the value mandate.checkout.open.1. / checkout_hash is the base64url-encoded hash of the value of checkout_jwt. The algorithm used MUST be the same as the SD-JWT, as defined by the _sd_alg claim in the base payload, or sha-256 if not present. checkout_jwt is the merchant-signed JWT containing the details of the checkout. / \"alg\": \"ES256\", \"typ\": \"kb+sd-jwt\" / \"issuer_signed_jwt\": { \"header\": { \"alg\": \"ES256\", \"typ\": \"kb+sd-jwt\" } / \"disclosures\": [ { \"digest\": \"FzLoxbbtgQGYZxoSM2NJYJtkFTSsdfUBoVEQ12k7JN8\" / The Checkout Mandate is a Mandate used for authorizing the completion of a checkout. / The Checkout Mandate Content is created by the Shopping Agent, rendered to the User by the Trusted Surface and verified by the Merchant.", "ref": 8 }, { "label": "[9]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/index.md", "claim": "Google (google-agentic-commerce), *Agent Payments Protocol (AP2)*, fetched 2026-10-30", "date": null, "quote": "Agent Payments Protocol (AP2) is an open protocol for the emerging Agent Economy. It's designed to enable secure, reliable, and interoperable agent commerce for developers, merchants, and the payments industry. / Standardization of the specification will continue within the Agentic Authentication Technical and Payments Technical Working Groups in FIDO. / Our public GitHub repo hosts the lastest version of AP2 specification, documentation and SDK. / The protocol is available as an extension for the open-source Agent2Agent (A2A) protocol and Universal Commerce Protocol / Today's payment systems assume a human is directly clicking \"buy\" on a trusted website. When an autonomous agent initiates a payment, this core assumption is broken, leading to critical questions that current systems cannot answer: - Authorization: How can we verify that a user gave an agent specific authority for a particular purchase? - Authenticity: How can a merchant be sure an agent's request accurately reflects the user's true intent, without errors or AI \"hallucinations\"? - Accountability: If a fraudulent or incorrect transaction occurs, who is accountable / The protocol is available as an extension for the open-source Agent2Agent (A2A) protocol and Universal Commerce Protocol with more integrations in progress. ... MCP ... Human Not Present x402 ... Standardization of the specification will continue within the Agentic Authentication Technical and Payments Technical Working Groups in FIDO. / Today's payment systems assume a human is directly clicking \"buy\" on a trusted website. When an autonomous agent initiates a payment, this core assumption is broken", "ref": 9 }, { "label": "[10]", "url": "https://github.com/google-agentic-commerce/AP2/releases", "claim": "google-agentic-commerce, *Releases · google-agentic-commerce/AP2*, v0.1.0 (2025-09-16); v0.2.0 released 28 Apr", "date": null, "quote": "GarethCOliver released this 28 Apr 12:40 v0.2.0 ... This is the second release of AP2. It focuses on providing Human Not Present flows. ... 0.1.0 (2025-09-16) Features Create Agent Payments Protocol (AP2) / 0.1.0 (2025-09-16) / Create Agent Payments Protocol (AP2) / GarethCOliver released this 28 Apr 12:40 v0.2.0 / This is the second release of AP2. It focuses on providing Human Not Present flows.", "ref": 10 }, { "label": "[11]", "url": "https://github.com/google-agentic-commerce/AP2", "claim": "google-agentic-commerce, *Agent Payments Protocol (AP2)*, fetched 2026-10-30", "date": null, "quote": "\"created_at\": \"2025-05-30T19:37:20Z\" / \"homepage\": \"https://ap2-protocol.org/\" / \"name\": \"Apache License 2.0\" / \"spdx_id\": \"Apache-2.0\" / The protocol's core objects are defined under code/sdk/python/ap2/ / A PyPI package will be published at a later time. / uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main / This repository contains code samples and demos of the Agent Payments Protocol.", "ref": 11 }, { "label": "[12]", "url": "https://fidoalliance.org/fido-alliance-to-develop-standards-for-trusted-ai-agent-interactions/", "claim": "FIDO Alliance, *FIDO Alliance to Develop Standards for Trusted AI Agent Interactions*, published 2026-04-28; modified 2026-10-19", "date": null, "quote": "the FIDO Alliance is developing specifications for agent-initiated commerce within its Payments Technical Working Group, chaired by members from Mastercard and Visa. / Google has contributed its Agent Payments Protocol (AP2), which introduces a model for secure delegation, verifiable authorization and trusted transaction execution. / These contributions will be reviewed and further developed through the FIDO Alliance's collaborative standards process within the Payments Technical Working Group. / through the newly formed Agentic Authentication Technical Working Group and the Payments Technical Working Group. / Mastercard has contributed its Verifiable Intent framework, co-developed with Google and designed to work with AP2", "ref": 12 }, { "label": "[13]", "url": "https://www.w3.org/2026/09/ecommerce-agents/slides/Jean_Luc_Di_Manno_FIDO.pdf", "claim": "FIDO Alliance, *FIDO Agentic Payment Specifications*, PDF created 2026-09-09", "date": null, "quote": "CreationDate(D:20260909090452+02'00') / September 2026: AP2/VI specs moved to public repository for review. / Targeting End 2026: Harmonize AP2 and VI specifications. / Mid-2027: Publish first version of consolidated specifications.", "ref": 13 }, { "label": "[14]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/agent_authorization.md", "claim": "Google (google-agentic-commerce), *Agent Authorization*, fetched 2026-10-30", "date": null, "quote": "While this document specifies using OpenID4VP with SD-JWT VCs, other VDC formats such as ISO mDocs (ISO18013-5) and protocols such as 18013-7 Annex C could be made to fulfill the same role. / other VDC formats such as ISO mDocs (ISO18013-5)", "ref": 14 }, { "label": "[15]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/v0.1.0/docs/a2a-extension.md", "claim": "Google (google-agentic-commerce), *A2A Extension for AP2 (v0.1)*, tag v0.1.0 (2025-09-16)", "date": null, "quote": "The URI for this extension is https://github.com/google-agentic-commerce/ap2/tree/v0.1. / Agents that support the AP2 extension MUST use this URI. / The URI for this extension is https://github.com/google-agentic-commerce/ap2/tree/v0.1. Agents that support the AP2 extension MUST use this URI. / This is an Agent2Agent (A2A) extension implementing the Agent Payments Protocol (AP2).", "ref": 15 }, { "label": "[16]", "url": "https://ap2-protocol.org/ap2/specification/", "claim": "Google (google-agentic-commerce), *Agentic Payment Protocol (v0.2)*, fetched 2026-10-30", "date": null, "quote": "Agentic Payment Protocol (v0.2)", "ref": 16 }, { "label": "[17]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/v0.1.0/docs/specification.md", "claim": "Google (google-agentic-commerce), *Agent Payments Protocol (AP2), v0.1.0 specification*, tag v0.1.0 (2025-09-16)", "date": null, "quote": "The primary VCs in this framework are the Cart Mandate, the Intent Mandate and the Payment Mandate. / The Cart Mandate is the foundational credential that captures the user's authorization for a purchase when the human is present ... The Intent Mandate is a separate verifiable credential which is critical for scenarios where the human is not present / AI Agent presence and transaction modality (Human Present v/s Not Present) signals must always be shared / Through payload encryption and a role-based architecture, agents involved in the shopping process are prevented from accessing sensitive payment card industry (PCI) data or other personally identifiable information (PII)", "ref": 17 }, { "label": "[18]", "url": "https://www.rfc-editor.org/rfc/rfc9901.html", "claim": "D. Fett, K. Yasuda, B. Campbell (IETF), *Selective Disclosure for JSON Web Tokens (RFC 9901)*, 2025-11", "date": null, "quote": "Selective Disclosure for JSON Web Tokens", "ref": 18 }, { "label": "[19]", "url": "https://arxiv.org/abs/2608.23858", "claim": "Avital Aviv, Parth A. Gandh, Ron Bitton, and Asaf Shabtai, *Beyond the Mandate: A Systematic Security Analysis of the Agent Payments Protocol (AP2)*, submitted 24 Aug 2026", "date": null, "quote": "arXiv:2608.23858 ... Agent interactions and external inputs that shape a transaction before authorization remain outside that protection, including Agent-to-Agent Protocol (A2A) messages and Model Context Protocol (MCP) tool calls. / Submitted on 24 Aug 2026 / Because no complete public AP2 deployment was available, we build a testbed spanning all five architectures", "ref": 19 }, { "label": "[20]", "url": "https://ucp.dev/latest/specification/payment/extensions/ap2-mandates/", "claim": "Universal Commerce Protocol, *AP2 Mandates Extension*, example profile version 2026-08-25; fetched 2026-10-30", "date": null, "quote": "Businesses declare support by adding dev.ucp.common.payment.ap2_mandate to their capabilities list in /.well-known/ucp. / The business MUST include ap2.merchant_authorization in all checkout responses. / The business MUST NOT accept a complete_checkout request that lacks ap2.checkout_mandate. / Mandates are SD-JWT credentials with Key Binding (+kb). / payment.instruments[*].credential.token", "ref": 20 }, { "label": "[21]", "url": "https://ucp.dev/2026-01-11/specification/ap2-mandates/", "claim": "Universal Commerce Protocol, *AP2 Mandates Extension*, specification version 2026-01-11", "date": null, "quote": "Businesses declare support by adding dev.ucp.shopping.ap2_mandate to their capabilities list ... \"extends\": \"dev.ucp.shopping.checkout\"", "ref": 21 }, { "label": "[22]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/v0.1.0/docs/topics/ap2-a2a-and-mcp.md", "claim": "Google (google-agentic-commerce), *AP2, A2A, and MCP*, tag v0.1.0 (2025-09-16)", "date": null, "quote": "Developers can implement their own tools to integrate with providers. We are working on MCP servers for AP2. / A2A: Agents communicate with other Agents (tasks and messages) / AP2: Agents communicate about payments (mandates)", "ref": 22 }, { "label": "[23]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/v0.1.0/docs/topics/ap2-and-x402.md", "claim": "Google (google-agentic-commerce), *AP2 and x402*, tag v0.1.0 (2025-09-16)", "date": null, "quote": "The Agent Payments Protocol (AP2) and x402 are complementary. ... A core principle of AP2 is its payment-method-agnostic and future-proof design. The initial version supports common \"pull\" payment methods like credit/debit cards, with a roadmap to include \"push\" payments like real-time bank transfers and digital currencies. / The Agent Payments Protocol (AP2) and x402 are complementary.", "ref": 23 }, { "label": "[24]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/faq.md", "claim": "Google (google-agentic-commerce), *Frequently Asked Questions*, fetched 2026-10-30", "date": null, "quote": "While the Universal Commerce Protocol orchestrates the broader purchase lifecycle, AP2 is the specialized payment layer responsible for authorizing and signing transactions. / We built sample agents around the core AP2 python library that demonstrate a rich shopping experience. / These samples mock actual payment service providers so you can explore with no dependencies. / We are working on an SDK and a MCP server right now, in collaboration with payment service providers. Check back soon. / like the Checkout Mandate and Payment Mandate", "ref": 24 }, { "label": "[25]", "url": "https://verifiableintent.dev/spec/", "claim": "Verifiable Intent Working Group, *Verifiable Intent specification*, 0.1-draft; date 2026-02-18", "date": null, "quote": "Verifiable Intent (VI) defines a layered SD-JWT credential format that creates a cryptographically verifiable chain binding an AI agent's commercial actions to an end-user's explicitly stated purchase intent.", "ref": 25 }, { "label": "[26]", "url": "https://singlefax.com/.well-known/agent-card.json", "claim": "Monocube LLC (SingleFax), *SingleFax A2A agent card*, fetched 2026-10-30", "date": null, "quote": "\"organization\":\"Monocube LLC (SingleFax)\" / \"uri\":\"https://github.com/google-agentic-commerce/AP2/tree/v0.1.0\",\"required\":true / \"roles\":[\"merchant\"],\"version\":\"0.1.0\",\"checkout_modes\":[\"human_present\"] / \"payment_methods\":[\"stripe_shared_payment_token\"]", "ref": 26 }, { "label": "[27]", "url": "https://singlefax.com/ap2.md", "claim": "SingleFax (Monocube LLC), *SingleFax AP2 payments*, fetched 2026-10-30", "date": null, "quote": "SingleFax implements the human-present merchant flow of AP2 v0.1.0 / This flow accepts Stripe Shared Payment Tokens (SPTs); it does not spend saved cards or existing account credit. / Supply a product ID and an unsigned AP2 IntentMandate / The response contains id, status and ap2.mandates.CartMandate. / JSON containing ap2.mandates.PaymentMandate / AP2 v0.2 and purchases without the user present are not negotiated.", "ref": 27 }, { "label": "[28]", "url": "https://api.algovoi.co.uk/ap2/extensions", "claim": "AlgoVoi, *AlgoVoi AP2 extensions*, fetched 2026-10-30", "date": null, "quote": "\"ap2_version\":\"0.1\" / Adds multi-chain blockchain payment methods to AP2 v0.1: Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo, and ARC. / Use as PaymentMethodData.supported_methods to advertise crypto payment acceptance. / Adds optional max_price and max_quantity fields to IntentMandate via a private extension namespace, enabling automated price bound enforcement at the gateway.", "ref": 28 }, { "label": "[29]", "url": "https://api.algovoi.co.uk/.well-known/agent-card.json", "claim": "AlgoVoi, *AlgoVoi Payment Agent card*, fetched 2026-10-30", "date": null, "quote": "\"name\":\"AlgoVoi Payment Agent\" / gates access to resources using x402, MPP (IETF), or AP2 (Google Agentic Payments) protocols.", "ref": 29 }, { "label": "[30]", "url": "https://api.algovoi.co.uk/openapi.json", "claim": "AlgoVoi, *AlgoVoi Gateway OpenAPI*, fetched 2026-10-30", "date": null, "quote": "\"title\":\"AlgoVoi Gateway\" / Public-facing x402 payment gateway.", "ref": 30 }, { "label": "[31]", "url": "https://www.allbirds.com/.well-known/ucp", "claim": "Allbirds, *UCP business profile (/.well-known/ucp)*, profile version 2026-08-25; fetched 2026-10-30", "date": null, "quote": "{\"ucp\":{\"version\":\"2026-08-25\" / dev.ucp.shopping.checkout", "ref": 31 }, { "label": "[32]", "url": "https://www.ikea.com/.well-known/ucp", "claim": "IKEA, *UCP business profile (/.well-known/ucp)*, profile version 2026-04-08; fetched 2026-10-30", "date": null, "quote": "\"supported_versions\": { \"2026-08-25\": \"https://ucp.checkout.ingka.com/.well-known/ucp/2026-08-25\" }, \"version\": \"2026-04-08\" / dev.ucp.shopping.checkout / dev.ucp.shopping.fulfillment / \"version\": \"2026-04-08\"", "ref": 32 }, { "label": "[33]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/v0.1.0/docs/partners.md", "claim": "Google Agentic Commerce, *AP2 partners (v0.1.0 docs/partners.md)*, v0.1.0 tag snapshot; fetched 2026-11-12", "date": null, "quote": "Below is a list of partners who are part of the AP2 community and are helping build, codify, and adopt A2A as the standard protocol for AI agent payments. / - [1Password](https://1password.com/) / - [manus.ai](https://manus.ai/) / - [Adyen](https://www.adyen.com/) / - [PayPal](https://www.paypal.com/)", "ref": 33 } ], "form": "endpoint", "governance": "FIDO Alliance, since Google donated AP2 on 2026-04-28. Google: \"Transitioning ownership to the FIDO Alliance ensures AP2 remains platform-agnostic and community-led, while accelerating adoption of secure agentic payments.\" FIDO develops it in its Payments Technical Working Group, chaired by members from Mastercard and Visa, and Google says the work also continues in FIDO's Agentic Authentication Technical Working Group. Google's GitHub repository still hosts the specification, documentation and SDK", "group": null, "history": [ { "date": "2026-09-06", "note": "verified against google-agentic-commerce/AP2 (README, CONTRIBUTING.md, docs/ap2/specification.md, docs/ap2/checkout_mandate.md) and Google Cloud blog launch announcement; folded in ap2-checkout-mandate as a component rather than a separate protocol" }, { "date": "2026-10-16", "note": "AP2 v0.2.0 released on 2026-04-28, and AP2 was donated to the FIDO Alliance (Payments TWG and Agentic Authentication TWG) the same day" }, { "date": "2026-10-29", "note": "Re-verified record against 35 sources on 2026-10-29: 2 live AP2 v0.1 endpoints (SingleFax, AlgoVoi), UCP AP2 Mandates extension check, 6 payment network/processor statements, and 3 research/press sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "ap2", "implementation": "multi-implementation", "last_verified": "2026-11-12", "name": "Agent Payments Protocol (AP2)", "native_status": "Pre-1.0. FIDO's September 2026 slides say: \"September 2026: AP2/VI specs moved to public repository for review.\" \"Targeting End 2026: Harmonize AP2 and VI specifications. Mid-2027: Publish first version of consolidated specifications.\" The dates after September 2026 are targets", "origin": { "date": "2025-09-16", "org": "Google" }, "part_of": null, "parties": [ "agent-site" ], "phase": "candidate", "probe": { "method": "none", "on_absent": "There is no generic HTTP probe for AP2: a Merchant, Credential Provider, or Merchant Payment Processor supports AP2 only if it accepts and validates AP2 Checkout/Payment Mandates inside its own commerce protocol's message flow (e.g. as a UCP payment handler), which cannot be detected by an unauthenticated GET against the origin.", "parse": "not applicable — AP2 is a client-side/in-band mandate format, not an origin-exposed endpoint or file", "path": "none" }, "question": "Did the user actually authorize what this agent is about to buy and pay for, and can the merchant prove it later?", "scope": "payments", "spec_url": "https://ap2-protocol.org/ap2/specification/", "step": "pay", "summary_md": "The Agentic Payment Protocol (AP2) provides a protocol to secure agent-performed payment transactions. It is an open protocol for the emerging Agent Economy, designed to enable secure, reliable, and interoperable agent commerce. The Shopping Agent passes Checkout and Payment Mandate content from the merchant's Checkout JWT to a Trusted Surface for the user to sign. In Human Not Present mode, the user approves constraints, and an agent key signs the closed Mandates. GitHub shows `v0.2.0` as the second release, focused on Human Not Present flows, and `v0.1.0` (`2025-09-16`) as the release that created the protocol. On `2026-04-28`, Google's post says it is donating the Agent Payments Protocol to the FIDO Alliance.", "track": "industry-body", "version": { "date": "2026-04-28", "label": "v0.2.0" }, "watch": [ { "type": "github", "repo": "google-agentic-commerce/AP2", "mode": "release" }, { "type": "page", "url": "https://ap2-protocol.org/", "selector": "main" } ], "use_cases": [ "agent-checkout", "delegate-user-authority", "audit-agent-actions" ], "audience": [ "platform", "agent-builder" ], "pairs_with": [ "ap2-checkout-mandate", "ucp", "a2a", "vi", "x402", "agentic-commerce-protocol" ], "prerequisites": [ "ucp" ], "hatnote_md": "This page is about the Agent Payments Protocol (AP2), announced by Google on 2025-09-16 and donated to the FIDO Alliance on 2026-04-28. It is not the Agentic Commerce Protocol (ACP), maintained by OpenAI and Stripe; see [Agentic Commerce Protocol](https://agenticweb.wiki/protocols/agentic-commerce-protocol/). It is not Visa's Trusted Agent Protocol (TAP), with which an agent proves its identity and associated authorization directly to merchants; see [Visa Trusted Agent Protocol](https://agenticweb.wiki/protocols/tap/). For the separate A2A x402 extension and the x402 payment protocol, see [x402](https://agenticweb.wiki/protocols/x402/). For the Universal Commerce Protocol, which the AP2 v0.2 specification is designed to be compatible with, see [Universal Commerce Protocol](https://agenticweb.wiki/protocols/ucp/).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This page is about the Agent Payments Protocol (AP2), announced by Google on 2025-09-16 and donated to the FIDO Alliance on 2026-04-28. It is not the Agentic Commerce Protocol (ACP), maintained by OpenAI and Stripe; see [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/). It is not Visa's Trusted Agent Protocol (TAP), with which an agent proves its identity and associated authorization directly to merchants; see [Visa Trusted Agent Protocol](/protocols/tap/). For the separate A2A x402 extension and the x402 payment protocol, see [x402](/protocols/x402/). For the Universal Commerce Protocol, which the AP2 v0.2 specification is designed to be compatible with, see [Universal Commerce Protocol](/protocols/ucp/). [1][2][3][4][5][6][7]", "v05_elevator_pitch_md": "Agent Payments Protocol (`AP2`, also titled *Agentic Payment Protocol* in the `v0.2` specification) is an open payment-authorization protocol originated by Google and donated to the FIDO Alliance that binds agent-initiated purchases to cryptographically signed `Checkout Mandate` and `Payment Mandate` credentials. Across Human Present (`Direct`) and Human Not Present (`Autonomous`) flows, it uses Selective Disclosure JWTs (`typ: \"kb+sd-jwt\"`, `ES256`) so merchants verify authorized cart contents (`mandate.checkout.1`) and credential providers and payment processors verify payment authorization without exposing raw PCI credentials to the shopping agent. [2][7][8]", "v05_lead_md": "The Agentic Payment Protocol (AP2) provides a protocol to secure agent-performed payment transactions. It is an open protocol for the emerging Agent Economy, designed to enable secure, reliable, and interoperable agent commerce. [7][9] The Shopping Agent passes Checkout and Payment Mandate content from the merchant's Checkout JWT to a Trusted Surface for the user to sign. In Human Not Present mode, the user approves constraints, and an agent key signs the closed Mandates. [7] GitHub shows `v0.2.0` as the second release, focused on Human Not Present flows, and `v0.1.0` (`2025-09-16`) as the release that created the protocol. On `2026-04-28`, Google's post says it is donating the Agent Payments Protocol to the FIDO Alliance. [2][10]", "v05_identity_sentence_md": "The Agentic Payment Protocol (AP2) provides a protocol to secure agent-performed payment transactions. It is an open protocol for the emerging Agent Economy, designed to enable secure, reliable, and interoperable agent commerce. [7][9]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "Google (Stavan Parikh, VP/GM, Payments, and Rao Surapaneni, VP/GM, Business Applications Platform), announced September 16, 2025. The `google-agentic-commerce/AP2` repository was created 2025-05-30. [1][11]" }, { "label": "Governed by", "value_md": "FIDO Alliance, after Google's donation on 2026-04-28. FIDO is developing agent-initiated commerce specifications in its Payments Technical Working Group, chaired by members from Mastercard and Visa. Google's docs say standardization continues in FIDO's Agentic Authentication Technical Working Group and Payments Technical Working Group, and that the public GitHub repository hosts the specification, documentation, and SDK. [2][9][12]" }, { "label": "Track", "value_md": "Industry body (FIDO Alliance). Google's docs say standardization of the specification continues in the Agentic Authentication Technical and Payments Technical Working Groups in FIDO. [9][12]" }, { "label": "Status", "value_md": "Public specification titled Agentic Payment Protocol (v0.2). FIDO's September 2026 W3C workshop presentation (`Jean_Luc_Di_Manno_FIDO.pdf`, PDF creation timestamp 2026-09-09, Slide 6) states: \"September 2026: AP2/VI specs moved to public repository for review,\" and labels later steps as targets: harmonize the AP2 and VI specifications at the end of 2026, and publish a first version of the consolidated specifications in mid-2027. [7][13]" }, { "label": "Version", "value_md": "v0.1.0 (2025-09-16), the release that created the protocol, and v0.2.0, which GitHub shows as released 28 Apr and describes as the second release, focused on Human Not Present flows. Google's post dated 2026-04-28 says it is releasing AP2 v.0.2 that day. The current specification heading is Agentic Payment Protocol (v0.2). [2][7][10]" }, { "label": "Message format", "value_md": "Mandates secured as SD-JWTs. The authorization document specifies OpenID4VP with SD-JWT verifiable credentials, and says other verifiable digital credential formats such as ISO mDocs (ISO 18013-5) could be made to fulfill the same role. [7][14]" }, { "label": "Transports", "value_md": "Extension of Agent2Agent (A2A) and the Model Context Protocol (MCP), and of the Universal Commerce Protocol. `v0.1` defines an A2A extension URI of `https://github.com/google-agentic-commerce/ap2/tree/v0.1`, which supporting agents MUST use; `v0.2` defines no A2A binding (`v0.1` only). [1][9][15]" }, { "label": "Specification", "value_md": "[Agentic Payment Protocol (v0.2)](https://ap2-protocol.org/ap2/specification/) [7][16]" }, { "label": "Found at", "value_md": "[ap2-protocol.org](https://ap2-protocol.org/) (repository homepage) and [google-agentic-commerce/AP2](https://github.com/google-agentic-commerce/AP2), which the docs say hosts the specification, documentation, and SDK. [9][11]" }, { "label": "Licence", "value_md": "Apache License 2.0 (`Apache-2.0`) on the `google-agentic-commerce/AP2` repository. [11]" } ], "v05_problem_md": "Today's payment systems assume a human is directly clicking buy on a trusted website. When an autonomous agent initiates a payment, this core assumption is broken, and current systems cannot answer authorization, authenticity, and accountability. [9] AP2 builds trust with mandates: tamper-proof, cryptographically signed digital contracts that serve as verifiable proof of a user's instructions. Mandates are the means AP2 uses to authorize agents, and the specification defines two types, the Checkout Mandate and the Payment Mandate. [1][7] AP2 operates as a security feature within a Commerce Protocol. Catalog APIs, checkout updates, and the specific APIs for communication between the different roles are outside the scope of AP2. [7]", "v05_mechanism_delta_md": "AP2 builds trust with mandates: tamper-proof, cryptographically signed digital contracts that serve as verifiable proof of a user's instructions. Mandates are the means AP2 uses to authorize agents, and the specification defines two types, the Checkout Mandate and the Payment Mandate. [1][7]", "v05_scope_boundary_md": "AP2 operates as a security feature within a Commerce Protocol. Catalog APIs, checkout updates, and the specific APIs for communication between the different roles are outside the scope of AP2. [7]", "v05_fuzzy_additions": [ { "id": "mandate-lifecycle-checkout-vs-payment-mandates-and-sd-jwt-cryptographic-bindings", "heading": "Mandate lifecycle, Checkout vs Payment Mandates, and SD-JWT cryptographic bindings", "body_md": "While `AP2` `v0.1.0` (`2025-09-16`) modeled authorizations around three W3C Verifiable Credentials (`CartMandate`, `IntentMandate`, and `PaymentMandate`), `AP2` `v0.2` (`v0.2.0`, `2026-04-28`) consolidates agent authorization onto two linked Selective Disclosure JWT (`RFC 9901`) credential families—the Checkout Mandate and the Payment Mandate—paired with signed Receipts for dispute evidence. Across both `Direct` (Human Present) and `Autonomous` (Human Not Present) modes, verifiers always receive closed mandates whose schema version is pinned via a mandatory numeric suffix on `vct`. [7][10][17][18]", "bullets": [ { "label": "Closed and open Checkout Mandates (`mandate.checkout.1` / `mandate.checkout.open.1`)", "text_md": "Replacing `v0.1.0`'s separate `CartMandate` and `IntentMandate`, a closed Checkout Mandate MUST set `vct` to `mandate.checkout.1` and bind the merchant-signed `checkout_jwt` via its base64url-encoded `checkout_hash` (`_sd_alg` `sha-256` by default). In `Autonomous` mode, the user first signs an open Checkout Mandate (`vct` `mandate.checkout.open.1`) over merchant and line-item constraints with the Shopping Agent's public key in `cnf`, allowing the agent key to sign the final closed mandate. [7][8][17]" }, { "label": "Linked Payment Mandate (`mandate.payment.1`) and non-deterministic cart signing", "text_md": "The Payment Mandate (`mandate.payment.1`) gives the Credential Provider, payment network, and Merchant Payment Processor cryptographic proof that the Shopping Agent is authorized to pay for a specific Checkout, bound via the cryptographic hash of the Checkout JWT while conveying agent presence and modality signals. To prevent rainbow-table attacks against selective disclosures, the Checkout JWT MUST use a non-deterministic signature scheme such as `ECDSA` (`ES256`) rather than deterministic `Ed25519`. [7][8][17]" }, { "label": "`kb+sd-jwt` key binding and selective disclosure", "text_md": "Mandate tokens use JOSE header `typ` `kb+sd-jwt` (`ES256`) with salted `disclosures` digests so only constraints relevant to a given verifier are revealed: the Merchant inspects line items and `checkout_jwt` without seeing raw payment credentials, while payment rails verify authorization constraints without full shopping-session transcripts. [7][8]" }, { "label": "Receipts and pre-authorization boundary", "text_md": "Upon completion or rejection, the Merchant returns a Checkout Receipt and the Merchant Payment Processor MUST return a signed Payment Receipt for audit and dispute resolution. Security analysis (`arXiv:2608.23858`) notes that pre-authorization LLM inputs—such as `A2A` messages and `MCP` tool calls—remain outside mandate signature protection. [7][19]" } ] }, { "id": "role-separation-payment-processor-rails-and-ucp-a2a-x402-integration", "heading": "Role separation, payment processor rails, and UCP / A2A / x402 integration", "body_md": "AP2 `v0.2` partitions transaction trust across four operational parties—Shopping Agent, Merchant, Credential Provider, and Merchant Payment Processor—plus a mandatory non-agentic Trusted Surface that collects informed user consent. Designed as a payment-method-agnostic security layer inside host commerce and agent transports, AP2 integrates with Universal Commerce Protocol (`UCP`), Agent2Agent (`A2A`), Model Context Protocol (`MCP`), and `x402` digital-currency flows under FIDO Alliance governance. [7][9]", "bullets": [ { "label": "Deterministic verification and PCI isolation", "text_md": "While the Shopping Agent is expected to be an LLM-driven agent (and Merchant, Credential Provider, and Merchant Payment Processor MAY be agentic or non-agentic), the Trusted Surface MUST be non-agentic and every role's mandate validation MUST execute in deterministic code. Role separation and payload encryption keep sensitive PCI and PII payment credentials inside Credential Providers and payment processors rather than the Shopping Agent. [7][17]" }, { "label": "UCP checkout capability and MCP tooling", "text_md": "AP2 `v0.2` is designed to pair directly with UCP: merchants advertise support in `/.well-known/ucp` via `dev.ucp.common.payment.ap2_mandate` in `ucp.dev/latest` (earlier `dev.ucp.shopping.ap2_mandate` extending `dev.ucp.shopping.checkout` in UCP `2026-01-11`). Developers can also expose AP2 provider integrations through MCP tools and servers. [7][20][21][22]" }, { "label": "A2A extension (`v0.1`) and `x402` payment rails", "text_md": "In the `v0.1.0` A2A extension, supporting agents MUST advertise extension URI `https://github.com/google-agentic-commerce/ap2/tree/v0.1` (version 0.2 delegates transport to the host commerce protocol). Because AP2 is payment-method agnostic across pull cards and push rails, it pairs with `x402` (`google-agentic-commerce/a2a-x402`) for digital-currency settlement alongside partners including Adyen, American Express, Coinbase, Mastercard, PayPal, and Worldpay. [1][15][23]" }, { "label": "FIDO Alliance donation and working groups", "text_md": "On `2026-04-28`—alongside the `v0.2.0` release—Google contributed Agent Payments Protocol to the FIDO Alliance, where ongoing specification work sits under the Agentic Authentication Technical Working Group and the Payments Technical Working Group. [2][10][12]" } ] } ], "v05_diagram": { "title": "Direct and Autonomous Checkout and Payment Mandates", "heading": "Direct and Autonomous Checkout and Payment Mandates", "mermaid": "sequenceDiagram\n participant SA as Shopping Agent\n participant TS as Trusted Surface\n participant CP as Credential Provider\n participant Merchant\n participant MPP as Merchant Payment Processor\n alt Direct, Human Present\n Merchant-->>SA: merchant-signed JWT containing the Checkout\n SA->>TS: Checkout and Payment Mandate Content\n TS-->>SA: signed Checkout and Payment Mandates\n else Autonomous, Human Not Present\n SA->>TS: open Checkout and Payment Mandate Content\n Note over TS: cnf is the agent's public key\n TS-->>SA: user-signed open Mandate\n Note over SA: signs the closed Mandates with its Agent Key\n end\n SA->>CP: Payment Mandate\n CP-->>SA: payment credential\n SA->>Merchant: payment credential and a Checkout Mandate\n Merchant->>MPP: initiates payment\n Merchant-->>SA: Checkout Receipt\n MPP-->>SA: Payment Receipt", "caption_md": "`Human Present` direct mode and `Human Not Present` autonomous mode. The Shopping Agent passes Checkout Mandate and Payment Mandate content to the Trusted Surface. Autonomous open mandates include the agent's public key as `cnf`. Verifiers always receive a closed Payment Mandate and a closed Checkout Mandate. [7]" }, "v05_wire_artifact": { "title": "Closed Checkout Mandate (`kb+sd-jwt`, `vct: mandate.checkout.1`)", "heading": "Closed Checkout Mandate (`kb+sd-jwt`, `vct: mandate.checkout.1`)", "lang": "json", "code": "{\n \"issuer_signed_jwt\": {\n \"header\": {\n \"alg\": \"ES256\",\n \"typ\": \"kb+sd-jwt\"\n },\n \"payload\": {\n \"delegate_payload\": [\n {\n \"...\": \"7VLY-eKTFSShLoZRXY5jXcD2UHm1JvPmoANYRqqxy34\"\n }\n ],\n \"iat\": 1777342376,\n \"aud\": \"merchant\",\n \"nonce\": \"b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4\",\n \"sd_hash\": \"FzLoxbbtgQGYZxoSM2NJYJtkFTSsdfUBoVEQ12k7JN8\",\n \"_sd_alg\": \"sha-256\"\n }\n },\n \"disclosures\": [\n {\n \"digest\": \"FzLoxbbtgQGYZxoSM2NJYJtkFTSsdfUBoVEQ12k7JN8\",\n \"decoded\": [\n \"w-n1leFT6z8rHTNHwr5Wow\",\n \"checkout_jwt\",\n {\n \"header\": {\n \"alg\": \"ES256\",\n \"typ\": \"JWT\"\n },\n \"payload\": {\n \"order_id\": \"09414145-b7bi-432e-bf5c-ha0ba0bc4580\",\n \"merchant\": {\n \"id\": \"merchant_1\",\n \"name\": \"Demo Merchant\",\n \"website\": \"https://demo-merchant.example\"\n },\n \"line_items\": [\n {\n \"id\": \"line_1\",\n \"product\": {\n \"id\": \"supershoe_limited_edition_gold_sneaker_womens_9_0\",\n \"title\": \"SuperShoe Limited Edition Gold — Women's 9\",\n \"price\": 199.0,\n \"currency\": \"USD\"\n },\n \"quantity\": 1\n }\n ],\n \"total_price\": 199.0,\n \"currency\": \"USD\",\n \"shipping_policy\": \"Standard Shipping\",\n \"return_policy\": \"30-day returns\"\n }\n }\n ]\n },\n {\n \"digest\": \"7VLY-eKTFSShLoZRXY5jXcD2UHm1JvPmoANYRqqxy34\",\n \"decoded\": [\n \"szhpxKrgGJwyqMEN9WI5Sw\",\n {\n \"_sd\": [\n \"3A9UyZJofw2eMP-Lx2tYaNpCcuB8elnhwwLhZLwqFFM\"\n ],\n \"vct\": \"mandate.checkout.1\",\n \"checkout_hash\": \"NivWhuqfzcvZNapvIEJ2-3tsdQLkiuIcye2g46WVgX8\"\n }\n ]\n }\n ]\n}", "caption_md": "Closed Checkout Mandate SD-JWT (`alg` `ES256`, `typ` `kb+sd-jwt`, `_sd_alg` `sha-256`) plus decoded disclosures: one disclosure reveals the merchant-signed `checkout_jwt` order payload, while the delegate disclosure binds `vct` `mandate.checkout.1` and `checkout_hash`. [8]" }, "v05_counterparts": { "classic_analogues": [ { "name": "Selective Disclosure for JWTs (SD-JWT, RFC 9901)", "spec_or_rfc": "RFC 9901", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "AP2 v0.2 specifies SD-JWTs for securing the Payment and Checkout Mandates. AP2's authorization document also names other verifiable digital credential formats, such as ISO mDocs (ISO 18013-5), that could be made to fulfill the same role. [7][14]" }, { "name": "EMV 3-D Secure", "spec_or_rfc": "EMV 3-D Secure", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Whereas classic web payment flows assume a human is directly clicking buy on a trusted website, AP2 authorizes agent-initiated transactions with a signed Checkout Mandate or Payment Mandate secured as an SD-JWT in v0.2. [7][9]" } ], "agentic_peers": [ { "target_id": "ap2-checkout-mandate", "target_name": "AP2 Checkout Mandate", "relation_type": "has_component", "relation_label": "Has component", "delta_md": "The Checkout Mandate is an AP2 component, specified as a mandate for authorizing completion of a checkout. The Shopping Agent creates the mandate content, the Trusted Surface renders it to the user, and the Merchant verifies it. The v0.2 specification pairs that object with the Payment Mandate. [7][8]" }, { "target_id": "ucp", "target_name": "Universal Commerce Protocol (UCP)", "relation_type": "builds_on", "relation_label": "Builds on", "delta_md": "UCP is the commerce protocol that AP2 v0.2 is designed to be compatible with and to integrate with. AP2's FAQ calls AP2 the specialized payment layer for authorizing and signing transactions, while UCP orchestrates the broader purchase lifecycle. UCP's AP2 Mandates extension is how a business adds `dev.ucp.common.payment.ap2_mandate` to its `/.well-known/ucp` capabilities list. [7][20][24]" }, { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "A2A is the agent-to-agent protocol that AP2 extends. Under the v0.1 A2A extension, the extension URI is `https://github.com/google-agentic-commerce/ap2/tree/v0.1`, and agents that support AP2 MUST use that URI. The v0.1 topic note treats A2A as tasks and messages between agents, and AP2 as how agents communicate about payments. [15][22]" }, { "target_id": "vi", "target_name": "Verifiable Intent", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Verifiable Intent is the framework Mastercard contributed to the FIDO Alliance, co-developed with Google and designed to work with AP2. The VI specification describes it as a layered SD-JWT credential format that binds an agent's commercial actions to a user's purchase intent. FIDO's slide deck targets harmonizing the AP2 and VI specifications by the end of 2026 and publishing a first consolidated version in mid-2027. AP2 v0.2, on its own specification, secures its checkout and payment mandates as SD-JWTs. [7][12][13][25]" }, { "target_id": "x402", "target_name": "x402", "relation_type": "complements", "relation_label": "Complements", "delta_md": "x402 is the internet-native payment protocol whose v2 specification defines a payment payload and names the `PAYMENT-SIGNATURE` header. Google's AP2 launch describes crypto payment through a separate A2A x402 extension, and the AP2 x402 topic calls AP2 and x402 complementary. AP2 v0.2 secures its checkout and payment mandates as SD-JWTs. [1][6][7][23]" }, { "target_id": "agentic-commerce-protocol", "target_name": "Agentic Commerce Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ACP is an open standard, maintained by OpenAI and Stripe, for connecting buyers, their AI agents, and businesses to complete purchases. AP2 is the mandate protocol for authorizing agent payments. In v0.1, AP2 is discovered by an A2A extension URI rather than by a path named in that extension document. [3][7][15]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (4 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Merchants, payment gateways & protocol extensions", "col4_header": "Mandate type (`Checkout Mandate` / `CartMandate`, `Payment Mandate` / `PaymentMandate`, `IntentMandate`) & rail", "note_md": null, "rows": [ { "actor": "SingleFax (Monocube LLC)", "role": "Merchant", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Monocube LLC publishes the SingleFax agent card with a required AP2 extension at `https://github.com/google-agentic-commerce/AP2/tree/v0.1.0`, role `merchant`, version `0.1.0`, checkout mode `human_present`, and payment method `stripe_shared_payment_token`. singlefax.com/ap2.md says SingleFax implements the human-present merchant flow of AP2 v0.1.0 and accepts Stripe Shared Payment Tokens (SPTs). The cart request carries an unsigned `IntentMandate`; the response includes `ap2.mandates.CartMandate`; prepare sends `ap2.mandates.PaymentMandate`. AP2 v0.2 and purchases without the user present are not negotiated.", "source_md": "[SingleFax agent card (fetched 2026-10-30)](https://singlefax.com/.well-known/agent-card.json) [26] · [SingleFax AP2 payments (fetched 2026-10-30)](https://singlefax.com/ap2.md) [27]" }, { "actor": "AlgoVoi", "role": "Payment gateway", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "The extensions document sets `ap2_version` to `0.1`. AlgoVoi Crypto Payment Method adds multi-chain methods for Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo, and ARC, used as `PaymentMethodData.supported_methods`. AlgoVoi Intent Bounds adds optional max_price and max_quantity fields to `IntentMandate`. The AlgoVoi Payment Agent card says it gates access using x402, MPP (IETF), or AP2. The host OpenAPI document titles the service AlgoVoi Gateway, a public-facing x402 payment gateway.", "source_md": "[AlgoVoi AP2 extensions (fetched 2026-10-30)](https://api.algovoi.co.uk/ap2/extensions) [28] · [AlgoVoi Payment Agent card (fetched 2026-10-30)](https://api.algovoi.co.uk/.well-known/agent-card.json) [29] · [AlgoVoi Gateway OpenAPI (fetched 2026-10-30)](https://api.algovoi.co.uk/openapi.json) [30]" }, { "actor": "Universal Commerce Protocol (UCP) AP2 Mandates Extension", "role": "Protocol extension", "status": "Supported", "status_display": "Supported · as of 2026-08-25", "col4_md": "Businesses declare support by adding `dev.ucp.common.payment.ap2_mandate` to their capabilities list in `/.well-known/ucp`. When that capability is in the intersection, the business MUST include `ap2.merchant_authorization` on checkout responses and MUST NOT accept `complete_checkout` without `ap2.checkout_mandate`. Mandates are SD-JWT credentials; the extension places `checkout_mandate` at `ap2.checkout_mandate` and `payment_mandate` at `payment.instruments[*].credential.token`. Allbirds' `/.well-known/ucp` (version 2026-08-25) lists `dev.ucp.shopping.checkout`, and IKEA's `/.well-known/ucp` (version 2026-04-08, with 2026-08-25 under `supported_versions`) lists `dev.ucp.shopping.checkout` and `dev.ucp.shopping.fulfillment`; neither declares `dev.ucp.common.payment.ap2_mandate`.", "source_md": "[UCP AP2 Mandates Extension (fetched 2026-10-30)](https://ucp.dev/latest/specification/payment/extensions/ap2-mandates/) [20] · [allbirds.com UCP profile (fetched 2026-10-30)](https://www.allbirds.com/.well-known/ucp) [31] · [ikea.com UCP profile (fetched 2026-10-30)](https://www.ikea.com/.well-known/ucp) [32]" } ] }, "side_b": { "visible": true, "heading": "Buying agents, wallets & client SDKs", "col4_header": "Supported mandates & SDK surface", "note_md": null, "rows": [ { "actor": "google-agentic-commerce/AP2 Python package", "role": "Client SDK", "status": "Partial", "status_display": "Partial · as of 2026-10-30", "col4_md": "The repository defines the protocol's core objects under `code/sdk/python/ap2/`, with Pydantic models and canonical JSON schemas. A PyPI package will be published at a later time; until then the documented install is `uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main`. The FAQ says sample agents were built around the core AP2 python library, that those samples mock actual payment service providers, and that an SDK and a MCP server are still in progress with payment service providers. That FAQ names the Checkout Mandate and the Payment Mandate as verifiable credentials.", "source_md": "[google-agentic-commerce/AP2 (fetched 2026-10-30)](https://github.com/google-agentic-commerce/AP2) [11] · [AP2 FAQ (fetched 2026-10-30)](https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/faq.md) [24]" } ] }, "additional_tables": null, "censuses": [ { "label": "arXiv 2608.23858", "as_of": "2026-08-24", "value_md": "A security analysis submitted on 24 Aug 2026 says no complete public AP2 deployment was available, so the authors built a testbed instead. [19]" }, { "label": "allbirds.com and ikea.com UCP profiles", "as_of": "2026-10-30", "value_md": "0 of 2 UCP business profiles fetched on 2026-10-30 (allbirds.com version 2026-08-25, ikea.com version 2026-04-08) declare dev.ucp.common.payment.ap2_mandate. [20][31][32]" }, { "label": "AP2 v0.1.0 docs/partners.md", "as_of": null, "value_md": "The tagged v0.1.0 docs/partners.md snapshot lists 56 named launch-community partners in the AP2 community, from 1Password through manus.ai (including Adyen and PayPal); its introductory line referred to adopting A2A (which AP2 v0.1 extended) for AI agent payments. [33]" } ], "footer_md": null }, "v05_see_also": [ { "item_md": "**[Machine Payments Protocol (MPP)](/protocols/mpp/)** *(Complements)* — MPP moves the HTTP request's payment via an Authorization: Payment credential, while AP2 is the SD-JWT Checkout Mandate that records delegated authority and is not the WWW-Authenticate challenge." }, { "item_md": "**[VCAP: Verified Commerce for Agent Protocols](/protocols/vcap/)** *(Complements)* — VCAP binds release and refund to machine-checkable delivery evidence, while AP2 is the SD-JWT Checkout Mandate and does not define those escrow transitions." }, { "item_md": "**[s402](/protocols/s402/)** *(Deprecated; formerly a profile/extension)* — Retired in September 2026 in favor of standard x402; s402 marked its profile with the extensions.s402 key on the x402 v2 402 envelope over Sui transactions rather than AP2 SD-JWT Checkout Mandates." }, { "item_md": "**[EMV® Agentic Payments – Framework for Specifications](/protocols/emv-agentic-payments/)** *(Complements)* — AP2 already specifies an SD-JWT Checkout Mandate and Payment Mandate a merchant can verify, while this EMVCo draft is a framework for future specifications, including possible later changes to 3-D Secure, and has no mandate syntax." }, { "item_md": "**[Agent-Initiated Payment Gating](/protocols/agentic-payments-gating-model/)** *(Complements)* — The draft cites AP2 as the mandate for delegated authority at the gate, while its own text is the task state machine and not the SD-JWT Checkout Mandate." }, { "item_md": "**[Agentic Mobile Protocol (AMP)](/protocols/amp-ant/)** *(Peer alternative)* — AMP assurance data is an SD-JWT across three layers, followed by an Alipay+ CGCP Payment Token longer than 24 bits, while AP2's checkout credential is an SD-JWT verifiable credential for the Checkout Mandate signed on a Trusted Surface." }, { "item_md": "**[KYAPay Token](/protocols/kyapay-token/)** *(Peer alternative)* — KYAPay binds the authorizing party, the agent platform, and a coin or card instrument inside one JWT, while AP2's checkout authorization is an SD-JWT verifiable credential for the Checkout Mandate." }, { "item_md": "**[Agent Commerce Kit (ACK)](/protocols/agent-commerce-kit/)** *(Peer alternative)* — ACK-Pay's published proof of payment is a W3C VC receipt and ACK-ID is the DID identity layer, while AP2's proof of authorization is an SD-JWT Checkout Mandate signed on a Trusted Surface." }, { "item_md": "**[Agent Network Protocol (ANP)](/protocols/anp/)** *(Complements)* — `ANP-10` (`Version: 1.1`, `Status: Draft / not released`) adapts `AP2` `v0.1.0` `CartMandate` and `PaymentMandate` objects (plus `DeliveryReceipt`) signed with `JWT`/`JWS` for `did:wba` agents (`IntentMandate` deferred / not supported; `SD-JWT` listed as an unchecked future roadmap item), rather than `AP2` `v0.2` `Checkout Mandate` and `Payment Mandate` `SD-JWT`s (`mandate.checkout.1` / `mandate.payment.1`)." }, { "item_md": "**[Agent Interaction & Transaction Protocol (AITP)](/protocols/aitp/)** *(Peer alternative)* — AITP defines its own quote and payment JSON capability messages in AITP-01: Payments (Spec Status: Ideation, Implementation Status: In Development) and does not reference AP2, whereas AP2 is Google's verifiable-credential mandate protocol." }, { "item_md": "**[Agent-to-Wallet Protocol for Digital Credentials (A2WP)](/protocols/a2wp/)** *(Complements)* — AP2 is the verifiable-credential mandate protocol, while A2WP is the agent-to-wallet hand-off of OpenID4VCI and OpenID4VP requests and leaves transport out of scope." }, { "item_md": "**[Trusted Agent Protocol (TAP)](/protocols/tap/)** *(Complements)* — AP2 carries checkout and payment mandates for a purchase, while TAP authenticates the agent HTTP call to the merchant with the message signature and Visa ID Token." }, { "item_md": "**[ERC-8226 Regulated Agent Mandate](/protocols/erc-8226/)** *(Peer alternative)* — AP2 mandates are off-chain checkout and payment credentials presented to a merchant or network, while an ERC-8226 mandate is an on-chain IAgentMandate record checked inside the token call." }, { "item_md": "**[Agent Attribution Protocol (AAP)](/protocols/agent-attribution-protocol/)** *(Complements)* — AP2 authorizes a payment with checkout and payment mandates, while AAP's Rako-signed AAP Code attributes a recommend() event to a later checkout() conversion." }, { "item_md": "**[Agent Delegation Receipts](/protocols/agent-delegation-receipts/)** *(Complements)* — AP2 payment mandates authorize a checkout, while a delegation receipt is a JWS over JCS JSON, or a COSE_Sign1, that binds the operator-instruction hash before the agent acts." }, { "item_md": "**[Agent Decision Commitments for Payments (ADC)](/protocols/agent-decision-commitment/)** *(Depended on by)* — AP2 is the payment-mandate protocol ADC binds to, and the added claim is decision_context, a salted hash commitment registered with a SCITT transparency service." }, { "item_md": "**[ERC-8196: AI Agent Authenticated Wallet](/protocols/erc-8196/)** *(Complements)* — AP2 authorizes a checkout with payment mandates, and ERC-8196 is the ERC-4337 wallet that executes an agent transaction only when cryptographic proof shows the action matches the registered policy." }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: ap2\ntitle: \"Agent Payments Protocol (AP2)\"\ntier: flagship\nlifecycle_status: active\ncategory: pay\nform: endpoint\nwire_archetype: payments_onchain\nspec_url: https://ap2-protocol.org/ap2/specification/\nlast_checked: 2026-11-12\n---\n\n# Agent Payments Protocol (AP2)\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-12\n\n> *This page is about the Agent Payments Protocol (AP2), announced by Google on 2025-09-16 and donated to the FIDO Alliance on 2026-04-28. It is not the Agentic Commerce Protocol (ACP), maintained by OpenAI and Stripe; see [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/). It is not Visa's Trusted Agent Protocol (TAP), with which an agent proves its identity and associated authorization directly to merchants; see [Visa Trusted Agent Protocol](/protocols/tap/). For the separate A2A x402 extension and the x402 payment protocol, see [x402](/protocols/x402/). For the Universal Commerce Protocol, which the AP2 v0.2 specification is designed to be compatible with, see [Universal Commerce Protocol](/protocols/ucp/). [1][2][3][4][5][6][7]*\n\n> **In brief:** Agent Payments Protocol (`AP2`, also titled *Agentic Payment Protocol* in the `v0.2` specification) is an open payment-authorization protocol originated by Google and donated to the FIDO Alliance that binds agent-initiated purchases to cryptographically signed `Checkout Mandate` and `Payment Mandate` credentials. Across Human Present (`Direct`) and Human Not Present (`Autonomous`) flows, it uses Selective Disclosure JWTs (`typ: \"kb+sd-jwt\"`, `ES256`) so merchants verify authorized cart contents (`mandate.checkout.1`) and credential providers and payment processors verify payment authorization without exposing raw PCI credentials to the shopping agent. [2][7][8]\n\nThe Agentic Payment Protocol (AP2) provides a protocol to secure agent-performed payment transactions. It is an open protocol for the emerging Agent Economy, designed to enable secure, reliable, and interoperable agent commerce. [7][9] The Shopping Agent passes Checkout and Payment Mandate content from the merchant's Checkout JWT to a Trusted Surface for the user to sign. In Human Not Present mode, the user approves constraints, and an agent key signs the closed Mandates. [7] GitHub shows `v0.2.0` as the second release, focused on Human Not Present flows, and `v0.1.0` (`2025-09-16`) as the release that created the protocol. On `2026-04-28`, Google's post says it is donating the Agent Payments Protocol to the FIDO Alliance. [2][10]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | Google (Stavan Parikh, VP/GM, Payments, and Rao Surapaneni, VP/GM, Business Applications Platform), announced September 16, 2025. The `google-agentic-commerce/AP2` repository was created 2025-05-30. [1][11] |\n| **Governed by** | FIDO Alliance, after Google's donation on 2026-04-28. FIDO is developing agent-initiated commerce specifications in its Payments Technical Working Group, chaired by members from Mastercard and Visa. Google's docs say standardization continues in FIDO's Agentic Authentication Technical Working Group and Payments Technical Working Group, and that the public GitHub repository hosts the specification, documentation, and SDK. [2][9][12] |\n| **Track** | Industry body (FIDO Alliance). Google's docs say standardization of the specification continues in the Agentic Authentication Technical and Payments Technical Working Groups in FIDO. [9][12] |\n| **Status** | Public specification titled Agentic Payment Protocol (v0.2). FIDO's September 2026 W3C workshop presentation (`Jean_Luc_Di_Manno_FIDO.pdf`, PDF creation timestamp 2026-09-09, Slide 6) states: \"September 2026: AP2/VI specs moved to public repository for review,\" and labels later steps as targets: harmonize the AP2 and VI specifications at the end of 2026, and publish a first version of the consolidated specifications in mid-2027. [7][13] |\n| **Version** | v0.1.0 (2025-09-16), the release that created the protocol, and v0.2.0, which GitHub shows as released 28 Apr and describes as the second release, focused on Human Not Present flows. Google's post dated 2026-04-28 says it is releasing AP2 v.0.2 that day. The current specification heading is Agentic Payment Protocol (v0.2). [2][7][10] |\n| **Message format** | Mandates secured as SD-JWTs. The authorization document specifies OpenID4VP with SD-JWT verifiable credentials, and says other verifiable digital credential formats such as ISO mDocs (ISO 18013-5) could be made to fulfill the same role. [7][14] |\n| **Transports** | Extension of Agent2Agent (A2A) and the Model Context Protocol (MCP), and of the Universal Commerce Protocol. `v0.1` defines an A2A extension URI of `https://github.com/google-agentic-commerce/ap2/tree/v0.1`, which supporting agents MUST use; `v0.2` defines no A2A binding (`v0.1` only). [1][9][15] |\n| **Specification** | [Agentic Payment Protocol (v0.2)](https://ap2-protocol.org/ap2/specification/) [7][16] |\n| **Found at** | [ap2-protocol.org](https://ap2-protocol.org/) (repository homepage) and [google-agentic-commerce/AP2](https://github.com/google-agentic-commerce/AP2), which the docs say hosts the specification, documentation, and SDK. [9][11] |\n| **Licence** | Apache License 2.0 (`Apache-2.0`) on the `google-agentic-commerce/AP2` repository. [11] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Mandate lifecycle, Checkout vs Payment Mandates, and SD-JWT cryptographic bindings](#mandate-lifecycle-checkout-vs-payment-mandates-and-sd-jwt-cryptographic-bindings)\n3. [Role separation, payment processor rails, and UCP / A2A / x402 integration](#role-separation-payment-processor-rails-and-ucp-a2a-x402-integration)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nToday's payment systems assume a human is directly clicking buy on a trusted website. When an autonomous agent initiates a payment, this core assumption is broken, and current systems cannot answer authorization, authenticity, and accountability. [9] AP2 builds trust with mandates: tamper-proof, cryptographically signed digital contracts that serve as verifiable proof of a user's instructions. Mandates are the means AP2 uses to authorize agents, and the specification defines two types, the Checkout Mandate and the Payment Mandate. [1][7] AP2 operates as a security feature within a Commerce Protocol. Catalog APIs, checkout updates, and the specific APIs for communication between the different roles are outside the scope of AP2. [7]\n\n### Direct and Autonomous Checkout and Payment Mandates\n\n```mermaid\nsequenceDiagram\n participant SA as Shopping Agent\n participant TS as Trusted Surface\n participant CP as Credential Provider\n participant Merchant\n participant MPP as Merchant Payment Processor\n alt Direct, Human Present\n Merchant-->>SA: merchant-signed JWT containing the Checkout\n SA->>TS: Checkout and Payment Mandate Content\n TS-->>SA: signed Checkout and Payment Mandates\n else Autonomous, Human Not Present\n SA->>TS: open Checkout and Payment Mandate Content\n Note over TS: cnf is the agent's public key\n TS-->>SA: user-signed open Mandate\n Note over SA: signs the closed Mandates with its Agent Key\n end\n SA->>CP: Payment Mandate\n CP-->>SA: payment credential\n SA->>Merchant: payment credential and a Checkout Mandate\n Merchant->>MPP: initiates payment\n Merchant-->>SA: Checkout Receipt\n MPP-->>SA: Payment Receipt\n```\n\n*`Human Present` direct mode and `Human Not Present` autonomous mode. The Shopping Agent passes Checkout Mandate and Payment Mandate content to the Trusted Surface. Autonomous open mandates include the agent's public key as `cnf`. Verifiers always receive a closed Payment Mandate and a closed Checkout Mandate. [7]*\n\n### Closed Checkout Mandate (`kb+sd-jwt`, `vct: mandate.checkout.1`)\n\n```json\n{\n \"issuer_signed_jwt\": {\n \"header\": {\n \"alg\": \"ES256\",\n \"typ\": \"kb+sd-jwt\"\n },\n \"payload\": {\n \"delegate_payload\": [\n {\n \"...\": \"7VLY-eKTFSShLoZRXY5jXcD2UHm1JvPmoANYRqqxy34\"\n }\n ],\n \"iat\": 1777342376,\n \"aud\": \"merchant\",\n \"nonce\": \"b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4\",\n \"sd_hash\": \"FzLoxbbtgQGYZxoSM2NJYJtkFTSsdfUBoVEQ12k7JN8\",\n \"_sd_alg\": \"sha-256\"\n }\n },\n \"disclosures\": [\n {\n \"digest\": \"FzLoxbbtgQGYZxoSM2NJYJtkFTSsdfUBoVEQ12k7JN8\",\n \"decoded\": [\n \"w-n1leFT6z8rHTNHwr5Wow\",\n \"checkout_jwt\",\n {\n \"header\": {\n \"alg\": \"ES256\",\n \"typ\": \"JWT\"\n },\n \"payload\": {\n \"order_id\": \"09414145-b7bi-432e-bf5c-ha0ba0bc4580\",\n \"merchant\": {\n \"id\": \"merchant_1\",\n \"name\": \"Demo Merchant\",\n \"website\": \"https://demo-merchant.example\"\n },\n \"line_items\": [\n {\n \"id\": \"line_1\",\n \"product\": {\n \"id\": \"supershoe_limited_edition_gold_sneaker_womens_9_0\",\n \"title\": \"SuperShoe Limited Edition Gold — Women's 9\",\n \"price\": 199.0,\n \"currency\": \"USD\"\n },\n \"quantity\": 1\n }\n ],\n \"total_price\": 199.0,\n \"currency\": \"USD\",\n \"shipping_policy\": \"Standard Shipping\",\n \"return_policy\": \"30-day returns\"\n }\n }\n ]\n },\n {\n \"digest\": \"7VLY-eKTFSShLoZRXY5jXcD2UHm1JvPmoANYRqqxy34\",\n \"decoded\": [\n \"szhpxKrgGJwyqMEN9WI5Sw\",\n {\n \"_sd\": [\n \"3A9UyZJofw2eMP-Lx2tYaNpCcuB8elnhwwLhZLwqFFM\"\n ],\n \"vct\": \"mandate.checkout.1\",\n \"checkout_hash\": \"NivWhuqfzcvZNapvIEJ2-3tsdQLkiuIcye2g46WVgX8\"\n }\n ]\n }\n ]\n}\n```\n\n*Closed Checkout Mandate SD-JWT (`alg` `ES256`, `typ` `kb+sd-jwt`, `_sd_alg` `sha-256`) plus decoded disclosures: one disclosure reveals the merchant-signed `checkout_jwt` order payload, while the delegate disclosure binds `vct` `mandate.checkout.1` and `checkout_hash`. [8]*\n\n---\n\n## Mandate lifecycle, Checkout vs Payment Mandates, and SD-JWT cryptographic bindings\n\nWhile `AP2` `v0.1.0` (`2025-09-16`) modeled authorizations around three W3C Verifiable Credentials (`CartMandate`, `IntentMandate`, and `PaymentMandate`), `AP2` `v0.2` (`v0.2.0`, `2026-04-28`) consolidates agent authorization onto two linked Selective Disclosure JWT (`RFC 9901`) credential families—the Checkout Mandate and the Payment Mandate—paired with signed Receipts for dispute evidence. Across both `Direct` (Human Present) and `Autonomous` (Human Not Present) modes, verifiers always receive closed mandates whose schema version is pinned via a mandatory numeric suffix on `vct`. [7][10][17][18]\n\n- **Closed and open Checkout Mandates (`mandate.checkout.1` / `mandate.checkout.open.1`):** Replacing `v0.1.0`'s separate `CartMandate` and `IntentMandate`, a closed Checkout Mandate MUST set `vct` to `mandate.checkout.1` and bind the merchant-signed `checkout_jwt` via its base64url-encoded `checkout_hash` (`_sd_alg` `sha-256` by default). In `Autonomous` mode, the user first signs an open Checkout Mandate (`vct` `mandate.checkout.open.1`) over merchant and line-item constraints with the Shopping Agent's public key in `cnf`, allowing the agent key to sign the final closed mandate. [7][8][17]\n- **Linked Payment Mandate (`mandate.payment.1`) and non-deterministic cart signing:** The Payment Mandate (`mandate.payment.1`) gives the Credential Provider, payment network, and Merchant Payment Processor cryptographic proof that the Shopping Agent is authorized to pay for a specific Checkout, bound via the cryptographic hash of the Checkout JWT while conveying agent presence and modality signals. To prevent rainbow-table attacks against selective disclosures, the Checkout JWT MUST use a non-deterministic signature scheme such as `ECDSA` (`ES256`) rather than deterministic `Ed25519`. [7][8][17]\n- **`kb+sd-jwt` key binding and selective disclosure:** Mandate tokens use JOSE header `typ` `kb+sd-jwt` (`ES256`) with salted `disclosures` digests so only constraints relevant to a given verifier are revealed: the Merchant inspects line items and `checkout_jwt` without seeing raw payment credentials, while payment rails verify authorization constraints without full shopping-session transcripts. [7][8]\n- **Receipts and pre-authorization boundary:** Upon completion or rejection, the Merchant returns a Checkout Receipt and the Merchant Payment Processor MUST return a signed Payment Receipt for audit and dispute resolution. Security analysis (`arXiv:2608.23858`) notes that pre-authorization LLM inputs—such as `A2A` messages and `MCP` tool calls—remain outside mandate signature protection. [7][19]\n\n---\n\n## Role separation, payment processor rails, and UCP / A2A / x402 integration\n\nAP2 `v0.2` partitions transaction trust across four operational parties—Shopping Agent, Merchant, Credential Provider, and Merchant Payment Processor—plus a mandatory non-agentic Trusted Surface that collects informed user consent. Designed as a payment-method-agnostic security layer inside host commerce and agent transports, AP2 integrates with Universal Commerce Protocol (`UCP`), Agent2Agent (`A2A`), Model Context Protocol (`MCP`), and `x402` digital-currency flows under FIDO Alliance governance. [7][9]\n\n- **Deterministic verification and PCI isolation:** While the Shopping Agent is expected to be an LLM-driven agent (and Merchant, Credential Provider, and Merchant Payment Processor MAY be agentic or non-agentic), the Trusted Surface MUST be non-agentic and every role's mandate validation MUST execute in deterministic code. Role separation and payload encryption keep sensitive PCI and PII payment credentials inside Credential Providers and payment processors rather than the Shopping Agent. [7][17]\n- **UCP checkout capability and MCP tooling:** AP2 `v0.2` is designed to pair directly with UCP: merchants advertise support in `/.well-known/ucp` via `dev.ucp.common.payment.ap2_mandate` in `ucp.dev/latest` (earlier `dev.ucp.shopping.ap2_mandate` extending `dev.ucp.shopping.checkout` in UCP `2026-01-11`). Developers can also expose AP2 provider integrations through MCP tools and servers. [7][20][21][22]\n- **A2A extension (`v0.1`) and `x402` payment rails:** In the `v0.1.0` A2A extension, supporting agents MUST advertise extension URI `https://github.com/google-agentic-commerce/ap2/tree/v0.1` (version 0.2 delegates transport to the host commerce protocol). Because AP2 is payment-method agnostic across pull cards and push rails, it pairs with `x402` (`google-agentic-commerce/a2a-x402`) for digital-currency settlement alongside partners including Adyen, American Express, Coinbase, Mastercard, PayPal, and Worldpay. [1][15][23]\n- **FIDO Alliance donation and working groups:** On `2026-04-28`—alongside the `v0.2.0` release—Google contributed Agent Payments Protocol to the FIDO Alliance, where ongoing specification work sits under the Agentic Authentication Technical Working Group and the Payments Technical Working Group. [2][10][12]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Selective Disclosure for JWTs (SD-JWT, RFC 9901)** | `RFC 9901` | Profiles classic standard | AP2 v0.2 specifies SD-JWTs for securing the Payment and Checkout Mandates. AP2's authorization document also names other verifiable digital credential formats, such as ISO mDocs (ISO 18013-5), that could be made to fulfill the same role. [7][14] |\n| **EMV 3-D Secure** | `EMV 3-D Secure` | Analogous to classic standard | Whereas classic web payment flows assume a human is directly clicking buy on a trusted website, AP2 authorizes agent-initiated transactions with a signed Checkout Mandate or Payment Mandate secured as an SD-JWT in v0.2. [7][9] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[AP2 Checkout Mandate](/protocols/ap2-checkout-mandate/)** | Has component | The Checkout Mandate is an AP2 component, specified as a mandate for authorizing completion of a checkout. The Shopping Agent creates the mandate content, the Trusted Surface renders it to the user, and the Merchant verifies it. The v0.2 specification pairs that object with the Payment Mandate. [7][8] |\n| **[Universal Commerce Protocol (UCP)](/protocols/ucp/)** | Builds on | UCP is the commerce protocol that AP2 v0.2 is designed to be compatible with and to integrate with. AP2's FAQ calls AP2 the specialized payment layer for authorizing and signing transactions, while UCP orchestrates the broader purchase lifecycle. UCP's AP2 Mandates extension is how a business adds `dev.ucp.common.payment.ap2_mandate` to its `/.well-known/ucp` capabilities list. [7][20][24] |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Complements | A2A is the agent-to-agent protocol that AP2 extends. Under the v0.1 A2A extension, the extension URI is `https://github.com/google-agentic-commerce/ap2/tree/v0.1`, and agents that support AP2 MUST use that URI. The v0.1 topic note treats A2A as tasks and messages between agents, and AP2 as how agents communicate about payments. [15][22] |\n| **[Verifiable Intent](/protocols/vi/)** | Peer alternative | Verifiable Intent is the framework Mastercard contributed to the FIDO Alliance, co-developed with Google and designed to work with AP2. The VI specification describes it as a layered SD-JWT credential format that binds an agent's commercial actions to a user's purchase intent. FIDO's slide deck targets harmonizing the AP2 and VI specifications by the end of 2026 and publishing a first consolidated version in mid-2027. AP2 v0.2, on its own specification, secures its checkout and payment mandates as SD-JWTs. [7][12][13][25] |\n| **[x402](/protocols/x402/)** | Complements | x402 is the internet-native payment protocol whose v2 specification defines a payment payload and names the `PAYMENT-SIGNATURE` header. Google's AP2 launch describes crypto payment through a separate A2A x402 extension, and the AP2 x402 topic calls AP2 and x402 complementary. AP2 v0.2 secures its checkout and payment mandates as SD-JWTs. [1][6][7][23] |\n| **[Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/)** | Complements | ACP is an open standard, maintained by OpenAI and Stripe, for connecting buyers, their AI agents, and businesses to complete purchases. AP2 is the mandate protocol for authorizing agent payments. In v0.1, AP2 is discovered by an A2A extension URI rather than by a path named in that extension document. [3][7][15] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (4 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Merchants, payment gateways & protocol extensions\n\n| Actor | Role | Status | Mandate type (`Checkout Mandate` / `CartMandate`, `Payment Mandate` / `PaymentMandate`, `IntentMandate`) & rail | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **SingleFax (Monocube LLC)** | Merchant | Live (HTTP 200) · checked 2026-10-30 | Monocube LLC publishes the SingleFax agent card with a required AP2 extension at `https://github.com/google-agentic-commerce/AP2/tree/v0.1.0`, role `merchant`, version `0.1.0`, checkout mode `human_present`, and payment method `stripe_shared_payment_token`. singlefax.com/ap2.md says SingleFax implements the human-present merchant flow of AP2 v0.1.0 and accepts Stripe Shared Payment Tokens (SPTs). The cart request carries an unsigned `IntentMandate`; the response includes `ap2.mandates.CartMandate`; prepare sends `ap2.mandates.PaymentMandate`. AP2 v0.2 and purchases without the user present are not negotiated. | [SingleFax agent card (fetched 2026-10-30)](https://singlefax.com/.well-known/agent-card.json) [26] · [SingleFax AP2 payments (fetched 2026-10-30)](https://singlefax.com/ap2.md) [27] |\n| **AlgoVoi** | Payment gateway | Live (HTTP 200) · checked 2026-10-30 | The extensions document sets `ap2_version` to `0.1`. AlgoVoi Crypto Payment Method adds multi-chain methods for Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo, and ARC, used as `PaymentMethodData.supported_methods`. AlgoVoi Intent Bounds adds optional max_price and max_quantity fields to `IntentMandate`. The AlgoVoi Payment Agent card says it gates access using x402, MPP (IETF), or AP2. The host OpenAPI document titles the service AlgoVoi Gateway, a public-facing x402 payment gateway. | [AlgoVoi AP2 extensions (fetched 2026-10-30)](https://api.algovoi.co.uk/ap2/extensions) [28] · [AlgoVoi Payment Agent card (fetched 2026-10-30)](https://api.algovoi.co.uk/.well-known/agent-card.json) [29] · [AlgoVoi Gateway OpenAPI (fetched 2026-10-30)](https://api.algovoi.co.uk/openapi.json) [30] |\n| **Universal Commerce Protocol (UCP) AP2 Mandates Extension** | Protocol extension | Supported · as of 2026-08-25 | Businesses declare support by adding `dev.ucp.common.payment.ap2_mandate` to their capabilities list in `/.well-known/ucp`. When that capability is in the intersection, the business MUST include `ap2.merchant_authorization` on checkout responses and MUST NOT accept `complete_checkout` without `ap2.checkout_mandate`. Mandates are SD-JWT credentials; the extension places `checkout_mandate` at `ap2.checkout_mandate` and `payment_mandate` at `payment.instruments[*].credential.token`. Allbirds' `/.well-known/ucp` (version 2026-08-25) lists `dev.ucp.shopping.checkout`, and IKEA's `/.well-known/ucp` (version 2026-04-08, with 2026-08-25 under `supported_versions`) lists `dev.ucp.shopping.checkout` and `dev.ucp.shopping.fulfillment`; neither declares `dev.ucp.common.payment.ap2_mandate`. | [UCP AP2 Mandates Extension (fetched 2026-10-30)](https://ucp.dev/latest/specification/payment/extensions/ap2-mandates/) [20] · [allbirds.com UCP profile (fetched 2026-10-30)](https://www.allbirds.com/.well-known/ucp) [31] · [ikea.com UCP profile (fetched 2026-10-30)](https://www.ikea.com/.well-known/ucp) [32] |\n\n### Buying agents, wallets & client SDKs\n\n| Actor | Role | Status | Supported mandates & SDK surface | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **google-agentic-commerce/AP2 Python package** | Client SDK | Partial · as of 2026-10-30 | The repository defines the protocol's core objects under `code/sdk/python/ap2/`, with Pydantic models and canonical JSON schemas. A PyPI package will be published at a later time; until then the documented install is `uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main`. The FAQ says sample agents were built around the core AP2 python library, that those samples mock actual payment service providers, and that an SDK and a MCP server are still in progress with payment service providers. That FAQ names the Checkout Mandate and the Payment Mandate as verifiable credentials. | [google-agentic-commerce/AP2 (fetched 2026-10-30)](https://github.com/google-agentic-commerce/AP2) [11] · [AP2 FAQ (fetched 2026-10-30)](https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/faq.md) [24] |\n\n### Ecosystem censuses\n\n- **arXiv 2608.23858** (*as of 2026-08-24*): A security analysis submitted on 24 Aug 2026 says no complete public AP2 deployment was available, so the authors built a testbed instead. [19]\n- **allbirds.com and ikea.com UCP profiles** (*as of 2026-10-30*): 0 of 2 UCP business profiles fetched on 2026-10-30 (allbirds.com version 2026-08-25, ikea.com version 2026-04-08) declare dev.ucp.common.payment.ap2_mandate. [20][31][32]\n- **AP2 v0.1.0 docs/partners.md**: The tagged v0.1.0 docs/partners.md snapshot lists 56 named launch-community partners in the AP2 community, from 1Password through manus.ai (including Adyen and PayPal); its introductory line referred to adopting A2A (which AP2 v0.1 extended) for AI agent payments. [33]\n\n---\n\n## See also\n\n- **[Machine Payments Protocol (MPP)](/protocols/mpp/)** *(Complements)* — MPP moves the HTTP request's payment via an Authorization: Payment credential, while AP2 is the SD-JWT Checkout Mandate that records delegated authority and is not the WWW-Authenticate challenge.\n- **[VCAP: Verified Commerce for Agent Protocols](/protocols/vcap/)** *(Complements)* — VCAP binds release and refund to machine-checkable delivery evidence, while AP2 is the SD-JWT Checkout Mandate and does not define those escrow transitions.\n- **[s402](/protocols/s402/)** *(Deprecated; formerly a profile/extension)* — Retired in September 2026 in favor of standard x402; s402 marked its profile with the extensions.s402 key on the x402 v2 402 envelope over Sui transactions rather than AP2 SD-JWT Checkout Mandates.\n- **[EMV® Agentic Payments – Framework for Specifications](/protocols/emv-agentic-payments/)** *(Complements)* — AP2 already specifies an SD-JWT Checkout Mandate and Payment Mandate a merchant can verify, while this EMVCo draft is a framework for future specifications, including possible later changes to 3-D Secure, and has no mandate syntax.\n- **[Agent-Initiated Payment Gating](/protocols/agentic-payments-gating-model/)** *(Complements)* — The draft cites AP2 as the mandate for delegated authority at the gate, while its own text is the task state machine and not the SD-JWT Checkout Mandate.\n- **[Agentic Mobile Protocol (AMP)](/protocols/amp-ant/)** *(Peer alternative)* — AMP assurance data is an SD-JWT across three layers, followed by an Alipay+ CGCP Payment Token longer than 24 bits, while AP2's checkout credential is an SD-JWT verifiable credential for the Checkout Mandate signed on a Trusted Surface.\n- **[KYAPay Token](/protocols/kyapay-token/)** *(Peer alternative)* — KYAPay binds the authorizing party, the agent platform, and a coin or card instrument inside one JWT, while AP2's checkout authorization is an SD-JWT verifiable credential for the Checkout Mandate.\n- **[Agent Commerce Kit (ACK)](/protocols/agent-commerce-kit/)** *(Peer alternative)* — ACK-Pay's published proof of payment is a W3C VC receipt and ACK-ID is the DID identity layer, while AP2's proof of authorization is an SD-JWT Checkout Mandate signed on a Trusted Surface.\n- **[Agent Network Protocol (ANP)](/protocols/anp/)** *(Complements)* — `ANP-10` (`Version: 1.1`, `Status: Draft / not released`) adapts `AP2` `v0.1.0` `CartMandate` and `PaymentMandate` objects (plus `DeliveryReceipt`) signed with `JWT`/`JWS` for `did:wba` agents (`IntentMandate` deferred / not supported; `SD-JWT` listed as an unchecked future roadmap item), rather than `AP2` `v0.2` `Checkout Mandate` and `Payment Mandate` `SD-JWT`s (`mandate.checkout.1` / `mandate.payment.1`).\n- **[Agent Interaction & Transaction Protocol (AITP)](/protocols/aitp/)** *(Peer alternative)* — AITP defines its own quote and payment JSON capability messages in AITP-01: Payments (Spec Status: Ideation, Implementation Status: In Development) and does not reference AP2, whereas AP2 is Google's verifiable-credential mandate protocol.\n- **[Agent-to-Wallet Protocol for Digital Credentials (A2WP)](/protocols/a2wp/)** *(Complements)* — AP2 is the verifiable-credential mandate protocol, while A2WP is the agent-to-wallet hand-off of OpenID4VCI and OpenID4VP requests and leaves transport out of scope.\n- **[Trusted Agent Protocol (TAP)](/protocols/tap/)** *(Complements)* — AP2 carries checkout and payment mandates for a purchase, while TAP authenticates the agent HTTP call to the merchant with the message signature and Visa ID Token.\n- **[ERC-8226 Regulated Agent Mandate](/protocols/erc-8226/)** *(Peer alternative)* — AP2 mandates are off-chain checkout and payment credentials presented to a merchant or network, while an ERC-8226 mandate is an on-chain IAgentMandate record checked inside the token call.\n- **[Agent Attribution Protocol (AAP)](/protocols/agent-attribution-protocol/)** *(Complements)* — AP2 authorizes a payment with checkout and payment mandates, while AAP's Rako-signed AAP Code attributes a recommend() event to a later checkout() conversion.\n- **[Agent Delegation Receipts](/protocols/agent-delegation-receipts/)** *(Complements)* — AP2 payment mandates authorize a checkout, while a delegation receipt is a JWS over JCS JSON, or a COSE_Sign1, that binds the operator-instruction hash before the agent acts.\n- **[Agent Decision Commitments for Payments (ADC)](/protocols/agent-decision-commitment/)** *(Depended on by)* — AP2 is the payment-mandate protocol ADC binds to, and the added claim is decision_context, a salted hash commitment registered with a SCITT transparency service.\n- **[ERC-8196: AI Agent Authenticated Wallet](/protocols/erc-8196/)** *(Complements)* — AP2 authorizes a checkout with payment mandates, and ERC-8196 is the ERC-4337 wallet that executes an agent transaction only when cryptographic proof shows the action matches the registered policy.\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. Stavan Parikh and Rao Surapaneni (Google Cloud), *Announcing Agent Payments Protocol (AP2)* (published 2025-09-16) — \n2. Stavan Parikh (Google), *Google donates Agent Payments Protocol to FIDO Alliance* (published 2026-04-28) — \n3. OpenAI and Stripe, *Agentic Commerce Protocol* (fetched 2026-10-30) — \n4. OpenAI, *Buy it in ChatGPT: Instant Checkout and the Agentic Commerce Protocol* (archived 2026-10-22) — \n5. Visa, *Trusted Agent Protocol* (fetched 2026-10-30) — \n6. x402, *X402 Protocol Specification* (protocol version 2; fetched 2026-10-30) — \n7. Google (google-agentic-commerce), *Agentic Payment Protocol (v0.2)* (fetched 2026-10-30) — \n8. Google (google-agentic-commerce), *Checkout Mandate* (fetched 2026-10-30) — \n9. Google (google-agentic-commerce), *Agent Payments Protocol (AP2)* (fetched 2026-10-30) — \n10. google-agentic-commerce, *Releases · google-agentic-commerce/AP2* (v0.1.0 (2025-09-16); v0.2.0 released 28 Apr) — \n11. google-agentic-commerce, *Agent Payments Protocol (AP2)* (fetched 2026-10-30) — \n12. FIDO Alliance, *FIDO Alliance to Develop Standards for Trusted AI Agent Interactions* (published 2026-04-28; modified 2026-10-19) — \n13. FIDO Alliance, *FIDO Agentic Payment Specifications* (PDF created 2026-09-09) — \n14. Google (google-agentic-commerce), *Agent Authorization* (fetched 2026-10-30) — \n15. Google (google-agentic-commerce), *A2A Extension for AP2 (v0.1)* (tag v0.1.0 (2025-09-16)) — \n16. Google (google-agentic-commerce), *Agentic Payment Protocol (v0.2)* (fetched 2026-10-30) — \n17. Google (google-agentic-commerce), *Agent Payments Protocol (AP2), v0.1.0 specification* (tag v0.1.0 (2025-09-16)) — \n18. D. Fett, K. Yasuda, B. Campbell (IETF), *Selective Disclosure for JSON Web Tokens (RFC 9901)* (2025-11) — \n19. Avital Aviv, Parth A. Gandh, Ron Bitton, and Asaf Shabtai, *Beyond the Mandate: A Systematic Security Analysis of the Agent Payments Protocol (AP2)* (submitted 24 Aug 2026) — \n20. Universal Commerce Protocol, *AP2 Mandates Extension* (example profile version 2026-08-25; fetched 2026-10-30) — \n21. Universal Commerce Protocol, *AP2 Mandates Extension* (specification version 2026-01-11) — \n22. Google (google-agentic-commerce), *AP2, A2A, and MCP* (tag v0.1.0 (2025-09-16)) — \n23. Google (google-agentic-commerce), *AP2 and x402* (tag v0.1.0 (2025-09-16)) — \n24. Google (google-agentic-commerce), *Frequently Asked Questions* (fetched 2026-10-30) — \n25. Verifiable Intent Working Group, *Verifiable Intent specification* (0.1-draft; date 2026-02-18) — \n26. Monocube LLC (SingleFax), *SingleFax A2A agent card* (fetched 2026-10-30) — \n27. SingleFax (Monocube LLC), *SingleFax AP2 payments* (fetched 2026-10-30) — \n28. AlgoVoi, *AlgoVoi AP2 extensions* (fetched 2026-10-30) — \n29. AlgoVoi, *AlgoVoi Payment Agent card* (fetched 2026-10-30) — \n30. AlgoVoi, *AlgoVoi Gateway OpenAPI* (fetched 2026-10-30) — \n31. Allbirds, *UCP business profile (/.well-known/ucp)* (profile version 2026-08-25; fetched 2026-10-30) — \n32. IKEA, *UCP business profile (/.well-known/ucp)* (profile version 2026-04-08; fetched 2026-10-30) — \n33. Google Agentic Commerce, *AP2 partners (v0.1.0 docs/partners.md)* (v0.1.0 tag snapshot; fetched 2026-11-12) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "", "adoption": { "level": "unmeasured", "by": null, "probe_run": null }, "aliases": [], "analog": "Signed purchase order", "collisions": [], "discovery": { "mechanism": "none — see ap2", "path": "none" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/specification.md", "claim": "Google Agentic Commerce, *Agentic Payment Protocol (v0.2) Specification*, v0.2.0; fetched 2026-10-31", "date": null, "quote": "AP2 defines two Mandate types: Checkout Mandate and Payment Mandate. / A Checkout Mandate and Receipt for securing *what* is being purchased. - A linked Payment Mandate and Receipt for the *payment* of the Checkout. / Each AP2 Mandate type identifies its schema using the vct claim. The vct value includes a numeric suffix that acts as a schema version number (e.g. mandate.payment.1, mandate.checkout.open.1). Implementations MUST match the exact vct string, including the version suffix. / Agentic Payment Protocol (v0.2) The Agentic Payment Protocol (AP2) provides a protocol to secure Agent-performed payment transactions. It makes use of the Agent Authorization model. This specification describes the following: The different roles of entities within AP2. The verification responsibilities of these roles. A Checkout Mandate and Receipt for securing what is being purchased. A linked Payment Mandate and Receipt for the payment of the Checkout. / The Agentic Payment Protocol (AP2) provides a protocol to secure Agent-performed / as a schema version number (e.g. `mandate.payment.1`, `mandate.checkout.open.1`). Implementations MUST match the exact `vct` / as a security feature within a Commerce Protocol. The exact details of the Commerce / When communication happens between two non-agentic Roles, standard web security is sufficient to ensure integrity. However, when either role is agentic, then the Agent itself is a potential attacker. As such, additional tamper-evident mechanisms are needed to ensure secure communication. / The Checkout Mandate is designed to provide the Merchant cryptographic proof that the Shopping Agent is authorized to purchase the Checkout that it has assembled. / The Merchant MUST provide a merchant-signed JWT containing the Checkout to the Shopping Agent. The closed Checkout Mandate is bound to this Checkout JWT using a cryptographic hash. / Once the Merchant has accepted or rejected the Checkout Mandate, it MUST return a Checkout Receipt. / AP2 operates as a security feature within a Commerce Protocol. The exact details of the Commerce Protocol (e.g., catalog APIs, checkout updates, and specific APIs for communication between the different roles) are outside the scope of AP2. / Trusted Surface (TS): The Trusted Surface role is a UI surface that is trusted to get informed user consent for an Intent before creating a user-signed Mandate. / Conceptually, it is possible to use this protocol to support delegation of Mandates from one Shopping Agent to another. This is outside the scope of the current specification. / Providing an automated method to retrieve the Checkout Mandate, from either the Shopping Agent or the Merchant, would provide substantial utility to the ecosystem. The exact details are outside the scope of the current version, but would be done by using the Payment Mandate transaction_id as the key to request it. / Agentic Payment Protocol (v0.2) / AP2 specifies the use of SD-JWTs for securing the Payment and Checkout Mandates. ... mandate.payment.1, mandate.checkout.open.1", "ref": 1 }, { "label": "[2]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/checkout_mandate.md", "claim": "Google Agentic Commerce, *AP2 Specification: Checkout Mandate*, v0.2.0; fetched 2026-10-31", "date": null, "quote": "The closed Checkout Mandate ... mandate.checkout.1 / The Checkout Mandate is a Mandate used for authorizing the completion of a checkout. / The Checkout Mandate Content is created by the Shopping Agent, rendered to the User by the Trusted Surface and verified by the Merchant. / The Merchant creates a signed Checkout object which is included in closed Checkout Mandate Content. / A closed Checkout Mandate MUST use the value mandate.checkout.1 for the vct claim and an open Checkout Mandate MUST use the value mandate.checkout.open.1. / \"header\": { \"alg\": \"ES256\", \"typ\": \"kb+sd-jwt\" } / checkout_hash is the base64url-encoded hash of the value of checkout_jwt. The algorithm used MUST be the same as the SD-JWT, as defined by the _sd_alg claim in the base payload, or sha-256 if not present. / checkout_jwt is the merchant-signed JWT containing the details of the checkout. / Versioning for how the version suffix works. ## Mandate Schema The closed Checkout Mandate / }} Examples Open Checkout Mandate SD-JWT plus disclosures json {\"issuer_signed_jwt\":{\"header\":{\"alg\":\"ES256\",\"typ\":\"example+sd-jwt\",\"kid\":\"agent-provider-key-1\" }, \"payload\":{\"delegate_payload\":{\" / conforms to the following schema: {{ schema_fields('checkout_mandate', 'ap2', show_sd=True) }} checkout_hash is the base64url-encoded / with the Universal Commerce Protocol this MUST be the Checkout object. ## Constraints The / The details of the payload are outside the scope of this specification, when used with the Universal Commerce Protocol this MUST be the Checkout object. / mandate.checkout.1 for the vct claim and an open Checkout Mandate MUST use the value mandate.checkout.open.1.", "ref": 2 }, { "label": "[3]", "url": "https://github.com/google-agentic-commerce/AP2/releases/tag/v0.2.0", "claim": "Google Agentic Commerce, *AP2 Release v0.2.0*, released 2026-04-28; fetched 2026-10-31", "date": null, "quote": "This is the second release of AP2. It focuses on providing Human Not Present flows. / Release v0.2.0 · google-agentic-commerce/AP2 · GitHub Skip to content {\"props\":{\"docsUrl\":\"https://docs.github.com/get-started/accessibility/keyboard-shortcuts\"}} {\"props\":{}} / Oct 2026 03:34:22 GMT content-type: text/html; charset=utf-8 vary: X-PJAX, X-PJAX-Container, Turbo-Visit, Turbo-Frame, X-Requested-With, X-GitHub-Client-Version,", "ref": 3 }, { "label": "[4]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/README.md", "claim": "Google Agentic Commerce, *Agent Payments Protocol (AP2) Repository README*, fetched 2026-10-31", "date": null, "quote": "Agent Payments Protocol (AP2) / the package directly using this command: sh uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main connection: close content-length: / Oct 2026 03:39:23 GMT source-age: 0 Agent Payments Protocol (AP2) !Apache License(LICENSE) !Ask DeepWiki(https://deepwiki.com/google-agentic-commerce/AP2)", "ref": 4 }, { "label": "[5]", "url": "https://github.com/google-agentic-commerce/AP2", "claim": "Google Agentic Commerce, *GitHub API repository metadata for google-agentic-commerce/AP2*, created 2025-05-30; fetched 2026-10-31", "date": null, "quote": "\"created_at\": \"2025-05-30T19:37:20Z\" / \"full_name\": \"google-agentic-commerce/AP2\", / \"https://api.github.com/users/google-agentic-commerce/received_events\", \"type\": \"Organization\", \"user_view_type\": \"public\", \"site_admin\": false }, \"html_url\": \"https://github.com/google-agentic-commerce/AP2\", / \"name\": \"Apache License 2.0\", \"spdx_id\": \"Apache-2.0\"", "ref": 5 }, { "label": "[6]", "url": "https://fidoalliance.org/fido-alliance-to-develop-standards-for-trusted-ai-agent-interactions/", "claim": "FIDO Alliance, *FIDO Alliance to Develop Standards for Trusted AI Agent Interactions*, published 2026-04-28; modified 2026-10-19", "date": null, "quote": "Google has contributed its Agent Payments Protocol (AP2), which introduces a model for secure delegation, verifiable authorization and trusted transaction execution. / the FIDO Alliance is developing specifications for agent-initiated commerce within its Payments Technical Working Group, chaired by members from Mastercard and Visa.", "ref": 6 }, { "label": "[7]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/index.md", "claim": "Google Agentic Commerce, *Agent Payments Protocol (AP2) Documentation Index*, fetched 2026-10-30", "date": null, "quote": "Standardization of the specification will continue within the Agentic Authentication Technical and Payments Technical Working Groups in FIDO.", "ref": 7 }, { "label": "[8]", "url": "https://www.rfc-editor.org/rfc/rfc9901.html", "claim": "IETF, *RFC 9901: Selective Disclosure for JSON Web Tokens*, IETF RFC", "date": null, "quote": "This specification defines a mechanism for the selective disclosure of individual elements of a JSON data structure used as the payload of a JSON Web Signature (JWS).", "ref": 8 }, { "label": "[9]", "url": "https://ucp.dev/documentation/announcements/", "claim": "Universal Commerce Protocol, *Announcements*, fetched 2026-10-30", "date": null, "quote": "August 25, 2026: Protocol Release v2026-08-25", "ref": 9 }, { "label": "[10]", "url": "https://verifiableintent.dev/spec/", "claim": "Verifiable Intent Working Group, *Verifiable Intent (VI) — Specification Overview (v0.1-draft)*, 2026-02-18 (v0.1-draft); fetched 2026-10-31", "date": null, "quote": "Overview¶ Version: 0.1-draft Status: Draft Date: 2026-02-18 Authors: Verifiable Intent Working Group Abstract¶ Verifiable", "ref": 10 }, { "label": "[11]", "url": "https://developer.visa.com/docs/trusted-agent-protocol/trusted-agent-protocol-specifications", "claim": "Visa, *Trusted Agent Protocol specifications*, checked 2026-10-30", "date": null, "quote": "By accessing, downloading, or using this specification, you agree to the terms and conditions outlined in the Visa Trusted Agent Protocol Product Terms.", "ref": 11 }, { "label": "[12]", "url": "https://www.emvco.com/resources/emv-agentic-payments-framework-for-specifications-v1-0-draft-comment-period-ends-30-sept-2026/", "claim": "EMVCo, *EMV Agentic Payments - Framework for Specifications v1.0 DRAFT: Comment period ends 30-Sept 2026*, published 2026-08-30; modified 2026-08-31", "date": null, "quote": "Comment period ends 30-Sept 2026", "ref": 12 }, { "label": "[13]", "url": "https://raw.githubusercontent.com/agent-network-protocol/AgentNetworkProtocol/main/application/10-anp-agent-payment-protocol-specification.md", "claim": "Agent Network Protocol, *ANP-10: Agent Payment Protocol Specification (v1.1 Draft)*, checked 2026-10-30", "date": null, "quote": "Document ID: ANP-10 - Title: ANP Agent Payment Protocol Specification - Status: Draft / not released - Version: 1.1 / Original AP2 Protocol: An open protocol released by Google in September 2025 ... CartMandate, PaymentMandate, and DeliveryReceipt 3. Using JWT/JWS standard for authorization signatures ... did:wba for agent identity authentication ... IntentMandate | Supports pre-authorized autonomous agent shopping | Not supported (planned) ... - [ ] Support SD-JWT", "ref": 13 } ], "form": "document-format", "governance": "Contributed by Google to the FIDO Alliance on 2026-04-28, with standardization continuing in FIDO's Agentic Authentication Technical and Payments Technical Working Groups while `google-agentic-commerce/AP2` hosts the public specification and SDK.", "group": null, "history": [ { "date": "2026-09-06", "note": "verified: confirmed this is a component of ap2's specification.md, not a distinct protocol; set phase=withdrawn and merged content into ap2" }, { "date": "2026-10-16", "note": "version v0.2.0" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "ap2-checkout-mandate", "implementation": "none-found", "last_verified": "2026-11-12", "name": "AP2 Checkout Mandate", "native_status": "Active component (AP2 v0.2.0); supersedes v0.1 CartMandate (not an independently published protocol)", "origin": { "date": null, "org": "Google AP2" }, "part_of": "ap2", "parties": [ "agent-site" ], "phase": "candidate", "probe": { "method": "none", "on_absent": "Not applicable — AP2 CheckoutMandate (mandate.checkout.1) travels in-band as a kb+sd-jwt Verifiable Credential inside a commerce protocol checkout flow rather than an origin-exposed HTTP endpoint.", "parse": "not applicable — in-band mandate credential, see ap2", "path": "none" }, "question": "What exactly did the user approve for checkout?", "scope": "payments", "spec_url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/checkout_mandate.md", "step": "pay", "summary_md": "**AP2 Checkout Mandate** is the Mandate defined in the **Agentic Payment Protocol** (`AP2`, also titled **Agent Payments Protocol** in the parent repository) specification for authorizing the completion of a checkout and securing what is being purchased, paired with a linked Payment Mandate and Checkout Receipt. The Checkout Mandate Content is created by the Shopping Agent, rendered to the User by the Trusted Surface, and verified by the Merchant, while the Merchant creates a signed Checkout object that is included in closed Checkout Mandate Content. Secured as an SD-JWT (`typ` `kb+sd-jwt`, `alg` `ES256`), a closed Checkout Mandate MUST use `mandate.checkout.1` for the `vct` claim and an open Checkout Mandate MUST use `mandate.checkout.open.1`. In a closed Checkout Mandate, `checkout_jwt` is the merchant-signed JWT containing the details of the checkout, and `checkout_hash` is the base64url-encoded hash of `checkout_jwt` computed with the algorithm in the `_sd_alg` claim or `sha-256` if not present. Each AP2 Mandate type identifies its schema using a numeric version suffix on the `vct` claim, and implementations MUST match the exact `vct` string including the version suffix. The `google-agentic-commerce/AP2` repository was created on 2025-05-30 under the `Apache-2.0` license, and release `v0.2.0` on 2026-04-28 (`Agentic Payment Protocol (v0.2)`) is the second release of AP2 focusing on Human Not Present flows and centering the protocol on the linked `Checkout Mandate` and `Payment Mandate` pair.", "track": "industry-body", "version": { "label": "v0.2.0", "date": "2026-04-28" }, "watch": [ { "type": "github", "repo": "google-agentic-commerce/AP2", "mode": "release" } ], "use_cases": [ "agent-checkout", "delegate-user-authority", "audit-agent-actions" ], "audience": [ "agent-builder", "platform" ], "pairs_with": [ "ap2", "ucp", "vi", "tap", "emv-agentic-payments" ], "prerequisites": [ "ap2" ], "hatnote_md": "This page covers the AP2 Checkout Mandate (`mandate.checkout.1` and `mandate.checkout.open.1`), the active checkout-authorization component introduced in [Agent Payments Protocol (AP2)](/protocols/ap2/) `v0.2.0` (`2026-04-28`) to replace v0.1's `CartMandate`. For the full four-party protocol and the companion `PaymentMandate` (`mandate.payment.1`), see [Agent Payments Protocol (AP2)](/protocols/ap2/).", "tier": "spec_brief", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This page covers the AP2 Checkout Mandate (`mandate.checkout.1` and `mandate.checkout.open.1`), the active checkout-authorization component introduced in [Agent Payments Protocol (AP2)](/protocols/ap2/) `v0.2.0` (`2026-04-28`) to replace v0.1's `CartMandate`. For the full four-party protocol and the companion `PaymentMandate` (`mandate.payment.1`), see [Agent Payments Protocol (AP2)](/protocols/ap2/). [1][2][3]", "v05_elevator_pitch_md": null, "v05_lead_md": "**AP2 Checkout Mandate** is the Mandate defined in the **Agentic Payment Protocol** (`AP2`, also titled **Agent Payments Protocol** in the parent repository) specification for authorizing the completion of a checkout and securing what is being purchased, paired with a linked Payment Mandate and Checkout Receipt. [1][2][4] The Checkout Mandate Content is created by the Shopping Agent, rendered to the User by the Trusted Surface, and verified by the Merchant, while the Merchant creates a signed Checkout object that is included in closed Checkout Mandate Content. [2] Secured as an SD-JWT (`typ` `kb+sd-jwt`, `alg` `ES256`), a closed Checkout Mandate MUST use `mandate.checkout.1` for the `vct` claim and an open Checkout Mandate MUST use `mandate.checkout.open.1`. [2] In a closed Checkout Mandate, `checkout_jwt` is the merchant-signed JWT containing the details of the checkout, and `checkout_hash` is the base64url-encoded hash of `checkout_jwt` computed with the algorithm in the `_sd_alg` claim or `sha-256` if not present. [2] Each AP2 Mandate type identifies its schema using a numeric version suffix on the `vct` claim, and implementations MUST match the exact `vct` string including the version suffix. [1] The `google-agentic-commerce/AP2` repository was created on 2025-05-30 under the `Apache-2.0` license, and release `v0.2.0` on 2026-04-28 (`Agentic Payment Protocol (v0.2)`) is the second release of AP2 focusing on Human Not Present flows and centering the protocol on the linked `Checkout Mandate` and `Payment Mandate` pair. [1][3][5]", "v05_identity_sentence_md": "**AP2 Checkout Mandate** is the Mandate defined in the **Agentic Payment Protocol** (`AP2`, also titled **Agent Payments Protocol** in the parent repository) specification for authorizing the completion of a checkout and securing what is being purchased, paired with a linked Payment Mandate and Checkout Receipt. [1][2][4] The Checkout Mandate Content is created by the Shopping Agent, rendered to the User by the Trusted Surface, and verified by the Merchant, while the Merchant creates a signed Checkout object that is included in closed Checkout Mandate Content. [2]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "Document format (`document-format`)" }, { "label": "Originated by", "value_md": "Google (`google-agentic-commerce/AP2`) [4][5]" }, { "label": "Governed by", "value_md": "FIDO Alliance (Agentic Authentication and Payments Technical Working Groups, following Google's `2026-04-28` AP2 contribution); public specification and SDK hosted in `google-agentic-commerce/AP2` [1][4][5][6][7]" }, { "label": "Track", "value_md": "Industry consortium specification (FIDO Alliance Agentic Authentication and Payments Technical Working Groups) [6][7]" }, { "label": "Status", "value_md": "Active component (`AP2 v0.2.0`, released `2026-04-28`); supersedes v0.1 `CartMandate` (not an independently published protocol) [1][2][3]" }, { "label": "Version", "value_md": "AP2 `v0.2.0` (released 2026-04-28); schema version `vct` `mandate.checkout.1` (closed) and `mandate.checkout.open.1` (open) [1][2][3]" }, { "label": "Wire format", "value_md": "Selective Disclosure JSON Web Token (`SD-JWT`, `ES256`, `_sd_alg: sha-256`) wrapping a merchant-signed `checkout_jwt` or open constraint disclosures [2]" }, { "label": "Specification", "value_md": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/checkout_mandate.md [2]" }, { "label": "Found at", "value_md": "Embedded within Commerce Protocol flows (such as Universal Commerce Protocol `Checkout` objects) and identified on the wire by the `vct` claim [1][2]" }, { "label": "Licence", "value_md": "Apache License 2.0 (`Apache-2.0`) [5]" } ], "v05_problem_md": "When communication happens between two non-agentic roles, standard web security is sufficient to ensure integrity, but when either role is handled by a non-deterministic LLM, the agent itself is a potential attacker and additional tamper-evident mechanisms are needed. [1] The Checkout Mandate provides the Merchant cryptographic proof that the Shopping Agent is authorized to purchase the Checkout it has assembled, binding the closed Checkout Mandate to the merchant-signed Checkout JWT using a cryptographic hash. [1] Once the Merchant has accepted or rejected the Checkout Mandate, it MUST return a Checkout Receipt. [1] AP2 operates as a security feature within a Commerce Protocol (`checkout_jwt` MUST be the Checkout object when used with `UCP`), and because the Shopping Agent creates `Checkout Mandate Content` before rendering, the Trusted Surface UI role is required to obtain informed user consent before creating a user-signed Mandate. [1][2] Delegation of Mandates from one Shopping Agent to another and automated retrieval of a Checkout Mandate using the Payment Mandate `transaction_id` are outside the scope of the current version. [1]", "v05_mechanism_delta_md": "The Checkout Mandate provides the Merchant cryptographic proof that the Shopping Agent is authorized to purchase the Checkout it has assembled, binding the closed Checkout Mandate to the merchant-signed Checkout JWT using a cryptographic hash. [1] Once the Merchant has accepted or rejected the Checkout Mandate, it MUST return a Checkout Receipt. [1]", "v05_scope_boundary_md": "AP2 operates as a security feature within a Commerce Protocol (`checkout_jwt` MUST be the Checkout object when used with `UCP`), and because the Shopping Agent creates `Checkout Mandate Content` before rendering, the Trusted Surface UI role is required to obtain informed user consent before creating a user-signed Mandate. [1][2] Delegation of Mandates from one Shopping Agent to another and automated retrieval of a Checkout Mandate using the Payment Mandate `transaction_id` are outside the scope of the current version. [1]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "Selective Disclosure for JWTs (SD-JWT, RFC 9901)", "spec_or_rfc": "RFC 9901", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "The Checkout Mandate is the AP2 v0.2 SD-JWT verifiable credential defined in docs/ap2/checkout_mandate.md, paired with a Checkout Receipt, and this record has no separate endpoint or well-known file. [2][8]" } ], "agentic_peers": [ { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "part_of", "relation_label": "Part of", "delta_md": "The checkout mandate is the topic page docs/ap2/checkout_mandate.md inside the AP2 v0.2 specification, defining the Checkout Mandate object and its Checkout Receipt, and it has no separate endpoint or well-known file. [1][2]" }, { "target_id": "ucp", "target_name": "Universal Commerce Protocol (UCP)", "relation_type": "builds_on", "relation_label": "Builds on", "delta_md": "The Checkout Mandate is one of the two AP2 v0.2 mandates, and AP2 v0.2 is built to work inside UCP, so the mandate rides on UCP's /.well-known/ucp profile and optional AP2 Mandates extension rather than defining its own transport. [2][9]" }, { "target_id": "vi", "target_name": "Verifiable Intent", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Verifiable Intent is a separate Mastercard credential that FIDO plans to consolidate with AP2 in 2027, while this object is the AP2 Checkout Mandate and its Checkout Receipt. [2][10]" }, { "target_id": "tap", "target_name": "Trusted Agent Protocol (TAP)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "TAP checks an agent by a signature on the merchant request, while the checkout mandate is the user-signed Checkout Mandate, produced on a Trusted Surface, over one merchant checkout. [2][11]" }, { "target_id": "emv-agentic-payments", "target_name": "EMV® Agentic Payments – Framework for Specifications", "relation_type": "complements", "relation_label": "Complements", "delta_md": "The EMV Agentic Payments draft proposes Intent Services and defines no message syntax, while the checkout mandate is the concrete Checkout Mandate object and Checkout Receipt inside AP2. [2][12]" } ] }, "v05_adoption": { "visible": false, "empty_state_note_md": null, "scope_note_md": null, "side_a": null, "side_b": null, "additional_tables": null, "censuses": [], "footer_md": null }, "v05_see_also": [ { "target_id": "agent-decision-commitment", "target_name": "Agent Decision Commitments for Payments", "relation_label": "Complements", "delta": "The checkout mandate authorizes the cart, and decision_context is an additional selectively disclosable claim, registered with SCITT, about the model inputs behind that cart. [2]", "item_md": "**[Agent Decision Commitments for Payments](/protocols/agent-decision-commitment/)** (Complements) — The checkout mandate authorizes the cart, and decision_context is an additional selectively disclosable claim, registered with SCITT, about the model inputs behind that cart. [2]" }, { "target_id": "anp", "target_name": "Agent Network Protocol", "relation_label": "Complements", "delta": "`ANP-10` (`Version: 1.1`, `Status: Draft / not released`) adapts `AP2` `v0.1` `CartMandate` and `PaymentMandate` objects (plus `DeliveryReceipt`) signed with `JWT`/`JWS` for `did:wba` agents (`IntentMandate` not supported / planned; `SD-JWT` listed as an unchecked future roadmap item), rather than binding to this `AP2` `v0.2` `mandate.checkout.1` / `mandate.checkout.open.1` `SD-JWT` schema. [1][2][13]", "item_md": "**[Agent Network Protocol](/protocols/anp/)** (Complements) — `ANP-10` (`Version: 1.1`, `Status: Draft / not released`) adapts `AP2` `v0.1` `CartMandate` and `PaymentMandate` objects (plus `DeliveryReceipt`) signed with `JWT`/`JWS` for `did:wba` agents (`IntentMandate` not supported / planned; `SD-JWT` listed as an unchecked future roadmap item), rather than binding to this `AP2` `v0.2` `mandate.checkout.1` / `mandate.checkout.open.1` `SD-JWT` schema. [1][2][13]" }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: ap2-checkout-mandate\ntitle: \"AP2 Checkout Mandate\"\ntier: spec_brief\nlifecycle_status: active\ncategory: pay\nform: document-format\nwire_archetype: payments_onchain\nspec_url: https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/checkout_mandate.md\nlast_checked: 2026-11-12\n---\n\n# AP2 Checkout Mandate\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** Document format (`document-format`) · **Last checked:** 2026-11-12\n\n> *This page covers the AP2 Checkout Mandate (`mandate.checkout.1` and `mandate.checkout.open.1`), the active checkout-authorization component introduced in [Agent Payments Protocol (AP2)](/protocols/ap2/) `v0.2.0` (`2026-04-28`) to replace v0.1's `CartMandate`. For the full four-party protocol and the companion `PaymentMandate` (`mandate.payment.1`), see [Agent Payments Protocol (AP2)](/protocols/ap2/). [1][2][3]*\n\n**AP2 Checkout Mandate** is the Mandate defined in the **Agentic Payment Protocol** (`AP2`, also titled **Agent Payments Protocol** in the parent repository) specification for authorizing the completion of a checkout and securing what is being purchased, paired with a linked Payment Mandate and Checkout Receipt. [1][2][4] The Checkout Mandate Content is created by the Shopping Agent, rendered to the User by the Trusted Surface, and verified by the Merchant, while the Merchant creates a signed Checkout object that is included in closed Checkout Mandate Content. [2] Secured as an SD-JWT (`typ` `kb+sd-jwt`, `alg` `ES256`), a closed Checkout Mandate MUST use `mandate.checkout.1` for the `vct` claim and an open Checkout Mandate MUST use `mandate.checkout.open.1`. [2] In a closed Checkout Mandate, `checkout_jwt` is the merchant-signed JWT containing the details of the checkout, and `checkout_hash` is the base64url-encoded hash of `checkout_jwt` computed with the algorithm in the `_sd_alg` claim or `sha-256` if not present. [2] Each AP2 Mandate type identifies its schema using a numeric version suffix on the `vct` claim, and implementations MUST match the exact `vct` string including the version suffix. [1] The `google-agentic-commerce/AP2` repository was created on 2025-05-30 under the `Apache-2.0` license, and release `v0.2.0` on 2026-04-28 (`Agentic Payment Protocol (v0.2)`) is the second release of AP2 focusing on Human Not Present flows and centering the protocol on the linked `Checkout Mandate` and `Payment Mandate` pair. [1][3][5]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | Document format (`document-format`) |\n| **Originated by** | Google (`google-agentic-commerce/AP2`) [4][5] |\n| **Governed by** | FIDO Alliance (Agentic Authentication and Payments Technical Working Groups, following Google's `2026-04-28` AP2 contribution); public specification and SDK hosted in `google-agentic-commerce/AP2` [1][4][5][6][7] |\n| **Track** | Industry consortium specification (FIDO Alliance Agentic Authentication and Payments Technical Working Groups) [6][7] |\n| **Status** | Active component (`AP2 v0.2.0`, released `2026-04-28`); supersedes v0.1 `CartMandate` (not an independently published protocol) [1][2][3] |\n| **Version** | AP2 `v0.2.0` (released 2026-04-28); schema version `vct` `mandate.checkout.1` (closed) and `mandate.checkout.open.1` (open) [1][2][3] |\n| **Wire format** | Selective Disclosure JSON Web Token (`SD-JWT`, `ES256`, `_sd_alg: sha-256`) wrapping a merchant-signed `checkout_jwt` or open constraint disclosures [2] |\n| **Specification** | https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/checkout_mandate.md [2] |\n| **Found at** | Embedded within Commerce Protocol flows (such as Universal Commerce Protocol `Checkout` objects) and identified on the wire by the `vct` claim [1][2] |\n| **Licence** | Apache License 2.0 (`Apache-2.0`) [5] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [See also](#see-also)\n4. [References](#references)\n\n---\n\n## Problem and scope\n\nWhen communication happens between two non-agentic roles, standard web security is sufficient to ensure integrity, but when either role is handled by a non-deterministic LLM, the agent itself is a potential attacker and additional tamper-evident mechanisms are needed. [1] The Checkout Mandate provides the Merchant cryptographic proof that the Shopping Agent is authorized to purchase the Checkout it has assembled, binding the closed Checkout Mandate to the merchant-signed Checkout JWT using a cryptographic hash. [1] Once the Merchant has accepted or rejected the Checkout Mandate, it MUST return a Checkout Receipt. [1] AP2 operates as a security feature within a Commerce Protocol (`checkout_jwt` MUST be the Checkout object when used with `UCP`), and because the Shopping Agent creates `Checkout Mandate Content` before rendering, the Trusted Surface UI role is required to obtain informed user consent before creating a user-signed Mandate. [1][2] Delegation of Mandates from one Shopping Agent to another and automated retrieval of a Checkout Mandate using the Payment Mandate `transaction_id` are outside the scope of the current version. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Selective Disclosure for JWTs (SD-JWT, RFC 9901)** | `RFC 9901` | Profiles classic standard | The Checkout Mandate is the AP2 v0.2 SD-JWT verifiable credential defined in docs/ap2/checkout_mandate.md, paired with a Checkout Receipt, and this record has no separate endpoint or well-known file. [2][8] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Part of | The checkout mandate is the topic page docs/ap2/checkout_mandate.md inside the AP2 v0.2 specification, defining the Checkout Mandate object and its Checkout Receipt, and it has no separate endpoint or well-known file. [1][2] |\n| **[Universal Commerce Protocol (UCP)](/protocols/ucp/)** | Builds on | The Checkout Mandate is one of the two AP2 v0.2 mandates, and AP2 v0.2 is built to work inside UCP, so the mandate rides on UCP's /.well-known/ucp profile and optional AP2 Mandates extension rather than defining its own transport. [2][9] |\n| **[Verifiable Intent](/protocols/vi/)** | Peer alternative | Verifiable Intent is a separate Mastercard credential that FIDO plans to consolidate with AP2 in 2027, while this object is the AP2 Checkout Mandate and its Checkout Receipt. [2][10] |\n| **[Trusted Agent Protocol (TAP)](/protocols/tap/)** | Complements | TAP checks an agent by a signature on the merchant request, while the checkout mandate is the user-signed Checkout Mandate, produced on a Trusted Surface, over one merchant checkout. [2][11] |\n| **[EMV® Agentic Payments – Framework for Specifications](/protocols/emv-agentic-payments/)** | Complements | The EMV Agentic Payments draft proposes Intent Services and defines no message syntax, while the checkout mandate is the concrete Checkout Mandate object and Checkout Receipt inside AP2. [2][12] |\n\n---\n\n## See also\n\n- **[Agent Decision Commitments for Payments](/protocols/agent-decision-commitment/)** *(Complements)* — The checkout mandate authorizes the cart, and decision_context is an additional selectively disclosable claim, registered with SCITT, about the model inputs behind that cart. [2]\n- **[Agent Network Protocol](/protocols/anp/)** *(Complements)* — `ANP-10` (`Version: 1.1`, `Status: Draft / not released`) adapts `AP2` `v0.1` `CartMandate` and `PaymentMandate` objects (plus `DeliveryReceipt`) signed with `JWT`/`JWS` for `did:wba` agents (`IntentMandate` not supported / planned; `SD-JWT` listed as an unchecked future roadmap item), rather than binding to this `AP2` `v0.2` `mandate.checkout.1` / `mandate.checkout.open.1` `SD-JWT` schema. [1][2][13]\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. Google Agentic Commerce, *Agentic Payment Protocol (v0.2) Specification* (v0.2.0; fetched 2026-10-31) — \n2. Google Agentic Commerce, *AP2 Specification: Checkout Mandate* (v0.2.0; fetched 2026-10-31) — \n3. Google Agentic Commerce, *AP2 Release v0.2.0* (released 2026-04-28; fetched 2026-10-31) — \n4. Google Agentic Commerce, *Agent Payments Protocol (AP2) Repository README* (fetched 2026-10-31) — \n5. Google Agentic Commerce, *GitHub API repository metadata for google-agentic-commerce/AP2* (created 2025-05-30; fetched 2026-10-31) — \n6. FIDO Alliance, *FIDO Alliance to Develop Standards for Trusted AI Agent Interactions* (published 2026-04-28; modified 2026-10-19) — \n7. Google Agentic Commerce, *Agent Payments Protocol (AP2) Documentation Index* (fetched 2026-10-30) — \n8. IETF, *RFC 9901: Selective Disclosure for JSON Web Tokens* (IETF RFC) — \n9. Universal Commerce Protocol, *Announcements* (fetched 2026-10-30) — \n10. Verifiable Intent Working Group, *Verifiable Intent (VI) — Specification Overview (v0.1-draft)* (2026-02-18 (v0.1-draft); fetched 2026-10-31) — \n11. Visa, *Trusted Agent Protocol specifications* (checked 2026-10-30) — \n12. EMVCo, *EMV Agentic Payments - Framework for Specifications v1.0 DRAFT: Comment period ends 30-Sept 2026* (published 2026-08-30; modified 2026-08-31) — \n13. Agent Network Protocol, *ANP-10: Agent Payment Protocol Specification (v1.1 Draft)* (checked 2026-10-30) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "x402", "adoption": { "level": "observed", "by": "CoinGecko, CoinMarketCap, Bitrefill, AWS (Amazon Bedrock AgentCore payments), Cloudflare Agents SDK, Vercel x402-mcp, Coinbase CDP Facilitator, Stripe, and 5 other verified implementations", "probe_run": null }, "aliases": [ "x402 Protocol", "x402 Payment Protocol" ], "analog": "HTTP 402 Payment Required, finally implemented", "collisions": [], "discovery": { "mechanism": "HTTP 402 response carrying payment requirements in a header", "path": "No fixed path: a resource signals x402 per request by answering HTTP 402. Discovery is through the Bazaar, a /discovery/resources listing that facilitators may offer; Coinbase's is public at https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources (checked 2026-10-28)" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://www.rfc-editor.org/rfc/rfc9110.html", "claim": "R. Fielding, M. Nottingham, and J. Reschke (eds.), *RFC 9110: HTTP Semantics*, June 2022", "date": null, "quote": "15.5.3. 402 Payment Required The 402 (Payment Required) status code is reserved for future use.", "ref": 1 }, { "label": "[2]", "url": "https://docs.lightning.engineering/the-lightning-network/l402/protocol-specification", "claim": "Lightning Labs, *L402 Protocol Specification*, fetched 2026-10-30", "date": null, "quote": "Alongside the 402 status code, the server should specify the WWW-Authenticate header ([RFC 7235], Section 4.1) field to indicate the L402 authentication scheme and the macaroon needed for the client to form a complete L402.", "ref": 2 }, { "label": "[3]", "url": "https://docs.stripe.com/payments/machine/x402", "claim": "Stripe, *x402*, fetched 2026-10-30", "date": null, "quote": "To accept card payments alongside stablecoin payments, you should also integrate with the Machine Payments Protocol (MPP) . / When a client requests a paid resource, your server returns an HTTP 402 response with payment details, including a Stripe deposit address. The client pays, then retries the request with authorization. After the facilitator settles the payment on-chain, Stripe records it as a PaymentIntent . / curl https://api.stripe.com/v1/crypto/deposit_addresses / Stripe-Version: 2026-05-27.preview / scheme : \"exact\" , price : \"$0.01\" , network : \"eip155:8453\" / mode : \"transaction_verification\" / Stablecoin payments are available to businesses in all US states, except New York. … Go to your Payment methods settings in the Dashboard and request the Stablecoins and Crypto payment method.", "ref": 3 }, { "label": "[4]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "claim": "x402 Foundation, *x402 Protocol Specification*, v2.0 dated 2025-12-9", "date": null, "quote": "x402 is an open payment standard that enables clients to pay for external resources. / Resource Server: A service that requires payment for access to protected resources (APIs, content, data, etc.) / Client: Any application or agent that requests access to protected resources / PaymentRequirements, PaymentPayload, SettlementResponse / which depends on the transport mechanism (e.g., HTTP, MCP, A2A) / Blockchain network identifier in CAIP-2 format / Required payment amount in atomic token units / Token contract address or ISO 4217 currency code for fiat / v2.0 | 2025-12-9 | Protocol v2: CAIP-2 networks, restructured PaymentPayload/Required, ResourceInfo separation, extensions support / paymentFlow / auth-capture / exact, upto, and batch-settlement; see specs/schemes/ / batch-settlement, and auth-capture / authorization (default) | verify → resource → settle → respond / upfront | settle → resource → respond / escrow | settle → resource → settle → respond / For HTTP, the canonical wire location is the base64-encoded PAYMENT-REQUIRED response header / X402 Protocol Specification Protocol Version: 2 / POST /verify / POST /settle / GET /supported / Each PaymentRequirements object in the accepts array contains / scheme | string | Required | Payment scheme identifier / The `accepted` field contains a `PaymentRequirements` object / The `payload` field contains scheme-specific data. / it validates payment state but MUST NOT commit payment state or write onchain state. / Durably commits payment state for the request / delegate blockchain operations to trusted third parties or host the endpoints themselves. / including `exact`, `upto`, `batch-settlement`, and `auth-capture` / Out of Scope: This specification does not include: - Transport-specific implementations (covered in transport specifications) - Specific implementation patterns (covered in application notes) - Framework-specific integrations - Client-side budget management - Session handling mechanisms / GET /discovery/resources / List discoverable x402 resources from the Bazaar. / though the discovered resources may use any x402-supported transport. / 1. **Client Request**: Client makes a request to a resource server / 2. **Payment Required Response**: If no valid payment is attached, the server responds with a payment required signal and payment requirements / 3. **Payment Authorization Request**: Client submits a signed payment authorization in the subsequent request / 4. **Settlement Response**: Server verifies the payment authorization and initiates blockchain settlement / This cycle describes the default `authorization` payment flow, in which the payment is verified before the resource executes and settled afterward. / The resolved flow determines which of the facilitator's read-only `/verify` (section 7.1) and state-committing `/settle` (section 7.2) run, and in what order, around the resource server's execution of the protected request. / | `authorization` (default) | verify → resource → settle → respond | Read-only verify before the resource executes; funds move only after it completes successfully. | / This allows resource servers to delegate blockchain operations to trusted third parties or host the endpoints themselves. / /verify is read-only: it validates payment state but must not commit payment state or write onchain state. / | upfront | settle → resource → respond | Payment is durably committed before the resource executes, giving the server finality first. / These are completely independent of both transport mechanism and payment scheme. / When a resource server requires payment, it responds with a payment required signal containing the `PaymentRequired` object. / How to construct the `payload` field within `PaymentPayload` / Schemes are independent of the underlying transport mechanism. / for example `eip3009` vs `permit2` / `authorization` (default) | verify → resource → settle → respond / extra.paymentFlow / EIP-712 signature for authorization / EIP-3009 authorization parameters / 32-byte random nonce to prevent replay attacks / `validAfter` | `string` | Required | Unix timestamp when authorization becomes valid / `validBefore` | `string` | Required | Unix timestamp when authorization expires / in the `upto` scheme, the `amount` field in `paymentRequirements` represents the maximum authorized amount at verification time, but the actual amount to settle at settlement time. / The settlement transaction was broadcast but its confirmation could not be established / MUST be non-empty when `errorReason` is `settlement_pending` / signature | string | Required | EIP-712 signature for authorization / authorization | object | Required | EIP-3009 authorization parameters", "ref": 4 }, { "label": "[5]", "url": "https://blog.cloudflare.com/x402/", "claim": "Will Allen, Cam Whiteside, Rohin Lohe, and Steve James, Cloudflare, *Launching the x402 Foundation with Coinbase, and support for x402 transactions*, September 23, 2025", "date": null, "quote": "Clients and servers capable of interpreting the x402 protocol are able to transact without the need for accounts, subscriptions, or API keys. / September 23, 2025 / Cloudflare is partnering with Coinbase to create the x402 Foundation. / Without a specification for how to format and respond to those response codes, content creators, publishers, and website operators lack adequate tools to convey their payment requests. / we are shipping a set of features to allow developers to use x402 in the Agents SDK and our MCP integrations, as well as proposing a new deferred payment scheme.", "ref": 5 }, { "label": "[6]", "url": "https://vercel.com/blog/introducing-x402-mcp-open-protocol-payments-for-mcp-tools", "claim": "Ethan Niser, Vercel, *Introducing x402-mcp: Open protocol payments for MCP tools*, 12 Sep 2025", "date": null, "quote": "The current model requires pre-registering with every API, managing keys, and maintaining separate billing relationships. / We built x402-mcp to integrate x402 payments with Model Context Protocol (MCP) servers and the Vercel AI SDK. / import { paymentMiddleware } from \"x402-next\" / import { wrapFetchWithPayment } from \"x402-fetch\"", "ref": 6 }, { "label": "[7]", "url": "https://www.coinbase.com/developer-platform/discover/launches/x402", "claim": "Erik Reppel, Nemil Dalal, and Dan Kim, Coinbase, *Introducing x402: a new standard for internet-native payments*, May 6, 2025", "date": null, "quote": "May 6, 2025 / Coinbase is launching x402, a payment protocol that enables instant stablecoin payments directly over HTTP. / Introducing x402: a new standard for internet-native payments May 6, 2025 By: Erik Reppel, Nemil Dalal, Dan Kim", "ref": 7 }, { "label": "[8]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/transports-v1/http.md", "claim": "x402 Foundation, *HTTP transport for x402 v1*, fetched 2026-10-30", "date": null, "quote": "HTTP 402 status code with JSON response body / Servers communicate payment settlement results using the `X-PAYMENT-RESPONSE` header. / Clients send payment data using the `X-PAYMENT` HTTP header. / Clients send payment data using the X-PAYMENT HTTP header. / Servers communicate payment settlement results using the X-PAYMENT-RESPONSE header. / **Data Format**: `PaymentRequirementsResponse` schema in response body / \"maxAmountRequired\": \"10000\" / \"network\": \"base-sepolia\"", "ref": 8 }, { "label": "[9]", "url": "https://x402.org/x402-v2-launch/", "claim": "Erik Reppel, Carson Roscoe, and Josh Nickerson, *Introducing x402 V2: Evolving the Standard for Internet-native Payments*, published December 11, 2025; updated June 24th, 2026", "date": null, "quote": "Moving all payment data to headers for the HTTP transport, freeing up response body to be used alongside a 402 status code and Payment Required header / December 11, 2025", "ref": 9 }, { "label": "[10]", "url": "https://www.linuxfoundation.org/press/linux-foundation-is-launching-the-x402-foundation-and-welcoming-the-contribution-of-the-x402-protocol", "claim": "Linux Foundation, *Linux Foundation is Launching the x402 Foundation and Welcoming the Contribution of the x402 Protocol*, April 2, 2026", "date": null, "quote": "April 2, 2026 – The Linux Foundation, t he nonprofit organization enabling mass innovation through open source, today announced it is launching the x402 Foundation / The x402 protocol, created by Coinbase, is moving to the Linux Foundation.", "ref": 10 }, { "label": "[11]", "url": "https://github.com/x402-foundation/x402/blob/main/TSC.md", "claim": "x402 Foundation, *Technical Steering Committee*, fetched 2026-10-30", "date": null, "quote": "|Coinbase, Inc. | Erik Reppel | |Cloudflare, Inc. | Rohin Lohe | |Stripe, Inc. | Steve Kaliski | / Stripe, Inc. | Steve Kaliski", "ref": 11 }, { "label": "[12]", "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-operational-launch-of-x402-foundation-to-standardize-internet-native-payments-for-ai-agents-and-applications", "claim": "Linux Foundation, *Linux Foundation Announces Operational Launch of x402 Foundation to Standardize Internet-Native Payments for AI Agents and Applications*, July 14, 2026", "date": null, "quote": "The Linux Foundation today announced the operational launch of the x402 Foundation, a new open-governance body formed to steward the x402 protocol / The Foundation is now fully active under formal, open governance to steward the x402 protocol / SAN FRANCISCO, July 14, 2026 – The Linux Foundation , the nonprofit organization enabling mass innovation through open source, today announced the operational launch of the x402 Foundation / Foundation gathers 40 members dedicated to building an open, vendor-neutral payment standard over HTTP", "ref": 12 }, { "label": "[13]", "url": "https://x402.org/linux-foundation-appoints-michael-hursta-as-executive-director-of-the-x402-foundation/", "claim": "Linux Foundation, *Linux Foundation Appoints Michael Hursta as Executive Director of the x402 Foundation*, Oct. 1, 2026", "date": null, "quote": "The Linux Foundation appointed payments veteran Michael Hursta as Executive Director of the x402 Foundation. / Hursta will lead 50+ member organizations advancing x402, an open standard for internet-native payments", "ref": 13 }, { "label": "[14]", "url": "https://x402.org/", "claim": "x402 Foundation, *x402*, fetched 2026-10-30", "date": null, "quote": "x402 a Series of LF Projects, LLC", "ref": 14 }, { "label": "[15]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md", "claim": "x402 Foundation, *x402 Protocol Specification*, Protocol Version: 1", "date": null, "quote": "Protocol Version: 1", "ref": 15 }, { "label": "[16]", "url": "https://github.com/x402-foundation/x402/commits/HEAD/specs/x402-specification-v2.md", "claim": "x402 Foundation, *Commit history for specs/x402-specification-v2.md*, 2026-10-26", "date": "2026-10-26", "quote": "\"date\":\"2026-10-26T12:11:08Z\"},\"message\":\"docs(specs): document facilitator error messages (#3947)\"", "ref": 16 }, { "label": "[17]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md", "claim": "x402 Foundation, *HTTP transport for x402 v2*, fetched 2026-10-30", "date": null, "quote": "HTTP 402 status code with PAYMENT-REQUIRED header / Clients send payment data using the PAYMENT-SIGNATURE HTTP header. / Servers communicate payment settlement results using the PAYMENT-RESPONSE header. / The HTTP transport implements x402 payment flows over standard HTTP/HTTPS protocols. / The `PAYMENT-REQUIRED` header is the canonical HTTP transport location for the `PaymentRequired` object. / All x402 protocol information is communicated through headers (`PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`). / None of the three headers above is CORS-safelisted. A cross-origin `fetch()` / cannot read `PAYMENT-REQUIRED` or `PAYMENT-RESPONSE` unless the / response names them in `Access-Control-Expose-Headers` / cannot send `PAYMENT-SIGNATURE` unless the preflight allows it. / Invalid Payment | 400 | Malformed payment payload or requirements / Payment Failed | 402 | Payment verification or settlement failed / Server Error | 500 | Internal server error during payment processing", "ref": 17 }, { "label": "[18]", "url": "https://docs.x402.org/core-concepts/network-and-token-support", "claim": "x402 Foundation, *Networks and Token Support*, fetched 2026-10-30", "date": null, "quote": "x402 uses CAIP-2 standard network identifiers ( namespace:reference ) for unambiguous cross-chain support / eip155:8453 for Base / x402 supports tokens on EVM, Solana, TON, Algorand (AVM), Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui, and Canton networks / EVM Any ERC-20 token EIP-3009 or Permit2 Solana Any SPL or Token-2022 token SPL Transfer / x402 supports tokens on EVM, Solana, TON, Algorand (AVM), Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui, and Canton networks:", "ref": 18 }, { "label": "[19]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/a2a.md", "claim": "x402 Foundation, *Transport: A2A (Agent-to-Agent Protocol)*, fetched 2026-10-30", "date": null, "quote": "The A2A transport implements x402 payment flows over the Agent-to-Agent protocol using JSON-RPC messages and task-based state management. / Array of `SettlementResponse` schemas in `x402.payment.receipts` metadata field / Task with `state: \"input-required\"` and `x402.payment.status: \"payment-required\"` / PaymentRequired schema in `x402.payment.required` metadata field / PaymentPayload schema in `x402.payment.payload` metadata field / **Mechanism**: Message with `x402.payment.payload` metadata field and `taskId` for correlation / \"method\": \"message/send\" / `payment-submitted` | Payment payload received by server / `payment-verified` | Payment payload verified by server / `payment-completed` | Payment settled on-chain successfully / `payment-failed` | Payment verification or settlement failed / `payment-rejected` | Client rejected payment requirements / PaymentRequired schema in x402.payment.required metadata field / PaymentPayload schema in x402.payment.payload metadata field", "ref": 19 }, { "label": "[20]", "url": "https://raw.githubusercontent.com/x402-foundation/x402/main/specs/transports-v2/mcp.md", "claim": "x402 Foundation, *Transport: MCP (Model Context Protocol)*, fetched 2026-11-05", "date": null, "quote": "Client retries the tool call with payment in `_meta[\"x402/payment\"]` / Server returns tool result with settlement info in `_meta[\"x402/payment-response\"]` / **Data Format**: `PaymentPayload` schema / servers MUST return a tool result with `isError: true` containing the `PaymentRequired` data. / `structuredContent`** (REQUIRED): Direct `PaymentRequired` object / `content[0].text`** (REQUIRED): JSON-encoded string of the same `PaymentRequired` object / JSON.stringify(structuredContent) / Clients SHOULD prefer `structuredContent` when available, falling back to parsing `content[0].text` / Check if `result.structuredContent` exists and contains `x402Version` and `accepts` fields / Payment Invalid | Tool result with `isError: true` | Payment verification failed / Settlement Failed | Tool result with `isError: true` / Clients send payment data using the MCP `_meta` field with key `x402/payment`. / **Mechanism**: `_meta[\"x402/payment\"]` field in request parameters / Servers communicate payment settlement results using the `_meta[\"x402/payment-response\"]` field. / **Data Format**: `SettlementResponse` schema / If settlement fails after the tool has already executed, the server should not return the tool's content - only the payment error.", "ref": 20 }, { "label": "[21]", "url": "https://docs.x402.org/extensions/bazaar", "claim": "x402 Foundation, *Bazaar (Discovery Layer)*, fetched 2026-10-30", "date": null, "quote": "The x402 Bazaar is the discovery layer for the x402 ecosystem - a machine-readable catalog", "ref": 21 }, { "label": "[22]", "url": "https://github.com/x402-foundation/x402", "claim": "x402 Foundation, *x402*, Apache-2.0; fetched 2026-10-30", "date": null, "quote": "Apache-2.0 license", "ref": 22 }, { "label": "[23]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md", "claim": "x402 Foundation, *Exact Scheme Specification for EVM (EIP-3009 and Permit2)*, 2026", "date": null, "quote": "the Facilitator cannot modify the amount or destination. They serve only as the transaction broadcaster. / If no `assetTransferMethod` is specified in `PaymentRequired.extra`, clients should default to `\"eip3009\"`. / Tokens with native `transferWithAuthorization` (e.g., USDC). / The 65-byte signature of the `transferWithAuthorization` operation. / `authorization`: The parameters required to reconstruct the signed message. / `extra.name` (required): The EIP-712 domain name of the token contract. / `extra.version` (required): The EIP-712 domain version of the token contract. / One-time use / 1. Race Condition Risk: A facilitator may be vulnerable to a race condition where the client invalidates their delegation between simulation and transaction execution, causing the facilitator to pay gas for a failed transaction. / Tokens without EIP-3009. Uses a Proxy + Permit2. / **Universal Fallback** (Works for any ERC-20). / This asset transfer method uses the `permitWitnessTransferFrom` / to enforce receiver address security via the \"Witness\" pattern. / The `spender` in the signature is the / x402ExactPermit2Proxy / The user submits a standard on-chain `approve(Permit2)` transaction paying their own gas. / erc20ApprovalGasSponsoring / If the token supports EIP-2612, the user signs a permit authorizing Permit2. / Facilitator calls `x402ExactPermit2Proxy.settleWithPermit()` / eip2612GasSponsoring / The `eip3009` asset transfer method uses the `transferWithAuthorization` function", "ref": 23 }, { "label": "[24]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_svm.md", "claim": "x402 Foundation, *Exact Scheme Specification for Solana SVM (SPL TransferChecked)*, 2026", "date": null, "quote": "The transfer MAY appear either as a top-level instruction or as an inner instruction (CPI) emitted by another program. / `spl-token` `TransferChecked` / `token-2022` `TransferChecked` / A transfer of at least `PaymentRequirements.amount` / Of the asset identified by `PaymentRequirements.asset` / To the recipient identified by `PaymentRequirements.payTo` / The transfer MAY appear either as a top-level instruction or as an inner instruction (CPI) / Across all top-level instructions and the full CPI trace, **exactly one** transfer MUST match the requirements / When `extra.splits` is present, this rule applies **per payment leg** / Split legs MUST match their declared `amount` **exactly** / Clients MUST include a Memo instruction containing either the value of `extra.memo` (when present) or a random nonce (at least 16 bytes, hex-encoded for UTF-8 compliance). / Only `SetComputeUnitLimit` (discriminator 2) and `SetComputeUnitPrice` (discriminator 3) SHOULD be accepted / any `ComputeBudgetProgram` instructions / The `feePayer` MUST NOT appear in the `accounts` list of any instruction / The `feePayer` MUST NOT be used as an authority, source, or delegate for any transfer.", "ref": 24 }, { "label": "[25]", "url": "https://github.com/x402-foundation/x402/pull/3074", "claim": "x402 Foundation, *Pull Request #3074: Buffer response body until settlement succeeds in PaymentFilter*, 2026-09-04", "date": "2026-09-04", "quote": "buffer response body until settlement succeeds", "ref": 25 }, { "label": "[26]", "url": "https://www.usenix.org/system/files/usenixsecurity26-wang-qinying.pdf", "claim": "Qinying Wang (EPFL), Yong Yang (Zhejiang University), Yuan Chen (Independent Researcher), Shouling Ji (Zhejiang University), and Mathias Payer (EPFL), *When HTTP 402 Meets the Blockchain: Risks on Emerging x402 Payments (USENIX Security '26)*, August 12–14, 2026", "date": null, "quote": "identifying eight security rules for facilitators as critical payment infrastructure. Based on our analysis of rule violations, we derive four new attack vectors, including Free Shopping, Asset Theft, Service Denial, and Gas Abuse. / apply it to 15 major x402 facilitators collectively used by over 60K sellers and 360K buyers. Alarmingly, we find violations in all evaluated facilitators. / apply it to 15 major x402 facilitators collectively used by over 60K sellers and 360K buyers. Alarmingly, we find violations in all evaluated facilitators. We responsibly disclosed our findings to the affected parties, who acknowledged the issues and adopted mitigations, including changes by Coinbase. Finally, we complement our controlled testing with an empirical measurement of over 119 million recent Base and Solana transactions / Qinying Wang, EPFL; Yong Yang, Zhejiang University; Yuan Chen, Independent Researcher; Shouling Ji, Zhejiang University; Mathias Payer, EPFL", "ref": 26 }, { "label": "[27]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/schemes/batch-settlement/scheme_batch_settlement.md", "claim": "x402 Foundation, *Batch-Settlement Scheme Specification*, 2026-05", "date": null, "quote": "`batch-settlement` is a payment scheme in which the client provides a cryptographic payment commitment at request time / The commitment is accepted, access is granted immediately / The actual charge is communicated via the `PAYMENT-RESPONSE`. / pre-funded escrow, a payment channel, or a delegated authorization against a wallet balance / verified identity associated with a billing account / ### Capital-backed / ### Credit-backed", "ref": 27 }, { "label": "[28]", "url": "https://docs.x402.org/extensions/builder-code", "claim": "x402 Foundation, *Builder Code (ERC-8021)*, fetched 2026-11-11", "date": null, "quote": "builder-code extension enables on-chain attribution tracking for x402 payments by appending ERC-8021 Schema 2 builder codes to settlement transaction calldata.", "ref": 28 }, { "label": "[29]", "url": "https://docs.x402.org/extensions/payment-identifier", "claim": "x402 Foundation, *Payment-Identifier (Idempotency)*, fetched 2026-11-11", "date": null, "quote": "payment-identifier extension enables idempotency for x402 payments, allowing clients to safely retry requests without duplicate payment processing.", "ref": 29 }, { "label": "[30]", "url": "https://docs.x402.org/extensions/sign-in-with-x", "claim": "x402 Foundation, *Sign-In-With-X (SIWX)*, fetched 2026-11-11", "date": null, "quote": "Sign-In-With-X (SIWX) extension implements CAIP-122 for chain-agnostic wallet authentication. It allows clients to prove control of a wallet that previously paid for a resource, enabling access without requiring repurchase.", "ref": 30 }, { "label": "[31]", "url": "https://docs.x402.org/extensions/offer-receipt", "claim": "x402 Foundation, *Signed Offers and Receipts*, fetched 2026-11-11", "date": null, "quote": "The Offer & Receipt extension adds cryptographic proof-of-interaction to x402 payment flows.", "ref": 31 }, { "label": "[32]", "url": "https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/", "claim": "Chethan Shriyan and Madhu Samhitha Vangara, AWS, *Amazon Bedrock AgentCore payments is now generally available*, 18 AUG 2026", "date": null, "quote": "At GA, we have expanded protocol support to include the Machine Payment Protocol (MPP), another standard for machine payments co-authored by Stripe and Tempo / AgentCore payments addresses this by integrating with Coinbase and Stripe Privy wallets, enabling developers to set up payment capabilities by providing Coinbase or Privy API keys and secrets. / Additionally, we have introduced support for the “upto” scheme within x402, which enables an agent to set a spending ceiling rather than committing to a fixed price. / (as with the “exact” scheme supported today). / AgentCore exposes pay-per-use x402 endpoints offered by Coinbase as an MCP server via AgentCore Gateway", "ref": 32 }, { "label": "[33]", "url": "https://cloud.google.com/blog/products/ai-machine-learning/announcing-agents-to-payments-ap2-protocol", "claim": "Stavan Parikh and Rao Surapaneni, Google Cloud, *Announcing Agent Payments Protocol (AP2)*, September 16, 2025", "date": null, "quote": "launched the A2A x402 extension , a production-ready solution for agent-based crypto payments.", "ref": 33 }, { "label": "[34]", "url": "https://github.com/google-agentic-commerce/a2a-x402", "claim": "google-agentic-commerce/a2a-x402, *A2A x402 Extension*, fetched 2026-10-30", "date": null, "quote": "The A2A x402 Extension brings cryptocurrency payments to the Agent-to-Agent (A2A) protocol, enabling agents to monetize their services through on-chain payments. / Language-specific implementations (e.g., python/, typescript/)", "ref": 34 }, { "label": "[35]", "url": "https://www.trmlabs.com/trm-tech-blog/whos-actually-paying-measuring-ai-agent-payments-onchain", "claim": "Noah Hodge, TRM Labs, *Who's Actually Paying? Measuring AI Agent Payments Onchain*, September 9, 2026", "date": null, "quote": "OpenAI and Stripe’s ACP connects AI assistants to merchants so users can complete purchases within a conversation. / x402 makes payment part of a web request, allowing software to pay for a resource through an on-chain transaction. / The strict test keeps only those that also sustained the pattern across months and either registered in a public agent registry (ERC-8004) or paid more than one seller. / Across Base, Solana, and Polygon, TRM identified roughly USD 52.7 million across 198.9 million settlement transactions mediated by known x402 facilitators since May 2025. / Applied to the USD 25.62 million of screened x402 commerce, the two tests put the share that appears to be agentic at between 0.6% and 7.5% . / USD 52.47 million of USD 52.68 million (99.6%) settled in USDC", "ref": 35 }, { "label": "[36]", "url": "https://stripe.com/blog/10-lessons", "claim": "Roshan Sadanani, Stripe, *10 things we learned building for the first generation of agentic commerce*, March 12, 2026", "date": null, "quote": "we launched the Agentic Commerce Protocol (ACP), an open checkout specification that lets buyers, AI agents, and sellers transact through APIs / We’re starting with support for x402 using USDC on Base, with more protocols coming.", "ref": 36 }, { "label": "[37]", "url": "https://eips.ethereum.org/EIPS/eip-8004", "claim": "Ethereum Improvement Proposals, *ERC-8004: Trustless Agents*, 2025-08-13", "date": "2025-08-13", "quote": "Identity Registry Reputation Registry Validation Registry / This protocol proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust", "ref": 37 }, { "label": "[38]", "url": "https://docs.x402.org/dev-tools/facilitators", "claim": "x402 Foundation, *Facilitators*, fetched 2026-10-30", "date": null, "quote": "The table below lists selected production options; it is not an exhaustive catalog.", "ref": 38 }, { "label": "[39]", "url": "https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools?query=weth", "claim": "CoinGecko, *Onchain DEX pool search*, HTTP 402; fetched 2026-10-30", "date": null, "quote": "HTTP 402 PAYMENT-REQUIRED decoded: {\"x402Version\":2,\"resource\":{\"url\":\"https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools\" / {\"scheme\":\"exact\",\"network\":\"eip155:8453\",\"amount\":\"5000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"payTo\":\"0x110cdBba7FE6434Ec4CE3464CC523942ad6Fb784\",\"maxTimeoutSeconds\":60,\"extra\":{\"name\":\"USD Coin\",\"version\":\"2\"}} / {\"scheme\":\"exact\",\"network\":\"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\",\"amount\":\"5000\",\"asset\":\"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\" / {\"scheme\":\"exact\",\"network\":\"eip155:137\",\"amount\":\"5000\",\"asset\":\"0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359\" / \"extensions\":{\"bazaar\":", "ref": 39 }, { "label": "[40]", "url": "https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1", "claim": "CoinMarketCap, *Cryptocurrency quotes latest*, HTTP 402; fetched 2026-10-30", "date": null, "quote": "HTTP 402 PAYMENT-REQUIRED decoded: {\"x402Version\":2,\"resource\":{\"url\":\"https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest\" / {\"scheme\":\"exact\",\"network\":\"eip155:56\",\"asset\":\"0xcE24439F2D9C6a2289F741120FE202248B666666\" / \"assetTransferMethod\":\"permit2-exact\" / {\"scheme\":\"exact\",\"network\":\"eip155:8453\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"payTo\":\"0x3C5f3a6cE224BB89D72f5EB4232ecC27F67B3eeA\",\"maxTimeoutSeconds\":30,\"extra\":{\"name\":\"USD Coin\",\"version\":\"2\",\"x402PaymentConfigId\":\"699dbab79f32ffde650104aa\",\"assetTransferMethod\":\"eip3009\"},\"amount\":\"10000\"} / \"name\":\"World Liberty Financial USD\" / \"name\":\"Tether USD\" / \"name\":\"United Stables\"", "ref": 40 }, { "label": "[41]", "url": "https://api.bitrefill.com/x402/gift-cards/search?q=amazon", "claim": "Bitrefill, *Gift-card search*, HTTP 402; fetched 2026-10-30", "date": null, "quote": "HTTP 402 PAYMENT-REQUIRED decoded: {\"x402Version\":2,\"error\":\"Payment required\",\"resource\":{\"url\":\"https://api.bitrefill.com/x402/gift-cards/search?q=amazon\" / {\"scheme\":\"exact\",\"network\":\"eip155:8453\",\"amount\":\"2000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\" / {\"scheme\":\"exact\",\"network\":\"eip155:42161\",\"amount\":\"2000\" / {\"scheme\":\"exact\",\"network\":\"eip155:137\",\"amount\":\"2000\" / {\"scheme\":\"exact\",\"network\":\"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\",\"amount\":\"2000\" / {\"scheme\":\"exact\",\"network\":\"lnbtc:000000000019d6689c085ae165831e93\",\"amount\":\"3000\",\"asset\":\"BTC\",\"payTo\":\"03c913d061dfe0adbfd87c0e98e66033be0dbbb2413de26bd363c63970480a9a80\",\"maxTimeoutSeconds\":300,\"extra\":{\"assetTransferMethod\":\"bolt11\",\"paymentFlow\":\"upfront\"", "ref": 41 }, { "label": "[42]", "url": "https://blog.cloudflare.com/wallets/", "claim": "Cloudflare, *Announcing Cloudflare Wallets: The programmable wallet for the agentic Internet*, August 4, 2026", "date": null, "quote": "If you want to pay or get paid for services behind Monetization Gateway and other x402-compatible endpoints , you’ll need a wallet. Cloudflare Wallets will allow you to store stablecoins, purchase services, and receive funds across the web.", "ref": 42 }, { "label": "[43]", "url": "https://docs.cdp.coinbase.com/x402/seller/facilitator", "claim": "Coinbase Developer Platform, *CDP Facilitator*, fetched 2026-10-30", "date": null, "quote": "The CDP Facilitator handles that work as a hosted service: it validates signed payments, screens transactions, submits settlement onchain, and reports the result to your resource server. / The CDP Facilitator has processed more than 100 million transactions and $28 million in payment volume across Base and Solana alone. Built-in screening. OFAC and Know Your Transaction (KYT) checks identify and decline payments involving sanctioned or high-risk addresses. / The CDP Facilitator supports all ERC-20 tokens on its EVM networks through EIP-3009 or Permit2, and SPL tokens on Solana. The following table shows x402 v2 support: Network CAIP-2 identifier Schemes Base eip155:8453 exact , upto , batch-settlement Base Sepolia eip155:84532 exact , upto , batch-settlement Polygon eip155:137 exact , upto , batch-settlement Arbitrum eip155:42161 exact , upto , batch-settlement Monad eip155:143 exact , upto , batch-settlement World eip155:480 exact , upto , batch-settlement World Sepolia eip155:4801 exact , upto , batch-settlement Solana solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp exact , upto", "ref": 43 }, { "label": "[44]", "url": "https://blog.cloudflare.com/monetization-gateway-beta/", "claim": "Cloudflare, *Monetization Gateway beta: charge AI agents for consumption with HTTP 402*, September 30, 2026", "date": null, "quote": "Today, we’re making the Cloudflare Monetization Gateway available as part of a closed beta, and showcasing four customer use cases that are in production today. / We handle the rest: payment verification and settlement through Coinbase's x402 Facilitator , failures and retries, analytics, and keeping up with changes to the x402 protocol. Payments settle on the Base blockchain using USDC, a stablecoin pegged to the U.S. dollar. / --header \"Payment-Method: x402\"", "ref": 44 }, { "label": "[45]", "url": "https://pkg.go.dev/github.com/x402-foundation/x402/go/v2", "claim": "Go Packages, *github.com/x402-foundation/x402/go/v2*, v2.30.0, published Nov 4, 2026", "date": null, "quote": "Go implementation of the x402 protocol - a standard for HTTP 402 Payment Required responses with cryptocurrency micropayments. / evm/auth-capture / svm/paymentchannels", "ref": 45 }, { "label": "[46]", "url": "https://github.com/Merit-Systems/x402scan", "claim": "Merit Systems, *x402scan*, fetched 2026-11-06", "date": null, "quote": "x402scan lets you explore the ecosystem of x402 servers, see their transaction volumes and directly access their resources through an embedded wallet. / It's live at x402scan.com. / Shared facilitator configuration", "ref": 46 }, { "label": "[47]", "url": "https://stablecoin.com/402/ecosystem", "claim": "Stablecoin.com, *x402 ecosystem directory*, fetched 2026-11-06", "date": null, "quote": "Varies by scheme and facilitator / Listed by x402 as the default testnet facilitator. / Independent Rust facilitator listed in the x402 ecosystem.", "ref": 47 }, { "label": "[48]", "url": "https://www.chainalysis.com/blog/x402-agentic-payments-adoption/", "claim": "Chainalysis Team, *Agentic Payments Cross the Threshold: Inside x402's Path to Meaningful Adoption*, June 3, 2026", "date": null, "quote": "Agentic payments on Base crossed 100 million transactions in approximately three quarters, surging from near-zero in Q3 2025 before moderating in early 2026. / Transactions of $1+ now represent 95% of total volume transferred, up from 49% in early 2025.", "ref": 48 }, { "label": "[49]", "url": "https://financetracked.com/ai-agent-payments", "claim": "Adewale Amure, FinanceTracked (citing Visa & Artemis), *AI Agent Payments: Where Does the Real Usage Lie?*, published 2026-09-18; citing Visa & Artemis report published July 16, 2026, data through 2026-04-21", "date": null, "quote": "A joint report from Visa and Artemis, published 16 July with data to 21 April, adjusted x402’s volume to about $15 million across 109.6 million transactions, with roughly 422,000 buyers and about 5,300 sellers. / That study filtered and identified wash and test activity rather than modeling which transactions came from agents.", "ref": 49 }, { "label": "[50]", "url": "https://v12.sh/blog/x402", "claim": "V12 Security, *25 Vulnerabilities in the x402 Protocol: Inside Three Critical Findings*, 2026-10-22", "date": "2026-10-22", "quote": "V12 found 25 vulnerabilities / We reported the 3 critical and 13 high severity findings to the x402 team on August 12, 2026. The 3 critical vulnerabilities were fixed by August 20th.", "ref": 50 }, { "label": "[51]", "url": "https://24klabs.ai/wall", "claim": "24K Labs, *The Gold-402 Index*, fetched 2026-11-06", "date": null, "quote": "731 curated x402 services, every one live‑knocked before it was listed. / 479 carry a dated knock / APIs & Services 348 / A knock is one HTTP request that got an answer — it is not a delivery test.", "ref": 51 }, { "label": "[52]", "url": "https://s402-protocol.org/specification", "claim": "s402, *s402 Wire Format Specification (retired September 2026)*, 2026-09", "date": null, "quote": "s402 was retired in September 2026. It was an HTTP 402 payment protocol for agents on Sui, and x402 has since become the industry standard. For new work, use x402", "ref": 52 }, { "label": "[53]", "url": "https://github.com/s402-protocol/core/blob/main/AGENTS.md", "claim": "s402, *s402-protocol/core — AGENTS.md*, 2026-09-04", "date": "2026-09-04", "quote": "`payment-required` carries an x402 V2 `PaymentRequired` envelope on every route / its envelope-level fields ride in `extensions.s402`", "ref": 53 } ], "form": "http-header", "governance": "The x402 Foundation, a Linux Foundation project (\"x402 a Series of LF Projects, LLC\"). The Linux Foundation announced it on 2026-04-02 with the contribution of the protocol from Coinbase, and announced its operational launch and the completed contribution on 2026-07-14, with 40 member organisations by then. Premier members (2026-07-14): Adyen, AWS, American Express, Circle, Cloudflare, Coinbase, Fiserv, Google, Mastercard, Monad Foundation, MoonPay, Ripple, Shopify, Solana Foundation, Stellar Development Foundation, Stripe and Visa. Michael Hursta was appointed Executive Director on 2026-10-01. The Technical Steering Committee lists Coinbase, Cloudflare and Stripe", "group": "HTTP 402 family", "history": [ { "date": "2026-09-06", "note": "verified against x402.org (homepage, /announcement), x402-foundation/x402 specs/transports-v2/http.md" }, { "date": "2026-10-16", "note": "The Linux Foundation appointed Michael Hursta as executive director of the x402 Foundation, effective 2026-10-01; the foundation has 50+ members" }, { "date": "2026-10-28", "note": "Re-verified record against 27 sources on 2026-10-28: 5 live HTTP 402 x402 v2 endpoints (CoinGecko, CoinMarketCap, Bitrefill, Apify, OneSource), 5 vendor implementations, and 2 independent coverage sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "x402", "implementation": "multi-implementation", "last_verified": "2026-11-11", "name": "x402", "native_status": "In production use; the Foundation calls it \"an open, neutral standard for internet-native payments\"", "origin": { "date": "2025-05-06", "org": "Coinbase" }, "part_of": null, "parties": [ "agent-site", "agent-payment" ], "phase": "living", "probe": { "method": "GET", "on_absent": "A 200 or a 402 without a PAYMENT-REQUIRED header means this specific path is not (or no longer) gated by x402 v2 over HTTP; the same origin could still use x402 over the MCP or other transports, or the legacy v1 header shape, so the probe only rules out v2/HTTP on the probed path.", "parse": "HTTP 402 status with a base64-encoded PaymentRequired object in the PAYMENT-REQUIRED response header (x402 v2 HTTP transport)", "path": "{origin}/{paid-path}" }, "question": "How can an HTTP client pay per-request or per-resource, in stablecoins, without accounts, API keys, or signup?", "scope": "payments", "spec_url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "step": "pay", "summary_md": "**x402** is an open payment standard originated by Coinbase on May 6, 2025 that enables applications and autonomous agents to pay resource servers inline for protected APIs, content, and data. Its transport-independent core schemas (`PaymentRequirements`, `PaymentPayload`, and `SettlementResponse`) bind a `CAIP-2` network, atomic `amount`, and `asset` across HTTP, MCP, and A2A transports. On HTTP in v2, the server challenges an unpaid request with `402 Payment Required` and `PAYMENT-REQUIRED`, the client submits `PaymentPayload` in `PAYMENT-SIGNATURE`, verification (`POST /verify`) and settlement (`POST /settle`) execute according to `paymentFlow` (`authorization` by default, or `upfront` / `escrow`), and the server returns `PAYMENT-RESPONSE` on `200 OK`. Announced December 11, 2025, `v2.0` (`2025-12-9`) replaced v1's HTTP 402 response body and `X-PAYMENT` / `X-PAYMENT-RESPONSE` headers with `CAIP-2` identifiers and `extensions`, and on April 2, 2026 the protocol transferred to the Linux Foundation's x402 Foundation under a Technical Steering Committee of Coinbase, Cloudflare, and Stripe.", "track": "linux-foundation", "version": { "date": "2025-12-09", "label": "2.0" }, "watch": [ { "type": "github", "repo": "x402-foundation/x402", "mode": "release", "version": false } ], "use_cases": [ "accept-agent-payments", "agent-checkout" ], "audience": [ "agent-builder", "site-owner", "platform" ], "pairs_with": [ "mpp", "l402", "ap2", "agentic-commerce-protocol", "erc-8004" ], "prerequisites": [], "hatnote_md": "For the reserved HTTP status code, see [HTTP 402 Payment Required](/terms/http-402-payment-required/). Not to be confused with [L402](/protocols/l402/) (`WWW-Authenticate: L402` macaroon and Lightning invoice) or [Machine Payments Protocol (MPP)](/protocols/mpp/).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-11", "v05_hatnote_html_md": "For the reserved HTTP status code, see [HTTP 402 Payment Required](/terms/http-402-payment-required/). Not to be confused with [L402](/protocols/l402/) (`WWW-Authenticate: L402` macaroon and Lightning invoice) or [Machine Payments Protocol (MPP)](/protocols/mpp/). [1][2][3]", "v05_elevator_pitch_md": "x402 is an open payment protocol that lets AI agents and software clients pay per request for APIs, data feeds, and web content directly over HTTP, MCP, or A2A without human checkout flows. Instead of forcing developers to pre-register accounts, manage API keys, and maintain separate subscriptions with every provider, a server returns an HTTP `402 Payment Required` challenge with `PaymentRequirements` and fulfills the request as soon as the client attaches a signed `PaymentPayload`. [4][5][6]", "v05_lead_md": "**x402** is an open payment standard originated by Coinbase on May 6, 2025 that enables applications and autonomous agents to pay resource servers inline for protected APIs, content, and data. [4][7] Its transport-independent core schemas (`PaymentRequirements`, `PaymentPayload`, and `SettlementResponse`) bind a `CAIP-2` network, atomic `amount`, and `asset` across HTTP, MCP, and A2A transports. On HTTP in v2, the server challenges an unpaid request with `402 Payment Required` and `PAYMENT-REQUIRED`, the client submits `PaymentPayload` in `PAYMENT-SIGNATURE`, verification (`POST /verify`) and settlement (`POST /settle`) execute according to `paymentFlow` (`authorization` by default, or `upfront` / `escrow`), and the server returns `PAYMENT-RESPONSE` on `200 OK`. [4][8][9] Announced December 11, 2025, `v2.0` (`2025-12-9`) replaced v1's HTTP 402 response body and `X-PAYMENT` / `X-PAYMENT-RESPONSE` headers with `CAIP-2` identifiers and `extensions`, and on April 2, 2026 the protocol transferred to the Linux Foundation's x402 Foundation under a Technical Steering Committee of Coinbase, Cloudflare, and Stripe. [4][8][9][10][11]", "v05_identity_sentence_md": "**x402** is an open payment standard originated by Coinbase on May 6, 2025 that enables applications and autonomous agents to pay resource servers inline for protected APIs, content, and data. [4][7]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "HTTP header (`http-header`)" }, { "label": "Originated by", "value_md": "Coinbase (Erik Reppel, Nemil Dalal, Dan Kim; May 6, 2025); x402 Foundation co-founded with Cloudflare (September 23, 2025). [5][7]" }, { "label": "Governed by", "value_md": "x402 Foundation (Linux Foundation); Technical Steering Committee: Coinbase, Cloudflare, and Stripe; Executive Director: Michael Hursta. [11][12][13]" }, { "label": "Track", "value_md": "Foundation / Consortium Specification (`x402 a Series of LF Projects, LLC`, under Linux Foundation open governance). [12][14]" }, { "label": "Status", "value_md": "Production open standard; x402 Foundation operational under Linux Foundation (40 members at July 14, 2026 operational launch; 50+ member organizations by October 2026). [12][13]" }, { "label": "Version", "value_md": "v2.0 (specification header dated 2025-12-9; launched December 11, 2025; `specs/x402-specification-v2.md` on `main` revised through 2026-10-26 with `paymentFlow` and `auth-capture` additions without a version bump); v1 launched May 6, 2025. [4][7][9][15][16]" }, { "label": "Headers", "value_md": "v2: `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`; v1: `X-PAYMENT`, `X-PAYMENT-RESPONSE` (with HTTP 402 JSON body). [8][17]" }, { "label": "Schemes", "value_md": "`exact`, `upto`, `batch-settlement`, and `auth-capture` (`specs/schemes/`); payment flows: `authorization` (default), `upfront`, and `escrow`. [4]" }, { "label": "Networks", "value_md": "CAIP-2 identifiers (`namespace:reference`, e.g., `eip155:8453`) across EVM, Solana, TON, Algorand, Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui, and Canton. [18]" }, { "label": "Transports", "value_md": "HTTP/HTTPS, Model Context Protocol (MCP), and Agent-to-Agent (A2A) JSON-RPC task metadata. [4][17][19]" }, { "label": "Message format", "value_md": "Transport-specific JSON representations: Base64 JSON objects in HTTP headers; structured JSON objects in MCP `_meta` with text fallbacks. [4][20]" }, { "label": "Token format", "value_md": "On-chain token contract address (e.g., ERC-20 via EIP-3009/Permit2, SPL) or ISO 4217 fiat currency code. [4][18]" }, { "label": "Specification", "value_md": "[x402 Protocol Specification v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [v1](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md) [4][15]" }, { "label": "Found at", "value_md": "Per-resource HTTP 402 response headers; Facilitator `/verify`, `/settle`, `/supported`, and optional Bazaar `/discovery/resources` catalog. [4][21]" }, { "label": "Licence", "value_md": "Apache-2.0 [22]" } ], "v05_problem_md": "RFC 9110 reserves the 402 (Payment Required) status code for future use and defines no challenge or settlement record. Without a specification for how to format and respond to that status, publishers lack adequate tools to convey a payment request. Clients that interpret a defined protocol transact without accounts, subscriptions, or API keys. Automated clients otherwise pre-register with every API, manage keys, and maintain separate billing relationships. [1][5][6] x402 standardizes those messages. Each object in `accepts` is a `PaymentRequirements` record naming `scheme`, `network`, `amount`, `asset`, and `payTo`. The client submits a `PaymentPayload` whose `accepted` field is the chosen requirement and whose `payload` carries the scheme-specific signature. `POST /verify` validates payment state without writing onchain state, and `POST /settle` durably commits it, whether a facilitator or the resource server hosts the endpoints. The schemes specified from the core document are `exact`, `upto`, `batch-settlement`, and `auth-capture`. [4] Transport-specific implementations, framework-specific integrations, client-side budget management, and session handling mechanisms sit outside the core specification. Finding a resource is a separate surface: `GET /discovery/resources` lists Bazaar entries, and the discovered resources may use any x402-supported transport. [4]", "v05_mechanism_delta_md": "x402 standardizes those messages. Each object in `accepts` is a `PaymentRequirements` record naming `scheme`, `network`, `amount`, `asset`, and `payTo`. The client submits a `PaymentPayload` whose `accepted` field is the chosen requirement and whose `payload` carries the scheme-specific signature. `POST /verify` validates payment state without writing onchain state, and `POST /settle` durably commits it, whether a facilitator or the resource server hosts the endpoints. The schemes specified from the core document are `exact`, `upto`, `batch-settlement`, and `auth-capture`. [4]", "v05_scope_boundary_md": "Transport-specific implementations, framework-specific integrations, client-side budget management, and session handling mechanisms sit outside the core specification. Finding a resource is a separate surface: `GET /discovery/resources` lists Bazaar entries, and the discovered resources may use any x402-supported transport. [4]", "v05_fuzzy_additions": [ { "id": "transport-carriers-for-the-payment-objects", "heading": "Transport carriers for the payment objects", "body_md": "Transports share the `PaymentRequired`, `PaymentPayload`, and `SettlementResponse` schemas. While HTTP v2 encodes the challenge in the `PAYMENT-REQUIRED` response header, MCP, A2A, and HTTP v1 carry the same payment objects in transport-specific fields. [4][17][19][20]", "bullets": [ { "label": "MCP tool-result challenge", "text_md": "The server returns `isError` true with `PaymentRequired` in `structuredContent` and in `content[0].text`, defined as `JSON.stringify` of `structuredContent`. Clients read `structuredContent` when `x402Version` and `accepts` are present, and parse `content[0].text` otherwise. Failed verification and failed settlement use that same `isError` result. [20]" }, { "label": "MCP payment and receipt keys", "text_md": "The client sends `PaymentPayload` in `_meta[\"x402/payment\"]` on the tool call. The server returns `SettlementResponse` in `_meta[\"x402/payment-response\"]`. If settlement fails after the tool has executed, the server sets `isError` true and should not return the tool content, only the payment error. [20]" }, { "label": "A2A task metadata", "text_md": "The agent sets `state` to `input-required` and `x402.payment.status` to `payment-required`, with `PaymentRequired` in `x402.payment.required`. The client sends `PaymentPayload` in `x402.payment.payload` on `message/send` with `taskId`. Receipts are `SettlementResponse` values in `x402.payment.receipts`. Status moves through `payment-submitted`, `payment-verified`, `payment-completed`, `payment-failed`, and `payment-rejected`. [19]" }, { "label": "HTTP v1 fields and browser exposure", "text_md": "The v1 body is a `PaymentRequirementsResponse` with `maxAmountRequired` and a network such as `base-sepolia`. v2 headers are not CORS-safelisted: `fetch` needs `Access-Control-Expose-Headers` to read `PAYMENT-REQUIRED` and `PAYMENT-RESPONSE`, and a preflight that allows `PAYMENT-SIGNATURE`. HTTP 400 is malformed input, HTTP 402 a failed check, and HTTP 500 a server fault. [8][17]" } ] }, { "id": "per-network-exact-payloads-and-sibling-schemes", "heading": "Per-network exact payloads and sibling schemes", "body_md": "A payment `scheme` defines how to construct the `payload` inside `PaymentPayload`, while `extra.paymentFlow` selects verification and settlement ordering (`authorization` by default). EVM `exact` sets `assetTransferMethod` to `eip3009` or `permit2`, where the facilitator acts solely as transaction broadcaster without modifying amount or destination, and Solana `exact` verifies an SPL token transfer instruction. [4][23][24] x402 supports tokens on EVM, Solana, TON, Algorand (AVM), Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui, and Canton networks, identified with CAIP-2 (`namespace:reference`). Newer families include Keeta (`keeta:21378`), Concordium, XRPL (`xrpl:0`), and Cardano. [18]", "bullets": [ { "label": "EVM eip3009 transferWithAuthorization", "text_md": "`eip3009` is the default `assetTransferMethod` for tokens with `transferWithAuthorization`. The `payload` carries a 65-byte `signature` and an `authorization` of `from`, `to`, `value`, `validAfter`, `validBefore`, and a 32-byte random `nonce`. `extra.name` and `extra.version` are the EIP-712 domain. The authorization is one-time use. Because facilitator `/verify` is read-only and does not lock funds or consume the `nonce` on-chain before `/settle` executes, concurrent requests carrying the same signed authorization can pass `/verify` before settlement (a race condition risk between simulation and execution) unless the server serializes or deduplicates on the `nonce`, buffers the response body until settlement succeeds (as in reference middleware pull request `3074`), or uses the `upfront` payment flow for irreversible actions. [4][23][25][26]" }, { "label": "EVM permit2 and the proxy witness", "text_md": "`permit2` covers an ERC-20 without EIP-3009. The client signs `permitWitnessTransferFrom` with `spender` equal to `x402ExactPermit2Proxy`, so the witness binds the receiver. A one-time `approve` of Permit2 is paid by the user, sponsored via `erc20ApprovalGasSponsoring`, or replaced by an EIP-2612 signature that `settleWithPermit` submits under `eip2612GasSponsoring`. [23]" }, { "label": "Solana TransferChecked, memo nonce, and CPI", "text_md": "SVM `exact` uses `spl-token` or `token-2022` `TransferChecked` for at least `PaymentRequirements.amount` of `asset` to `payTo`, top-level or as an inner `CPI`. Exactly one transfer must match. `extra.splits` gives each leg its own transfer, and a split `amount` must match exactly. The Memo holds `extra.memo` or a random nonce of at least 16 bytes (>= 16 bytes, hex-encoded). `ComputeBudgetProgram` allows `SetComputeUnitLimit` and `SetComputeUnitPrice`. `feePayer` must not appear in any instruction `accounts` list and must not be an authority, source, or delegate. [24]" }, { "label": "Sibling schemes and protocol extensions", "text_md": "`upto` treats `amount` as the maximum at verification and the settled amount later. `batch-settlement` submits a cryptographic commitment, grants access immediately, and returns the charge in `PAYMENT-RESPONSE`. Backing is `capital-backed` (escrow, a channel, or a delegated wallet) or `credit-backed` (a billing identity), with `auth-capture` also named. Unconfirmed settlement sets `errorReason` to `settlement_pending` with a non-empty `transaction`. Published extensions add `builder-code` (appending ERC-8021 Schema 2 builder codes to settlement transaction calldata for on-chain attribution) and `payment-identifier` (making x402 payments idempotent across client retries). Two further extensions define Sign-In-With-X (`sign-in-with-x`, implementing CAIP-122 wallet authentication so prior payers access resources without repurchase) and `offer-receipt` (adding cryptographic proof-of-interaction to x402 payment flows). [4][27][28][29][30][31]" } ] } ], "v05_diagram": { "title": "Default authorization payment flow", "heading": "Default authorization payment flow", "mermaid": "sequenceDiagram\n participant Client\n participant RS as Resource Server\n participant Facilitator\n Client->>RS: 1. Client Request\n RS-->>Client: 2. Payment Required Response\n Client->>RS: 3. Payment Authorization Request\n Note over RS,Facilitator: authorization default: verify, then resource, then settle, then respond\n RS->>Facilitator: POST /verify\n Note over RS: Resource executes after read-only verify\n RS->>Facilitator: POST /settle\n RS-->>Client: 4. Settlement Response", "caption_md": "Default `authorization` flow. Read-only `/verify` runs before the resource executes, then `/settle`, then the settlement response. Because `/verify` is read-only and MUST NOT commit payment state or write onchain state, funds move only when `/settle` executes (`upfront` commits payment via `/settle` before the resource executes, and `escrow` runs an initial `/settle` before the resource executes). The resource server may host `/verify` and `/settle` itself. `upfront` and `escrow` are different orderings. [4]" }, "v05_wire_artifact": { "title": "Canonical HTTP 402 PAYMENT-REQUIRED decoded payload (x402 v2)", "heading": "Canonical HTTP 402 PAYMENT-REQUIRED decoded payload (x402 v2)", "lang": "json", "code": "{\n \"x402Version\": 2,\n \"error\": \"PAYMENT-SIGNATURE header is required\",\n \"resource\": {\n \"url\": \"https://api.example.com/premium-data\",\n \"description\": \"Access to premium market data\",\n \"mimeType\": \"application/json\"\n },\n \"accepts\": [\n {\n \"scheme\": \"exact\",\n \"network\": \"eip155:84532\",\n \"amount\": \"10000\",\n \"asset\": \"0x036CbD53842c5426634e7929541eC2318f3dCF7e\",\n \"payTo\": \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\",\n \"maxTimeoutSeconds\": 60,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\"\n }\n }\n ]\n}", "caption_md": "Canonical `PaymentRequired` JSON object decoded from the base64 `PAYMENT-REQUIRED` HTTP `402` response header in the x402 v2 HTTP transport specification (`eip155:84532`, `exact` scheme, `10000` atomic `USDC` units). [17]" }, "v05_counterparts": { "classic_analogues": [ { "name": "HTTP 402 Payment Required", "spec_or_rfc": "RFC 9110", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "RFC 9110 reserves HTTP 402 without wire headers; x402 v2 binds it to `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE`. [1][17]" }, { "name": "EIP-712 Typed Data & EIP-3009 Transfer With Authorization", "spec_or_rfc": "EIP-3009", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "x402's EVM `exact` scheme wraps an EIP-712 signature and EIP-3009 authorization parameters inside the transport `PaymentPayload`. [4][23]" } ], "agentic_peers": [ { "target_id": "mpp", "target_name": "Machine Payments Protocol (MPP)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Co-authored by Stripe and Tempo for card and stablecoin machine payments alongside x402 in Stripe and AWS AgentCore. [3][32]" }, { "target_id": "l402", "target_name": "L402", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "L402 challenges via `WWW-Authenticate: L402` with a macaroon and BOLT 11 Lightning invoice instead of CAIP-2 `PAYMENT-REQUIRED` headers. [2][17]" }, { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "AP2 verifies user-authorized agent mandates, while the `a2a-x402` extension settles on-chain cryptocurrency payments over A2A tasks. [33][34]" }, { "target_id": "agentic-commerce-protocol", "target_name": "Agentic Commerce Protocol", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "OpenAI and Stripe's ACP handles conversational merchant checkout, whereas x402 settles per-request API payments inline over HTTP 402. [35][36]" }, { "target_id": "erc-8004", "target_name": "ERC-8004: Trustless Agents", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Defines on-chain Identity, Reputation, and Validation registries for cross-organization agent discovery; TRM Labs' strict x402 payment model uses `ERC-8004` registration as one attribution heuristic alongside multi-seller payment patterns. [35][37]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (13 probed or cited examples across 4 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Paywalled origins & API sellers", "col4_header": "Observed challenge & accepted assets", "note_md": "Facilitator and resource-server rows reflect vendor-declared capabilities, documentation, and `/supported` or HTTP 402 endpoint probes rather than audited protocol conformance; see the USENIX Security '26 facilitator study and V12 audit in the ecosystem censuses and notes below. [26][38]", "rows": [ { "actor": "CoinGecko", "role": "Seller", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "HTTP 402 `PAYMENT-REQUIRED` (`x402Version` 2, `exact`) accepting USDC across Base, Solana, and Polygon.", "source_md": "[CoinGecko onchain pool search (HTTP 402)](https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools?query=weth) [39] · [x402 networks and token support](https://docs.x402.org/core-concepts/network-and-token-support) [18]" }, { "actor": "CoinMarketCap", "role": "Seller", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "HTTP 402 `PAYMENT-REQUIRED` (`x402Version` 2, `exact`, `eip3009` / `permit2-exact`) on `eip155:8453` (USDC) and `eip155:56` (4 stablecoins).", "source_md": "[CoinMarketCap quotes (HTTP 402)](https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1) [40]" }, { "actor": "Bitrefill", "role": "Seller", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "HTTP 402 `PAYMENT-REQUIRED` (`x402Version` 2, `exact`) on `eip155:8453`, `eip155:42161`, `eip155:137`, Solana, and Lightning (`bolt11`, `upfront`).", "source_md": "[Bitrefill gift-card search (HTTP 402)](https://api.bitrefill.com/x402/gift-cards/search?q=amazon) [41] · [x402 networks and token support](https://docs.x402.org/core-concepts/network-and-token-support) [18]" } ] }, "side_b": { "visible": true, "heading": "Buyer harnesses & cloud runtimes", "col4_header": "Runtime integration & payment flow", "note_md": null, "rows": [ { "actor": "AWS (Amazon Bedrock AgentCore payments)", "role": "Agent platform / runtime", "status": "Supported", "status_display": "Supported · as of 2026-08-18", "col4_md": "GA runtime supporting x402 `exact` and `upto` with Coinbase/Privy USDC wallets and AgentCore Gateway MCP discovery.", "source_md": "[AWS ML Blog (18 AUG 2026)](https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/) [32]" }, { "actor": "Cloudflare Agents SDK", "role": "Agent SDK / runtime", "status": "Supported", "status_display": "Supported · as of 2026-08-04", "col4_md": "Supports x402 transactions in Cloudflare Agents SDK and MCP integrations, paired with Cloudflare Wallets for stablecoin payments.", "source_md": "[Cloudflare Blog (September 23, 2025)](https://blog.cloudflare.com/x402/) [5] · [Cloudflare Wallets (August 4, 2026)](https://blog.cloudflare.com/wallets/) [42]" }, { "actor": "Vercel x402-mcp", "role": "SDK integration", "status": "Supported", "status_display": "Supported · as of 2025-09-12", "col4_md": "Integrates x402 payments into MCP servers and Vercel AI SDK alongside `x402-fetch` and `x402-next` middleware.", "source_md": "[Vercel Blog (12 Sep 2025)](https://vercel.com/blog/introducing-x402-mcp-open-protocol-payments-for-mcp-tools) [6]" } ] }, "additional_tables": [ { "visible": true, "heading": "Payment facilitators, gateways & reference SDKs", "col4_header": "Supported schemes, networks & surface", "note_md": null, "rows": [ { "actor": "Coinbase CDP Facilitator", "role": "Payment rail (Originator)", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "Hosted `exact`, `upto`, and `batch-settlement` facilitator on `eip155:8453`, `eip155:137`, `eip155:42161`, and Solana with OFAC/KYT screening.", "source_md": "[Coinbase CDP Facilitator](https://docs.cdp.coinbase.com/x402/seller/facilitator) [43]" }, { "actor": "Stripe", "role": "Payment rail (TSC member)", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "Accepts `exact` USDC on Base (`2026-05-27.preview` `transaction_verification`); requires Dashboard approval and US (ex-NY) or 30+ country eligibility.", "source_md": "[Stripe x402 docs](https://docs.stripe.com/payments/machine/x402) [3] · [Stripe Blog (March 12, 2026)](https://stripe.com/blog/10-lessons) [36] · [x402 Technical Steering Committee](https://github.com/x402-foundation/x402/blob/main/TSC.md) [11]" }, { "actor": "Cloudflare Monetization Gateway", "role": "Platform", "status": "Experimental", "status_display": "Experimental · as of 2026-09-30", "col4_md": "Closed-beta HTTP 402 edge paywall and AI Gateway (`Payment-Method: x402`) settling USDC on Base via Coinbase's Facilitator.", "source_md": "[Cloudflare Blog (September 30, 2026)](https://blog.cloudflare.com/monetization-gateway-beta/) [44]" }, { "actor": "x402 Go SDK", "role": "Reference SDK", "status": "Supported", "status_display": "Supported · as of 2026-11-04", "col4_md": "Reference `go/v2` module implementing EVM (`exact`, `upto`, `batch-settlement`, `auth-capture`) and SVM (`exact`, `upto`, `batch-settlement`, `paymentchannels`) packages.", "source_md": "[pkg.go.dev x402 go/v2 (v2.30.0, Nov 4, 2026)](https://pkg.go.dev/github.com/x402-foundation/x402/go/v2) [45]" }, { "actor": "Google Cloud (a2a-x402)", "role": "Protocol extension", "status": "Supported", "status_display": "Supported · as of 2025-09-16", "col4_md": "Carries x402 payloads over A2A JSON-RPC tasks via `x402.payment.required` and `x402.payment.payload` metadata in Python and TypeScript.", "source_md": "[Google Cloud Blog (September 16, 2025)](https://cloud.google.com/blog/products/ai-machine-learning/announcing-agents-to-payments-ap2-protocol) [33] · [a2a-x402 GitHub](https://github.com/google-agentic-commerce/a2a-x402) [34] · [x402 A2A transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/a2a.md) [19]" } ] }, { "visible": true, "heading": "Ecosystem explorers and directories", "col4_header": "Index scope", "note_md": null, "rows": [ { "actor": "x402scan", "role": "Ecosystem explorer", "status": "Listed", "status_display": "Listed · checked 2026-11-06", "col4_md": "Explorer of x402 servers, volumes, and facilitator configuration.", "source_md": "[x402scan repository](https://github.com/Merit-Systems/x402scan) [46]" }, { "actor": "stablecoin.com x402 ecosystem", "role": "Ecosystem directory", "status": "Listed", "status_display": "Listed · checked 2026-11-06", "col4_md": "Directory of facilitators, payment schemes, and settlement chains.", "source_md": "[stablecoin.com x402 ecosystem](https://stablecoin.com/402/ecosystem) [47]" } ] } ], "censuses": [ { "label": "TRM Labs, Measuring AI Agent Payments Onchain", "as_of": "2026-09-09", "value_md": "TRM Labs measured roughly USD 52.7 million across 198.9 million settlement transactions mediated by known x402 facilitators across Base, Solana, and Polygon since May 2025, with USD 52.47 million of USD 52.68 million (99.6%) settled in USDC; across USD 25.62 million of anomaly-screened commerce, 0.6% to 7.5% matched strict-to-permissive autonomous agent criteria. [35]" }, { "label": "Chainalysis, Inside x402's Path to Meaningful Adoption", "as_of": "2026-06-03", "value_md": "Chainalysis reported that x402 transactions on Base crossed 100 million cumulative transactions over approximately three quarters through Q1 2026, with transactions of $1 or more representing 95% of total volume transferred (up from 49% in early 2025). [48]" }, { "label": "USENIX Security '26 (Wang et al., EPFL, Zhejiang University & Independent Researcher)", "as_of": "2026-08", "value_md": "Evaluated 15 major x402 facilitators collectively used by over 60,000 sellers and 360,000 buyers; the study formalized eight security rules for facilitator authorization correctness and execution safety and derived four attack vectors from rule violations—Free Shopping, Asset Theft, Service Denial, and Gas Abuse—across all evaluated facilitators, followed by responsible disclosure and vendor mitigations (including changes by Coinbase), alongside an empirical measurement of over 119M Base and Solana transactions. [26]" }, { "label": "Visa & Artemis (FinanceTracked, AI Agent Payments)", "as_of": "2026-04-21", "value_md": "A joint Visa and Artemis report (published July 16, 2026, with data through April 21, 2026) adjusted x402 organic volume to about `$15 million` across `109.6 million` transactions, roughly `422,000` buyers, and about `5,300` sellers after filtering wash and test activity. [49]" }, { "label": "V12 Security Audit & PR #3074 Settlement Buffering", "as_of": "2026-10-22", "value_md": "In a post published on Oct 22, 2026, V12 documented 25 vulnerabilities across x402 implementations (spanning payment bypass, session takeover, and token theft), after reporting 3 critical and 13 high severity findings to the x402 team on August 12, 2026 (with the 3 critical vulnerabilities fixed by August 20th); reference middleware merged pull request 3074 on Sep 4, 2026 (`PaymentFilter`) to buffer downstream HTTP response bodies until facilitator settlement succeeds. [25][50]" }, { "label": "Third-party live-knock index", "as_of": "2026-11-06", "value_md": "Lists 731 curated x402 services knocked before listing (including 348 in APIs & Services and 479 carrying a dated knock), noting that a knock represents a single HTTP response rather than an end-to-end delivery test. [51]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "s402", "target_name": "s402", "relation_label": "Deprecated → x402; formerly a Sui profile/extension of x402", "delta": "An HTTP 402 payment protocol for agents on Sui that carried x402 v2's `PaymentRequired` envelope in `payment-required` with Sui-specific fields in `extensions.s402` and added `prepaid`, `stream`, `escrow`, and `unlock` schemes; `s402` was retired in September 2026, directing new work to `x402`. [52][53]", "item_md": "**[s402](/protocols/s402/)** (Deprecated → x402; formerly a Sui profile/extension of x402) — An HTTP 402 payment protocol for agents on Sui that carried x402 v2's `PaymentRequired` envelope in `payment-required` with Sui-specific fields in `extensions.s402` and added `prepaid`, `stream`, `escrow`, and `unlock` schemes; `s402` was retired in September 2026, directing new work to `x402`. [52][53]" }, { "item_md": "**Peer alternatives:** [Agent Commerce Kit (ACK)](/protocols/agent-commerce-kit/), [Agentic Mobile Protocol (AMP)](/protocols/amp-ant/), [Agora (agent marketplace protocol)](/protocols/agora-commerce-protocol/), [ERC-8183: Agentic Commerce](/protocols/erc-8183/), [KYAPay Token](/protocols/kyapay-token/), [Trusted Agent Protocol (TAP)](/protocols/tap/)" }, { "item_md": "**Complements:** [Cloudflare Pay Per Crawl](/protocols/cloudflare-pay-per-crawl/), [Agent-Initiated Payment Gating](/protocols/agentic-payments-gating-model/), [agents.txt](/protocols/agents-txt/), [auth.md](/protocols/auth-md/), [Coral Protocol (CoralOS)](/protocols/coral-protocol/), [ERC-8444: Agentic Resource Discovery (ARD) Onchain](/protocols/erc-8444/), [VCAP: Verified Commerce for Agent Protocols](/protocols/vcap/), [x401: HTTP Proof Requirement Protocol](/protocols/x401/)" }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: x402\ntitle: \"x402\"\ntier: flagship\nlifecycle_status: active\ncategory: pay\nform: http-header\nwire_archetype: payments_onchain\nspec_url: https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md\nlast_checked: 2026-11-11\n---\n\n# x402\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** HTTP header (`http-header`) · **Last checked:** 2026-11-11\n\n> *For the reserved HTTP status code, see [HTTP 402 Payment Required](/terms/http-402-payment-required/). Not to be confused with [L402](/protocols/l402/) (`WWW-Authenticate: L402` macaroon and Lightning invoice) or [Machine Payments Protocol (MPP)](/protocols/mpp/). [1][2][3]*\n\n> **In brief:** x402 is an open payment protocol that lets AI agents and software clients pay per request for APIs, data feeds, and web content directly over HTTP, MCP, or A2A without human checkout flows. Instead of forcing developers to pre-register accounts, manage API keys, and maintain separate subscriptions with every provider, a server returns an HTTP `402 Payment Required` challenge with `PaymentRequirements` and fulfills the request as soon as the client attaches a signed `PaymentPayload`. [4][5][6]\n\n**x402** is an open payment standard originated by Coinbase on May 6, 2025 that enables applications and autonomous agents to pay resource servers inline for protected APIs, content, and data. [4][7] Its transport-independent core schemas (`PaymentRequirements`, `PaymentPayload`, and `SettlementResponse`) bind a `CAIP-2` network, atomic `amount`, and `asset` across HTTP, MCP, and A2A transports. On HTTP in v2, the server challenges an unpaid request with `402 Payment Required` and `PAYMENT-REQUIRED`, the client submits `PaymentPayload` in `PAYMENT-SIGNATURE`, verification (`POST /verify`) and settlement (`POST /settle`) execute according to `paymentFlow` (`authorization` by default, or `upfront` / `escrow`), and the server returns `PAYMENT-RESPONSE` on `200 OK`. [4][8][9] Announced December 11, 2025, `v2.0` (`2025-12-9`) replaced v1's HTTP 402 response body and `X-PAYMENT` / `X-PAYMENT-RESPONSE` headers with `CAIP-2` identifiers and `extensions`, and on April 2, 2026 the protocol transferred to the Linux Foundation's x402 Foundation under a Technical Steering Committee of Coinbase, Cloudflare, and Stripe. [4][8][9][10][11]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | HTTP header (`http-header`) |\n| **Originated by** | Coinbase (Erik Reppel, Nemil Dalal, Dan Kim; May 6, 2025); x402 Foundation co-founded with Cloudflare (September 23, 2025). [5][7] |\n| **Governed by** | x402 Foundation (Linux Foundation); Technical Steering Committee: Coinbase, Cloudflare, and Stripe; Executive Director: Michael Hursta. [11][12][13] |\n| **Track** | Foundation / Consortium Specification (`x402 a Series of LF Projects, LLC`, under Linux Foundation open governance). [12][14] |\n| **Status** | Production open standard; x402 Foundation operational under Linux Foundation (40 members at July 14, 2026 operational launch; 50+ member organizations by October 2026). [12][13] |\n| **Version** | v2.0 (specification header dated 2025-12-9; launched December 11, 2025; `specs/x402-specification-v2.md` on `main` revised through 2026-10-26 with `paymentFlow` and `auth-capture` additions without a version bump); v1 launched May 6, 2025. [4][7][9][15][16] |\n| **Headers** | v2: `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`; v1: `X-PAYMENT`, `X-PAYMENT-RESPONSE` (with HTTP 402 JSON body). [8][17] |\n| **Schemes** | `exact`, `upto`, `batch-settlement`, and `auth-capture` (`specs/schemes/`); payment flows: `authorization` (default), `upfront`, and `escrow`. [4] |\n| **Networks** | CAIP-2 identifiers (`namespace:reference`, e.g., `eip155:8453`) across EVM, Solana, TON, Algorand, Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui, and Canton. [18] |\n| **Transports** | HTTP/HTTPS, Model Context Protocol (MCP), and Agent-to-Agent (A2A) JSON-RPC task metadata. [4][17][19] |\n| **Message format** | Transport-specific JSON representations: Base64 JSON objects in HTTP headers; structured JSON objects in MCP `_meta` with text fallbacks. [4][20] |\n| **Token format** | On-chain token contract address (e.g., ERC-20 via EIP-3009/Permit2, SPL) or ISO 4217 fiat currency code. [4][18] |\n| **Specification** | [x402 Protocol Specification v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [v1](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md) [4][15] |\n| **Found at** | Per-resource HTTP 402 response headers; Facilitator `/verify`, `/settle`, `/supported`, and optional Bazaar `/discovery/resources` catalog. [4][21] |\n| **Licence** | Apache-2.0 [22] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Transport carriers for the payment objects](#transport-carriers-for-the-payment-objects)\n3. [Per-network exact payloads and sibling schemes](#per-network-exact-payloads-and-sibling-schemes)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nRFC 9110 reserves the 402 (Payment Required) status code for future use and defines no challenge or settlement record. Without a specification for how to format and respond to that status, publishers lack adequate tools to convey a payment request. Clients that interpret a defined protocol transact without accounts, subscriptions, or API keys. Automated clients otherwise pre-register with every API, manage keys, and maintain separate billing relationships. [1][5][6] x402 standardizes those messages. Each object in `accepts` is a `PaymentRequirements` record naming `scheme`, `network`, `amount`, `asset`, and `payTo`. The client submits a `PaymentPayload` whose `accepted` field is the chosen requirement and whose `payload` carries the scheme-specific signature. `POST /verify` validates payment state without writing onchain state, and `POST /settle` durably commits it, whether a facilitator or the resource server hosts the endpoints. The schemes specified from the core document are `exact`, `upto`, `batch-settlement`, and `auth-capture`. [4] Transport-specific implementations, framework-specific integrations, client-side budget management, and session handling mechanisms sit outside the core specification. Finding a resource is a separate surface: `GET /discovery/resources` lists Bazaar entries, and the discovered resources may use any x402-supported transport. [4]\n\n### Default authorization payment flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant RS as Resource Server\n participant Facilitator\n Client->>RS: 1. Client Request\n RS-->>Client: 2. Payment Required Response\n Client->>RS: 3. Payment Authorization Request\n Note over RS,Facilitator: authorization default: verify, then resource, then settle, then respond\n RS->>Facilitator: POST /verify\n Note over RS: Resource executes after read-only verify\n RS->>Facilitator: POST /settle\n RS-->>Client: 4. Settlement Response\n```\n\n*Default `authorization` flow. Read-only `/verify` runs before the resource executes, then `/settle`, then the settlement response. Because `/verify` is read-only and MUST NOT commit payment state or write onchain state, funds move only when `/settle` executes (`upfront` commits payment via `/settle` before the resource executes, and `escrow` runs an initial `/settle` before the resource executes). The resource server may host `/verify` and `/settle` itself. `upfront` and `escrow` are different orderings. [4]*\n\n### Canonical HTTP 402 PAYMENT-REQUIRED decoded payload (x402 v2)\n\n```json\n{\n \"x402Version\": 2,\n \"error\": \"PAYMENT-SIGNATURE header is required\",\n \"resource\": {\n \"url\": \"https://api.example.com/premium-data\",\n \"description\": \"Access to premium market data\",\n \"mimeType\": \"application/json\"\n },\n \"accepts\": [\n {\n \"scheme\": \"exact\",\n \"network\": \"eip155:84532\",\n \"amount\": \"10000\",\n \"asset\": \"0x036CbD53842c5426634e7929541eC2318f3dCF7e\",\n \"payTo\": \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\",\n \"maxTimeoutSeconds\": 60,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\"\n }\n }\n ]\n}\n```\n\n*Canonical `PaymentRequired` JSON object decoded from the base64 `PAYMENT-REQUIRED` HTTP `402` response header in the x402 v2 HTTP transport specification (`eip155:84532`, `exact` scheme, `10000` atomic `USDC` units). [17]*\n\n---\n\n## Transport carriers for the payment objects\n\nTransports share the `PaymentRequired`, `PaymentPayload`, and `SettlementResponse` schemas. While HTTP v2 encodes the challenge in the `PAYMENT-REQUIRED` response header, MCP, A2A, and HTTP v1 carry the same payment objects in transport-specific fields. [4][17][19][20]\n\n- **MCP tool-result challenge:** The server returns `isError` true with `PaymentRequired` in `structuredContent` and in `content[0].text`, defined as `JSON.stringify` of `structuredContent`. Clients read `structuredContent` when `x402Version` and `accepts` are present, and parse `content[0].text` otherwise. Failed verification and failed settlement use that same `isError` result. [20]\n- **MCP payment and receipt keys:** The client sends `PaymentPayload` in `_meta[\"x402/payment\"]` on the tool call. The server returns `SettlementResponse` in `_meta[\"x402/payment-response\"]`. If settlement fails after the tool has executed, the server sets `isError` true and should not return the tool content, only the payment error. [20]\n- **A2A task metadata:** The agent sets `state` to `input-required` and `x402.payment.status` to `payment-required`, with `PaymentRequired` in `x402.payment.required`. The client sends `PaymentPayload` in `x402.payment.payload` on `message/send` with `taskId`. Receipts are `SettlementResponse` values in `x402.payment.receipts`. Status moves through `payment-submitted`, `payment-verified`, `payment-completed`, `payment-failed`, and `payment-rejected`. [19]\n- **HTTP v1 fields and browser exposure:** The v1 body is a `PaymentRequirementsResponse` with `maxAmountRequired` and a network such as `base-sepolia`. v2 headers are not CORS-safelisted: `fetch` needs `Access-Control-Expose-Headers` to read `PAYMENT-REQUIRED` and `PAYMENT-RESPONSE`, and a preflight that allows `PAYMENT-SIGNATURE`. HTTP 400 is malformed input, HTTP 402 a failed check, and HTTP 500 a server fault. [8][17]\n\n---\n\n## Per-network exact payloads and sibling schemes\n\nA payment `scheme` defines how to construct the `payload` inside `PaymentPayload`, while `extra.paymentFlow` selects verification and settlement ordering (`authorization` by default). EVM `exact` sets `assetTransferMethod` to `eip3009` or `permit2`, where the facilitator acts solely as transaction broadcaster without modifying amount or destination, and Solana `exact` verifies an SPL token transfer instruction. [4][23][24] x402 supports tokens on EVM, Solana, TON, Algorand (AVM), Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui, and Canton networks, identified with CAIP-2 (`namespace:reference`). Newer families include Keeta (`keeta:21378`), Concordium, XRPL (`xrpl:0`), and Cardano. [18]\n\n- **EVM eip3009 transferWithAuthorization:** `eip3009` is the default `assetTransferMethod` for tokens with `transferWithAuthorization`. The `payload` carries a 65-byte `signature` and an `authorization` of `from`, `to`, `value`, `validAfter`, `validBefore`, and a 32-byte random `nonce`. `extra.name` and `extra.version` are the EIP-712 domain. The authorization is one-time use. Because facilitator `/verify` is read-only and does not lock funds or consume the `nonce` on-chain before `/settle` executes, concurrent requests carrying the same signed authorization can pass `/verify` before settlement (a race condition risk between simulation and execution) unless the server serializes or deduplicates on the `nonce`, buffers the response body until settlement succeeds (as in reference middleware pull request `3074`), or uses the `upfront` payment flow for irreversible actions. [4][23][25][26]\n- **EVM permit2 and the proxy witness:** `permit2` covers an ERC-20 without EIP-3009. The client signs `permitWitnessTransferFrom` with `spender` equal to `x402ExactPermit2Proxy`, so the witness binds the receiver. A one-time `approve` of Permit2 is paid by the user, sponsored via `erc20ApprovalGasSponsoring`, or replaced by an EIP-2612 signature that `settleWithPermit` submits under `eip2612GasSponsoring`. [23]\n- **Solana TransferChecked, memo nonce, and CPI:** SVM `exact` uses `spl-token` or `token-2022` `TransferChecked` for at least `PaymentRequirements.amount` of `asset` to `payTo`, top-level or as an inner `CPI`. Exactly one transfer must match. `extra.splits` gives each leg its own transfer, and a split `amount` must match exactly. The Memo holds `extra.memo` or a random nonce of at least 16 bytes (>= 16 bytes, hex-encoded). `ComputeBudgetProgram` allows `SetComputeUnitLimit` and `SetComputeUnitPrice`. `feePayer` must not appear in any instruction `accounts` list and must not be an authority, source, or delegate. [24]\n- **Sibling schemes and protocol extensions:** `upto` treats `amount` as the maximum at verification and the settled amount later. `batch-settlement` submits a cryptographic commitment, grants access immediately, and returns the charge in `PAYMENT-RESPONSE`. Backing is `capital-backed` (escrow, a channel, or a delegated wallet) or `credit-backed` (a billing identity), with `auth-capture` also named. Unconfirmed settlement sets `errorReason` to `settlement_pending` with a non-empty `transaction`. Published extensions add `builder-code` (appending ERC-8021 Schema 2 builder codes to settlement transaction calldata for on-chain attribution) and `payment-identifier` (making x402 payments idempotent across client retries). Two further extensions define Sign-In-With-X (`sign-in-with-x`, implementing CAIP-122 wallet authentication so prior payers access resources without repurchase) and `offer-receipt` (adding cryptographic proof-of-interaction to x402 payment flows). [4][27][28][29][30][31]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **HTTP 402 Payment Required** | `RFC 9110` | Profiles classic standard | RFC 9110 reserves HTTP 402 without wire headers; x402 v2 binds it to `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE`. [1][17] |\n| **EIP-712 Typed Data & EIP-3009 Transfer With Authorization** | `EIP-3009` | Profiles classic standard | x402's EVM `exact` scheme wraps an EIP-712 signature and EIP-3009 authorization parameters inside the transport `PaymentPayload`. [4][23] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Machine Payments Protocol (MPP)](/protocols/mpp/)** | Peer alternative | Co-authored by Stripe and Tempo for card and stablecoin machine payments alongside x402 in Stripe and AWS AgentCore. [3][32] |\n| **[L402](/protocols/l402/)** | Peer alternative | L402 challenges via `WWW-Authenticate: L402` with a macaroon and BOLT 11 Lightning invoice instead of CAIP-2 `PAYMENT-REQUIRED` headers. [2][17] |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Complements | AP2 verifies user-authorized agent mandates, while the `a2a-x402` extension settles on-chain cryptocurrency payments over A2A tasks. [33][34] |\n| **[Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/)** | Peer alternative | OpenAI and Stripe's ACP handles conversational merchant checkout, whereas x402 settles per-request API payments inline over HTTP 402. [35][36] |\n| **[ERC-8004: Trustless Agents](/protocols/erc-8004/)** | Complements | Defines on-chain Identity, Reputation, and Validation registries for cross-organization agent discovery; TRM Labs' strict x402 payment model uses `ERC-8004` registration as one attribution heuristic alongside multi-seller payment patterns. [35][37] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (13 probed or cited examples across 4 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Paywalled origins & API sellers\n\nFacilitator and resource-server rows reflect vendor-declared capabilities, documentation, and `/supported` or HTTP 402 endpoint probes rather than audited protocol conformance; see the USENIX Security '26 facilitator study and V12 audit in the ecosystem censuses and notes below. [26][38]\n\n| Actor | Role | Status | Observed challenge & accepted assets | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **CoinGecko** | Seller | Live (HTTP 402) · checked 2026-10-30 | HTTP 402 `PAYMENT-REQUIRED` (`x402Version` 2, `exact`) accepting USDC across Base, Solana, and Polygon. | [CoinGecko onchain pool search (HTTP 402)](https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools?query=weth) [39] · [x402 networks and token support](https://docs.x402.org/core-concepts/network-and-token-support) [18] |\n| **CoinMarketCap** | Seller | Live (HTTP 402) · checked 2026-10-30 | HTTP 402 `PAYMENT-REQUIRED` (`x402Version` 2, `exact`, `eip3009` / `permit2-exact`) on `eip155:8453` (USDC) and `eip155:56` (4 stablecoins). | [CoinMarketCap quotes (HTTP 402)](https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1) [40] |\n| **Bitrefill** | Seller | Live (HTTP 402) · checked 2026-10-30 | HTTP 402 `PAYMENT-REQUIRED` (`x402Version` 2, `exact`) on `eip155:8453`, `eip155:42161`, `eip155:137`, Solana, and Lightning (`bolt11`, `upfront`). | [Bitrefill gift-card search (HTTP 402)](https://api.bitrefill.com/x402/gift-cards/search?q=amazon) [41] · [x402 networks and token support](https://docs.x402.org/core-concepts/network-and-token-support) [18] |\n\n### Buyer harnesses & cloud runtimes\n\n| Actor | Role | Status | Runtime integration & payment flow | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **AWS (Amazon Bedrock AgentCore payments)** | Agent platform / runtime | Supported · as of 2026-08-18 | GA runtime supporting x402 `exact` and `upto` with Coinbase/Privy USDC wallets and AgentCore Gateway MCP discovery. | [AWS ML Blog (18 AUG 2026)](https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/) [32] |\n| **Cloudflare Agents SDK** | Agent SDK / runtime | Supported · as of 2026-08-04 | Supports x402 transactions in Cloudflare Agents SDK and MCP integrations, paired with Cloudflare Wallets for stablecoin payments. | [Cloudflare Blog (September 23, 2025)](https://blog.cloudflare.com/x402/) [5] · [Cloudflare Wallets (August 4, 2026)](https://blog.cloudflare.com/wallets/) [42] |\n| **Vercel x402-mcp** | SDK integration | Supported · as of 2025-09-12 | Integrates x402 payments into MCP servers and Vercel AI SDK alongside `x402-fetch` and `x402-next` middleware. | [Vercel Blog (12 Sep 2025)](https://vercel.com/blog/introducing-x402-mcp-open-protocol-payments-for-mcp-tools) [6] |\n\n### Payment facilitators, gateways & reference SDKs\n\n| Actor | Role | Status | Supported schemes, networks & surface | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Coinbase CDP Facilitator** | Payment rail (Originator) | Supported · as of 2026-10-30 | Hosted `exact`, `upto`, and `batch-settlement` facilitator on `eip155:8453`, `eip155:137`, `eip155:42161`, and Solana with OFAC/KYT screening. | [Coinbase CDP Facilitator](https://docs.cdp.coinbase.com/x402/seller/facilitator) [43] |\n| **Stripe** | Payment rail (TSC member) | Supported · as of 2026-10-30 | Accepts `exact` USDC on Base (`2026-05-27.preview` `transaction_verification`); requires Dashboard approval and US (ex-NY) or 30+ country eligibility. | [Stripe x402 docs](https://docs.stripe.com/payments/machine/x402) [3] · [Stripe Blog (March 12, 2026)](https://stripe.com/blog/10-lessons) [36] · [x402 Technical Steering Committee](https://github.com/x402-foundation/x402/blob/main/TSC.md) [11] |\n| **Cloudflare Monetization Gateway** | Platform | Experimental · as of 2026-09-30 | Closed-beta HTTP 402 edge paywall and AI Gateway (`Payment-Method: x402`) settling USDC on Base via Coinbase's Facilitator. | [Cloudflare Blog (September 30, 2026)](https://blog.cloudflare.com/monetization-gateway-beta/) [44] |\n| **x402 Go SDK** | Reference SDK | Supported · as of 2026-11-04 | Reference `go/v2` module implementing EVM (`exact`, `upto`, `batch-settlement`, `auth-capture`) and SVM (`exact`, `upto`, `batch-settlement`, `paymentchannels`) packages. | [pkg.go.dev x402 go/v2 (v2.30.0, Nov 4, 2026)](https://pkg.go.dev/github.com/x402-foundation/x402/go/v2) [45] |\n| **Google Cloud (a2a-x402)** | Protocol extension | Supported · as of 2025-09-16 | Carries x402 payloads over A2A JSON-RPC tasks via `x402.payment.required` and `x402.payment.payload` metadata in Python and TypeScript. | [Google Cloud Blog (September 16, 2025)](https://cloud.google.com/blog/products/ai-machine-learning/announcing-agents-to-payments-ap2-protocol) [33] · [a2a-x402 GitHub](https://github.com/google-agentic-commerce/a2a-x402) [34] · [x402 A2A transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/a2a.md) [19] |\n\n### Ecosystem explorers and directories\n\n| Actor | Role | Status | Index scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **x402scan** | Ecosystem explorer | Listed · checked 2026-11-06 | Explorer of x402 servers, volumes, and facilitator configuration. | [x402scan repository](https://github.com/Merit-Systems/x402scan) [46] |\n| **stablecoin.com x402 ecosystem** | Ecosystem directory | Listed · checked 2026-11-06 | Directory of facilitators, payment schemes, and settlement chains. | [stablecoin.com x402 ecosystem](https://stablecoin.com/402/ecosystem) [47] |\n\n### Ecosystem censuses\n\n- **TRM Labs, Measuring AI Agent Payments Onchain** (*as of 2026-09-09*): TRM Labs measured roughly USD 52.7 million across 198.9 million settlement transactions mediated by known x402 facilitators across Base, Solana, and Polygon since May 2025, with USD 52.47 million of USD 52.68 million (99.6%) settled in USDC; across USD 25.62 million of anomaly-screened commerce, 0.6% to 7.5% matched strict-to-permissive autonomous agent criteria. [35]\n- **Chainalysis, Inside x402's Path to Meaningful Adoption** (*as of 2026-06-03*): Chainalysis reported that x402 transactions on Base crossed 100 million cumulative transactions over approximately three quarters through Q1 2026, with transactions of $1 or more representing 95% of total volume transferred (up from 49% in early 2025). [48]\n- **USENIX Security '26 (Wang et al., EPFL, Zhejiang University & Independent Researcher)** (*as of 2026-08*): Evaluated 15 major x402 facilitators collectively used by over 60,000 sellers and 360,000 buyers; the study formalized eight security rules for facilitator authorization correctness and execution safety and derived four attack vectors from rule violations—Free Shopping, Asset Theft, Service Denial, and Gas Abuse—across all evaluated facilitators, followed by responsible disclosure and vendor mitigations (including changes by Coinbase), alongside an empirical measurement of over 119M Base and Solana transactions. [26]\n- **Visa & Artemis (FinanceTracked, AI Agent Payments)** (*as of 2026-04-21*): A joint Visa and Artemis report (published July 16, 2026, with data through April 21, 2026) adjusted x402 organic volume to about `$15 million` across `109.6 million` transactions, roughly `422,000` buyers, and about `5,300` sellers after filtering wash and test activity. [49]\n- **V12 Security Audit & PR #3074 Settlement Buffering** (*as of 2026-10-22*): In a post published on Oct 22, 2026, V12 documented 25 vulnerabilities across x402 implementations (spanning payment bypass, session takeover, and token theft), after reporting 3 critical and 13 high severity findings to the x402 team on August 12, 2026 (with the 3 critical vulnerabilities fixed by August 20th); reference middleware merged pull request 3074 on Sep 4, 2026 (`PaymentFilter`) to buffer downstream HTTP response bodies until facilitator settlement succeeds. [25][50]\n- **Third-party live-knock index** (*as of 2026-11-06*): Lists 731 curated x402 services knocked before listing (including 348 in APIs & Services and 479 carrying a dated knock), noting that a knock represents a single HTTP response rather than an end-to-end delivery test. [51]\n\n---\n\n## See also\n\n- **[s402](/protocols/s402/)** *(Deprecated → x402; formerly a Sui profile/extension of x402)* — An HTTP 402 payment protocol for agents on Sui that carried x402 v2's `PaymentRequired` envelope in `payment-required` with Sui-specific fields in `extensions.s402` and added `prepaid`, `stream`, `escrow`, and `unlock` schemes; `s402` was retired in September 2026, directing new work to `x402`. [52][53]\n- **Peer alternatives:** [Agent Commerce Kit (ACK)](/protocols/agent-commerce-kit/), [Agentic Mobile Protocol (AMP)](/protocols/amp-ant/), [Agora (agent marketplace protocol)](/protocols/agora-commerce-protocol/), [ERC-8183: Agentic Commerce](/protocols/erc-8183/), [KYAPay Token](/protocols/kyapay-token/), [Trusted Agent Protocol (TAP)](/protocols/tap/)\n- **Complements:** [Cloudflare Pay Per Crawl](/protocols/cloudflare-pay-per-crawl/), [Agent-Initiated Payment Gating](/protocols/agentic-payments-gating-model/), [agents.txt](/protocols/agents-txt/), [auth.md](/protocols/auth-md/), [Coral Protocol (CoralOS)](/protocols/coral-protocol/), [ERC-8444: Agentic Resource Discovery (ARD) Onchain](/protocols/erc-8444/), [VCAP: Verified Commerce for Agent Protocols](/protocols/vcap/), [x401: HTTP Proof Requirement Protocol](/protocols/x401/)\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. R. Fielding, M. Nottingham, and J. Reschke (eds.), *RFC 9110: HTTP Semantics* (June 2022) — \n2. Lightning Labs, *L402 Protocol Specification* (fetched 2026-10-30) — \n3. Stripe, *x402* (fetched 2026-10-30) — \n4. x402 Foundation, *x402 Protocol Specification* (v2.0 dated 2025-12-9) — \n5. Will Allen, Cam Whiteside, Rohin Lohe, and Steve James, Cloudflare, *Launching the x402 Foundation with Coinbase, and support for x402 transactions* (September 23, 2025) — \n6. Ethan Niser, Vercel, *Introducing x402-mcp: Open protocol payments for MCP tools* (12 Sep 2025) — \n7. Erik Reppel, Nemil Dalal, and Dan Kim, Coinbase, *Introducing x402: a new standard for internet-native payments* (May 6, 2025) — \n8. x402 Foundation, *HTTP transport for x402 v1* (fetched 2026-10-30) — \n9. Erik Reppel, Carson Roscoe, and Josh Nickerson, *Introducing x402 V2: Evolving the Standard for Internet-native Payments* (published December 11, 2025; updated June 24th, 2026) — \n10. Linux Foundation, *Linux Foundation is Launching the x402 Foundation and Welcoming the Contribution of the x402 Protocol* (April 2, 2026) — \n11. x402 Foundation, *Technical Steering Committee* (fetched 2026-10-30) — \n12. Linux Foundation, *Linux Foundation Announces Operational Launch of x402 Foundation to Standardize Internet-Native Payments for AI Agents and Applications* (July 14, 2026) — \n13. Linux Foundation, *Linux Foundation Appoints Michael Hursta as Executive Director of the x402 Foundation* (Oct. 1, 2026) — \n14. x402 Foundation, *x402* (fetched 2026-10-30) — \n15. x402 Foundation, *x402 Protocol Specification* (Protocol Version: 1) — \n16. x402 Foundation, *Commit history for specs/x402-specification-v2.md* (2026-10-26) — \n17. x402 Foundation, *HTTP transport for x402 v2* (fetched 2026-10-30) — \n18. x402 Foundation, *Networks and Token Support* (fetched 2026-10-30) — \n19. x402 Foundation, *Transport: A2A (Agent-to-Agent Protocol)* (fetched 2026-10-30) — \n20. x402 Foundation, *Transport: MCP (Model Context Protocol)* (fetched 2026-11-05) — \n21. x402 Foundation, *Bazaar (Discovery Layer)* (fetched 2026-10-30) — \n22. x402 Foundation, *x402* (Apache-2.0; fetched 2026-10-30) — \n23. x402 Foundation, *Exact Scheme Specification for EVM (EIP-3009 and Permit2)* (2026) — \n24. x402 Foundation, *Exact Scheme Specification for Solana SVM (SPL TransferChecked)* (2026) — \n25. x402 Foundation, *Pull Request #3074: Buffer response body until settlement succeeds in PaymentFilter* (2026-09-04) — \n26. Qinying Wang (EPFL), Yong Yang (Zhejiang University), Yuan Chen (Independent Researcher), Shouling Ji (Zhejiang University), and Mathias Payer (EPFL), *When HTTP 402 Meets the Blockchain: Risks on Emerging x402 Payments (USENIX Security '26)* (August 12–14, 2026) — \n27. x402 Foundation, *Batch-Settlement Scheme Specification* (2026-05) — \n28. x402 Foundation, *Builder Code (ERC-8021)* (fetched 2026-11-11) — \n29. x402 Foundation, *Payment-Identifier (Idempotency)* (fetched 2026-11-11) — \n30. x402 Foundation, *Sign-In-With-X (SIWX)* (fetched 2026-11-11) — \n31. x402 Foundation, *Signed Offers and Receipts* (fetched 2026-11-11) — \n32. Chethan Shriyan and Madhu Samhitha Vangara, AWS, *Amazon Bedrock AgentCore payments is now generally available* (18 AUG 2026) — \n33. Stavan Parikh and Rao Surapaneni, Google Cloud, *Announcing Agent Payments Protocol (AP2)* (September 16, 2025) — \n34. google-agentic-commerce/a2a-x402, *A2A x402 Extension* (fetched 2026-10-30) — \n35. Noah Hodge, TRM Labs, *Who's Actually Paying? Measuring AI Agent Payments Onchain* (September 9, 2026) — \n36. Roshan Sadanani, Stripe, *10 things we learned building for the first generation of agentic commerce* (March 12, 2026) — \n37. Ethereum Improvement Proposals, *ERC-8004: Trustless Agents* (2025-08-13) — \n38. x402 Foundation, *Facilitators* (fetched 2026-10-30) — \n39. CoinGecko, *Onchain DEX pool search* (HTTP 402; fetched 2026-10-30) — \n40. CoinMarketCap, *Cryptocurrency quotes latest* (HTTP 402; fetched 2026-10-30) — \n41. Bitrefill, *Gift-card search* (HTTP 402; fetched 2026-10-30) — \n42. Cloudflare, *Announcing Cloudflare Wallets: The programmable wallet for the agentic Internet* (August 4, 2026) — \n43. Coinbase Developer Platform, *CDP Facilitator* (fetched 2026-10-30) — \n44. Cloudflare, *Monetization Gateway beta: charge AI agents for consumption with HTTP 402* (September 30, 2026) — \n45. Go Packages, *github.com/x402-foundation/x402/go/v2* (v2.30.0, published Nov 4, 2026) — \n46. Merit Systems, *x402scan* (fetched 2026-11-06) — \n47. Stablecoin.com, *x402 ecosystem directory* (fetched 2026-11-06) — \n48. Chainalysis Team, *Agentic Payments Cross the Threshold: Inside x402's Path to Meaningful Adoption* (June 3, 2026) — \n49. Adewale Amure, FinanceTracked (citing Visa & Artemis), *AI Agent Payments: Where Does the Real Usage Lie?* (published 2026-09-18; citing Visa & Artemis report published July 16, 2026, data through 2026-04-21) — \n50. V12 Security, *25 Vulnerabilities in the x402 Protocol: Inside Three Critical Findings* (2026-10-22) — \n51. 24K Labs, *The Gold-402 Index* (fetched 2026-11-06) — \n52. s402, *s402 Wire Format Specification (retired September 2026)* (2026-09) — \n53. s402, *s402-protocol/core — AGENTS.md* (2026-09-04) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "L402", "adoption": { "level": "observed", "by": "Lightning Labs (Lightning Loop & Aperture), Lightning Enable, Alby (l402.space), Lightning Faucet, Tierion (boltwall), Lightning Labs (lnget, L402sdk, LangChainBitcoin), Alby (getAlby/cli), Lightning Enable (lightning-enable-mcp), and 2 other verified implementations", "probe_run": null }, "aliases": [ "LSAT" ], "analog": "HTTP 402 plus a bearer credential (like an API key you buy per-use)", "collisions": [], "discovery": { "mechanism": "HTTP 402 response carrying a WWW-Authenticate challenge", "path": "No fixed path: a resource signals L402 per request by answering HTTP 402 with an L402 WWW-Authenticate challenge" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://raw.githubusercontent.com/lightninglabs/L402/master/protocol-specification.md", "claim": "Lightning Labs, *L402 Protocol Specification*, fetched 2026-10-30", "date": null, "quote": "The L402 protocol was formerly known as LSAT. / WWW-Authenticate: L402 macaroon=\"\", invoice=\"\" / When a server requires payment for a resource, it MUST respond with HTTP 402 and include a WWW-Authenticate header / L402 combines the HTTP 402 Payment Required status code with Lightning Network invoice payments to create a challenge-response protocol for paid API access. / This document specifies the L402 authentication scheme for HTTP and gRPC. / the client pays the invoice to obtain a preimage, then presents the credential and preimage together as proof of payment. / When a server requires payment for a resource, it MUST respond with HTTP 402 and include a WWW-Authenticate header of the form: / invoice (REQUIRED): A BOLT 11 payment request. / Authorization: L402 : / Servers SHOULD send both LSAT and L402 scheme names in WWW-Authenticate challenge headers. / The LSAT header SHOULD appear first for compatibility with older client implementations. / Clients and servers MUST accept both LSAT and L402 in Authorization headers. / it MUST respond with HTTP 402 and include a WWW-Authenticate header / The scheme name is \"L402\" (case-insensitive). / L402 combines the HTTP 402 Payment Required status code with Lightning Network invoice payments / invoice (REQUIRED): A BOLT 11 payment request. The client MUST pay this invoice to obtain the preimage / The credential is a macaroon (an HMAC-chain bearer token) that cryptographically commits to the invoice's payment hash. / The L402 scheme is registered under the HTTP Authentication Framework specified in RFC 7235. / L402 Protocol Specification / Officially, the HTTP specification marks 402 as \"reserved for future use\", but this document assumes the future has arrived. / This binding enables stateless verification: the server checks H == sha256(preimage) against the hash embedded in the macaroon, with no database lookup required. / The 402 status code is used exclusively for the initial payment challenge. / Once a client presents a credential (valid or not), the server MUST respond with 401 if verification fails, not 402. / This distinction lets clients differentiate \"you need to pay\" from \"your credential is broken.\" / The macaroon MUST commit to the payment hash H of the invoice P in its identifier / The SHA-256 hash H of the preimage, embedded in both the Lightning invoice and the macaroon identifier. / The 32-byte value r such that sha256(r) equals the payment hash of the Lightning invoice. / The macaroon is base64-encoded; the preimage is hex-encoded. / verify macaroon, check H == sha256(r) / gRPC is transmitted over HTTP/2 but uses special trailing headers for protocol-specific information. / The gRPC specification requires a status code of 200 in all responses. / The server MUST reply with HTTP 200 OK (not 402). / Grpc-Message: missing L402 / Grpc-Status: 402 Example: text HTTP/2 200 OK / After validating the invoice, the client MUST pay the invoice over the Lightning Network to obtain the payment preimage r. / The client MUST construct an Authorization header per Section 5.2: / The client MUST re-issue the original HTTP request with the Authorization header attached. / Possession of the preimage proves the invoice was paid. / Caveat. A restriction appended to a macaroon's HMAC chain. / Caveats can encode service access, capabilities, expiration, volume limits, and other constraints. / Each successive caveat can only _narrow_ the macaroon's authority, never widen it. / Expiry date encoded as a caveat / Credential present but macaroon invalid or tampered | 401 | Unauthorized / Credential present but preimage does not match payment hash | 401 | Unauthorized / If a client provides a macaroon or preimage containing control characters, the server MUST treat it as an invalid L402 and respond with 401. / containing an authentication credential and a Lightning invoice / Lightning Network invoice payments", "ref": 1 }, { "label": "[2]", "url": "https://raw.githubusercontent.com/lightninglabs/L402/master/README.md", "claim": "Lightning Labs, *L402: Lightning HTTP 402 Protocol*, fetched 2026-10-30", "date": null, "quote": "Developed by Lightning Labs / No accounts, no passwords. / Users pay a Lightning invoice and receive a cryptographic credential. / No email, no sign-up form, no personal data collected. / Instead of choosing between free tiers and monthly subscriptions, users pay for exactly what they use. / boltwall: Node.js middleware-based authentication using L402 / lsat-js: JavaScript utility library for working with L402 credentials", "ref": 2 }, { "label": "[3]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "claim": "x402 Foundation, *x402 Protocol Specification*, protocol version 2; fetched 2026-10-30", "date": null, "quote": "x402 is an open payment standard that enables clients to pay for external resources. / the base64-encoded PAYMENT-REQUIRED response header / PAYMENT-SIGNATURE header is required", "ref": 3 }, { "label": "[4]", "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-operational-launch-of-x402-foundation-to-standardize-internet-native-payments-for-ai-agents-and-applications", "claim": "Linux Foundation, *Linux Foundation Announces Operational Launch of x402 Foundation to Standardize Internet-Native Payments for AI Agents and Applications*, July 14, 2026", "date": null, "quote": "x402 was started at Coinbase", "ref": 4 }, { "label": "[5]", "url": "https://mpp.dev/overview.md", "claim": "Tempo and Stripe, *What is MPP?*, fetched 2026-10-30", "date": null, "quote": "The Machine Payments Protocol (MPP) is an open protocol co-authored by Tempo and Stripe.", "ref": 5 }, { "label": "[6]", "url": "https://datatracker.ietf.org/doc/html/draft-httpauth-payment-01", "claim": "B. Ryan, J. Moxey, and T. Meagher (Tempo Labs); J. Weinstein and S. Kaliski (Stripe), *The \"Payment\" HTTP Authentication Scheme (draft-httpauth-payment-01 HTML)*, draft-httpauth-payment-01, September 2026", "date": null, "quote": "A WWW-Authenticate header with scheme \"Payment\" indicating the payment requirements for accessing a resource. / 402 indicates a payment barrier (initial challenge or retry needed) / 401 is reserved for authentication failures unrelated to payment / 403 indicates the payment succeeded but access is denied by policy / Servers MUST return 402 with a WWW-Authenticate: Payment header when payment is required or when a payment credential fails validation", "ref": 6 }, { "label": "[7]", "url": "https://www.rfc-editor.org/rfc/rfc9110.html", "claim": "R. Fielding, M. Nottingham, and J. Reschke (eds.), *RFC 9110: HTTP Semantics*, June 2022", "date": null, "quote": "The 402 (Payment Required) status code is reserved for future use. / A server that receives valid credentials that are not adequate to gain access ought to respond with the 403 (Forbidden) status code / The \"WWW-Authenticate\" response header field indicates the authentication scheme(s) and parameters applicable to the target resource.", "ref": 7 }, { "label": "[8]", "url": "https://lightning.engineering/posts/2020-03-30-lsat/", "claim": "Olaoluwa Osuntokun, Lightning Labs, *L402: Authentication and Payments for the Lightning-Native Web*, March 30, 2020", "date": null, "quote": "Today we're excited to announce the release of our draft of a specification for Lightning Service Authentication Tokens (L402). / Olaoluwa Osuntokun March 30, 2020", "ref": 8 }, { "label": "[9]", "url": "https://github.com/lightninglabs/L402", "claim": "Lightning Labs, *lightninglabs/L402 repository*, created 2020-02-07; fetched 2026-10-30", "date": null, "quote": "\"full_name\": \"lightninglabs/L402\" / \"created_at\": \"2020-02-07T20:53:31Z\" / \"license\": null", "ref": 9 }, { "label": "[10]", "url": "https://raw.githubusercontent.com/Roasbeef/blips/697ae354c205f1aacc450e72067c92a7f2467321/blip-0026.md", "claim": "Olaoluwa Osuntokun, Oliver Gugger, and Wilmer Paulino, *bLIP-0026: L402: The Lightning HTTP 402 Protocol*, created 2023-06-06", "date": null, "quote": "bLIP: 26 Title: L402: The Lightning HTTP 402 Protocol Status: Active / Status: Active Author: Olaoluwa Osuntokun <[email redacted]> Oliver Gugger <[email redacted]> Wilmer Paulino <[email redacted]> Created: 2023-06-06 / A valid response header MUST take the form of: WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\" / The L402 protocol is token-format agnostic: any authentication token that can commit to a payment hash may be used. / Author: Olaoluwa Osuntokun <[email redacted]> Oliver Gugger <[email redacted]> Wilmer Paulino <[email redacted]> / Created: 2023-06-06 / Status: Active / The current version is \"0\". / WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\" / Title: L402: The Lightning HTTP 402 Protocol / bLIP: 26 / License: CC0 / The server MUST reply with a challenge using the 200 OK status code. / Grpc-Message: payment required / Grpc-Status: 13 # Internal / Caveats of a version 0 macaroon are represented as key-value pairs encoded as a string where the key and value are separated by a single = character. / The caveat key is services, while the value consists of a comma-separated list of target services. / If multiple services caveats exist, then verification should ensure each occurrence of the caveat restricts more access than the previous. / In the case of an unknown caveat, its evaluation must be skipped by the authorizer as the macaroon holder can further attenuate the macaroon for other applications. / a macaroon holder is able to further attenuate a macaroon if they wish to share it with a third party under more restrictive permissions. / Servers SHOULD accept macaroon= in addition to token= when parsing client requests and WWW-Authenticate headers from upstream proxies.", "ref": 10 }, { "label": "[11]", "url": "https://github.com/lightning/blips/issues/26", "claim": "Lightning Specification (BOLTs), *Comments on lightning/blips pull request 26*, fetched 2026-10-30", "date": null, "quote": "\"created_at\": \"2026-03-11T23:30:58Z\", \"updated_at\": \"2026-03-11T23:30:58Z\", \"body\": \"So we've recently updated our L402 github page. We plan on continuing development of the protocol there. / \"login\": \"Roasbeef\" … \"created_at\": \"2026-03-11T23:30:58Z\" … We plan on continuing development of the protocol there.", "ref": 11 }, { "label": "[12]", "url": "https://github.com/lightninglabs/L402/commits", "claim": "Lightning Labs, *lightninglabs/L402 commits*, fetched 2026-10-30", "date": null, "quote": "\"date\": \"2026-03-20T18:38:52Z\" … \"message\": \"docs: revert BLIP-0026 header changes, remove legacy files / \"name\": \"Olaoluwa Osuntokun\", \"email\": \"[email redacted]\", \"date\": \"2026-03-20T18:38:52Z\" / docs: revert BLIP-0026 header changes, remove legacy files / Identifier structure: version (2 bytes), payment_hash (32 bytes), token_id (32 bytes), all big-endian, 66 bytes total for v0. / payment check (sha256(preimage) == payment_hash) / how each caveat extends the chain via sig_i = HMAC(sig_{i-1}, caveat_id_i), and why the resulting structure is both tamper-proof and append-only. / Caveat format and standard types: preimage, services (name:tier), capabilities, constraints (volume, timeout). / \"date\": \"2020-02-17T13:23:46Z\" … \"message\": \"Add link to third-party caveat issue\"", "ref": 12 }, { "label": "[13]", "url": "https://github.com/lightning/blips/pull/26", "claim": "Roasbeef, *blip-0026: L402 - Lightning HTTP 402 Protocol (lightning/blips pull request 26)*, opened 2023-06-07; fetched 2026-10-30", "date": null, "quote": "\"state\": \"open\" … \"title\": \"blip-0026: L402 - Lightning HTTP 402 Protocol \" … \"login\": \"Roasbeef\" … \"created_at\": \"2023-06-07T02:38:15Z\" … \"merged_at\": null / \"title\": \"blip-0026: L402 - Lightning HTTP 402 Protocol \" / \"state\": \"open\" / \"merged_at\": null", "ref": 13 }, { "label": "[14]", "url": "https://docs.lightning.engineering/lightning-network-tools/aperture", "claim": "Lightning Labs, *Aperture | Builder's Guide*, fetched 2026-10-30", "date": null, "quote": "Aperture is currently used in production in Lightning Loop and Pool. / Aperture is an implementation of L402s as a reverse HTTP proxy. / obtains a Macaroon and sends it together with a Lightning invoice and the HTTP status code 402 Payment Required. / Aperture implements both the L402 as well as the MPP specifications.", "ref": 14 }, { "label": "[15]", "url": "https://www.iana.org/assignments/http-authschemes/authschemes.csv", "claim": "IANA, *Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry*, last updated 2025-02-18; last-modified 2026-10-13", "date": null, "quote": "Last Updated 2025-02-18 / Basic,[RFC 7617], Bearer,[RFC 6750], Concealed,[RFC 9729], Digest,[RFC 7616], DPoP,\"[RFC 9449, Section 7.1]\", GNAP,\"[RFC 9635, Section 7.2]\", HOBA,\"[RFC 7486, Section 3]\",\"The HOBA scheme can be used with either HTTP servers or proxies. When used in response to a 407 Proxy Authentication Required indication, the appropriate proxy authentication header fields are used instead, as with any other HTTP authentication scheme.\" Mutual,[RFC 8120], Negotiate,\"[RFC 4559, Section 3]\",This authentication scheme violates both HTTP semantics (being connection-oriented) and syntax (use of syntax incompatible with the WWW-Authenticate and Authorization header field syntax). OAuth,\"[RFC 5849, Section 3.5.1]\", PrivateToken,\"[RFC 9577, Section 2]\", SCRAM-SHA-1,[RFC 7804], SCRAM-SHA-256,[RFC 7804], vapid,\"[RFC 8292, Section 3]\"", "ref": 15 }, { "label": "[16]", "url": "https://github.com/lightninglabs/aperture", "claim": "Lightning Labs, *Aperture*, checked 2026-11-06", "date": null, "quote": "\"name\": \"MIT License\", \"spdx_id\": \"MIT\" / is enabled with `--authenticator.enablempp`. It supports two intents.", "ref": 16 }, { "label": "[17]", "url": "https://raw.githubusercontent.com/Tierion/lsat-js/master/README.md", "claim": "Tierion, *LSAT-JS*, fetched 2026-10-30", "date": null, "quote": "Adding new first party caveats / condition: 'expiration', value: / addFirstPartyCaveat method available on the Lsat object. / lsat-js is a suite of tools for working with LSATs in Nodejs and Typescript. / after the invoice is paid, you can add the preimage", "ref": 17 }, { "label": "[18]", "url": "https://github.com/lightninglabs/L402/pull/16", "claim": "Liongrass, *Edit documentation to reflect naming changes (lightninglabs/L402 pull request 16)*, merged 2023-04-20", "date": null, "quote": "The LSAT protocol shall henceforth be known as the L402 protocol. / \"merged_at\": \"2023-04-20T22:57:13Z\"", "ref": 18 }, { "label": "[19]", "url": "https://github.com/lightninglabs/aperture/releases/tag/v0.5.0", "claim": "Lightning Labs, *Aperture v0.5.0*, published 2026-03-25", "date": null, "quote": "\"tag_name\": \"v0.5.0\" / \"published_at\": \"2026-03-25T20:08:06Z\" / merging WWW-Authenticate headers so a single 402 can advertise LSAT, L402, and Payment challenges simultaneously / merging `WWW-Authenticate` headers so a single 402 can advertise `LSAT`, `L402`, and `Payment` challenges simultaneously", "ref": 19 }, { "label": "[20]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification*, 2026-07-28", "date": "2026-07-28", "quote": "The protocol uses JSON-RPC 2.0 messages to establish communication between: / Servers : Services that provide context and capabilities", "ref": 20 }, { "label": "[21]", "url": "https://developers.cloudflare.com/ai-crawl-control/features/pay-per-crawl/what-is-pay-per-crawl/", "claim": "Cloudflare, *What is Pay Per Crawl?*, fetched 2026-10-31", "date": null, "quote": "or receive an HTTP 402 Payment Required response with pricing. / For pay per crawl, Cloudflare is the merchant of record.", "ref": 21 }, { "label": "[22]", "url": "https://raw.githubusercontent.com/lightninglabs/loop/master/swap_server_client.go", "claim": "Lightning Labs, *lightninglabs/loop swap_server_client.go*, fetched 2026-10-30", "date": null, "quote": "while delegating token acquisition and stream authentication to Aperture's", "ref": 22 }, { "label": "[23]", "url": "https://www.lightningenable.com/llms.txt", "claim": "Lightning Enable (Refined Element), *Lightning Enable llms.txt*, last-modified 2026-10-30", "date": null, "quote": "Lightning Enable wraps existing HTTP APIs with a small middleware so agents get a 402 Payment Required with a Lightning invoice / a Lightning invoice and a macaroon / Agent retries the same request with Authorization: L402 / 402 Payment Required with WWW-Authenticate: L402 macaroon=\"...\", invoice=\"...\". / merchants (and agents acting as sellers) create and verify challenges directly / Payouts land in the merchant's own Lightning wallet over Nostr Wallet Connect, or in a Strike or OpenNode account.", "ref": 23 }, { "label": "[24]", "url": "https://api.lightningenable.com/api/l402/content/nwc-wallet-integration.md", "claim": "Lightning Enable, *NWC wallet integration payment response*, fetched 2026-10-30", "date": null, "quote": "\"error\":\"Payment Required\" / \"amount_sats\":3919 / lnbc39190n1 / Include in request: Authorization: L402", "ref": 24 }, { "label": "[25]", "url": "https://l402.space/docs", "claim": "L402 Space, *Universal 402 Gateway - API docs*, fetched 2026-10-30", "date": null, "quote": "You pay the gateway over YOUR rail; the gateway pays the upstream API on your behalf over whichever rail THAT API speaks (x402/USDC, MPP Tempo, MPP Lightning, or L402) / Challenge: `WWW-Authenticate: L402 token=\"\", invoice=\"\"`.", "ref": 25 }, { "label": "[26]", "url": "https://l402.space/l402/ping", "claim": "L402 Space, *l402.space paid ping response*, fetched 2026-10-30", "date": null, "quote": "{\"error\":\"Payment required\",\"amountSats\":1", "ref": 26 }, { "label": "[27]", "url": "https://getalby.com/blog/402-charted-tracking-the-rise-of-l402-x402-and-mpp", "claim": "Alby, *402, Charted - Tracking the rise of L402, x402, and MPP*, published Aug 12, 2026", "date": null, "quote": "Published Aug 12, 2026 / l402.space is a universal 402 gateway between your agent's wallet and everyone else's rail. / L402 grew from 94 endpoints in February to a peak of 1,209 in May - roughly 13× - then held flat through June, ending the month at 1,201. / L402 providers remained relatively stable (36 to 29), consistent with the limited growth in L402 endpoints.", "ref": 27 }, { "label": "[28]", "url": "https://lightningfaucet.com/llms.txt", "claim": "Lightning Faucet, *Lightning Faucet llms.txt*, last-modified 2026-10-27", "date": null, "quote": "25+ pay-per-call endpoints, 5 to 500 sats", "ref": 28 }, { "label": "[29]", "url": "https://lightningfaucet.com/api/l402/onchain_fee", "claim": "Lightning Faucet, *Onchain fee payment response*, fetched 2026-10-30", "date": null, "quote": "\"message\": \"Payment required\" / \"price_sats\": 50 / lnbc500n1 / \"token\": / \"macaroon\": / Retry this request with header: Authorization: L402 :", "ref": 29 }, { "label": "[30]", "url": "https://raw.githubusercontent.com/Tierion/boltwall/master/README.md", "claim": "Tierion, *Boltwall*, fetched 2026-10-30", "date": null, "quote": "Bitcoin Lightning paywall and authentication using LSATs. / Your project must also use Expressjs", "ref": 30 }, { "label": "[31]", "url": "https://github.com/Tierion/boltwall", "claim": "Tierion, *Tierion/boltwall repository*, pushed 2023-04-26; fetched 2026-10-30", "date": null, "quote": "\"pushed_at\": \"2023-04-26T19:00:52Z\"", "ref": 31 }, { "label": "[32]", "url": "https://lightning.engineering/posts/2026-02-11-ln-agent-tools/", "claim": "Michael Levin, Lightning Labs, *The Agents Are Here and They Want to Transact: Powering the AI Economy with Lightning*, February 11, 2026", "date": null, "quote": "Michael Levin February 11, 2026 / Today's launch also includes lnget, an L402-aware command-line HTTP client", "ref": 32 }, { "label": "[33]", "url": "https://raw.githubusercontent.com/lightninglabs/lnget/main/README.md", "claim": "Lightning Labs, *lnget*, fetched 2026-10-30", "date": null, "quote": "If server returns 402 with WWW-Authenticate: L402 macaroon=\"...\", invoice=\"...\" / Verifies the invoice amount is within --max-cost / Pays the invoice via the configured Lightning backend / Stores the token (macaroon + preimage) for the domain", "ref": 33 }, { "label": "[34]", "url": "https://github.com/lightninglabs/L402sdk", "claim": "Lightning Labs, *L402sdk: L402 client SDK for AI agent frameworks*, fetched 2026-10-30", "date": null, "quote": "L402 client SDK for AI agent frameworks / Built in Rust with TypeScript and Python bindings.", "ref": 34 }, { "label": "[35]", "url": "https://github.com/lightninglabs/LangChainBitcoin", "claim": "Lightning Labs, *lightninglabs/LangChainBitcoin repository*, pushed 2024-07-03; fetched 2026-10-30", "date": null, "quote": "\"pushed_at\": \"2024-07-03T00:51:20Z\" / AI tools for giving LangChain agents access to Bitcoin and the ability to traverse L402 APIs", "ref": 35 }, { "label": "[36]", "url": "https://github.com/getAlby/cli/releases/tag/v0.4.0", "claim": "Alby, *getAlby/cli v0.4.0*, published 2026-04-07", "date": null, "quote": "\"tag_name\": \"v0.4.0\" / \"published_at\": \"2026-04-07T14:56:14Z\" / Add unified command to fetch L402, X402 & MPP resource", "ref": 36 }, { "label": "[37]", "url": "https://raw.githubusercontent.com/refined-element/lightning-enable-mcp/main/README.md", "claim": "Lightning Enable (Refined Element), *Lightning Enable MCP Server*, fetched 2026-10-30", "date": null, "quote": "Lightning Enable MCP Server / Automatically pay L402 challenges for seamless API access / needs a wallet that returns the payment preimage", "ref": 37 }, { "label": "[38]", "url": "https://raw.githubusercontent.com/lightningfaucet/lightning-wallet-mcp/main/README.md", "claim": "Lightning Faucet, *Lightning Wallet MCP*, fetched 2026-10-30", "date": null, "quote": "Your agent can pay for L402 and X402 APIs, pay any Lightning invoice or Lightning address, receive payments, and hold sats, all through natural language tool calls. / Pay any BOLT11 invoice; returns the preimage / Custodial, so there is nothing to run", "ref": 38 }, { "label": "[39]", "url": "https://github.com/Tierion/lsat-js", "claim": "Tierion, *Tierion/lsat-js repository*, pushed 2023-08-09; fetched 2026-10-30", "date": null, "quote": "\"pushed_at\": \"2023-08-09T14:13:30Z\"", "ref": 39 }, { "label": "[40]", "url": "https://docs.lightning.engineering/the-lightning-network/l402/implementations-and-links", "claim": "Lightning Engineering, *Implementations and Links*, checked 2026-11-06", "date": null, "quote": "Satring, a repository for L402 endpoints / WoT Scoring, an L402-gated way to discover Nostr networks of trust / Lightning Pool / Lightning Loop / L402 Playground", "ref": 40 }, { "label": "[41]", "url": "https://satsforbots.com/directory/", "claim": "Sats for Bots, *Directory*, checked 2026-11-06", "date": null, "quote": "Lightning Labs' 7 open-source agent skills + MCP server to run a node, pay L402 APIs and host paid endpoints / L402 reverse proxy that gates any API behind Lightning payments, now with metered (pay-per-token) pricing and Wavelength-backed invoices / MCP server connecting an agent to a Lightning wallet via Nostr Wallet Connect / Decentralized AI inference router: access top AI models with Bitcoin Lightning payments, permissionless and private / PayPerQ: pay-per-prompt access to hundreds of AI models with no subscription or registration; featured as a Bitcoin Lightning app / Open-source, non-custodial Lightning wallet for autonomous agents: runs its own node, pays L402 APIs via CLI or a 25-tool MCP server / Lightning Labs' Rust L402 client SDK with TypeScript, Python, Vercel AI SDK and LangChain bindings and spend budgets / Python SDK for agent-to-agent and agent-to-merchant Lightning payments over your own LND, with an L402 client and Nostr coordination / Official MCP server for Spark wallets: agents create and pay Lightning invoices. / Second's MCP server that gives agents a Bark (barkd) wallet: pay Lightning invoices and L402 APIs", "ref": 41 }, { "label": "[42]", "url": "https://www.l402.directory/", "claim": "L402.directory, *Discover Lightning-Gated APIs*, checked 2026-11-06", "date": null, "quote": "Browse services: GET /api/services — returns all active L402 service listings with endpoints, pricing, and health status. / Protocol docs: GET /api — returns the full L402 protocol specification, endpoint reference, and agent quickstart guide. / ### First Channel Suggestion FREE / ### Unlock a Video 10 sats", "ref": 42 } ], "form": "http-header", "governance": "Lightning Labs (single vendor). The text lives in the lightninglabs/L402 repository on GitHub; on 2026-03-11 (UTC) Osuntokun wrote of that repository: \"We plan on continuing development of the protocol there.\". It was also submitted to the Lightning bLIP repository as PR #26, opened 2023-06-07 (UTC) and still open and unmerged on 2026-10-29. GitHub lists no licence for the L402 repository; the bLIP text is CC0", "group": "HTTP 402 family", "history": [ { "date": "2026-09-06", "note": "verified against lightninglabs/L402 README.md and protocol-specification.md on GitHub" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "l402", "implementation": "shipping", "last_verified": "2026-11-06", "name": "L402", "native_status": "In production use: Lightning Labs said in 2020 that Aperture was \"used in production today by Lightning Loop\". The bLIP header reads \"bLIP: 26 Title: L402: The Lightning HTTP 402 Protocol Status: Active\" although the PR is not merged", "origin": { "org": "Lightning Labs. The specification repository was created on 2020-02-07 (UTC); Olaoluwa Osuntokun announced the draft specification and the Aperture proxy on 2020-03-30. The bLIP version lists Olaoluwa Osuntokun, Oliver Gugger and Wilmer Paulino as authors", "date": null }, "part_of": null, "parties": [ "agent-site", "agent-payment" ], "phase": "living", "probe": { "method": "GET", "on_absent": "A 200, 401, or a 402 without an L402-scheme WWW-Authenticate header means this path does not issue L402 challenges; the credential scheme is registered under RFC 7235 so a server could in principle offer it alongside other schemes on the same 401/402 responses.", "parse": "HTTP 402 status with a WWW-Authenticate: L402 macaroon=\"...\", invoice=\"...\" header", "path": "{origin}/{paid-path}" }, "question": "How can a client pay for, and then authenticate to, a metered API resource over the Lightning Network with no accounts or database-backed sessions?", "scope": "payments", "spec_url": "https://raw.githubusercontent.com/lightninglabs/L402/master/protocol-specification.md", "step": "pay", "summary_md": "**L402** (formerly Lightning Service Authentication Tokens, or `LSAT`) is an HTTP and gRPC challenge-response authentication scheme originated by Lightning Labs that combines HTTP 402 (`Payment Required`) responses with Lightning Network invoices for paid API access. First committed to `lightninglabs/L402` on 2020-02-07 and announced by Olaoluwa Osuntokun on 2020-03-30, it pairs a bearer credential with a Lightning invoice so a client can pay for a preimage and present both as proof of payment. When a server requires payment for a resource, the master specification requires an HTTP 402 response carrying `WWW-Authenticate: L402 macaroon=\"\", invoice=\"\"`, and the client retries the request with `Authorization: L402 :`. For backward compatibility after the rename from `LSAT`, servers should send both `LSAT` and `L402` challenges and both parties must accept either scheme in `Authorization`. A token-agnostic revision (`bLIP-0026`, created 2023-06-06) uses `WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\"`, while active development continues in `lightninglabs/L402` (which reverted the `bLIP-0026` header changes on 2026-03-20).", "track": "single-vendor", "version": { "label": "No numbered release", "date": null }, "watch": [ { "type": "github", "repo": "lightninglabs/L402", "mode": "release" } ], "use_cases": [ "accept-agent-payments", "delegate-user-authority", "expose-tools-to-agents" ], "audience": [ "agent-builder", "platform", "site-owner" ], "pairs_with": [ "x402", "mpp", "mcp", "cloudflare-pay-per-crawl" ], "prerequisites": [], "hatnote_md": "This page is about L402 (formerly LSAT), the Lightning Labs HTTP 402 authentication and payment scheme. It is not [x402](https://agenticweb.wiki/protocols/x402/), the open payment protocol originated at Coinbase; not [MPP](https://agenticweb.wiki/protocols/mpp/), the Machine Payments Protocol co-authored by Tempo and Stripe using the Payment authentication scheme; and not the bare HTTP 402 status code in RFC 9110 (see [HTTP 402 Payment Required](https://agenticweb.wiki/terms/http-402-payment-required/)).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-06", "v05_hatnote_html_md": "This page is about L402 (formerly LSAT), the Lightning Labs HTTP 402 authentication and payment scheme. It is not [x402](/protocols/x402/), the open payment protocol originated at Coinbase; not [MPP](/protocols/mpp/), the Machine Payments Protocol co-authored by Tempo and Stripe using the Payment authentication scheme; and not the bare HTTP 402 status code in RFC 9110 (see [HTTP 402 Payment Required](/terms/http-402-payment-required/)). [1][2][3][4][5][6][7]", "v05_elevator_pitch_md": "L402 is a payment-gated authentication protocol for HTTP and gRPC APIs that lets autonomous agents and software clients pay per request over the Bitcoin Lightning Network without registering user accounts or storing static API keys. Instead of gating endpoints behind interactive sign-up flows and monthly subscriptions, a server returns an HTTP 402 `WWW-Authenticate` challenge containing a `macaroon` token and a BOLT 11 `invoice`, and the caller unlocks access by returning `Authorization: L402 :` once paid. [1][2]", "v05_lead_md": "**L402** (formerly Lightning Service Authentication Tokens, or `LSAT`) is an HTTP and gRPC challenge-response authentication scheme originated by Lightning Labs that combines HTTP 402 (`Payment Required`) responses with Lightning Network invoices for paid API access. [1][2][8] First committed to `lightninglabs/L402` on 2020-02-07 and announced by Olaoluwa Osuntokun on 2020-03-30, it pairs a bearer credential with a Lightning invoice so a client can pay for a preimage and present both as proof of payment. [1][8][9] When a server requires payment for a resource, the master specification requires an HTTP 402 response carrying `WWW-Authenticate: L402 macaroon=\"\", invoice=\"\"`, and the client retries the request with `Authorization: L402 :`. [1] For backward compatibility after the rename from `LSAT`, servers should send both `LSAT` and `L402` challenges and both parties must accept either scheme in `Authorization`. [1] A token-agnostic revision (`bLIP-0026`, created 2023-06-06) uses `WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\"`, while active development continues in `lightninglabs/L402` (which reverted the `bLIP-0026` header changes on 2026-03-20). [9][10][11][12]", "v05_identity_sentence_md": "**L402** (formerly Lightning Service Authentication Tokens, or `LSAT`) is an HTTP and gRPC challenge-response authentication scheme originated by Lightning Labs that combines HTTP 402 (`Payment Required`) responses with Lightning Network invoices for paid API access. [1][2][8] First committed to `lightninglabs/L402` on 2020-02-07 and announced by Olaoluwa Osuntokun on 2020-03-30, it pairs a bearer credential with a Lightning invoice so a client can pay for a preimage and present both as proof of payment. [1][8][9]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "HTTP header (`http-header`)" }, { "label": "Originated by", "value_md": "Lightning Labs (repo 2020-02-07). Osuntokun, Gugger, and Paulino authored bLIP-0026 (2023-06-06). [2][8][9][10]" }, { "label": "Governed by", "value_md": "Lightning Labs repo lightninglabs/L402. Roasbeef plans to continue development there. [2][9][11][13]" }, { "label": "Track", "value_md": "Lightning Labs text in lightninglabs/L402. bLIP-0026 is an open lightning/blips pull request. [2][9][13]" }, { "label": "Status", "value_md": "bLIP-0026 is Status: Active. Aperture is in production in Loop and Pool. PR 26 is unmerged. [10][13][14]" }, { "label": "Version", "value_md": "Master branch omits a version parameter; pinned bLIP-0026 snapshot uses version=\"0\". [1][10][12]" }, { "label": "Headers", "value_md": "Master challenge is macaroon plus invoice; bLIP snapshot uses version, token, and invoice. Authorization carries the preimage. [1][10]" }, { "label": "Schemes", "value_md": "L402 is case-insensitive (formerly LSAT). Servers SHOULD send both; clients and servers MUST accept both. [1]" }, { "label": "Networks", "value_md": "Lightning Network. The invoice is a BOLT 11 payment request paid for the preimage. [1]" }, { "label": "Transports", "value_md": "HTTP and gRPC. [1]" }, { "label": "Token format", "value_md": "Master credential is an HMAC-chain macaroon. The bLIP-0026 snapshot is token-format agnostic. [1][10]" }, { "label": "IANA registration", "value_md": "Spec claims RFC 7235 registration. The 2025-02-18 IANA scheme list does not name L402. [1][15]" }, { "label": "Specification", "value_md": "Master [L402 spec](https://raw.githubusercontent.com/lightninglabs/L402/master/protocol-specification.md) and pinned [bLIP-0026](https://raw.githubusercontent.com/Roasbeef/blips/697ae354c205f1aacc450e72067c92a7f2467321/blip-0026.md) snapshot. [1][10]" }, { "label": "Found at", "value_md": "No fixed path. A paid resource MUST return HTTP 402 with WWW-Authenticate. [1]" }, { "label": "Licence", "value_md": "lightninglabs/L402 `license` is null. bLIP-0026 is CC0. Aperture is MIT. [9][10][16]" } ], "v05_problem_md": "Although the HTTP specification historically marked status code 402 as reserved for future use, conventional API monetization forces callers through user accounts, passwords, sign-up forms, and monthly subscriptions rather than accountless, per-request payments where users pay only for what they use. [1][2] The credential is a macaroon (an HMAC-chain bearer token) that cryptographically commits to the invoice's payment hash. This binding enables stateless verification: the server checks `H == sha256(preimage)` against the hash embedded in the macaroon, with no database lookup required. [1] The 402 status code is used exclusively for the initial payment challenge. Once a client presents a credential (valid or not), the server MUST respond with 401 if verification fails, not 402. This distinction lets clients differentiate \"you need to pay\" from \"your credential is broken.\" [1]", "v05_mechanism_delta_md": "The credential is a macaroon (an HMAC-chain bearer token) that cryptographically commits to the invoice's payment hash. This binding enables stateless verification: the server checks `H == sha256(preimage)` against the hash embedded in the macaroon, with no database lookup required. [1]", "v05_scope_boundary_md": "The 402 status code is used exclusively for the initial payment challenge. Once a client presents a credential (valid or not), the server MUST respond with 401 if verification fails, not 402. This distinction lets clients differentiate \"you need to pay\" from \"your credential is broken.\" [1]", "v05_fuzzy_additions": [ { "id": "http-402-challenge-macaroon-identifier-and-preimage-authorization", "heading": "HTTP 402 challenge, macaroon identifier, and preimage authorization", "body_md": "The `lightninglabs/L402` master specification and `bLIP-0026` define two parameter variants for the `L402` `WWW-Authenticate` challenge header: master binds a base64 macaroon and BOLT 11 `invoice` via `WWW-Authenticate: L402 macaroon=\"\", invoice=\"\"`, whereas `bLIP-0026` specifies a versioned, token-agnostic format (`WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\"` with current version `\"0\"`). [1][10]", "bullets": [ { "label": "66-byte identifier", "text_md": "In the macaroon specification for v0, the binary macaroon identifier is 66 bytes in big-endian layout: a 2-byte version, a 32-byte `payment_hash` (`H`, the SHA-256 hash of preimage `r`), and a 32-byte `token_id`. The master specification requires the macaroon identifier to commit to the payment hash `H` of the BOLT 11 invoice `P`. [1][12]" }, { "label": "Authorization and preimage check", "text_md": "To authenticate a paid request, the client sends `Authorization: L402 :` combining the base64-encoded macaroon and hex-encoded preimage. The server verifies the macaroon's HMAC chain and checks that the SHA-256 digest of the preimage matches the embedded payment hash (`sha256(preimage) == payment_hash`, written `H == sha256(r)` in the overview). [1][12]" }, { "label": "gRPC 200 OK trailer", "text_md": "Because the gRPC wire protocol over HTTP/2 requires an HTTP `200 OK` status code on all responses, a gRPC server issuing an L402 challenge replies with HTTP `200 OK` and attaches the challenge in trailing headers (`Grpc-Message: missing L402` and `Grpc-Status: 402` on master, or `Grpc-Status: 13` in `bLIP-0026`). [1][10]" }, { "label": "Client payment and retry", "text_md": "After validating the invoice, the client MUST pay it over the Lightning Network to obtain preimage r, MUST construct the `Authorization` header, and MUST re-issue the original request with that header attached. Possession of the preimage proves the invoice was paid. [1]" } ] }, { "id": "first-party-caveats-lsat-rename-compatibility-and-aperture-dual-scheme-proxy", "heading": "First-party caveats, LSAT rename compatibility, and Aperture dual-scheme proxy", "body_md": "A caveat is an append-only restriction added to a macaroon's HMAC chain that encodes service access, capabilities, volume limits, or expiration, where each successive caveat can only narrow the token's authority. Client libraries such as `lsat-js` append first-party caveats (including `expiration` conditions) using `addFirstPartyCaveat`. [1][17]", "bullets": [ { "label": "HMAC chain and tier caveats", "text_md": "Each caveat extends the HMAC signature chain via `sig_i = HMAC(sig_{i-1}, caveat_id_i)`, producing a tamper-proof, append-only credential. Standard caveat types cover `services` (`name:tier`), capabilities, volume or timeout constraints, and expiry dates; in `bLIP-0026`, version 0 caveats are `=`-separated key-value strings where multiple `services` caveats must progressively narrow access. [1][10][12]" }, { "label": "Macaroon attenuation and unknown caveats", "text_md": "A macaroon holder can attenuate a credential by appending more restrictive first-party caveats before sharing it with a third party, while third-party caveats have been tracked as an open issue since 2020-02-17. Under `bLIP-0026`, an authorizer must skip evaluation of any unknown caveat so holders can add downstream application-specific restrictions. [10][12]" }, { "label": "LSAT scheme transition", "text_md": "Pull request #16 (merged 2023-04-20) formally renamed `LSAT` to `L402`. For compatibility with older clients, servers should emit the `LSAT` challenge header before `L402` in `WWW-Authenticate` responses, both parties must accept either scheme in `Authorization`, and `bLIP-0026` recommends accepting `macaroon=` alongside `token=` when parsing upstream proxy headers. [1][10][18]" }, { "label": "401, 403, and Aperture v0.5.0", "text_md": "When a presented credential has a tampered macaroon, a mismatched preimage, or control characters, the server responds with HTTP 401 Unauthorized, whereas RFC 9110 and the IETF `Payment` scheme draft use HTTP 403 Forbidden when a valid credential is denied by policy. In Aperture `v0.5.0` (published 2026-03-25, with MPP enabled via `--authenticator.enablempp`), the proxy merges `WWW-Authenticate` headers so a single HTTP 402 response advertises `LSAT`, `L402`, and `Payment` challenges together. [1][6][7][16][19]" } ] } ], "v05_diagram": { "title": "Payment challenge", "heading": "Payment challenge", "mermaid": "sequenceDiagram\n participant C as Client\n participant S as Server\n participant LN as Lightning Network\n\n C->>S: GET /resource\n S-->>C: 402 Payment Required
WWW-Authenticate: L402 macaroon=\"M\", invoice=\"P\"\n C->>LN: pay(P)\n LN-->>C: preimage r\n C->>S: GET /resource
Authorization: L402 M:r\n S->>S: verify macaroon, check H == sha256(r)\n S-->>C: 200 OK + resource", "caption_md": "The client gets `402 Payment Required` with `WWW-Authenticate: L402`, pays the invoice, and retries with `Authorization: L402`. The server checks `H == sha256(r)`. [1]" }, "v05_wire_artifact": { "title": "`HTTP 402` with `WWW-Authenticate: L402`", "heading": "`HTTP 402` with `WWW-Authenticate: L402`", "lang": "http", "code": "HTTP/1.1 402 Payment Required\nDate: Mon, 04 Feb 2014 16:50:53 GMT\nWWW-Authenticate: L402 macaroon=\"AGIAJEemVQUTEyNCR0exk7ek90Cg==\", invoice=\"lnbc1500n1pw5kjhmpp5fu6xhthlt2vucmzkx6c7wtlh2r625r30cyjsfqhu8rsx4xpz5lwqdpa2fjkzep6yptksct5yp5hxgrrv96hx6twvusycn3qv9jx7ur5d9hkugr5dusx6cqzpgxqr23s79ruapxc4j5uskt4htly2salw4drq979d7rcela9wz02elhypmdzmzlnxuknpgfyfm86pntt8vvkvffma5qc9n50h4mvqhngadqy3ngqjcym5a\"", "caption_md": "`HTTP/1.1 402 Payment Required` carries `WWW-Authenticate: L402` with `macaroon` and `invoice`. [1]" }, "v05_counterparts": { "classic_analogues": [ { "name": "HTTP 402 Payment Required (RFC 9110 §15.5.3)", "spec_or_rfc": "RFC 9110 §15.5.3", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "RFC 9110 reserves 402 for future use. L402 uses it as the initial Lightning payment challenge. [1][7]" }, { "name": "WWW-Authenticate (RFC 9110 §11.6.1)", "spec_or_rfc": "RFC 9110 §11.6.1", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "RFC 9110 defines WWW-Authenticate for the scheme and its parameters. L402 carries a macaroon and BOLT 11 invoice. [1][7][10]" } ], "agentic_peers": [ { "target_id": "x402", "target_name": "x402", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "x402 sends PAYMENT-REQUIRED and requires PAYMENT-SIGNATURE. L402 uses WWW-Authenticate and Authorization with a macaroon. [1][3]" }, { "target_id": "mpp", "target_name": "Machine Payments Protocol (MPP)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "MPP challenges with scheme Payment. L402's scheme is L402, and clients and servers MUST accept LSAT too. [1][5][6]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "MCP uses JSON-RPC 2.0 among hosts, clients, and servers. L402 is a separate HTTP and gRPC auth scheme. [1][20]" }, { "target_id": "cloudflare-pay-per-crawl", "target_name": "Cloudflare Pay Per Crawl", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Pay Per Crawl returns HTTP 402 pricing with Cloudflare as merchant. L402 returns a macaroon and BOLT 11 invoice. [1][21]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (10 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Sellers, reverse proxies & payment processors", "col4_header": "`WWW-Authenticate: L402` challenge, macaroon & Lightning invoice", "note_md": null, "rows": [ { "actor": "Lightning Labs (Lightning Loop & Aperture)", "role": "Seller & reverse proxy (Originator)", "status": "Supported", "status_display": "Supported · as of 2026-03-25", "col4_md": "Aperture `v0.5.0` proxies L402 in Loop and Pool, merging LSAT and Payment on one 402.", "source_md": "[Aperture \\| Builder's Guide (fetched 2026-10-30)](https://docs.lightning.engineering/lightning-network-tools/aperture) [14] · [Aperture v0.5.0 (published 2026-03-25)](https://github.com/lightninglabs/aperture/releases/tag/v0.5.0) [19] · [lightninglabs/loop swap_server_client.go (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/loop/master/swap_server_client.go) [22]" }, { "actor": "Lightning Enable", "role": "Seller & payment processor", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "Wraps APIs with a 402 macaroon invoice; probed `amount_sats` 3919.", "source_md": "[Lightning Enable llms.txt (fetched 2026-10-30)](https://www.lightningenable.com/llms.txt) [23] · [NWC wallet integration response (fetched 2026-10-30)](https://api.lightningenable.com/api/l402/content/nwc-wallet-integration.md) [24]" }, { "actor": "Alby (l402.space)", "role": "Seller & cross-rail gateway", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "Universal 402 gateway; `/l402/ping` returns `amountSats` 1.", "source_md": "[l402.space docs (fetched 2026-10-30)](https://l402.space/docs) [25] · [l402.space/l402/ping (fetched 2026-10-30)](https://l402.space/l402/ping) [26] · [Alby, 402, Charted (Aug 12, 2026)](https://getalby.com/blog/402-charted-tracking-the-rise-of-l402-x402-and-mpp) [27]" }, { "actor": "Lightning Faucet", "role": "Seller", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "Pay-per-call seller; `onchain_fee` probe is `price_sats` 50.", "source_md": "[lightningfaucet.com/llms.txt (fetched 2026-10-30)](https://lightningfaucet.com/llms.txt) [28] · [onchain fee response (fetched 2026-10-30)](https://lightningfaucet.com/api/l402/onchain_fee) [29]" }, { "actor": "Tierion (boltwall)", "role": "Server middleware", "status": "Listed", "status_display": "Listed · as of 2023-04-26", "col4_md": "Express LSAT paywall middleware; repo pushed 2023-04-26.", "source_md": "[Tierion/boltwall README (fetched 2026-10-30)](https://raw.githubusercontent.com/Tierion/boltwall/master/README.md) [30] · [Tierion/boltwall repository (pushed 2023-04-26)](https://github.com/Tierion/boltwall) [31] · [L402 README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/L402/master/README.md) [2]" } ] }, "side_b": { "visible": true, "heading": "Buying agents, wallets & client SDKs", "col4_header": "Preimage proof, wallet backend & MCP/SDK surface", "note_md": null, "rows": [ { "actor": "Lightning Labs (lnget, L402sdk, LangChainBitcoin)", "role": "Client CLI & SDKs (Originator)", "status": "Partial", "status_display": "Partial · as of 2026-02", "col4_md": "lnget handles HTTP 402; L402sdk and LangChainBitcoin are client libraries.", "source_md": "[Michael Levin, Lightning Labs (February 11, 2026)](https://lightning.engineering/posts/2026-02-11-ln-agent-tools/) [32] · [lnget README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/lnget/main/README.md) [33] · [lightninglabs/L402sdk (fetched 2026-10-30)](https://github.com/lightninglabs/L402sdk) [34] · [lightninglabs/LangChainBitcoin (pushed 2024-07-03)](https://github.com/lightninglabs/LangChainBitcoin) [35]" }, { "actor": "Alby (getAlby/cli)", "role": "Wallet CLI", "status": "Supported", "status_display": "Supported · as of 2026-04-07", "col4_md": "`v0.4.0` (2026-04-07) fetches L402, X402, and MPP resources.", "source_md": "[getAlby/cli v0.4.0 (published 2026-04-07)](https://github.com/getAlby/cli/releases/tag/v0.4.0) [36]" }, { "actor": "Lightning Enable (lightning-enable-mcp)", "role": "Client MCP server", "status": "Partial", "status_display": "Partial · as of 2026-10-30", "col4_md": "Main-branch MCP server pays L402 via Strike, NWC, or LND preimage.", "source_md": "[refined-element/lightning-enable-mcp README (fetched 2026-10-30)](https://raw.githubusercontent.com/refined-element/lightning-enable-mcp/main/README.md) [37]" }, { "actor": "Lightning Faucet (lightning-wallet-mcp)", "role": "Custodial agent wallet", "status": "Partial", "status_display": "Partial · as of 2026-10-30", "col4_md": "Custodial main-branch wallet; `pay_invoice` returns a BOLT11 preimage.", "source_md": "[lightningfaucet/lightning-wallet-mcp README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightningfaucet/lightning-wallet-mcp/main/README.md) [38]" }, { "actor": "Tierion (lsat-js)", "role": "Client SDK", "status": "Listed", "status_display": "Listed · as of 2023-08-09", "col4_md": "JavaScript LSAT tools; last push 2023-08-09.", "source_md": "[Tierion/lsat-js README (fetched 2026-10-30)](https://raw.githubusercontent.com/Tierion/lsat-js/master/README.md) [17] · [Tierion/lsat-js repository (pushed 2023-08-09)](https://github.com/Tierion/lsat-js) [39] · [L402 README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/L402/master/README.md) [2]" } ] }, "additional_tables": null, "censuses": [ { "label": "Alby, 402, Charted (Aug 12, 2026)", "as_of": "2026-06", "value_md": "L402 grew from 94 endpoints in February to a peak of 1,209 in May, then held flat through June, ending the month at 1,201. [27]" }, { "label": "Alby, 402, Charted (Aug 12, 2026)", "as_of": "2026-06", "value_md": "L402 providers in the same index remained relatively stable (36 to 29). [27]" }, { "label": "lightningfaucet.com/llms.txt (fetched 2026-10-30)", "as_of": "2026-10-30", "value_md": "Lightning Faucet lists 25+ pay-per-call endpoints, priced from 5 to 500 sats. [28]" }, { "label": "Lightning Engineering implementations and links", "as_of": "2026-11-06", "value_md": "The Lightning Engineering implementations page lists five projects using L402: Satring, WoT Scoring, Lightning Pool, Lightning Loop, and L402 Playground. [40]" }, { "label": "Sats for Bots directory", "as_of": "2026-11-06", "value_md": "The Sats for Bots directory categorizes Lightning Agent Tools, Aperture, the L402 Protocol Spec, Alby MCP Server, Nostr Wallet Connect (NWC), Routstr, PPQ.ai, SaturnZap, L402sdk, Lightning Enable MCP, Lightning Wallet MCP, agent-bitcoin, Spark MCP, and bark-mcp. [41]" }, { "label": "L402.directory", "as_of": "2026-11-06", "value_md": "L402.directory documents GET /api/services, which returns all active L402 service listings with endpoints, pricing, and health status, and GET /api for the protocol specification. The rendered directory names First Channel Suggestion and Unlock a Video. [42]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "s402", "target_name": "s402", "relation_label": "Peer alternative", "delta": "Retired in September 2026, s402's credential was a signed Sui transaction for schemes exact, upto, prepaid, stream, escrow, or unlock, whereas L402's credential is a macaroon and a BOLT 11 preimage in Authorization: L402.", "item_md": "**[s402](/protocols/s402/)** (Peer alternative) — Retired in September 2026, s402's credential was a signed Sui transaction for schemes exact, upto, prepaid, stream, escrow, or unlock, whereas L402's credential is a macaroon and a BOLT 11 preimage in Authorization: L402." }, { "target_id": "agent-commerce-kit", "target_name": "Agent Commerce Kit (ACK)", "relation_label": "Peer alternative", "delta": "ACK-Pay places L402 among the 402-shaped flows that fit its payment pattern, while L402's credential is a macaroon and a BOLT 11 preimage and ACK-Pay's receipt is a W3C Verifiable Credential.", "item_md": "**[Agent Commerce Kit (ACK)](/protocols/agent-commerce-kit/)** (Peer alternative) — ACK-Pay places L402 among the 402-shaped flows that fit its payment pattern, while L402's credential is a macaroon and a BOLT 11 preimage and ACK-Pay's receipt is a W3C Verifiable Credential." }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: l402\ntitle: \"L402\"\ntier: flagship\nlifecycle_status: active\ncategory: pay\nform: http-header\nwire_archetype: payments_onchain\nspec_url: https://raw.githubusercontent.com/lightninglabs/L402/master/protocol-specification.md\nlast_checked: 2026-11-06\n---\n\n# L402\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** HTTP header (`http-header`) · **Last checked:** 2026-11-06\n\n> *This page is about L402 (formerly LSAT), the Lightning Labs HTTP 402 authentication and payment scheme. It is not [x402](/protocols/x402/), the open payment protocol originated at Coinbase; not [MPP](/protocols/mpp/), the Machine Payments Protocol co-authored by Tempo and Stripe using the Payment authentication scheme; and not the bare HTTP 402 status code in RFC 9110 (see [HTTP 402 Payment Required](/terms/http-402-payment-required/)). [1][2][3][4][5][6][7]*\n\n> **In brief:** L402 is a payment-gated authentication protocol for HTTP and gRPC APIs that lets autonomous agents and software clients pay per request over the Bitcoin Lightning Network without registering user accounts or storing static API keys. Instead of gating endpoints behind interactive sign-up flows and monthly subscriptions, a server returns an HTTP 402 `WWW-Authenticate` challenge containing a `macaroon` token and a BOLT 11 `invoice`, and the caller unlocks access by returning `Authorization: L402 :` once paid. [1][2]\n\n**L402** (formerly Lightning Service Authentication Tokens, or `LSAT`) is an HTTP and gRPC challenge-response authentication scheme originated by Lightning Labs that combines HTTP 402 (`Payment Required`) responses with Lightning Network invoices for paid API access. [1][2][8] First committed to `lightninglabs/L402` on 2020-02-07 and announced by Olaoluwa Osuntokun on 2020-03-30, it pairs a bearer credential with a Lightning invoice so a client can pay for a preimage and present both as proof of payment. [1][8][9] When a server requires payment for a resource, the master specification requires an HTTP 402 response carrying `WWW-Authenticate: L402 macaroon=\"\", invoice=\"\"`, and the client retries the request with `Authorization: L402 :`. [1] For backward compatibility after the rename from `LSAT`, servers should send both `LSAT` and `L402` challenges and both parties must accept either scheme in `Authorization`. [1] A token-agnostic revision (`bLIP-0026`, created 2023-06-06) uses `WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\"`, while active development continues in `lightninglabs/L402` (which reverted the `bLIP-0026` header changes on 2026-03-20). [9][10][11][12]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | HTTP header (`http-header`) |\n| **Originated by** | Lightning Labs (repo 2020-02-07). Osuntokun, Gugger, and Paulino authored bLIP-0026 (2023-06-06). [2][8][9][10] |\n| **Governed by** | Lightning Labs repo lightninglabs/L402. Roasbeef plans to continue development there. [2][9][11][13] |\n| **Track** | Lightning Labs text in lightninglabs/L402. bLIP-0026 is an open lightning/blips pull request. [2][9][13] |\n| **Status** | bLIP-0026 is Status: Active. Aperture is in production in Loop and Pool. PR 26 is unmerged. [10][13][14] |\n| **Version** | Master branch omits a version parameter; pinned bLIP-0026 snapshot uses version=\"0\". [1][10][12] |\n| **Headers** | Master challenge is macaroon plus invoice; bLIP snapshot uses version, token, and invoice. Authorization carries the preimage. [1][10] |\n| **Schemes** | L402 is case-insensitive (formerly LSAT). Servers SHOULD send both; clients and servers MUST accept both. [1] |\n| **Networks** | Lightning Network. The invoice is a BOLT 11 payment request paid for the preimage. [1] |\n| **Transports** | HTTP and gRPC. [1] |\n| **Token format** | Master credential is an HMAC-chain macaroon. The bLIP-0026 snapshot is token-format agnostic. [1][10] |\n| **IANA registration** | Spec claims RFC 7235 registration. The 2025-02-18 IANA scheme list does not name L402. [1][15] |\n| **Specification** | Master [L402 spec](https://raw.githubusercontent.com/lightninglabs/L402/master/protocol-specification.md) and pinned [bLIP-0026](https://raw.githubusercontent.com/Roasbeef/blips/697ae354c205f1aacc450e72067c92a7f2467321/blip-0026.md) snapshot. [1][10] |\n| **Found at** | No fixed path. A paid resource MUST return HTTP 402 with WWW-Authenticate. [1] |\n| **Licence** | lightninglabs/L402 `license` is null. bLIP-0026 is CC0. Aperture is MIT. [9][10][16] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [HTTP 402 challenge, macaroon identifier, and preimage authorization](#http-402-challenge-macaroon-identifier-and-preimage-authorization)\n3. [First-party caveats, LSAT rename compatibility, and Aperture dual-scheme proxy](#first-party-caveats-lsat-rename-compatibility-and-aperture-dual-scheme-proxy)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nAlthough the HTTP specification historically marked status code 402 as reserved for future use, conventional API monetization forces callers through user accounts, passwords, sign-up forms, and monthly subscriptions rather than accountless, per-request payments where users pay only for what they use. [1][2] The credential is a macaroon (an HMAC-chain bearer token) that cryptographically commits to the invoice's payment hash. This binding enables stateless verification: the server checks `H == sha256(preimage)` against the hash embedded in the macaroon, with no database lookup required. [1] The 402 status code is used exclusively for the initial payment challenge. Once a client presents a credential (valid or not), the server MUST respond with 401 if verification fails, not 402. This distinction lets clients differentiate \"you need to pay\" from \"your credential is broken.\" [1]\n\n### Payment challenge\n\n```mermaid\nsequenceDiagram\n participant C as Client\n participant S as Server\n participant LN as Lightning Network\n\n C->>S: GET /resource\n S-->>C: 402 Payment Required
WWW-Authenticate: L402 macaroon=\"M\", invoice=\"P\"\n C->>LN: pay(P)\n LN-->>C: preimage r\n C->>S: GET /resource
Authorization: L402 M:r\n S->>S: verify macaroon, check H == sha256(r)\n S-->>C: 200 OK + resource\n```\n\n*The client gets `402 Payment Required` with `WWW-Authenticate: L402`, pays the invoice, and retries with `Authorization: L402`. The server checks `H == sha256(r)`. [1]*\n\n### `HTTP 402` with `WWW-Authenticate: L402`\n\n```http\nHTTP/1.1 402 Payment Required\nDate: Mon, 04 Feb 2014 16:50:53 GMT\nWWW-Authenticate: L402 macaroon=\"AGIAJEemVQUTEyNCR0exk7ek90Cg==\", invoice=\"lnbc1500n1pw5kjhmpp5fu6xhthlt2vucmzkx6c7wtlh2r625r30cyjsfqhu8rsx4xpz5lwqdpa2fjkzep6yptksct5yp5hxgrrv96hx6twvusycn3qv9jx7ur5d9hkugr5dusx6cqzpgxqr23s79ruapxc4j5uskt4htly2salw4drq979d7rcela9wz02elhypmdzmzlnxuknpgfyfm86pntt8vvkvffma5qc9n50h4mvqhngadqy3ngqjcym5a\"\n```\n\n*`HTTP/1.1 402 Payment Required` carries `WWW-Authenticate: L402` with `macaroon` and `invoice`. [1]*\n\n---\n\n## HTTP 402 challenge, macaroon identifier, and preimage authorization\n\nThe `lightninglabs/L402` master specification and `bLIP-0026` define two parameter variants for the `L402` `WWW-Authenticate` challenge header: master binds a base64 macaroon and BOLT 11 `invoice` via `WWW-Authenticate: L402 macaroon=\"\", invoice=\"\"`, whereas `bLIP-0026` specifies a versioned, token-agnostic format (`WWW-Authenticate: L402 version=\"0\", token=\"T\", invoice=\"P\"` with current version `\"0\"`). [1][10]\n\n- **66-byte identifier:** In the macaroon specification for v0, the binary macaroon identifier is 66 bytes in big-endian layout: a 2-byte version, a 32-byte `payment_hash` (`H`, the SHA-256 hash of preimage `r`), and a 32-byte `token_id`. The master specification requires the macaroon identifier to commit to the payment hash `H` of the BOLT 11 invoice `P`. [1][12]\n- **Authorization and preimage check:** To authenticate a paid request, the client sends `Authorization: L402 :` combining the base64-encoded macaroon and hex-encoded preimage. The server verifies the macaroon's HMAC chain and checks that the SHA-256 digest of the preimage matches the embedded payment hash (`sha256(preimage) == payment_hash`, written `H == sha256(r)` in the overview). [1][12]\n- **gRPC 200 OK trailer:** Because the gRPC wire protocol over HTTP/2 requires an HTTP `200 OK` status code on all responses, a gRPC server issuing an L402 challenge replies with HTTP `200 OK` and attaches the challenge in trailing headers (`Grpc-Message: missing L402` and `Grpc-Status: 402` on master, or `Grpc-Status: 13` in `bLIP-0026`). [1][10]\n- **Client payment and retry:** After validating the invoice, the client MUST pay it over the Lightning Network to obtain preimage r, MUST construct the `Authorization` header, and MUST re-issue the original request with that header attached. Possession of the preimage proves the invoice was paid. [1]\n\n---\n\n## First-party caveats, LSAT rename compatibility, and Aperture dual-scheme proxy\n\nA caveat is an append-only restriction added to a macaroon's HMAC chain that encodes service access, capabilities, volume limits, or expiration, where each successive caveat can only narrow the token's authority. Client libraries such as `lsat-js` append first-party caveats (including `expiration` conditions) using `addFirstPartyCaveat`. [1][17]\n\n- **HMAC chain and tier caveats:** Each caveat extends the HMAC signature chain via `sig_i = HMAC(sig_{i-1}, caveat_id_i)`, producing a tamper-proof, append-only credential. Standard caveat types cover `services` (`name:tier`), capabilities, volume or timeout constraints, and expiry dates; in `bLIP-0026`, version 0 caveats are `=`-separated key-value strings where multiple `services` caveats must progressively narrow access. [1][10][12]\n- **Macaroon attenuation and unknown caveats:** A macaroon holder can attenuate a credential by appending more restrictive first-party caveats before sharing it with a third party, while third-party caveats have been tracked as an open issue since 2020-02-17. Under `bLIP-0026`, an authorizer must skip evaluation of any unknown caveat so holders can add downstream application-specific restrictions. [10][12]\n- **LSAT scheme transition:** Pull request #16 (merged 2023-04-20) formally renamed `LSAT` to `L402`. For compatibility with older clients, servers should emit the `LSAT` challenge header before `L402` in `WWW-Authenticate` responses, both parties must accept either scheme in `Authorization`, and `bLIP-0026` recommends accepting `macaroon=` alongside `token=` when parsing upstream proxy headers. [1][10][18]\n- **401, 403, and Aperture v0.5.0:** When a presented credential has a tampered macaroon, a mismatched preimage, or control characters, the server responds with HTTP 401 Unauthorized, whereas RFC 9110 and the IETF `Payment` scheme draft use HTTP 403 Forbidden when a valid credential is denied by policy. In Aperture `v0.5.0` (published 2026-03-25, with MPP enabled via `--authenticator.enablempp`), the proxy merges `WWW-Authenticate` headers so a single HTTP 402 response advertises `LSAT`, `L402`, and `Payment` challenges together. [1][6][7][16][19]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **HTTP 402 Payment Required (RFC 9110 §15.5.3)** | `RFC 9110 §15.5.3` | Profiles classic standard | RFC 9110 reserves 402 for future use. L402 uses it as the initial Lightning payment challenge. [1][7] |\n| **WWW-Authenticate (RFC 9110 §11.6.1)** | `RFC 9110 §11.6.1` | Profiles classic standard | RFC 9110 defines WWW-Authenticate for the scheme and its parameters. L402 carries a macaroon and BOLT 11 invoice. [1][7][10] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[x402](/protocols/x402/)** | Peer alternative | x402 sends PAYMENT-REQUIRED and requires PAYMENT-SIGNATURE. L402 uses WWW-Authenticate and Authorization with a macaroon. [1][3] |\n| **[Machine Payments Protocol (MPP)](/protocols/mpp/)** | Peer alternative | MPP challenges with scheme Payment. L402's scheme is L402, and clients and servers MUST accept LSAT too. [1][5][6] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | MCP uses JSON-RPC 2.0 among hosts, clients, and servers. L402 is a separate HTTP and gRPC auth scheme. [1][20] |\n| **[Cloudflare Pay Per Crawl](/protocols/cloudflare-pay-per-crawl/)** | Peer alternative | Pay Per Crawl returns HTTP 402 pricing with Cloudflare as merchant. L402 returns a macaroon and BOLT 11 invoice. [1][21] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (10 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Sellers, reverse proxies & payment processors\n\n| Actor | Role | Status | `WWW-Authenticate: L402` challenge, macaroon & Lightning invoice | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Lightning Labs (Lightning Loop & Aperture)** | Seller & reverse proxy (Originator) | Supported · as of 2026-03-25 | Aperture `v0.5.0` proxies L402 in Loop and Pool, merging LSAT and Payment on one 402. | [Aperture \\| Builder's Guide (fetched 2026-10-30)](https://docs.lightning.engineering/lightning-network-tools/aperture) [14] · [Aperture v0.5.0 (published 2026-03-25)](https://github.com/lightninglabs/aperture/releases/tag/v0.5.0) [19] · [lightninglabs/loop swap_server_client.go (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/loop/master/swap_server_client.go) [22] |\n| **Lightning Enable** | Seller & payment processor | Live (HTTP 402) · checked 2026-10-30 | Wraps APIs with a 402 macaroon invoice; probed `amount_sats` 3919. | [Lightning Enable llms.txt (fetched 2026-10-30)](https://www.lightningenable.com/llms.txt) [23] · [NWC wallet integration response (fetched 2026-10-30)](https://api.lightningenable.com/api/l402/content/nwc-wallet-integration.md) [24] |\n| **Alby (l402.space)** | Seller & cross-rail gateway | Live (HTTP 402) · checked 2026-10-30 | Universal 402 gateway; `/l402/ping` returns `amountSats` 1. | [l402.space docs (fetched 2026-10-30)](https://l402.space/docs) [25] · [l402.space/l402/ping (fetched 2026-10-30)](https://l402.space/l402/ping) [26] · [Alby, 402, Charted (Aug 12, 2026)](https://getalby.com/blog/402-charted-tracking-the-rise-of-l402-x402-and-mpp) [27] |\n| **Lightning Faucet** | Seller | Live (HTTP 402) · checked 2026-10-30 | Pay-per-call seller; `onchain_fee` probe is `price_sats` 50. | [lightningfaucet.com/llms.txt (fetched 2026-10-30)](https://lightningfaucet.com/llms.txt) [28] · [onchain fee response (fetched 2026-10-30)](https://lightningfaucet.com/api/l402/onchain_fee) [29] |\n| **Tierion (boltwall)** | Server middleware | Listed · as of 2023-04-26 | Express LSAT paywall middleware; repo pushed 2023-04-26. | [Tierion/boltwall README (fetched 2026-10-30)](https://raw.githubusercontent.com/Tierion/boltwall/master/README.md) [30] · [Tierion/boltwall repository (pushed 2023-04-26)](https://github.com/Tierion/boltwall) [31] · [L402 README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/L402/master/README.md) [2] |\n\n### Buying agents, wallets & client SDKs\n\n| Actor | Role | Status | Preimage proof, wallet backend & MCP/SDK surface | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Lightning Labs (lnget, L402sdk, LangChainBitcoin)** | Client CLI & SDKs (Originator) | Partial · as of 2026-02 | lnget handles HTTP 402; L402sdk and LangChainBitcoin are client libraries. | [Michael Levin, Lightning Labs (February 11, 2026)](https://lightning.engineering/posts/2026-02-11-ln-agent-tools/) [32] · [lnget README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/lnget/main/README.md) [33] · [lightninglabs/L402sdk (fetched 2026-10-30)](https://github.com/lightninglabs/L402sdk) [34] · [lightninglabs/LangChainBitcoin (pushed 2024-07-03)](https://github.com/lightninglabs/LangChainBitcoin) [35] |\n| **Alby (getAlby/cli)** | Wallet CLI | Supported · as of 2026-04-07 | `v0.4.0` (2026-04-07) fetches L402, X402, and MPP resources. | [getAlby/cli v0.4.0 (published 2026-04-07)](https://github.com/getAlby/cli/releases/tag/v0.4.0) [36] |\n| **Lightning Enable (lightning-enable-mcp)** | Client MCP server | Partial · as of 2026-10-30 | Main-branch MCP server pays L402 via Strike, NWC, or LND preimage. | [refined-element/lightning-enable-mcp README (fetched 2026-10-30)](https://raw.githubusercontent.com/refined-element/lightning-enable-mcp/main/README.md) [37] |\n| **Lightning Faucet (lightning-wallet-mcp)** | Custodial agent wallet | Partial · as of 2026-10-30 | Custodial main-branch wallet; `pay_invoice` returns a BOLT11 preimage. | [lightningfaucet/lightning-wallet-mcp README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightningfaucet/lightning-wallet-mcp/main/README.md) [38] |\n| **Tierion (lsat-js)** | Client SDK | Listed · as of 2023-08-09 | JavaScript LSAT tools; last push 2023-08-09. | [Tierion/lsat-js README (fetched 2026-10-30)](https://raw.githubusercontent.com/Tierion/lsat-js/master/README.md) [17] · [Tierion/lsat-js repository (pushed 2023-08-09)](https://github.com/Tierion/lsat-js) [39] · [L402 README (fetched 2026-10-30)](https://raw.githubusercontent.com/lightninglabs/L402/master/README.md) [2] |\n\n### Ecosystem censuses\n\n- **Alby, 402, Charted (Aug 12, 2026)** (*as of 2026-06*): L402 grew from 94 endpoints in February to a peak of 1,209 in May, then held flat through June, ending the month at 1,201. [27]\n- **Alby, 402, Charted (Aug 12, 2026)** (*as of 2026-06*): L402 providers in the same index remained relatively stable (36 to 29). [27]\n- **lightningfaucet.com/llms.txt (fetched 2026-10-30)** (*as of 2026-10-30*): Lightning Faucet lists 25+ pay-per-call endpoints, priced from 5 to 500 sats. [28]\n- **Lightning Engineering implementations and links** (*as of 2026-11-06*): The Lightning Engineering implementations page lists five projects using L402: Satring, WoT Scoring, Lightning Pool, Lightning Loop, and L402 Playground. [40]\n- **Sats for Bots directory** (*as of 2026-11-06*): The Sats for Bots directory categorizes Lightning Agent Tools, Aperture, the L402 Protocol Spec, Alby MCP Server, Nostr Wallet Connect (NWC), Routstr, PPQ.ai, SaturnZap, L402sdk, Lightning Enable MCP, Lightning Wallet MCP, agent-bitcoin, Spark MCP, and bark-mcp. [41]\n- **L402.directory** (*as of 2026-11-06*): L402.directory documents GET /api/services, which returns all active L402 service listings with endpoints, pricing, and health status, and GET /api for the protocol specification. The rendered directory names First Channel Suggestion and Unlock a Video. [42]\n\n---\n\n## See also\n\n- **[s402](/protocols/s402/)** *(Peer alternative)* — Retired in September 2026, s402's credential was a signed Sui transaction for schemes exact, upto, prepaid, stream, escrow, or unlock, whereas L402's credential is a macaroon and a BOLT 11 preimage in Authorization: L402.\n- **[Agent Commerce Kit (ACK)](/protocols/agent-commerce-kit/)** *(Peer alternative)* — ACK-Pay places L402 among the 402-shaped flows that fit its payment pattern, while L402's credential is a macaroon and a BOLT 11 preimage and ACK-Pay's receipt is a W3C Verifiable Credential.\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. Lightning Labs, *L402 Protocol Specification* (fetched 2026-10-30) — \n2. Lightning Labs, *L402: Lightning HTTP 402 Protocol* (fetched 2026-10-30) — \n3. x402 Foundation, *x402 Protocol Specification* (protocol version 2; fetched 2026-10-30) — \n4. Linux Foundation, *Linux Foundation Announces Operational Launch of x402 Foundation to Standardize Internet-Native Payments for AI Agents and Applications* (July 14, 2026) — \n5. Tempo and Stripe, *What is MPP?* (fetched 2026-10-30) — \n6. B. Ryan, J. Moxey, and T. Meagher (Tempo Labs); J. Weinstein and S. Kaliski (Stripe), *The \"Payment\" HTTP Authentication Scheme (draft-httpauth-payment-01 HTML)* (draft-httpauth-payment-01, September 2026) — \n7. R. Fielding, M. Nottingham, and J. Reschke (eds.), *RFC 9110: HTTP Semantics* (June 2022) — \n8. Olaoluwa Osuntokun, Lightning Labs, *L402: Authentication and Payments for the Lightning-Native Web* (March 30, 2020) — \n9. Lightning Labs, *lightninglabs/L402 repository* (created 2020-02-07; fetched 2026-10-30) — \n10. Olaoluwa Osuntokun, Oliver Gugger, and Wilmer Paulino, *bLIP-0026: L402: The Lightning HTTP 402 Protocol* (created 2023-06-06) — \n11. Lightning Specification (BOLTs), *Comments on lightning/blips pull request 26* (fetched 2026-10-30) — \n12. Lightning Labs, *lightninglabs/L402 commits* (fetched 2026-10-30) — \n13. Roasbeef, *blip-0026: L402 - Lightning HTTP 402 Protocol (lightning/blips pull request 26)* (opened 2023-06-07; fetched 2026-10-30) — \n14. Lightning Labs, *Aperture | Builder's Guide* (fetched 2026-10-30) — \n15. IANA, *Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry* (last updated 2025-02-18; last-modified 2026-10-13) — \n16. Lightning Labs, *Aperture* (checked 2026-11-06) — \n17. Tierion, *LSAT-JS* (fetched 2026-10-30) — \n18. Liongrass, *Edit documentation to reflect naming changes (lightninglabs/L402 pull request 16)* (merged 2023-04-20) — \n19. Lightning Labs, *Aperture v0.5.0* (published 2026-03-25) — \n20. Model Context Protocol, *Specification* (2026-07-28) — \n21. Cloudflare, *What is Pay Per Crawl?* (fetched 2026-10-31) — \n22. Lightning Labs, *lightninglabs/loop swap_server_client.go* (fetched 2026-10-30) — \n23. Lightning Enable (Refined Element), *Lightning Enable llms.txt* (last-modified 2026-10-30) — \n24. Lightning Enable, *NWC wallet integration payment response* (fetched 2026-10-30) — \n25. L402 Space, *Universal 402 Gateway - API docs* (fetched 2026-10-30) — \n26. L402 Space, *l402.space paid ping response* (fetched 2026-10-30) — \n27. Alby, *402, Charted - Tracking the rise of L402, x402, and MPP* (published Aug 12, 2026) — \n28. Lightning Faucet, *Lightning Faucet llms.txt* (last-modified 2026-10-27) — \n29. Lightning Faucet, *Onchain fee payment response* (fetched 2026-10-30) — \n30. Tierion, *Boltwall* (fetched 2026-10-30) — \n31. Tierion, *Tierion/boltwall repository* (pushed 2023-04-26; fetched 2026-10-30) — \n32. Michael Levin, Lightning Labs, *The Agents Are Here and They Want to Transact: Powering the AI Economy with Lightning* (February 11, 2026) — \n33. Lightning Labs, *lnget* (fetched 2026-10-30) — \n34. Lightning Labs, *L402sdk: L402 client SDK for AI agent frameworks* (fetched 2026-10-30) — \n35. Lightning Labs, *lightninglabs/LangChainBitcoin repository* (pushed 2024-07-03; fetched 2026-10-30) — \n36. Alby, *getAlby/cli v0.4.0* (published 2026-04-07) — \n37. Lightning Enable (Refined Element), *Lightning Enable MCP Server* (fetched 2026-10-30) — \n38. Lightning Faucet, *Lightning Wallet MCP* (fetched 2026-10-30) — \n39. Tierion, *Tierion/lsat-js repository* (pushed 2023-08-09; fetched 2026-10-30) — \n40. Lightning Engineering, *Implementations and Links* (checked 2026-11-06) — \n41. Sats for Bots, *Directory* (checked 2026-11-06) — \n42. L402.directory, *Discover Lightning-Gated APIs* (checked 2026-11-06) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "MPP", "adoption": { "level": "observed", "by": "Stripe, Tempo (Tempo Labs / Paradigm), Visa, Lightning Labs (Aperture), Browserbase, Stripe Link CLI, mppx (Tempo Labs & Wevm), AWS (Amazon Bedrock AgentCore payments), and 7 other verified implementations", "probe_run": null }, "aliases": [ "MPP", "Machine Payments Protocol", "Machine Payment Protocol", "Payment HTTP Authentication Scheme" ], "analog": "A payment-method-agnostic HTTP 402 challenge/credential/receipt exchange", "collisions": [], "discovery": { "mechanism": "HTTP 402 response carrying a WWW-Authenticate: Payment challenge", "path": "No fixed path: a resource signals MPP per request by answering HTTP 402 with a WWW-Authenticate: Payment challenge. Services can also be listed in the curated mpp.dev/services directory (https://mpp.dev/api/services listed 138 services on 2026-10-29) or self-registered on MPPScan (by Merit Systems)" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://mpp.dev/overview.md", "claim": "Tempo and Stripe (mpp.dev), *What is MPP?*, checked 2026-10-30", "date": null, "quote": "The Machine Payments Protocol (MPP) is an open protocol co-authored by Tempo and Stripe. / When a client requests a paid resource, the server returns a 402 response with the payment options they support. The client chooses a payment method, fulfills the request and retries with a payment Credential which contains proof of payment. The server verifies the payment and returns the resource with a Receipt which contains proof of delivery. / MPP comes with a suite of official SDKs maintained by Tempo Labs and Wevm.", "ref": 1 }, { "label": "[2]", "url": "https://stripe.com/blog/machine-payments-protocol", "claim": "Jeff Weinstein and Steve Kaliski (Stripe), *Introducing the Machine Payments Protocol*, 2026-03-18", "date": "2026-03-18", "quote": "we're launching the Machine Payments Protocol (MPP), an open standard, internet-native way for agents to pay-co-authored by Tempo and Stripe. / March 18, 2026 Jeff Weinstein Product Lead, Agentic Commerce Steve Kaliski / Businesses can then accept payments directly from agents, in stablecoins as well as fiat with cards and buy now, pay later payment methods via Shared Payment Tokens (SPTs). / Browserbase, a browser infrastructure provider, now lets agents spin up headless browsers and pay per session. / PostalForm helps agents pay to print and send physical mail.", "ref": 2 }, { "label": "[3]", "url": "https://datatracker.ietf.org/doc/html/draft-httpauth-payment-01", "claim": "B. Ryan, J. Moxey, T. Meagher, J. Weinstein, and S. Kaliski, *The \"Payment\" HTTP Authentication Scheme (draft-httpauth-payment-01 HTML)*, published 9 September 2026; expires 13 March 2027", "date": null, "quote": "This document defines the \"Payment\" HTTP authentication scheme, enabling HTTP resources to require a payment challenge to be fulfilled before access. / This specification defines the \"Payment\" authentication scheme that gives 402 its semantics, enabling resources to require a payment challenge to be fulfilled before access. / Authors: B. Ryan Tempo Labs J. Moxey Tempo Labs T. Meagher Tempo Labs J. Weinstein Stripe S. Kaliski Stripe / Internet-Draft: draft-httpauth-payment-01 Published: 9 September 2026 Intended Status: Standards Track Expires: 13 March 2027 / Payment Challenge: A WWW-Authenticate header with scheme \"Payment\" / The default field name is Authorization. / A Payment challenge MAY select Payment-Authorization with the header parameter / The client MUST send the corresponding Payment credential in the `Payment-Authorization` header, not in `Authorization`. / Servers SHOULD include a `Payment-Receipt` header on successful responses: / Encoded as base64url JSON in the request parameter / registered value in the IANA \"HTTP Payment Intents\" registry / 12. IANA Considerations … Authentication Scheme Name: Payment … Accept-Payment … Payment-Authorization … Payment-Receipt … establishes the \"HTTP Payment Methods\" registry … establishes the \"HTTP Payment Intents\" registry / Code Components extracted from this document must include Revised BSD License text / This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents / HTTP 402 \"Payment Required\" was reserved in HTTP/one-point-one [RFC9110] but never standardized for common use. / The protocol is payment-method agnostic, supporting any payment network or currency through registered payment method identifiers. Specific payment methods are defined in separate payment method specifications. / 4.1. Request Flow / Step (4) uses the default Authorization header because the challenge did not include a specific header field. / A client requests a resource, receives a payment challenge, fulfills the payment, and receives the resource with a receipt.", "ref": 3 }, { "label": "[4]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "claim": "x402 Foundation, *X402 Protocol Specification*, protocol version 2", "date": null, "quote": "PAYMENT-REQUIRED / PAYMENT-SIGNATURE header is required / x402 is an open payment standard that enables clients to pay for external resources. / state-committing /settle", "ref": 4 }, { "label": "[5]", "url": "https://raw.githubusercontent.com/lightninglabs/L402/master/protocol-specification.md", "claim": "Lightning Labs, *L402 Protocol Specification*, checked 2026-10-30", "date": null, "quote": "WWW-Authenticate: L402 / containing a macaroon and a Lightning invoice / pays the invoice to obtain a preimage", "ref": 5 }, { "label": "[6]", "url": "https://www.rfc-editor.org/rfc/rfc9110.html", "claim": "R. Fielding, M. Nottingham, and J. Reschke (IETF), *RFC 9110: HTTP Semantics*, June 2022", "date": null, "quote": "The 402 (Payment Required) status code is reserved for future use. / 11.6.1. WWW-Authenticate", "ref": 6 }, { "label": "[7]", "url": "https://raw.githubusercontent.com/lightning/bolts/master/09-features.md", "claim": "Lightning Network, *BOLT #9: Assigned Feature Flags*, checked 2026-10-30", "date": null, "quote": "basic_mpp | Node can receive basic multi-part payments", "ref": 7 }, { "label": "[8]", "url": "https://learn.microsoft.com/en-us/dynamics365/project-operations/project-management/import_from_mpp", "claim": "Microsoft, *Import projects from the Microsoft Project desktop client*, checked 2026-10-30", "date": null, "quote": "Microsoft Project desktop client files (.mpp files)", "ref": 8 }, { "label": "[9]", "url": "https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/", "claim": "Chethan Shriyan and Madhu Samhitha Vangara (AWS), *Amazon Bedrock AgentCore payments is now generally available*, 2026-08-18", "date": "2026-08-18", "quote": "At GA, we have expanded protocol support to include the Machine Payment Protocol (MPP), another standard for machine payments co-authored by Stripe and Tempo / by Chethan Shriyan and Madhu Samhitha Vangara on 18 AUG 2026 / At GA, we have expanded protocol support to include the Machine Payment Protocol (MPP), another standard for machine payments co-authored by Stripe and Tempo, enabling developers to pay for any MPP-compatible service without an additional line of code.", "ref": 9 }, { "label": "[10]", "url": "https://tempo.xyz/blog/mainnet/", "claim": "Tempo, *Tempo Mainnet Is Live: Build on Tempo Today*, 2026-03-18", "date": "2026-03-18", "quote": "introducing the Machine Payments Protocol (MPP), an open standard for machine payments co-authored by Stripe and Tempo. / Tempo Mainnet is live Mar 18, 2026 / MPP runs on Tempo today, but the protocol itself is designed to be rail-agnostic and extensible. / For example, our design partner Visa has already extended MPP to support card-based payments on their network.", "ref": 10 }, { "label": "[11]", "url": "https://raw.githubusercontent.com/tempoxyz/mpp-specs/main/README.md", "claim": "Tempo Labs and Stripe, *Machine Payments Protocol (MPP)*, checked 2026-10-30", "date": null, "quote": "The Machine Payments Protocol (MPP) is an open standard for machine-to-machine payments, co-authored by Tempo and Stripe. / Server responds with 402 Payment Required and a WWW-Authenticate: Payment challenge describing what payment is needed … Client retries the request with an Authorization: Payment credential proving payment / The Machine Payments Protocol specification is currently maintained by the following organizations: … Tempo Labs … Stripe / currently maintained by the following organizations: … Tempo Labs … Stripe / Server responds with 402 Payment Required and a WWW-Authenticate: Payment challenge describing what payment is needed / Core: HTTP 402 semantics, headers, IANA registries. / Specifications: CC0 1.0 Universal (Public Domain) / Client retries the request with an Authorization: Payment credential proving payment / The Machine Payments Protocol specification is currently maintained by the following organizations: * Tempo Labs * Stripe", "ref": 11 }, { "label": "[12]", "url": "https://mpp.dev/governance.md", "claim": "Tempo and Stripe (mpp.dev), *Governance*, checked 2026-10-30", "date": null, "quote": "The core specification is published as the Payment HTTP Authentication Scheme and submitted to the IETF standards track, where it continues to progress as an open, vendor-neutral standard. / MPP is developed in the open on GitHub. / Each payment method specification is defined and maintained by the rail behind it-for example Visa, Mastercard, Solana, Bitcoin, Stripe, or Tempo-together with any corporate entities associated with that rail. / governed by IETF Trust licensing under BCP 78 and BCP 79. / Each payment method specification is defined and maintained by the rail behind it", "ref": 12 }, { "label": "[13]", "url": "https://paymentauth.org/draft-httpauth-payment-01.html", "claim": "B. Ryan, J. Moxey, T. Meagher, J. Weinstein, and S. Kaliski, *The \"Payment\" HTTP Authentication Scheme (editor rendering)*, published 2 November 2026; expires 6 May 2027", "date": null, "quote": "Servers SHOULD include a Payment-Receipt header on successful responses / Internet-Draft: draft-httpauth-payment-01 Published: 2 November 2026 Intended Status: Standards Track Expires: 6 May 2027 / Payment-Authorization is RECOMMENDED when a resource needs to preserve Authorization for ordinary authentication. / This document defines the \"Payment\" HTTP authentication scheme, enabling HTTP resources to require a payment challenge to be fulfilled before access. The scheme extends HTTP Authentication, using the HTTP 402 \"Payment Required\" status code. / id : Unique challenge identifier. This parameter is REQUIRED and its value MUST be non-empty … realm : Protection space identifier … Servers MUST include this parameter … method : Payment method identifier … MUST be a lowercase … intent : Payment intent type … The value MUST be a registered entry … request : Base64url-encoded … Padding characters (\"=\") MUST NOT be included. The JSON MUST be serialized using JSON Canonicalization Scheme (JCS) / digest : Content digest of the request body … Servers SHOULD include this parameter when the payment challenge applies to a request with a body … expires : Timestamp indicating when this challenge expires … Servers SHOULD include this parameter. / Servers MUST bind the challenge id to realm , method , intent , and request , and to expires , digest , opaque , and header when present. … Servers MAY use stateful storage (e.g., database lookup) or stateless verification (e.g., HMAC, authenticated encryption) to validate the binding. … Servers using HMAC-SHA256 for stateless challenge binding SHOULD compute the challenge id as follows … id = base64url(HMAC-SHA256(server_secret, input)) / The default HTTP field for the Payment credential is Authorization … Clients receiving such a challenge MUST send the Payment credential in the Authorization header. / Echoed challenge parameters … Payer identifier ( RECOMMENDED : DID format … Method-specific payment proof / Payment credentials are bearer tokens that authorize financial transactions. … Clients MUST verify before authorizing payment: … Requested amount is reasonable for the resource … Recipient/address is expected … Clients MUST NOT rely on the description parameter for payment verification. / Payment methods used with this specification MUST provide single-use proof semantics. A payment proof MUST be usable exactly once; subsequent attempts to use the same proof MUST be rejected by the payment method infrastructure. / Servers SHOULD include a Payment-Receipt header on successful responses: … Payment-Receipt = base64url-nopad … status … method … timestamp … reference … Servers MUST NOT return a Payment-Receipt header on error responses. / Servers SHOULD return Problem Details [RFC9457] error bodies for payment-related errors … payment-required … payment-insufficient … payment-expired … Content-Type: application/problem+json", "ref": 13 }, { "label": "[14]", "url": "https://datatracker.ietf.org/doc/draft-httpauth-payment/", "claim": "IETF Datatracker, *draft-httpauth-payment — The \"Payment\" HTTP Authentication Scheme (IETF Datatracker)*, last updated 2026-09-09", "date": null, "quote": "This I-D is not endorsed by the IETF and has no formal standing in the IETF standards process. … Active Internet-Draft (individual) … Last updated … 2026-09-09 … Intended RFC status … (None) … Intended status: Standards Track … Expires: 13 March 2027 … draft-httpauth-payment-01 / This I-D is not endorsed by the IETF and has no formal standing in the IETF standards process. / Document Type Active Internet-Draft (individual) / Last updated 2026-09-09 / IESG state I-D Exists / Document Type Active Internet-Draft (individual) … IESG state I-D Exists", "ref": 14 }, { "label": "[15]", "url": "https://mpp.dev/faq.md", "claim": "Tempo and Stripe (mpp.dev), *Frequently asked questions*, checked 2026-10-30", "date": null, "quote": "Today, Tempo stablecoin payments, card payments through Card or Stripe, and Lightning payments are in production. / MPP includes an MCP transport binding that maps the Challenge-Credential-Receipt flow onto the Model Context Protocol. / The protocol itself is free and open. There are no licensing fees for implementing MPP. / Sessions are a payment intent that enables streaming, pay-as-you-go payments. Instead of paying per request, a client opens a session by depositing funds into a channel reserve, then makes many requests by issuing signed vouchers off-chain. The server periodically settles the accumulated vouchers on-chain. / mppx can run x402-compatible EVM charges inline with an MPP route, so the same endpoint can serve x402 and MPP clients.", "ref": 15 }, { "label": "[16]", "url": "https://corporate.visa.com/en/sites/visa-perspectives/innovation/visa-card-specification-sdk-for-machine-payments-protocol.html", "claim": "Visa, *Visa introduces card spec and SDK for MPP*, 2026-03-18", "date": "2026-03-18", "quote": "the spec is now live / 03/18/2026 / As a design partner on MPP, Visa is releasing: / Visa is extending MPP to support card-based payments on its global network, and enabling it on the Visa Acceptance Platform. / Card-Based MPP Spec: Visa's full technical specification that defines how tokenized card credentials are passed, authenticated and processed inside MPP-compatible workflows.", "ref": 16 }, { "label": "[17]", "url": "https://mpp.browserbase.com/browser/session/create", "claim": "Browserbase, *Payment Required (browser session create)*, checked 2026-10-30", "date": null, "quote": "\"status\":402,\"detail\":\"Payment is required (Pay-per-use browser sessions with crypto. No API keys, no accounts -- just pay and connect via x402 or MPP.).\"", "ref": 17 }, { "label": "[18]", "url": "https://mpp.dev/payment-methods.md", "claim": "Tempo and Stripe (mpp.dev), *Payment methods*, checked 2026-10-30", "date": null, "quote": "WWW-Authenticate: Payment method=\"stripe\", intent=\"charge\" / method=\"tempo\" … method=\"stripe\" … method=\"evm\" … method=\"card\" … method=\"lightning\" … method=\"solana\" … method=\"xrpl\" … method=\"stellar\" … method=\"monad\" … method=\"nearintents\" … method=\"redotpay\" / Tempo - Web scale payments with TIP-20 stablecoins on Tempo with sub second settlement … Stripe - Traditional payment methods through Stripe … Card - Card payments via encrypted network tokens … Lightning - Bitcoin payments over the Lightning Network / WWW-Authenticate: Payment method=\"tempo\", intent=\"charge\" / WWW-Authenticate: Payment method=\"evm\", intent=\"charge\"", "ref": 18 }, { "label": "[19]", "url": "https://mpp.dev/mpp-vs-x402.md", "claim": "Tempo and Stripe (mpp.dev), *MPP vs x402*, checked 2026-10-30", "date": null, "quote": "Payment-Receipt / Authorization: Payment, or an advertised alternate field / MPP defines a payment-method-agnostic HTTP authentication framework for stablecoins, cards, Lightning, and other payment rails.", "ref": 19 }, { "label": "[20]", "url": "https://www.iana.org/assignments/http-authschemes/authschemes.csv", "claim": "IANA, *Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry (CSV)*, checked 2026-10-30", "date": null, "quote": "Authentication Scheme Name,Reference,Notes Basic,[RFC 7617], Bearer,[RFC 6750]", "ref": 20 }, { "label": "[21]", "url": "https://mpp.dev/services", "claim": "Machine Payments Protocol, *MPP services: APIs that accept MPP payments*, checked 2026-10-30", "date": null, "quote": "The curated directory accepts live, production-ready MPP services. / fetch advisory OpenAPI summaries / Browse services … fetch advisory OpenAPI summaries … Runtime 402 Challenges from the target service remain the authoritative source of current payment terms. / Install the Tempo CLI and its wallet to fund your agent's use of MPP services.", "ref": 21 }, { "label": "[22]", "url": "https://github.com/tempoxyz/mpp", "claim": "Tempo, *tempoxyz/mpp*, checked 2026-10-30", "date": null, "quote": "Register on … MPPScan … for immediate discovery; open a PR to include it in the curated … mpp.dev/services", "ref": 22 }, { "label": "[23]", "url": "https://mpp.dev/protocol/http-402.md", "claim": "Tempo and Stripe (mpp.dev), *HTTP 402*, checked 2026-10-30", "date": null, "quote": "MPP uses 402 when a server offers a payment Challenge, including retryable Credential validation failures. This differs from other HTTP authentication schemes that use 401 for failed Credentials.", "ref": 23 }, { "label": "[24]", "url": "https://developers.cloudflare.com/agents/tools/payments/mpp/", "claim": "Cloudflare, *MPP (Machine Payments Protocol)*, last updated 2026-08-05", "date": null, "quote": "MPP is payment-method agnostic. It supports stablecoins, cards through Stripe, and custom payment methods. … Model Context Protocol (MCP) tools use the same flow through JSON-RPC. … charge - Collect a one-time payment. … session - Charge for measured usage. / HTTP services exchange payment data in authentication headers. Model Context Protocol (MCP) tools use the same flow through JSON-RPC. / MPP is payment-method agnostic. It supports stablecoins, cards through Stripe, and custom payment methods. / It standardizes the HTTP 402 Payment Required status code with a formal authentication scheme proposed to the IETF / charge - Collect a one-time payment. / session - Charge for measured usage. / subscription - Sell recurring access.", "ref": 24 }, { "label": "[25]", "url": "https://docs.stripe.com/payments/machine/mpp", "claim": "Stripe, *MPP*, checked 2026-10-30", "date": null, "quote": "For card payments through Shared Payment Tokens (SPTs), the minimum amount is 0.50 USD. / Stripe automatically offramps these payments and settles them into your Stripe balance. / MPP, the Machine Payments Protocol, is an open protocol that lets agents pay for your APIs and services programmatically without a checkout UI, co-authored by Stripe and Tempo. / The link-cli is a tool that can provision one-time shared payment token credentials using your Link account. / register it as an MCP server in your preferred agent. / Run mppx validate to automatically verify your implementation end-to-end. … In a sandbox, the CLI automatically completes roundtrip test transactions against your server. In live mode, the CLI can also complete roundtrip transactions with real funds.", "ref": 25 }, { "label": "[26]", "url": "https://mpp.dev/intents.md", "claim": "Tempo and Stripe (mpp.dev), *Intents*, checked 2026-10-30", "date": null, "quote": "Charge: Collect a fixed one-time payment before returning the resource / Tempo supports charge, session, and subscription, while Stripe currently supports charge.", "ref": 26 }, { "label": "[27]", "url": "https://ap2-protocol.org/ap2/specification/", "claim": "AP2, *Agent Payments Protocol specification*, checked 2026-10-30", "date": null, "quote": "AP2 specifies the use of SD-JWTs for securing the Payment and Checkout Mandates.", "ref": 27 }, { "label": "[28]", "url": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol", "claim": "OpenAI and Stripe, *Agentic Commerce Protocol*, checked 2026-10-30", "date": null, "quote": "The Agentic Commerce Protocol (ACP) is an interaction model and open standard for connecting buyers, their AI agents, and businesses to complete purchases seamlessly. The specification is currently maintained by OpenAI and Stripe.", "ref": 28 }, { "label": "[29]", "url": "https://blog.cloudflare.com/introducing-pay-per-crawl/", "claim": "Cloudflare, *Introducing pay per crawl: Enabling content owners to charge AI crawlers for access*, published 2025-07-01; modified 2026-07-15", "date": null, "quote": "accompanied by a crawler-price header / HTTP 402 Payment Required crawler-price: USD XX.XX / using Web Bot Auth proposals", "ref": 29 }, { "label": "[30]", "url": "https://developers.cloudflare.com/ai-crawl-control/features/pay-per-crawl/what-is-pay-per-crawl/", "claim": "Cloudflare, *What is Pay Per Crawl?*, checked 2026-10-31", "date": null, "quote": "receive an HTTP 402 Payment Required response with pricing", "ref": 30 }, { "label": "[31]", "url": "https://fortune.com/2026/03/18/stripe-tempo-paradigm-mpp-ai-payments-protocol/", "claim": "Ben Weiss (Fortune), *Stripe-backed crypto startup Tempo releases AI payments protocol, launches blockchain*, published 2026-03-18; modified 2026-03-18", "date": null, "quote": "Tempo, incubated by Stripe and the venture firm Paradigm", "ref": 31 }, { "label": "[32]", "url": "https://docs.lightning.engineering/lightning-network-tools/aperture", "claim": "Lightning Labs, *Aperture*, checked 2026-10-30", "date": null, "quote": "Aperture is a reverse proxy that acts as a payment and authentication gateway for Lightning Network powered APIs. / Aperture implements both the L402 as well as the MPP specifications. / Aperture is currently used in production in Lightning Loop and Pool.", "ref": 32 }, { "label": "[33]", "url": "https://mpp.dev/api/services", "claim": "Machine Payments Protocol, *MPP services catalog*, checked 2026-10-30", "date": null, "quote": "\"id\":\"browserbase\",\"name\":\"Browserbase\" … \"status\":\"active\" … \"methods\":{\"tempo\":{\"intents\":[\"charge\"] … \"stripe\":{\"intents\":[\"charge\"] … \"path\":\"/browser/session/create\" / \"id\":\"postalform\",\"name\":\"PostalForm\" … \"status\":\"active\" … \"stripe\":{\"intents\":[\"charge\"] … \"path\":\"/api/machine/mpp/orders\",\"description\":\"Create and pay for a print-and-mail order\" / \"id\":\"stableenrich\",\"name\":\"StableEnrich\" … \"status\":\"active\" … \"methods\":{\"tempo\":{\"intents\":[\"charge\"] … \"path\":\"/api/apollo/people-search\" / \"id\":\"dune\",\"name\":\"Dune\" … \"status\":\"active\" … \"methods\":{\"tempo\":{\"intents\":[\"session\"] … \"path\":\"/api/v1/sql/execute\" / \"id\":\"alchemy\",\"name\":\"Alchemy\" … \"serviceUrl\":\"https://mpp.alchemy.com\" … \"status\":\"active\" … \"stripe\":{\"intents\":[\"charge\"] … \"path\":\"/:network/v2\",\"description\":\"JSON-RPC call (eth_*, alchemy_*)\" / {\"version\":1,\"services\":[ / \"status\":\"active\" / \"id\":\"tempo-api\",\"name\":\"Tempo API\" … \"status\":\"beta\" / \"id\":\"govlaws\",\"name\":\"GovLaws\" … \"status\":\"maintenance\" / \"id\":\"laso-finance\",\"name\":\"Laso Finance\" … \"methods\":{\"evm\":{\"intents\":[\"charge\"] / \"methods\":{\"tempo\":{\"intents\":[\"charge\"] / \"stripe\":{\"intents\":[\"charge\"],\"assets\":[\"usd\"]", "ref": 33 }, { "label": "[34]", "url": "https://github.com/stripe/link-cli", "claim": "Stripe, *link-cli*, checked 2026-10-30", "date": null, "quote": "Shared Payment Token … (SPT) for use when the seller accepts programmatic payments through … Machine Payment Protocols … (MPP) / For now, this is only available to US and Canadian Link accounts. / npx skills add stripe/link-cli / mpp pay … to complete purchases", "ref": 34 }, { "label": "[35]", "url": "https://mpp.dev/sdk.md", "claim": "Tempo and Stripe (mpp.dev), *SDKs*, checked 2026-10-30", "date": null, "quote": "the reference implementation of the MPP SDKs", "ref": 35 }, { "label": "[36]", "url": "https://developers.cloudflare.com/agents/tools/payments/mpp/pay-from-agents-sdk/", "claim": "Cloudflare, *Pay from the Agents SDK*, last updated 2026-08-05", "date": null, "quote": "Use the Cloudflare Agents SDK to pay MPP services. The mppx SDK handles payment retries for HTTP requests and Model Context Protocol (MCP) tool calls. / Last updated Aug 5, 2026", "ref": 36 }, { "label": "[37]", "url": "https://github.com/mbeato/awesome-mpp", "claim": "mbeato, *Awesome MPP*, fetched 2026-11-06", "date": null, "quote": "A curated list of resources, tools, SDKs, and services for the Machine Payments Protocol (MPP) / Official MPP specification using an RFC-style Payment HTTP auth scheme.", "ref": 37 } ], "form": "http-header", "governance": "Tempo and Stripe, in the open tempoxyz/mpp-specs repository: \"MPP is developed in the open on GitHub.\" mpp.dev splits governance in two. Core: \"The core specification is published as the Payment HTTP Authentication Scheme and submitted to the IETF standards track, where it continues to progress as an open, vendor-neutral standard.\" Payment methods: \"Each payment method specification is defined and maintained by the rail behind it—for example Visa, Mastercard, Solana, Bitcoin, Stripe, or Tempo—together with any corporate entities associated with that rail.\" \"Payment rails and third parties do not need explicit approval to add a payment method implementation to MPP.\" The IETF has not adopted the draft: \"This I-D is not endorsed by the IETF and has no formal standing in the IETF standards process.\" There is no MPP foundation or IETF working group", "group": "HTTP 402 family", "hatnote_md": "This page is about the Machine Payments Protocol (MPP), an open protocol co-authored by Tempo and Stripe and launched on March 18, 2026, whose core is the Payment HTTP authentication scheme. It is not x402, whose v2 specification uses a PAYMENT-REQUIRED header and a PAYMENT-SIGNATURE header. It is not L402, whose challenge is a WWW-Authenticate: L402 header containing a macaroon and a Lightning invoice. It is not the bare 402 status code: RFC 9110 says the 402 (Payment Required) status code is reserved for future use. In Lightning, basic_mpp means a node can receive basic multi-part payments. Microsoft uses .mpp for Microsoft Project desktop client files. AWS writes Machine Payment Protocol (singular). mpp.dev, Stripe, and Tempo write Machine Payments Protocol.", "history": [ { "date": "2026-09-06", "note": "verified against mpp.dev (homepage, /protocol, /governance)" }, { "date": "2026-10-16", "note": "The MPP draft was renamed draft-httpauth-payment; draft-httpauth-payment-01 is dated 2026-09-09" }, { "date": "2026-10-29", "note": "Re-verified record against 30 primary, live HTTP 402 endpoint, vendor, and coverage sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "mpp", "implementation": "multi-implementation", "last_verified": "2026-11-12", "name": "Machine Payments Protocol (MPP)", "native_status": "\"Document Type Active Internet-Draft (individual)\", \"Last updated 2026-09-09\", \"IESG state I-D Exists\". In production use: payment methods are in production, and five services checked live on 2026-10-29 answered with MPP challenges (see Who uses it)", "origin": { "date": "2026-03-18", "org": "Tempo and Stripe" }, "part_of": null, "parties": [ "agent-site", "agent-payment" ], "phase": "review", "probe": { "method": "GET", "on_absent": "A 200, 401, or a 402 without a Payment-scheme WWW-Authenticate header means this path is not gated by MPP; MPP also has MCP/JSON-RPC and WebSocket transport bindings, so an HTTP-only probe cannot rule out MPP support offered solely over those transports.", "parse": "HTTP 402 status with a WWW-Authenticate: Payment ... challenge header; a subsequent authorized retry returns 200 with a Payment-Receipt header", "path": "{origin}/{paid-path}" }, "question": "How can a machine client (an agent, script, or another server) pay for an HTTP resource using any payment network, not just one?", "scope": "payments", "spec_url": "https://datatracker.ietf.org/doc/html/draft-httpauth-payment-01", "step": "pay", "summary_md": "**Machine Payments Protocol** (`MPP`) is an open standard for machine-to-machine payments launched on 2026-03-18 and maintained by Tempo Labs and Stripe, whose core wire specification is published as the `Payment` HTTP Authentication Scheme. When a client requests a protected resource, the server responds with `402 Payment Required` and a `WWW-Authenticate: Payment` challenge; the client retries with an `Authorization: Payment` credential proving payment, and on success servers SHOULD include a `Payment-Receipt` header. Published as an individual Standards Track Internet-Draft (`draft-httpauth-payment-01`, updated 2026-09-09 on the IETF Datatracker and expiring 13 March 2027), the specification is an active individual submission and is not formally endorsed by an IETF working group.", "track": "vendor-consortium", "version": { "label": "draft-httpauth-payment-01", "date": "2026-09-09" }, "watch": [ { "type": "page", "url": "https://mpp.dev/overview.md", "selector": "main", "cadence": "weekly" }, { "type": "ietf", "doc": "draft-httpauth-payment" }, { "type": "github", "repo": "tempoxyz/mpp-specs", "mode": "tag", "version": false } ], "use_cases": [ "accept-agent-payments", "agent-checkout" ], "audience": [ "platform", "agent-builder", "standards-body" ], "pairs_with": [ "x402", "l402", "ap2", "agentic-commerce-protocol", "cloudflare-pay-per-crawl" ], "prerequisites": [], "ietf_tracker": { "doc": "draft-httpauth-payment", "rev": "01", "state": "active", "stream": null, "group_type": "Individual", "wg": null, "replaced_by": null, "posted_utc": "2026-09-09", "expires_utc": "2027-03-13", "as_of": "2026-11-08", "source": "https://datatracker.ietf.org/doc/draft-httpauth-payment/", "source_label": "per IETF Datatracker" }, "tier": "flagship", "lifecycle_status": "active_draft", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This page is about the Machine Payments Protocol (MPP), an open protocol co-authored by Tempo and Stripe and launched on March 18, 2026, whose core is the Payment HTTP authentication scheme. It is not x402, whose v2 specification uses a PAYMENT-REQUIRED header and a PAYMENT-SIGNATURE header. It is not L402, whose challenge is a WWW-Authenticate: L402 header containing a macaroon and a Lightning invoice. It is not the bare 402 status code: RFC 9110 says the 402 (Payment Required) status code is reserved for future use. In Lightning, basic_mpp means a node can receive basic multi-part payments. Microsoft uses .mpp for Microsoft Project desktop client files. AWS writes Machine Payment Protocol (singular). mpp.dev, Stripe, and Tempo write Machine Payments Protocol. [1][2][3][4][5][6][7][8][9][10]", "v05_elevator_pitch_md": "MPP (Machine Payments Protocol) is an HTTP payment specification co-authored by Tempo Labs and Stripe that lets autonomous agents and automated clients pay for API calls and digital resources on the fly. Giving concrete wire semantics to the long-reserved `402 Payment Required` HTTP status, servers return a `WWW-Authenticate: Payment` challenge and clients retry the request with an `Authorization: Payment` credential across any supported payment rail. [3][11]", "v05_lead_md": "**Machine Payments Protocol** (`MPP`) is an open standard for machine-to-machine payments launched on 2026-03-18 and maintained by Tempo Labs and Stripe, whose core wire specification is published as the `Payment` HTTP Authentication Scheme. [2][11][12] When a client requests a protected resource, the server responds with `402 Payment Required` and a `WWW-Authenticate: Payment` challenge; the client retries with an `Authorization: Payment` credential proving payment, and on success servers SHOULD include a `Payment-Receipt` header. [11][13] Published as an individual Standards Track Internet-Draft (`draft-httpauth-payment-01`, updated 2026-09-09 on the IETF Datatracker and expiring 13 March 2027), the specification is an active individual submission and is not formally endorsed by an IETF working group. [14]", "v05_identity_sentence_md": "**Machine Payments Protocol** (`MPP`) is an open standard for machine-to-machine payments launched on 2026-03-18 and maintained by Tempo Labs and Stripe, whose core wire specification is published as the `Payment` HTTP Authentication Scheme. [2][11][12]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "HTTP header (`http-header`)" }, { "label": "Originated by", "value_md": "Tempo and Stripe, 18 March 2026; draft authors are Tempo Labs and Stripe. [2][3][10]" }, { "label": "Governed by", "value_md": "Tempo Labs and Stripe maintain it on GitHub; this individual I-D is not IETF-endorsed. [11][12][14]" }, { "label": "Track", "value_md": "Individual Internet-Draft `draft-httpauth-payment-01`, intended Standards Track, not IETF-endorsed. [3][14]" }, { "label": "IETF tracker", "value_md": "[draft-httpauth-payment](https://datatracker.ietf.org/doc/draft-httpauth-payment/): Active Internet-Draft (individual); last updated 2026-09-09; IESG state I-D Exists. [14]" }, { "label": "Status", "value_md": "IESG state I-D Exists, updated 2026-09-09. Tempo, card/Stripe, and Lightning are in production. [14][15][16][17]" }, { "label": "Version", "value_md": "Datatracker `draft-httpauth-payment-01` published 9 September 2026; paymentauth.org editor's copy of that draft name is dated 2 November 2026 (`2026-11-02`; expires 6 May 2027). [3][13]" }, { "label": "Headers", "value_md": "`WWW-Authenticate: Payment` challenge; default credential `Authorization`; selected `Payment-Authorization` is MUST; `Payment-Receipt` is SHOULD. `Payment-Authorization` is RECOMMENDED when a resource needs to preserve `Authorization` for ordinary authentication. [3][11][13][18][19]" }, { "label": "Schemes", "value_md": "HTTP authentication scheme \"Payment\". [3]" }, { "label": "Networks", "value_md": "Documented methods: `tempo`, `stripe`, `evm`, `card`, `lightning`, `solana`, `xrpl`, `stellar`, `monad`, `nearintents`, `redotpay`. [15][18]" }, { "label": "Transports", "value_md": "HTTP 402 with the Payment scheme; an MCP binding maps Challenge, Credential, and Receipt. [11][15]" }, { "label": "Message format", "value_md": "Challenge `request` is base64url JSON; intents belong to a proposed IANA HTTP Payment Intents registry. [3][11]" }, { "label": "IANA registration", "value_md": "Section 12 proposes the `Payment` scheme, three headers, and two registries; the IANA CSV lists no `Payment`. [3][14][20]" }, { "label": "Specification", "value_md": "[The \"Payment\" HTTP Authentication Scheme (draft-httpauth-payment-01)](https://datatracker.ietf.org/doc/html/draft-httpauth-payment-01) [3]" }, { "label": "Found at", "value_md": "Servers answer HTTP 402 with `WWW-Authenticate: Payment`. Curated directory is mpp.dev/services. [11][21][22]" }, { "label": "Licence", "value_md": "No implementation fees. IETF text is under BCP 78; code uses Revised BSD; mpp-specs uses CC0 1.0. [3][11][12][15]" } ], "v05_problem_md": "Although RFC 9110 reserved the HTTP `402` (`Payment Required`) status code for future use, the status code was never standardized in HTTP/1.1 with a common challenge-response wire format. [3][6] The Payment specification defines the \"Payment\" authentication scheme that gives 402 its semantics, so a resource can require a fulfilled payment challenge before access. MPP uses 402 when a server offers a payment Challenge, including retryable Credential validation failures, unlike schemes that use 401 for failed Credentials. [3][23] The protocol is payment-method agnostic and supports any payment network or currency through registered payment method identifiers. Specific payment methods are defined in separate payment method specifications, and each is defined and maintained by the rail behind it. [3][12]", "v05_mechanism_delta_md": "The Payment specification defines the \"Payment\" authentication scheme that gives 402 its semantics, so a resource can require a fulfilled payment challenge before access. MPP uses 402 when a server offers a payment Challenge, including retryable Credential validation failures, unlike schemes that use 401 for failed Credentials. [3][23]", "v05_scope_boundary_md": "The protocol is payment-method agnostic and supports any payment network or currency through registered payment method identifiers. Specific payment methods are defined in separate payment method specifications, and each is defined and maintained by the rail behind it. [3][12]", "v05_fuzzy_additions": [ { "id": "http-402-payment-challenge-credential-retry-and-payment-receipt", "heading": "HTTP 402 Payment challenge, Credential retry, and Payment-Receipt", "body_md": "`draft-httpauth-payment-01` extends HTTP authentication over status code 402 with structured challenge parameters, bound challenge identifiers, single-use payment credentials, and optional settlement receipts. [12][13]", "bullets": [ { "label": "Challenge parameters", "text_md": "A `WWW-Authenticate: Payment` challenge MUST include a non-empty `id`, a `realm`, a lowercase `method`, and a registered `intent`. The `request` MUST be base64url JSON serialized with JCS and no padding. Servers SHOULD include `expires`, and SHOULD include `digest` when the request has a body. [13]" }, { "label": "Stateless HMAC binding", "text_md": "Servers MUST bind `id` to `realm`, `method`, `intent`, and `request`, and to `expires`, `digest`, `opaque`, and `header` when present. They MAY verify that binding with stored state or with stateless `HMAC-SHA256`. Servers that use HMAC-SHA256 SHOULD set `id` to the base64url HMAC over the pipe-joined challenge fields, using a server secret. [13]" }, { "label": "Credential retry", "text_md": "When a challenge omits `header`, clients MUST retry in `Authorization` as `Authorization: Payment` followed by base64url JSON. That object MUST echo the `challenge` parameters and include a method-specific `payload`. A `source` payer identifier is optional and RECOMMENDED in DID format. Because credentials are bearer tokens, TLS is required, and clients MUST verify `request` amount and recipient rather than `description` before paying. Payment methods used with the scheme MUST provide single-use proof semantics. A payment proof MUST be usable exactly once; subsequent attempts to use the same proof MUST be rejected by the payment method infrastructure. [13]" }, { "label": "Receipt and problem types", "text_md": "Servers SHOULD include a `Payment-Receipt` header on successful responses and MUST NOT return it on error responses; `Payment-Receipt` is an unsigned `base64url-nopad` JSON receipt (`status`, `method`, `timestamp`, and `reference`), not a cryptographic proof. Servers SHOULD return Problem Details (`application/problem+json`, such as `payment-required`, `payment-insufficient`, and `payment-expired`) for payment errors. [13]" } ] }, { "id": "payment-method-modularity-charge-vs-session-intents-and-service-discovery", "heading": "Payment method modularity, Charge vs Session intents, and service discovery", "body_md": "Across stablecoins, cards through Stripe, and custom payment methods, MPP distinguishes `charge` for a one-time payment from `session` for measured usage. Model Context Protocol tools use the same flow through JSON-RPC, and agents can fetch advisory OpenAPI summaries from the Services MCP. [21][24]", "bullets": [ { "label": "Pluggable payment methods", "text_md": "The `method` parameter names the rail: `tempo` uses TIP-20 stablecoins, `stripe` is traditional payment methods through Stripe, `lightning` is Bitcoin over the Lightning Network, and `card` uses encrypted network tokens. Stripe's MPP guide describes card payments through Shared Payment Tokens (SPTs). [18][25]" }, { "label": "Charge and session intents", "text_md": "A `charge` intent collects a fixed one-time payment before the resource is returned. A `session` intent is for streaming, pay-as-you-go payments: the client deposits funds into a channel reserve, then issues signed vouchers off-chain, and the server periodically settles those vouchers on-chain. [15][26]" }, { "label": "MCP JSON-RPC transport", "text_md": "MPP includes an MCP transport binding that maps the Challenge-Credential-Receipt flow onto the Model Context Protocol, so MCP servers can monetize tool calls directly. HTTP services exchange payment data in authentication headers, while MCP tools use that same flow through JSON-RPC. [15][24]" }, { "label": "Service discovery", "text_md": "Clients can browse the mpp.dev service directory or call the Services MCP to rank services, inspect payment offers, and fetch advisory OpenAPI summaries. Runtime 402 Challenges from the target service remain the authoritative source of current payment terms. [21]" } ] } ], "v05_diagram": { "title": "Section 4.1 Payment request flow", "heading": "Section 4.1 Payment request flow", "mermaid": "sequenceDiagram\n participant Client\n participant Server\n Client->>Server: (1) GET /resource\n Server-->>Client: (2) 402 Payment Required, WWW-Authenticate Payment\n Note over Client: (3) Fulfills the payment challenge\n Client->>Server: (4) GET /resource, Authorization Payment credential\n Note over Server: (5) Verifies and settles\n Server-->>Client: (6) 200 OK, Payment-Receipt", "caption_md": "Client sends `GET /resource`. Server returns `402 Payment Required` with `WWW-Authenticate: Payment`. Client retries with `Authorization: Payment`. Server returns `200 OK` with `Payment-Receipt`. [3]" }, "v05_wire_artifact": { "title": "Appendix B.1 one-time charge: HTTP 402 Payment challenge", "heading": "Appendix B.1 one-time charge: HTTP 402 Payment challenge", "lang": "http", "code": "HTTP/1.1 402 Payment Required\nCache-Control: no-store\nContent-Type: application/problem+json\nWWW-Authenticate: Payment id=\"qB3wErTyU7iOpAsD9fGhJk\",\n realm=\"api.example.com\",\n method=\"invoice\",\n intent=\"charge\",\n expires=\"2025-01-15T12:05:00Z\",\n request=\"eyJhbW91bnQiOiIxMDAwIiwiY3VycmVuY3kiOiJVU0QiLCJpbnZvaWNlIjoiaW52XzEyMzQ1In0\"\n\n{\n \"type\": \"https://paymentauth.org/problems/payment-required\",\n \"title\": \"Payment Required\",\n \"status\": 402,\n \"detail\": \"Payment required for access.\",\n \"challengeId\": \"qB3wErTyU7iOpAsD9fGhJk\"\n}", "caption_md": "Appendix B.1 one-time charge. After the challenge, the client sends `Authorization: Payment` and the server returns `Payment-Receipt` on `200 OK`. [3]" }, "v05_counterparts": { "classic_analogues": [ { "name": "HTTP 402 Payment Required (RFC 9110 §15.5.3)", "spec_or_rfc": "RFC 9110 §15.5.3", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "RFC 9110 reserves 402 for future use; MPP sends 402 with a Payment challenge, then Authorization: Payment. [1][6][11][23]" }, { "name": "HTTP WWW-Authenticate (RFC 9110 §11.6.1)", "spec_or_rfc": "RFC 9110 §11.6.1", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "RFC 9110 §11.6.1 defines WWW-Authenticate; MPP's challenge uses scheme Payment and defaults the credential to Authorization. [3][6]" } ], "agentic_peers": [ { "target_id": "x402", "target_name": "x402", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "x402 v2 uses PAYMENT-REQUIRED and PAYMENT-SIGNATURE plus a /settle step; MPP uses WWW-Authenticate: Payment, and mppx can serve both. [4][15][19]" }, { "target_id": "l402", "target_name": "L402", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "L402 uses WWW-Authenticate: L402 plus a macaroon and Lightning invoice; MPP uses scheme Payment and Authorization. [3][5]" }, { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "AP2 secures Payment and Checkout Mandates with SD-JWTs; MPP is the Payment HTTP authentication scheme on one resource. [3][27]" }, { "target_id": "agentic-commerce-protocol", "target_name": "Agentic Commerce Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ACP, maintained by OpenAI and Stripe, connects buyers, agents, and businesses for checkout; MPP pays for one HTTP resource. [3][28]" }, { "target_id": "cloudflare-pay-per-crawl", "target_name": "Cloudflare Pay Per Crawl", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Pay Per Crawl returns HTTP 402 with a crawler-price header; MPP's challenge is WWW-Authenticate with scheme Payment. [3][29][30]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (15 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Sellers, platforms & payment rails", "col4_header": "Payment method (`tempo`, `stripe`, `evm`), intent & asset", "note_md": null, "rows": [ { "actor": "Stripe", "role": "Payment rail (Co-author)", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "`stripe` `charge` via cards, buy-now-pay-later SPTs, and stablecoin offramp into the Stripe balance.", "source_md": "[Stripe MPP Docs (checked 2026-10-30)](https://docs.stripe.com/payments/machine/mpp) [25] · [Stripe Blog (2026-03-18)](https://stripe.com/blog/machine-payments-protocol) [2] · [mpp.dev Payment methods](https://mpp.dev/payment-methods.md) [18] · [mpp.dev Intents](https://mpp.dev/intents.md) [26]" }, { "actor": "Tempo (Tempo Labs / Paradigm)", "role": "Settlement chain (Co-author)", "status": "Supported", "status_display": "Supported · as of 2026-03-18", "col4_md": "`tempo` supports `charge`, `session`, and `subscription`; Tempo Labs and Stripe maintain the spec.", "source_md": "[Tempo Mainnet Blog (2026-03-18)](https://tempo.xyz/blog/mainnet/) [10] · [mpp.dev Intents](https://mpp.dev/intents.md) [26] · [mpp.dev Payment methods](https://mpp.dev/payment-methods.md) [18] · [MPP specs README](https://raw.githubusercontent.com/tempoxyz/mpp-specs/main/README.md) [11] · [Fortune (2026-03-18)](https://fortune.com/2026/03/18/stripe-tempo-paradigm-mpp-ai-payments-protocol/) [31]" }, { "actor": "Visa", "role": "Payment rail (Design partner)", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Design partner extending cards on Visa's network and Acceptance Platform; Card-Based MPP Spec is live.", "source_md": "[Visa Perspectives (03/18/2026)](https://corporate.visa.com/en/sites/visa-perspectives/innovation/visa-card-specification-sdk-for-machine-payments-protocol.html) [16] · [Tempo Mainnet Blog (2026-03-18)](https://tempo.xyz/blog/mainnet/) [10]" }, { "actor": "Lightning Labs (Aperture)", "role": "Reverse proxy", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "Aperture reverse proxy implements `L402` and `MPP`, in production on Loop and Pool.", "source_md": "[Aperture Docs (checked 2026-10-30)](https://docs.lightning.engineering/lightning-network-tools/aperture) [32]" }, { "actor": "Browserbase", "role": "Seller", "status": "Live (HTTP 402)", "status_display": "Live (HTTP 402) · checked 2026-10-30", "col4_md": "HTTP 402 on POST `/browser/session/create`; catalog `tempo` and `stripe` intent `charge`.", "source_md": "[mpp.browserbase.com/browser/session/create (problem document)](https://mpp.browserbase.com/browser/session/create) [17] · [mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] · [Stripe Blog (2026-03-18)](https://stripe.com/blog/machine-payments-protocol) [2]" }, { "actor": "PostalForm", "role": "Seller", "status": "Listed", "status_display": "Listed · as of 2026-10-30", "col4_md": "Catalog active: `tempo` and `stripe` `charge`; POST `/api/machine/mpp/orders` pays print-and-mail.", "source_md": "[mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] · [Stripe Blog (2026-03-18)](https://stripe.com/blog/machine-payments-protocol) [2]" }, { "actor": "StableEnrich", "role": "Seller", "status": "Listed", "status_display": "Listed · as of 2026-10-30", "col4_md": "Catalog active: Merit Systems, `tempo` `charge`; POST `/api/apollo/people-search` finds prospects.", "source_md": "[mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33]" }, { "actor": "Dune", "role": "Seller", "status": "Listed", "status_display": "Listed · as of 2026-10-30", "col4_md": "Catalog active: `tempo` intent `session`; POST `/api/v1/sql/execute` at `https://api.dune.com`.", "source_md": "[mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33]" }, { "actor": "Alchemy", "role": "Seller", "status": "Listed", "status_display": "Listed · as of 2026-10-30", "col4_md": "Catalog active: `tempo` and `stripe` `charge`; POST `/:network/v2` at `https://mpp.alchemy.com`.", "source_md": "[mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33]" } ] }, "side_b": { "visible": true, "heading": "Buying agents, wallets & client SDKs", "col4_header": "Supported methods, CLI/SDK surface & scope", "note_md": null, "rows": [ { "actor": "Stripe Link CLI", "role": "Wallet CLI & MCP server (Co-author)", "status": "Partial", "status_display": "Partial · as of 2026-10-30", "col4_md": "`npx skills add stripe/link-cli` provisions SPT credentials; `mpp pay` buys (US and Canada).", "source_md": "[stripe/link-cli on GitHub](https://github.com/stripe/link-cli) [34] · [Stripe MPP Docs (checked 2026-10-30)](https://docs.stripe.com/payments/machine/mpp) [25]" }, { "actor": "mppx (Tempo Labs & Wevm)", "role": "Client SDK & CLI (Co-author)", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "`mppx` is the Tempo Labs and Wevm reference SDK; `mppx validate` checks sandbox and live roundtrips.", "source_md": "[mpp.dev/sdk.md (checked 2026-10-30)](https://mpp.dev/sdk.md) [35] · [mpp.dev Overview](https://mpp.dev/overview.md) [1] · [mpp.dev FAQ](https://mpp.dev/faq.md) [15] · [Stripe MPP Docs](https://docs.stripe.com/payments/machine/mpp) [25]" }, { "actor": "AWS (Amazon Bedrock AgentCore payments)", "role": "Agent platform / runtime", "status": "Supported", "status_display": "Supported · as of 2026-08-18", "col4_md": "GA 18 August 2026: AgentCore payments pays an MPP service with no extra code.", "source_md": "[AWS ML Blog (18 AUG 2026)](https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/) [9]" }, { "actor": "Cloudflare Agents SDK", "role": "Agent SDK / runtime", "status": "Supported", "status_display": "Supported · as of 2026-08-05", "col4_md": "Agents SDK pays HTTP and MCP tools via `mppx`; the example creates `tempo.charge`.", "source_md": "[Cloudflare Pay from the Agents SDK (Aug 5, 2026)](https://developers.cloudflare.com/agents/tools/payments/mpp/pay-from-agents-sdk/) [36] · [Cloudflare MPP (Aug 5, 2026)](https://developers.cloudflare.com/agents/tools/payments/mpp/) [24]" }, { "actor": "Tempo CLI Wallet", "role": "Wallet CLI (Co-author)", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "Tempo CLI wallet funds agent use of MPP; the directory accepts production-ready services.", "source_md": "[mpp.dev/services (checked 2026-10-30)](https://mpp.dev/services) [21]" } ] }, "additional_tables": [ { "visible": true, "heading": "Community registries", "col4_header": "What the list covers", "note_md": null, "rows": [ { "actor": "Awesome MPP", "role": "Community registry", "status": "Listed", "status_display": "Listed · checked 2026-11-06", "col4_md": "Curated list of MPP specifications, SDKs, and services.", "source_md": "[Awesome MPP](https://github.com/mbeato/awesome-mpp) [37]" } ] } ], "censuses": [ { "label": "mpp.dev/api/services — catalog size (fetched 2026-10-30)", "as_of": "2026-10-30", "value_md": "138 services in the version 1 catalog at mpp.dev/api/services (counted across the services array on 2026-10-30). [33]" }, { "label": "mpp.dev/api/services — status breakdown (fetched 2026-10-30)", "as_of": "2026-10-30", "value_md": "136 active, 1 beta (tempo-api), and 1 maintenance (govlaws). Those three status values are the only ones in the 138-service catalog. [33]" }, { "label": "mpp.dev/api/services — method distribution (fetched 2026-10-30)", "as_of": "2026-10-30", "value_md": "Method keys on the 138 services: 135 tempo, 10 stripe, and 1 evm. A service can list more than one method, so these counts are not a partition of 138. The evm method is Laso Finance, intent charge. Both non-active services (tempo-api beta and govlaws maintenance) list tempo, which is why tempo (135) is not the same count as active (136). [18][33]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "s402", "target_name": "s402", "relation_label": "Peer alternative", "delta": "Retired in September 2026, s402 paid with a signed Sui transaction (including Programmable Transaction Blocks for the prepaid scheme) inside the x402 payment-required envelope, whereas MPP pays with Authorization: Payment answering WWW-Authenticate: Payment.", "item_md": "**[s402](/protocols/s402/)** (Peer alternative) — Retired in September 2026, s402 paid with a signed Sui transaction (including Programmable Transaction Blocks for the prepaid scheme) inside the x402 payment-required envelope, whereas MPP pays with Authorization: Payment answering WWW-Authenticate: Payment." }, { "target_id": "agentic-payments-gating-model", "target_name": "Agent-Initiated Payment Gating", "relation_label": "Complements", "delta": "The draft cites the HTTP Payment authentication scheme and MPP as wires that can satisfy its pre-fulfilment gate, and the draft's own content is the task state machine, which defines no protocol bytes.", "item_md": "**[Agent-Initiated Payment Gating](/protocols/agentic-payments-gating-model/)** (Complements) — The draft cites the HTTP Payment authentication scheme and MPP as wires that can satisfy its pre-fulfilment gate, and the draft's own content is the task state machine, which defines no protocol bytes." }, { "target_id": "kyapay-token", "target_name": "KYAPay Token", "relation_label": "Peer alternative", "delta": "KYAPay is presented as a PAY or KYA-PAY JWT in the KYAPay-Token header, while MPP's retry credential is Authorization: Payment answering a WWW-Authenticate: Payment challenge.", "item_md": "**[KYAPay Token](/protocols/kyapay-token/)** (Peer alternative) — KYAPay is presented as a PAY or KYA-PAY JWT in the KYAPay-Token header, while MPP's retry credential is Authorization: Payment answering a WWW-Authenticate: Payment challenge." }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: mpp\ntitle: \"Machine Payments Protocol (MPP)\"\ntier: flagship\nlifecycle_status: active_draft\ncategory: pay\nform: http-header\nwire_archetype: payments_onchain\nspec_url: https://datatracker.ietf.org/doc/html/draft-httpauth-payment-01\nlast_checked: 2026-11-12\n---\n\n# Machine Payments Protocol (MPP)\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** HTTP header (`http-header`) · **Last checked:** 2026-11-12\n\n> *This page is about the Machine Payments Protocol (MPP), an open protocol co-authored by Tempo and Stripe and launched on March 18, 2026, whose core is the Payment HTTP authentication scheme. It is not x402, whose v2 specification uses a PAYMENT-REQUIRED header and a PAYMENT-SIGNATURE header. It is not L402, whose challenge is a WWW-Authenticate: L402 header containing a macaroon and a Lightning invoice. It is not the bare 402 status code: RFC 9110 says the 402 (Payment Required) status code is reserved for future use. In Lightning, basic_mpp means a node can receive basic multi-part payments. Microsoft uses .mpp for Microsoft Project desktop client files. AWS writes Machine Payment Protocol (singular). mpp.dev, Stripe, and Tempo write Machine Payments Protocol. [1][2][3][4][5][6][7][8][9][10]*\n\n> **In brief:** MPP (Machine Payments Protocol) is an HTTP payment specification co-authored by Tempo Labs and Stripe that lets autonomous agents and automated clients pay for API calls and digital resources on the fly. Giving concrete wire semantics to the long-reserved `402 Payment Required` HTTP status, servers return a `WWW-Authenticate: Payment` challenge and clients retry the request with an `Authorization: Payment` credential across any supported payment rail. [3][11]\n\n**Machine Payments Protocol** (`MPP`) is an open standard for machine-to-machine payments launched on 2026-03-18 and maintained by Tempo Labs and Stripe, whose core wire specification is published as the `Payment` HTTP Authentication Scheme. [2][11][12] When a client requests a protected resource, the server responds with `402 Payment Required` and a `WWW-Authenticate: Payment` challenge; the client retries with an `Authorization: Payment` credential proving payment, and on success servers SHOULD include a `Payment-Receipt` header. [11][13] Published as an individual Standards Track Internet-Draft (`draft-httpauth-payment-01`, updated 2026-09-09 on the IETF Datatracker and expiring 13 March 2027), the specification is an active individual submission and is not formally endorsed by an IETF working group. [14]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | HTTP header (`http-header`) |\n| **Originated by** | Tempo and Stripe, 18 March 2026; draft authors are Tempo Labs and Stripe. [2][3][10] |\n| **Governed by** | Tempo Labs and Stripe maintain it on GitHub; this individual I-D is not IETF-endorsed. [11][12][14] |\n| **Track** | Individual Internet-Draft `draft-httpauth-payment-01`, intended Standards Track, not IETF-endorsed. [3][14] |\n| **IETF tracker** | [draft-httpauth-payment](https://datatracker.ietf.org/doc/draft-httpauth-payment/): Active Internet-Draft (individual); last updated 2026-09-09; IESG state I-D Exists. [14] |\n| **Status** | IESG state I-D Exists, updated 2026-09-09. Tempo, card/Stripe, and Lightning are in production. [14][15][16][17] |\n| **Version** | Datatracker `draft-httpauth-payment-01` published 9 September 2026; paymentauth.org editor's copy of that draft name is dated 2 November 2026 (`2026-11-02`; expires 6 May 2027). [3][13] |\n| **Headers** | `WWW-Authenticate: Payment` challenge; default credential `Authorization`; selected `Payment-Authorization` is MUST; `Payment-Receipt` is SHOULD. `Payment-Authorization` is RECOMMENDED when a resource needs to preserve `Authorization` for ordinary authentication. [3][11][13][18][19] |\n| **Schemes** | HTTP authentication scheme \"Payment\". [3] |\n| **Networks** | Documented methods: `tempo`, `stripe`, `evm`, `card`, `lightning`, `solana`, `xrpl`, `stellar`, `monad`, `nearintents`, `redotpay`. [15][18] |\n| **Transports** | HTTP 402 with the Payment scheme; an MCP binding maps Challenge, Credential, and Receipt. [11][15] |\n| **Message format** | Challenge `request` is base64url JSON; intents belong to a proposed IANA HTTP Payment Intents registry. [3][11] |\n| **IANA registration** | Section 12 proposes the `Payment` scheme, three headers, and two registries; the IANA CSV lists no `Payment`. [3][14][20] |\n| **Specification** | [The \"Payment\" HTTP Authentication Scheme (draft-httpauth-payment-01)](https://datatracker.ietf.org/doc/html/draft-httpauth-payment-01) [3] |\n| **Found at** | Servers answer HTTP 402 with `WWW-Authenticate: Payment`. Curated directory is mpp.dev/services. [11][21][22] |\n| **Licence** | No implementation fees. IETF text is under BCP 78; code uses Revised BSD; mpp-specs uses CC0 1.0. [3][11][12][15] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [HTTP 402 Payment challenge, Credential retry, and Payment-Receipt](#http-402-payment-challenge-credential-retry-and-payment-receipt)\n3. [Payment method modularity, Charge vs Session intents, and service discovery](#payment-method-modularity-charge-vs-session-intents-and-service-discovery)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nAlthough RFC 9110 reserved the HTTP `402` (`Payment Required`) status code for future use, the status code was never standardized in HTTP/1.1 with a common challenge-response wire format. [3][6] The Payment specification defines the \"Payment\" authentication scheme that gives 402 its semantics, so a resource can require a fulfilled payment challenge before access. MPP uses 402 when a server offers a payment Challenge, including retryable Credential validation failures, unlike schemes that use 401 for failed Credentials. [3][23] The protocol is payment-method agnostic and supports any payment network or currency through registered payment method identifiers. Specific payment methods are defined in separate payment method specifications, and each is defined and maintained by the rail behind it. [3][12]\n\n### Section 4.1 Payment request flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n Client->>Server: (1) GET /resource\n Server-->>Client: (2) 402 Payment Required, WWW-Authenticate Payment\n Note over Client: (3) Fulfills the payment challenge\n Client->>Server: (4) GET /resource, Authorization Payment credential\n Note over Server: (5) Verifies and settles\n Server-->>Client: (6) 200 OK, Payment-Receipt\n```\n\n*Client sends `GET /resource`. Server returns `402 Payment Required` with `WWW-Authenticate: Payment`. Client retries with `Authorization: Payment`. Server returns `200 OK` with `Payment-Receipt`. [3]*\n\n### Appendix B.1 one-time charge: HTTP 402 Payment challenge\n\n```http\nHTTP/1.1 402 Payment Required\nCache-Control: no-store\nContent-Type: application/problem+json\nWWW-Authenticate: Payment id=\"qB3wErTyU7iOpAsD9fGhJk\",\n realm=\"api.example.com\",\n method=\"invoice\",\n intent=\"charge\",\n expires=\"2025-01-15T12:05:00Z\",\n request=\"eyJhbW91bnQiOiIxMDAwIiwiY3VycmVuY3kiOiJVU0QiLCJpbnZvaWNlIjoiaW52XzEyMzQ1In0\"\n\n{\n \"type\": \"https://paymentauth.org/problems/payment-required\",\n \"title\": \"Payment Required\",\n \"status\": 402,\n \"detail\": \"Payment required for access.\",\n \"challengeId\": \"qB3wErTyU7iOpAsD9fGhJk\"\n}\n```\n\n*Appendix B.1 one-time charge. After the challenge, the client sends `Authorization: Payment` and the server returns `Payment-Receipt` on `200 OK`. [3]*\n\n---\n\n## HTTP 402 Payment challenge, Credential retry, and Payment-Receipt\n\n`draft-httpauth-payment-01` extends HTTP authentication over status code 402 with structured challenge parameters, bound challenge identifiers, single-use payment credentials, and optional settlement receipts. [12][13]\n\n- **Challenge parameters:** A `WWW-Authenticate: Payment` challenge MUST include a non-empty `id`, a `realm`, a lowercase `method`, and a registered `intent`. The `request` MUST be base64url JSON serialized with JCS and no padding. Servers SHOULD include `expires`, and SHOULD include `digest` when the request has a body. [13]\n- **Stateless HMAC binding:** Servers MUST bind `id` to `realm`, `method`, `intent`, and `request`, and to `expires`, `digest`, `opaque`, and `header` when present. They MAY verify that binding with stored state or with stateless `HMAC-SHA256`. Servers that use HMAC-SHA256 SHOULD set `id` to the base64url HMAC over the pipe-joined challenge fields, using a server secret. [13]\n- **Credential retry:** When a challenge omits `header`, clients MUST retry in `Authorization` as `Authorization: Payment` followed by base64url JSON. That object MUST echo the `challenge` parameters and include a method-specific `payload`. A `source` payer identifier is optional and RECOMMENDED in DID format. Because credentials are bearer tokens, TLS is required, and clients MUST verify `request` amount and recipient rather than `description` before paying. Payment methods used with the scheme MUST provide single-use proof semantics. A payment proof MUST be usable exactly once; subsequent attempts to use the same proof MUST be rejected by the payment method infrastructure. [13]\n- **Receipt and problem types:** Servers SHOULD include a `Payment-Receipt` header on successful responses and MUST NOT return it on error responses; `Payment-Receipt` is an unsigned `base64url-nopad` JSON receipt (`status`, `method`, `timestamp`, and `reference`), not a cryptographic proof. Servers SHOULD return Problem Details (`application/problem+json`, such as `payment-required`, `payment-insufficient`, and `payment-expired`) for payment errors. [13]\n\n---\n\n## Payment method modularity, Charge vs Session intents, and service discovery\n\nAcross stablecoins, cards through Stripe, and custom payment methods, MPP distinguishes `charge` for a one-time payment from `session` for measured usage. Model Context Protocol tools use the same flow through JSON-RPC, and agents can fetch advisory OpenAPI summaries from the Services MCP. [21][24]\n\n- **Pluggable payment methods:** The `method` parameter names the rail: `tempo` uses TIP-20 stablecoins, `stripe` is traditional payment methods through Stripe, `lightning` is Bitcoin over the Lightning Network, and `card` uses encrypted network tokens. Stripe's MPP guide describes card payments through Shared Payment Tokens (SPTs). [18][25]\n- **Charge and session intents:** A `charge` intent collects a fixed one-time payment before the resource is returned. A `session` intent is for streaming, pay-as-you-go payments: the client deposits funds into a channel reserve, then issues signed vouchers off-chain, and the server periodically settles those vouchers on-chain. [15][26]\n- **MCP JSON-RPC transport:** MPP includes an MCP transport binding that maps the Challenge-Credential-Receipt flow onto the Model Context Protocol, so MCP servers can monetize tool calls directly. HTTP services exchange payment data in authentication headers, while MCP tools use that same flow through JSON-RPC. [15][24]\n- **Service discovery:** Clients can browse the mpp.dev service directory or call the Services MCP to rank services, inspect payment offers, and fetch advisory OpenAPI summaries. Runtime 402 Challenges from the target service remain the authoritative source of current payment terms. [21]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **HTTP 402 Payment Required (RFC 9110 §15.5.3)** | `RFC 9110 §15.5.3` | Profiles classic standard | RFC 9110 reserves 402 for future use; MPP sends 402 with a Payment challenge, then Authorization: Payment. [1][6][11][23] |\n| **HTTP WWW-Authenticate (RFC 9110 §11.6.1)** | `RFC 9110 §11.6.1` | Profiles classic standard | RFC 9110 §11.6.1 defines WWW-Authenticate; MPP's challenge uses scheme Payment and defaults the credential to Authorization. [3][6] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[x402](/protocols/x402/)** | Peer alternative | x402 v2 uses PAYMENT-REQUIRED and PAYMENT-SIGNATURE plus a /settle step; MPP uses WWW-Authenticate: Payment, and mppx can serve both. [4][15][19] |\n| **[L402](/protocols/l402/)** | Peer alternative | L402 uses WWW-Authenticate: L402 plus a macaroon and Lightning invoice; MPP uses scheme Payment and Authorization. [3][5] |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Complements | AP2 secures Payment and Checkout Mandates with SD-JWTs; MPP is the Payment HTTP authentication scheme on one resource. [3][27] |\n| **[Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/)** | Complements | ACP, maintained by OpenAI and Stripe, connects buyers, agents, and businesses for checkout; MPP pays for one HTTP resource. [3][28] |\n| **[Cloudflare Pay Per Crawl](/protocols/cloudflare-pay-per-crawl/)** | Peer alternative | Pay Per Crawl returns HTTP 402 with a crawler-price header; MPP's challenge is WWW-Authenticate with scheme Payment. [3][29][30] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (15 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Sellers, platforms & payment rails\n\n| Actor | Role | Status | Payment method (`tempo`, `stripe`, `evm`), intent & asset | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Stripe** | Payment rail (Co-author) | Supported · as of 2026-10-30 | `stripe` `charge` via cards, buy-now-pay-later SPTs, and stablecoin offramp into the Stripe balance. | [Stripe MPP Docs (checked 2026-10-30)](https://docs.stripe.com/payments/machine/mpp) [25] · [Stripe Blog (2026-03-18)](https://stripe.com/blog/machine-payments-protocol) [2] · [mpp.dev Payment methods](https://mpp.dev/payment-methods.md) [18] · [mpp.dev Intents](https://mpp.dev/intents.md) [26] |\n| **Tempo (Tempo Labs / Paradigm)** | Settlement chain (Co-author) | Supported · as of 2026-03-18 | `tempo` supports `charge`, `session`, and `subscription`; Tempo Labs and Stripe maintain the spec. | [Tempo Mainnet Blog (2026-03-18)](https://tempo.xyz/blog/mainnet/) [10] · [mpp.dev Intents](https://mpp.dev/intents.md) [26] · [mpp.dev Payment methods](https://mpp.dev/payment-methods.md) [18] · [MPP specs README](https://raw.githubusercontent.com/tempoxyz/mpp-specs/main/README.md) [11] · [Fortune (2026-03-18)](https://fortune.com/2026/03/18/stripe-tempo-paradigm-mpp-ai-payments-protocol/) [31] |\n| **Visa** | Payment rail (Design partner) | Supported · checked 2026-10-30 | Design partner extending cards on Visa's network and Acceptance Platform; Card-Based MPP Spec is live. | [Visa Perspectives (03/18/2026)](https://corporate.visa.com/en/sites/visa-perspectives/innovation/visa-card-specification-sdk-for-machine-payments-protocol.html) [16] · [Tempo Mainnet Blog (2026-03-18)](https://tempo.xyz/blog/mainnet/) [10] |\n| **Lightning Labs (Aperture)** | Reverse proxy | Supported · as of 2026-10-30 | Aperture reverse proxy implements `L402` and `MPP`, in production on Loop and Pool. | [Aperture Docs (checked 2026-10-30)](https://docs.lightning.engineering/lightning-network-tools/aperture) [32] |\n| **Browserbase** | Seller | Live (HTTP 402) · checked 2026-10-30 | HTTP 402 on POST `/browser/session/create`; catalog `tempo` and `stripe` intent `charge`. | [mpp.browserbase.com/browser/session/create (problem document)](https://mpp.browserbase.com/browser/session/create) [17] · [mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] · [Stripe Blog (2026-03-18)](https://stripe.com/blog/machine-payments-protocol) [2] |\n| **PostalForm** | Seller | Listed · as of 2026-10-30 | Catalog active: `tempo` and `stripe` `charge`; POST `/api/machine/mpp/orders` pays print-and-mail. | [mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] · [Stripe Blog (2026-03-18)](https://stripe.com/blog/machine-payments-protocol) [2] |\n| **StableEnrich** | Seller | Listed · as of 2026-10-30 | Catalog active: Merit Systems, `tempo` `charge`; POST `/api/apollo/people-search` finds prospects. | [mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] |\n| **Dune** | Seller | Listed · as of 2026-10-30 | Catalog active: `tempo` intent `session`; POST `/api/v1/sql/execute` at `https://api.dune.com`. | [mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] |\n| **Alchemy** | Seller | Listed · as of 2026-10-30 | Catalog active: `tempo` and `stripe` `charge`; POST `/:network/v2` at `https://mpp.alchemy.com`. | [mpp.dev/api/services (checked 2026-10-30)](https://mpp.dev/api/services) [33] |\n\n### Buying agents, wallets & client SDKs\n\n| Actor | Role | Status | Supported methods, CLI/SDK surface & scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Stripe Link CLI** | Wallet CLI & MCP server (Co-author) | Partial · as of 2026-10-30 | `npx skills add stripe/link-cli` provisions SPT credentials; `mpp pay` buys (US and Canada). | [stripe/link-cli on GitHub](https://github.com/stripe/link-cli) [34] · [Stripe MPP Docs (checked 2026-10-30)](https://docs.stripe.com/payments/machine/mpp) [25] |\n| **mppx (Tempo Labs & Wevm)** | Client SDK & CLI (Co-author) | Supported · as of 2026-10-30 | `mppx` is the Tempo Labs and Wevm reference SDK; `mppx validate` checks sandbox and live roundtrips. | [mpp.dev/sdk.md (checked 2026-10-30)](https://mpp.dev/sdk.md) [35] · [mpp.dev Overview](https://mpp.dev/overview.md) [1] · [mpp.dev FAQ](https://mpp.dev/faq.md) [15] · [Stripe MPP Docs](https://docs.stripe.com/payments/machine/mpp) [25] |\n| **AWS (Amazon Bedrock AgentCore payments)** | Agent platform / runtime | Supported · as of 2026-08-18 | GA 18 August 2026: AgentCore payments pays an MPP service with no extra code. | [AWS ML Blog (18 AUG 2026)](https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/) [9] |\n| **Cloudflare Agents SDK** | Agent SDK / runtime | Supported · as of 2026-08-05 | Agents SDK pays HTTP and MCP tools via `mppx`; the example creates `tempo.charge`. | [Cloudflare Pay from the Agents SDK (Aug 5, 2026)](https://developers.cloudflare.com/agents/tools/payments/mpp/pay-from-agents-sdk/) [36] · [Cloudflare MPP (Aug 5, 2026)](https://developers.cloudflare.com/agents/tools/payments/mpp/) [24] |\n| **Tempo CLI Wallet** | Wallet CLI (Co-author) | Supported · as of 2026-10-30 | Tempo CLI wallet funds agent use of MPP; the directory accepts production-ready services. | [mpp.dev/services (checked 2026-10-30)](https://mpp.dev/services) [21] |\n\n### Community registries\n\n| Actor | Role | Status | What the list covers | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Awesome MPP** | Community registry | Listed · checked 2026-11-06 | Curated list of MPP specifications, SDKs, and services. | [Awesome MPP](https://github.com/mbeato/awesome-mpp) [37] |\n\n### Ecosystem censuses\n\n- **mpp.dev/api/services — catalog size (fetched 2026-10-30)** (*as of 2026-10-30*): 138 services in the version 1 catalog at mpp.dev/api/services (counted across the services array on 2026-10-30). [33]\n- **mpp.dev/api/services — status breakdown (fetched 2026-10-30)** (*as of 2026-10-30*): 136 active, 1 beta (tempo-api), and 1 maintenance (govlaws). Those three status values are the only ones in the 138-service catalog. [33]\n- **mpp.dev/api/services — method distribution (fetched 2026-10-30)** (*as of 2026-10-30*): Method keys on the 138 services: 135 tempo, 10 stripe, and 1 evm. A service can list more than one method, so these counts are not a partition of 138. The evm method is Laso Finance, intent charge. Both non-active services (tempo-api beta and govlaws maintenance) list tempo, which is why tempo (135) is not the same count as active (136). [18][33]\n\n---\n\n## See also\n\n- **[s402](/protocols/s402/)** *(Peer alternative)* — Retired in September 2026, s402 paid with a signed Sui transaction (including Programmable Transaction Blocks for the prepaid scheme) inside the x402 payment-required envelope, whereas MPP pays with Authorization: Payment answering WWW-Authenticate: Payment.\n- **[Agent-Initiated Payment Gating](/protocols/agentic-payments-gating-model/)** *(Complements)* — The draft cites the HTTP Payment authentication scheme and MPP as wires that can satisfy its pre-fulfilment gate, and the draft's own content is the task state machine, which defines no protocol bytes.\n- **[KYAPay Token](/protocols/kyapay-token/)** *(Peer alternative)* — KYAPay is presented as a PAY or KYA-PAY JWT in the KYAPay-Token header, while MPP's retry credential is Authorization: Payment answering a WWW-Authenticate: Payment challenge.\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. Tempo and Stripe (mpp.dev), *What is MPP?* (checked 2026-10-30) — \n2. Jeff Weinstein and Steve Kaliski (Stripe), *Introducing the Machine Payments Protocol* (2026-03-18) — \n3. B. Ryan, J. Moxey, T. Meagher, J. Weinstein, and S. Kaliski, *The \"Payment\" HTTP Authentication Scheme (draft-httpauth-payment-01 HTML)* (published 9 September 2026; expires 13 March 2027) — \n4. x402 Foundation, *X402 Protocol Specification* (protocol version 2) — \n5. Lightning Labs, *L402 Protocol Specification* (checked 2026-10-30) — \n6. R. Fielding, M. Nottingham, and J. Reschke (IETF), *RFC 9110: HTTP Semantics* (June 2022) — \n7. Lightning Network, *BOLT #9: Assigned Feature Flags* (checked 2026-10-30) — \n8. Microsoft, *Import projects from the Microsoft Project desktop client* (checked 2026-10-30) — \n9. Chethan Shriyan and Madhu Samhitha Vangara (AWS), *Amazon Bedrock AgentCore payments is now generally available* (2026-08-18) — \n10. Tempo, *Tempo Mainnet Is Live: Build on Tempo Today* (2026-03-18) — \n11. Tempo Labs and Stripe, *Machine Payments Protocol (MPP)* (checked 2026-10-30) — \n12. Tempo and Stripe (mpp.dev), *Governance* (checked 2026-10-30) — \n13. B. Ryan, J. Moxey, T. Meagher, J. Weinstein, and S. Kaliski, *The \"Payment\" HTTP Authentication Scheme (editor rendering)* (published 2 November 2026; expires 6 May 2027) — \n14. IETF Datatracker, *draft-httpauth-payment — The \"Payment\" HTTP Authentication Scheme (IETF Datatracker)* (last updated 2026-09-09) — \n15. Tempo and Stripe (mpp.dev), *Frequently asked questions* (checked 2026-10-30) — \n16. Visa, *Visa introduces card spec and SDK for MPP* (2026-03-18) — \n17. Browserbase, *Payment Required (browser session create)* (checked 2026-10-30) — \n18. Tempo and Stripe (mpp.dev), *Payment methods* (checked 2026-10-30) — \n19. Tempo and Stripe (mpp.dev), *MPP vs x402* (checked 2026-10-30) — \n20. IANA, *Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry (CSV)* (checked 2026-10-30) — \n21. Machine Payments Protocol, *MPP services: APIs that accept MPP payments* (checked 2026-10-30) — \n22. Tempo, *tempoxyz/mpp* (checked 2026-10-30) — \n23. Tempo and Stripe (mpp.dev), *HTTP 402* (checked 2026-10-30) — \n24. Cloudflare, *MPP (Machine Payments Protocol)* (last updated 2026-08-05) — \n25. Stripe, *MPP* (checked 2026-10-30) — \n26. Tempo and Stripe (mpp.dev), *Intents* (checked 2026-10-30) — \n27. AP2, *Agent Payments Protocol specification* (checked 2026-10-30) — \n28. OpenAI and Stripe, *Agentic Commerce Protocol* (checked 2026-10-30) — \n29. Cloudflare, *Introducing pay per crawl: Enabling content owners to charge AI crawlers for access* (published 2025-07-01; modified 2026-07-15) — \n30. Cloudflare, *What is Pay Per Crawl?* (checked 2026-10-31) — \n31. Ben Weiss (Fortune), *Stripe-backed crypto startup Tempo releases AI payments protocol, launches blockchain* (published 2026-03-18; modified 2026-03-18) — \n32. Lightning Labs, *Aperture* (checked 2026-10-30) — \n33. Machine Payments Protocol, *MPP services catalog* (checked 2026-10-30) — \n34. Stripe, *link-cli* (checked 2026-10-30) — \n35. Tempo and Stripe (mpp.dev), *SDKs* (checked 2026-10-30) — \n36. Cloudflare, *Pay from the Agents SDK* (last updated 2026-08-05) — \n37. mbeato, *Awesome MPP* (fetched 2026-11-06) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "ERC-8004", "adoption": { "level": "observed", "by": "ERC-8004 Identity and Reputation Registries, Virtuals Protocol, 8004scan (AltLayer), Quicknode ERC-8004 Explorer, RNWY, Agent0 SDK, and ChaosChain", "probe_run": null }, "aliases": [ "Trustless Agents", "EIP-8004" ], "analog": "DNS plus a public review/reputation ledger", "collisions": [], "discovery": { "mechanism": "ERC-721 Identity Registry token (agentId) resolves via agentURI to a JSON agent registration file; optional HTTPS domain proof at a fixed well-known path", "path": "/.well-known/agent-registration.json" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://eips.ethereum.org/EIPS/eip-8122", "claim": "Prem Makeig (@nxt3d), *ERC-8122: Minimal Agent Registry*, created 2025-12-17", "date": null, "quote": "This protocol proposes a lightweight onchain registry for discovering AI agents using ERC-6909 as the underlying registry design, ERC-7930 for cross-chain agent identification, and ERC-8048 for onchain metadata. / ERC-8004 provides an existing agent registry standard, but it defines a singleton registry-one per chain.", "ref": 1 }, { "label": "[2]", "url": "https://eips.ethereum.org/EIPS/eip-8183", "claim": "Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce*, created 2026-02-25", "date": null, "quote": "ACP remains the payment and escrow layer; ERC‑8004 is the identity and reputation layer.", "ref": 2 }, { "label": "[3]", "url": "https://eips.ethereum.org/EIPS/eip-8126", "claim": "Leigh Cronian (Cybercentry) and Chris Johnson (Virtuals), *ERC-8126: AI Agent Verification*, created 2026-01-15", "date": null, "quote": "This ERC defines a standard interface for verifying AI agents on Ethereum that have been registered via ERC-8004. / unified risk score (0-100) / Verification attestations can additionally be posted to ERC-8004's Validation Registry", "ref": 3 }, { "label": "[4]", "url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8004.md", "claim": "Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERCS/erc-8004.md (Trustless Agents)*, created 2025-08-13; fetched 2026-10-30", "date": null, "quote": "This protocol proposes to use blockchains to **discover, choose, and interact with agents across organizational boundaries** without pre-existing trust, thus enabling **open-ended agent economies**. / However, these agent communication protocols don't inherently cover agent discovery and trust. / eip: 8004 title: Trustless Agents description: Discover agents and establish trust through reputation and validation author: Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis), Jordan Ellis , Erik Reppel discussions-to: https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098 status: Draft type: Standards Track category: ERC created: 2025-08-13 / handle based on ERC-721 with URIStorage extension / New agents can be minted by calling one of these functions: … function register(string agentURI) external returns (uint256 agentId) / \"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\" / \"services\": [ { \"name\": \"web\", \"endpoint\": \"https://web.agentxyz.com/\" }, { \"name\": \"A2A\" / \"name\": \"MCP\" / \"name\": \"OASF\" / \"name\": \"ENS\" / \"name\": \"DID\" / function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external / \"supportedTrust\": [ \"reputation\", \"crypto-economic\", \"tee-attestation\" ] / An agent MAY optionally prove control of an HTTPS endpoint-domain by publishing https://{endpoint-domain}/.well-known/agent-registration.json / \"registrations\" / author: Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis) , Jordan Ellis , Erik Reppel discussions-to: https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098 status: Draft type: Standards Track category: ERC created: 2025-08-13 requires: 155, 712, 721, 1271 / status: Draft / The *version* field in endpoints is a SHOULD, not a MUST. / three lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons / The Identity Registry uses ERC-721 with the URIStorage extension / tokenId* in ERC-721 is referred to as *agentId* and *tokenURI* in ERC-721 is referred to as *agentURI* / A colon-separated string {namespace}:{chainId}:{identityRegistry} / function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash) / The *valueDecimals* MUST be between 0 and 18. / valid EIP-712 signature for EOAs or ERC-1271 for smart contract wallets / publishing https://{endpoint-domain}/.well-known/agent-registration.json / description: Discover agents and establish trust through reputation and validation / Model context protocol (MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent (A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. / This protocol proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust / Developers can choose from different trust models: reputation systems using client feedback, validation via stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, or trusted execution environment (TEE) oracles. / Payments are orthogonal to this protocol and not covered here. / The *supportedTrust* field is OPTIONAL. If absent or empty, this ERC is used only for discovery, not for trust. / function getSummary(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2) / clientAddresses MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. / While this ERC cryptographically ensures the registration file corresponds to the on-chain agent / it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. / This ERC addresses this need through three lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons: / function register(string agentURI) external returns (uint256 agentId) / The *agentURI* MUST resolve to the agent registration file. / Users MAY treat the endpoint-domain as verified if the file is reachable over HTTPS and includes a `registrations` entry whose `agentRegistry` and `agentId` match the on-chain agent / When the Reputation Registry is deployed, the *identityRegistry* address is set via `initialize(address identityRegistry_)` / The feedback submitter MUST NOT be the agent owner or an approved operator for *agentId*. / This function MUST be called by the owner or operator of *agentId*. / This function MUST be called by the *validatorAddress* specified in the original request. / The registration file MUST have the following structure: / New agents can be minted by calling one of these functions / A colon-separated string {namespace}:{chainId}:{identityRegistry} (e.g., eip155:1:0x742...) / eip155 for EVM chains / \"name\": \"A2A\" / Agents SHOULD have at least one registration (multiple are possible), and all fields in the registration are mandatory. / The *supportedTrust* field is OPTIONAL. / an agent MAY optionally prove control of an HTTPS endpoint-domain / containing at least a registrations list (or the full agent registration file) / The key agentWallet is reserved and cannot be set via setMetadata() or during register() (including the metadata array overload). / It represents the address where the agent receives payments and is initially set to the owner's address. / To change it, the agent owner must prove control of the new wallet by providing a valid EIP-712 signature for EOAs or ERC-1271 for smart contract wallets / function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) / When the agent is transferred, agentWallet is automatically cleared (effectively resetting it to the zero address) and must be re-verified by the new owner. / When the Reputation Registry is deployed, the *identityRegistry* address is set via initialize(address identityRegistry_) / function getIdentityRegistry() external view returns (address identityRegistry) / function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash) external / The *agentId* must be a validly registered agent. The *valueDecimals* MUST be between 0 and 18. The feedback submitter MUST NOT be the agent owner or an approved operator for *agentId*. *tag1*, *tag2*, *endpoint*, *feedbackURI*, and *feedbackHash* are OPTIONAL. / The feedback fields *value*, *valueDecimals*, *tag1*, *tag2*, and *isRevoked* are stored in the contract storage along with the feedbackIndex (a 1-indexed counter of feedback submissions that *clientAddress* has given to *agentId*). The fields *endpoint*, *feedbackURI*, and *feedbackHash* are emitted but are not stored. / event NewFeedback(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, int128 value, uint8 valueDecimals, string indexed indexedTag1, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash) / function validationRequest(address validatorAddress, uint256 agentId, string requestURI, bytes32 requestHash) / function validationResponse(bytes32 requestHash, uint8 response, string responseURI, bytes32 responseHash, string tag) / stake-secured inference re-execution, zkML verifiers or TEE oracles / *tag1*, *tag2*, *endpoint*, *feedbackURI*, and *feedbackHash* are OPTIONAL. / // MUST FIELDS \"agentRegistry\": \"eip155:1:{identityRegistry}\", \"agentId\": 22, \"clientAddress\": \"eip155:1:{clientAddress}\", \"createdAt\": \"2025-09-23T12:00:00Z\", \"value\": 100, \"valueDecimals\": 0, // ALL OPTIONAL FIELDS / \"proofOfPayment\": { // this can be used for x402 proof of payment \"fromAddress\": \"0x00...\", \"toAddress\": \"0x00...\", \"chainId\": \"1\", \"txHash\": \"0x00...\" } / An agent registered and receiving feedback on chain A can still operate and transact on other chains / { \"name\": \"A2A\", \"endpoint\": \"https://agent.example/.well-known/agent-card.json\", \"version\": \"0.3.0\" } / { \"name\": \"MCP\", \"endpoint\": \"https://mcp.agent.eth/\", \"version\": \"2025-06-18\" } / \"x402Support\": false / how x402 payments … can enrich feedback signals", "ref": 4 }, { "label": "[5]", "url": "https://raw.githubusercontent.com/erc-8004/erc-8004-contracts/master/README.md", "claim": "erc-8004, *ERC-8004 contracts README*, fetched 2026-10-30", "date": null, "quote": "Ethereum Mainnet - IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 - ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 … ValidationRegistryUpgradeable.sol - Validation request/response (upgradeable) / The Validation Registry portion of the ERC-8004 spec is still under active update and discussion with the TEE community. / ERC-8004 is a community effort coordinated by Marco De Rossi (MetaMask) and Davide Crapis (EF), with the co-authorship of Jordan Ellis (Google) and Erik Reppel (Coinbase). / The Validation Registry portion of the ERC-8004 spec is still under active update / Ethereum Mainnet - IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 - ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 / Ethereum Mainnet - IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 - ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 #### Ethereum Sepolia - IdentityRegistry: 0x8004A818BFB912233c491871b3d84c89A494BD9e - ReputationRegistry: 0x8004B663056A597Dffe9eCcC1965A193B7388713 / Ethereum Mainnet … Base Mainnet … Abstract Mainnet … Arbitrum Mainnet … Avalanche Mainnet … BSC Mainnet … Celo Mainnet … Gnosis Mainnet … GOAT Network Mainnet … Linea Mainnet … Mantle Mainnet … MegaETH Mainnet … Metis Mainnet … Monad Mainnet … Optimism Mainnet … Polygon Mainnet … Robinhood Chain Mainnet … Scroll Mainnet … SKALE Base Mainnet … Soneium Mainnet … Taiko Mainnet … XLayer Mainnet … Billions Mainnet … Injective Mainnet … 0G Mainnet / Ethereum Sepolia … Base Sepolia … Abstract Testnet … Arbitrum Testnet … Avalanche Testnet … BSC Testnet … Celo Testnet … Linea Sepolia … Mantle Testnet … MegaETH Testnet … Metis Sepolia … Monad Testnet … Optimism Testnet … Polygon Amoy … Robinhood Chain Testnet … Scroll Testnet … SKALE Base Sepolia … Soneium Minato … Taiko Hoodi … XLayer Testnet … Hedera Testnet … Arc Testnet … Billions Testnet … Injective Testnet … 0G Galileo Testnet / Ethereum Sepolia - IdentityRegistry: 0x8004A818BFB912233c491871b3d84c89A494BD9e - ReputationRegistry: 0x8004B663056A597Dffe9eCcC1965A193B7388713", "ref": 5 }, { "label": "[6]", "url": "https://eips.ethereum.org/EIPS/eip-8004", "claim": "Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERC-8004: Trustless Agents*, created 2025-08-13; fetched 2026-10-30", "date": null, "quote": "Draft Standards Track: ERC / Users MAY treat the endpoint-domain as verified if the file is reachable over HTTPS and includes a registrations entry whose agentRegistry and agentId match the on-chain agent; / This protocol proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust, thus enabling open-ended agent economies. / Copyright and related rights waived via CC0. / lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons", "ref": 6 }, { "label": "[7]", "url": "https://raw.githubusercontent.com/sudeepb02/awesome-erc8004/main/README.md", "claim": "Sudeep (sudeepb02), *Awesome ERC-8004*, fetched 2026-10-30", "date": null, "quote": "The Identity Registry uses vanity address 0x8004A169... on mainnets and 0x8004A818... on testnets. / | Ethereum | 0x8004A169...432 | 0x8004BAa1...b63 | / CAIP-10: Chain-agnostic account identification / What standards does ERC-8004 build upon? / CompraBTC - Non-custodial Bitcoin DCA agent on Celo", "ref": 7 }, { "label": "[8]", "url": "https://rnwy.com/skill.md", "claim": "AI Rights Institute, *RNWY skill.md*, version 7.5.0; fetched 2026-10-30", "date": null, "quote": "Same address on all EVM chains (CREATE2): 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 / version: 7.5.0 / POST to https://rnwy.com/api/mcp / reviewer_analysis exposes sybil patterns by checking every reviewer's wallet age and funding source / Covers ERC-8004, Olas, Virtuals, and SATI registries", "ref": 8 }, { "label": "[9]", "url": "https://www.8004.org/blog/welcome-to-8004", "claim": "ERC-8004 Community, *Welcome to ERC-8004 and the open agentic economy*, published 2026-01-29", "date": null, "quote": "2026-01-29 … Today, ERC-8004, the standard for Trustless Agents, is officially live on Ethereum mainnet. / date: \"2026-01-29\" / Today, ERC-8004, the standard for Trustless Agents, is officially live on Ethereum mainnet. / The registries are deployed as singleton contracts, meaning there's one canonical deployment per chain that all agents share. / All deployments will use singleton contracts with verified, identical bytecode.", "ref": 9 }, { "label": "[10]", "url": "https://arxiv.org/html/2606.26028", "claim": "Xihan Xiong, Zelin Li, Wei Wei, Qin Wang, William Knottenbelt, and Zhipeng Wang, *Can Trustless Agents Be Trusted? An Empirical Study of the ERC-8004 Decentralized AI Agent Ecosystem*, submitted 2026-06-24; revised 2026-10-18 (v3)", "date": null, "quote": "The ERC-8004 (\"Trustless Agents\") protocol De Rossi et al. (2025) fills this gap. Introduced on the Ethereum mainnet on January 29, 2026 / QuantuLabs 8004-solana: an ERC-8004 sdk for solana. / covering the period from protocol deployment through May 13, 2026 / We crawl on-chain Identity and Reputation events, off-chain files, and x402 payment transactions. / a substantial fraction of reviewers ( 73.5 % 73.5\\%, 59.2 % 59.2\\%, and 90.6 % 90.6\\% across Ethereum, BSC, and Base) exhibit coordinated Sybil behavior", "ref": 10 }, { "label": "[11]", "url": "https://www.8004.org/learn", "claim": "ERC-8004 Community, *8004 Learn*, fetched 2026-10-30", "date": null, "quote": "Note: the Validation Registry is still undergoing technical due diligence and is not yet available. / the Validation Registry is still undergoing technical due diligence and is not yet available.", "ref": 11 }, { "label": "[12]", "url": "https://github.com/BRC8004/brc8004-contracts", "claim": "BRC8004, *BRC8004: Trustless Agents on BNB Chain*, fetched 2026-11-06", "date": null, "quote": "Implementation of the ERC-8004 protocol for agent discovery and trust through reputation on BNB Chain. / eip155:{chainId}:{identityRegistry}", "ref": 12 }, { "label": "[13]", "url": "https://anchor-x402.com/.well-known/agent-registration.json", "claim": "anchor-x402, *agent-registration.json (anchor-x402)*, fetched 2026-10-30", "date": null, "quote": "\"agentRegistry\": \"solana:101:metaplex\" / \"agentRegistry\": \"eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432\"", "ref": 13 }, { "label": "[14]", "url": "https://a2a-protocol.org/latest/specification/", "claim": "A2A Protocol, *Agent2Agent (A2A) Protocol Specification*, fetched 2026-10-30", "date": null, "quote": "an open standard for secure communication and interoperability between AI agents. / A2A Servers MUST make an Agent Card available.", "ref": 14 }, { "label": "[15]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification 2026-07-28*, version 2026-07-28", "date": null, "quote": "MCP provides a standardized way to connect LLMs with the context they need.", "ref": 15 }, { "label": "[16]", "url": "https://datatracker.ietf.org/doc/draft-narajala-courtney-ansv2/", "claim": "Scott Courtney, Vineeth Sai Narajala, Ken Huang, Idan Habler, and Akram Sheriff, *draft-narajala-courtney-ansv2 — Agent Name Service v2 (ANS): A Domain-Anchored Trust Layer for Autonomous AI Agent Identity (IETF Datatracker)*, draft-narajala-courtney-ansv2-01; last updated 2026-10-15", "date": null, "quote": "The _ans TXT record is a connection hint published in DNS, telling a client which protocol the agent supports and where to find the metadata. / child-label records (_ans, _ans-badge, _443._tcp) / recommends that zones be DNSSEC-signed", "ref": 16 }, { "label": "[17]", "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md", "claim": "x402 Foundation, *X402 Protocol Specification*, protocol version 2", "date": null, "quote": "This specification defines the core x402 protocol for internet-native payments.", "ref": 17 }, { "label": "[18]", "url": "https://whitepaper.virtuals.io/acp/acp-changelogs", "claim": "Virtuals Protocol, *ACP Changelogs*, ERC-8004 release note 2026-02-01", "date": null, "quote": "01 Feb 2026 … ERC-8004 support has been fully enabled for all agents that have completed the ACP agent registration process. … All graduated agents are automatically registered on ERC-8004. … Agent reviews and ratings are now written directly on-chain via ERC-8004, under the corresponding agent identity.", "ref": 18 }, { "label": "[19]", "url": "https://8004scan.io/", "claim": "Alt Research, *8004scan*, fetched 2026-10-30", "date": null, "quote": "Identity, reputation and validation for trustless agents across 29 chains. / \"name\":\"Alt Research\",\"url\":\"https://www.altlayer.io\"", "ref": 19 }, { "label": "[20]", "url": "https://erc-8004.quicknode.com/", "claim": "Quicknode, *ERC-8004 Explorer*, fetched 2026-10-30", "date": null, "quote": "Query ERC-8004 registrations, reputation, feedback, and validations across 32 EVM networks through a single JSON-RPC endpoint. / Pay per request in USDC over x402 / The composite formula is public", "ref": 20 }, { "label": "[21]", "url": "https://raw.githubusercontent.com/agent0lab/agent0-ts/main/README.md", "claim": "agent0lab, *Agent0 SDK*, fetched 2026-10-30", "date": null, "quote": "Agent0 is the TypeScript SDK for agentic economies. / using blockchain infrastructure (ERC-8004) / Publish MCP and A2A endpoints, with automated extraction of MCP tools and A2A skills from endpoints / OASF taxonomies / Subgraph indexing both on-chain and IPFS data", "ref": 21 }, { "label": "[22]", "url": "https://raw.githubusercontent.com/ChaosChain/chaoschain/main/README.md", "claim": "ChaosChain, *ChaosChain README*, fetched 2026-10-30", "date": null, "quote": "RewardsDistributor V4 correctly publishes verifier consensus accuracy to ERC-8004. Both sides of reputation now populated.", "ref": 22 } ], "form": "onchain-registry", "governance": "Ethereum EIP process; no formal steward until finalized", "group": null, "history": [ { "date": "2026-10-29", "note": "Verified record against EIP-8004 primary spec, GitHub commit history, 8004.org, live /.well-known/agent-registration.json deployments, explorers/SDKs, and arXiv:2606.26028" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "erc-8004", "implementation": "multi-implementation", "last_verified": "2026-11-06", "name": "ERC-8004: Trustless Agents", "native_status": "`status: Draft` on master ERCS/erc-8004.md (created 2025-08-13) and Draft on the published EIP page. Commit cb7ae283 (2025-10-08) is titled Move to Review; the fetched master file and published page do not contain status: Review. Newest file commit is 503591a6 (2026-01-25).", "origin": { "date": "2025-08-13", "org": "Marco De Rossi (@MarcoMetaMask, AI Lead, MetaMask / Consensys), Davide Crapis (@dcrapis, Head of AI, Ethereum Foundation), Jordan Ellis (jordanellis@google.com, Software Engineer, Google), and Erik Reppel (erik.reppel@coinbase.com, Head of Engineering, Coinbase)" }, "part_of": null, "parties": [ "agent-registry", "agent-agent" ], "phase": "draft", "probe": { "method": "GET", "on_absent": "Endpoint-domain control is not proven by this optional file; the agent's core identity may still be valid via the onchain agentURI directly", "parse": "JSON body has a registrations[] entry whose agentRegistry (eip155:{chainId}:{identityRegistry}) and agentId match the onchain agent being checked", "path": "https://{endpoint-domain}/.well-known/agent-registration.json" }, "question": "Who is an agent, and what onchain identity, reputation and validation record does it carry?", "scope": "general", "spec_url": "https://eips.ethereum.org/EIPS/eip-8004", "step": "identify", "summary_md": "**ERC-8004 (Trustless Agents)** is a Standards Track Ethereum Request for Comments (drafted August 13, 2025 by Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel) that specifies three on-chain singleton registries (`IdentityRegistry`, `ReputationRegistry`, and `ValidationRegistry`) for discovering and evaluating autonomous agents across organizational boundaries without pre-existing trust. Each agent is minted via `register(string agentURI)` as an ERC-721 token with `URIStorage` whose `agentURI` resolves to a registration JSON document (`\"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\"`) listing `services` entries (such as `A2A`, `MCP`, `OASF`, `ENS`, or `DID`), while binding payment addresses on-chain via `setAgentWallet`, alongside `supportedTrust` models (`reputation`, `crypto-economic`, and `tee-attestation`). Optionally, an agent can verify control of an HTTPS endpoint domain by serving a matching `registrations` entry at `/.well-known/agent-registration.json`. While the EIP specification remains in `Draft` status on `eips.ethereum.org`, deterministic `CREATE2` singleton contracts for the Identity (`0x8004A169...`) and Reputation (`0x8004BAa1...`) registries launched on Ethereum Mainnet on January 29, 2026 and are deployed across peer EVM chains, whereas the Validation Registry remains under active specification update.", "track": "community", "version": { "date": "2025-08-13", "label": "Draft EIP; registration schema `eip-8004#registration-v1` (per-endpoint `version` field is `SHOULD`)", "citations": [ { "source_url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8004.md", "anchor_quote": "status: Draft" }, { "source_url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8004.md", "anchor_quote": "\"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\"" }, { "source_url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8004.md", "anchor_quote": "The *version* field in endpoints is a SHOULD, not a MUST." } ] }, "watch": [ { "type": "erc", "num": 8004 } ], "use_cases": [ "agent-naming", "prove-agent-identity", "describe-agent-capabilities", "audit-agent-actions" ], "audience": [ "agent-builder", "platform", "standards-body" ], "pairs_with": [ "a2a", "mcp", "ans", "erc-8126", "x402" ], "prerequisites": [], "hatnote_md": "ERC-8004 defines per-chain singleton identity, reputation, and validation registries; for the multi-registry minimal factory alternative using ERC-6909 and ERC-8048, see [ERC-8122](https://eips.ethereum.org/EIPS/eip-8122); for the job-escrow commerce layer that delegates identity and reputation to ERC-8004, see [ERC-8183](/protocols/erc-8183/); and for multi-dimensional risk-score verification of ERC-8004 agents, see [ERC-8126](/protocols/erc-8126/).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-06", "v05_hatnote_html_md": "ERC-8004 defines per-chain singleton identity, reputation, and validation registries; for the multi-registry minimal factory alternative using ERC-6909 and ERC-8048, see [ERC-8122](https://eips.ethereum.org/EIPS/eip-8122); for the job-escrow commerce layer that delegates identity and reputation to ERC-8004, see [ERC-8183](/protocols/erc-8183/); and for multi-dimensional risk-score verification of ERC-8004 agents, see [ERC-8126](/protocols/erc-8126/). [1][2][3]", "v05_elevator_pitch_md": "ERC-8004 is an Ethereum standard that gives autonomous AI agents portable on-chain identities, public reputation records, and verifiable execution proofs so services from different organizations can find and evaluate one another. Because communication protocols like MCP and A2A do not solve cross-organization discovery or trust on their own, ERC-8004 anchors each agent to an on-chain `IdentityRegistry` token pointing to an `agentURI` registration file alongside shared `ReputationRegistry` and `ValidationRegistry` contracts. [4][5]", "v05_lead_md": "**ERC-8004 (Trustless Agents)** is a Standards Track Ethereum Request for Comments (drafted August 13, 2025 by Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel) that specifies three on-chain singleton registries (`IdentityRegistry`, `ReputationRegistry`, and `ValidationRegistry`) for discovering and evaluating autonomous agents across organizational boundaries without pre-existing trust. [4][5] Each agent is minted via `register(string agentURI)` as an ERC-721 token with `URIStorage` whose `agentURI` resolves to a registration JSON document (`\"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\"`) listing `services` entries (such as `A2A`, `MCP`, `OASF`, `ENS`, or `DID`), while binding payment addresses on-chain via `setAgentWallet`, alongside `supportedTrust` models (`reputation`, `crypto-economic`, and `tee-attestation`). Optionally, an agent can verify control of an HTTPS endpoint domain by serving a matching `registrations` entry at `/.well-known/agent-registration.json`. [4] While the EIP specification remains in `Draft` status on `eips.ethereum.org`, deterministic `CREATE2` singleton contracts for the Identity (`0x8004A169...`) and Reputation (`0x8004BAa1...`) registries launched on Ethereum Mainnet on January 29, 2026 and are deployed across peer EVM chains, whereas the Validation Registry remains under active specification update. [5][6][7][8][9]", "v05_identity_sentence_md": "**ERC-8004 (Trustless Agents)** is a Standards Track Ethereum Request for Comments (drafted August 13, 2025 by Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel) that specifies three on-chain singleton registries (`IdentityRegistry`, `ReputationRegistry`, and `ValidationRegistry`) for discovering and evaluating autonomous agents across organizational boundaries without pre-existing trust. [4][5]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Identify](/category/identify/) (`identify`)" }, { "label": "Form", "value_md": "On-chain registry (`onchain-registry`)" }, { "label": "Originated by", "value_md": "Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis), Jordan Ellis, and Erik Reppel; created 2025-08-13 [4]" }, { "label": "Governed by", "value_md": "Community effort: Marco De Rossi (MetaMask), Davide Crapis (EF), Jordan Ellis (Google), Erik Reppel (Coinbase). [4][5]" }, { "label": "Track", "value_md": "Community (`community`); EIP `type: Standards Track`, `category: ERC`. [4][5]" }, { "label": "Status", "value_md": "Draft (created 2025-08-13). Mainnet Identity and Reputation live since 2026-01-29; Validation Registry unavailable. [4][5][9][10][11]" }, { "label": "Version", "value_md": "Draft EIP; registration schema `eip-8004#registration-v1` (per-endpoint `version` field is `SHOULD`) [4]" }, { "label": "Networks", "value_md": "Per-chain singletons on Ethereum Mainnet and 24 peer EVM mainnets (`IdentityRegistry` `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`; `ReputationRegistry` `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`) [4][5]" }, { "label": "Token format", "value_md": "ERC-721 with URIStorage. `tokenId` is `agentId` and `tokenURI` is `agentURI`. `agentRegistry` is `{namespace}:{chainId}:{identityRegistry}`. [4]" }, { "label": "Record format", "value_md": "Registration `#registration-v1` with `services` and `registrations`; `giveFeedback` `valueDecimals` MUST be 0-18. [4]" }, { "label": "Found at", "value_md": "`/.well-known/agent-registration.json` on an HTTPS endpoint domain (optional domain proof) [4][6]" }, { "label": "Specification", "value_md": "[ERC-8004: Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004) [4][6]" }, { "label": "Licence", "value_md": "CC0 (copyright and related rights waived) [6]" } ], "v05_problem_md": "Model context protocol (MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent (A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. However, these agent communication protocols don't inherently cover agent discovery and trust. [4] ERC-8004 uses blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust. Across its Identity, Reputation, and Validation registries, developers can combine client-feedback reputation, stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, and trusted execution environment (TEE) oracles. [4] Payments are orthogonal to ERC-8004 and not covered by the specification. The `supportedTrust` field is OPTIONAL; if absent or empty, ERC-8004 is used only for discovery, not for trust. On `getSummary`, `clientAddresses` MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. While ERC-8004 cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. [4]", "v05_mechanism_delta_md": "ERC-8004 uses blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust. Across its Identity, Reputation, and Validation registries, developers can combine client-feedback reputation, stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, and trusted execution environment (TEE) oracles. [4]", "v05_scope_boundary_md": "Payments are orthogonal to ERC-8004 and not covered by the specification. The `supportedTrust` field is OPTIONAL; if absent or empty, ERC-8004 is used only for discovery, not for trust. On `getSummary`, `clientAddresses` MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. While ERC-8004 cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. [4]", "v05_fuzzy_additions": [ { "id": "three-per-chain-singleton-registries-and-the-agent-registration-file", "heading": "Three per-chain singleton registries and the agent registration file", "body_md": "Three lightweight registries can be deployed on any L2 or on Mainnet as per-chain singletons: the Identity Registry, the Reputation Registry, and the Validation Registry. `agentURI` MUST resolve to the agent registration file. [4]", "bullets": [ { "label": "Global agent identifier", "text_md": "New agents can be minted by calling `register(string agentURI)`. `tokenId` is `agentId` and `tokenURI` is `agentURI`. Global `agentRegistry` is `{namespace}:{chainId}:{identityRegistry}` (example `eip155:1:0x742...`), and `eip155` is the namespace for EVM chains. The awesome list names `CAIP-10` as chain-agnostic account identification that ERC-8004 builds upon. BRC8004 writes that id as `eip155:{chainId}:{identityRegistry}`. [4][7][12]" }, { "label": "registration-v1 services", "text_md": "The registration file MUST have `type` `https://eips.ethereum.org/EIPS/eip-8004#registration-v1`. `services` names `A2A`, `MCP`, `OASF`, `ENS`, and `DID` endpoints. Endpoint `version` is a SHOULD, not a MUST. `registrations` carry `agentId` and `agentRegistry`. Agents SHOULD have at least one registration. `supportedTrust` is OPTIONAL. [4]" }, { "label": "Domain verification", "text_md": "An agent MAY optionally prove control of an HTTPS endpoint-domain by publishing `https://{endpoint-domain}/.well-known/agent-registration.json`, with at least a `registrations` list or the full file. Users MAY treat the endpoint-domain as verified when a `registrations` entry has `agentRegistry` and `agentId` matching the on-chain agent. [4]" }, { "label": "agentWallet", "text_md": "`agentWallet` cannot be set via `setMetadata()` or during `register()`. It is the address where the agent receives payments and starts as the owner's address. To change it, the agent owner must prove control of the new wallet with a valid `EIP-712` signature for EOAs or `ERC-1271` for smart contract wallets, by calling `setAgentWallet`. A transfer clears `agentWallet`, and the new owner must re-verify it. [4]" } ] }, { "id": "reputation-registry-validation-registry-and-x402-proof-of-payment", "heading": "Reputation Registry, Validation Registry, and x402 Proof of Payment", "body_md": "When deployed on a chain, the Reputation Registry and Validation Registry are initialized with the chain's `identityRegistry` address (`getIdentityRegistry()`) so that client feedback signals and validator attestations bind directly to each agent's ERC-721 `agentId`. [4]", "bullets": [ { "label": "giveFeedback", "text_md": "Any `clientAddress` other than the agent owner or an approved operator can call `giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash)`, where `valueDecimals` MUST be between `0` and `18` and `tag1`, `tag2`, `endpoint`, `feedbackURI`, and `feedbackHash` are optional on-chain parameters. The contract stores `value`, `valueDecimals`, `tag1`, `tag2`, and `isRevoked` in contract storage alongside a 1-indexed `feedbackIndex`, whereas `endpoint`, `feedbackURI`, and `feedbackHash` are emitted in `NewFeedback` events without on-chain storage. [4]" }, { "label": "Validation hooks", "text_md": "`validationRequest` MUST be called by the owner or operator of `agentId`. `validationResponse` MUST be called by the `validatorAddress` specified in the original request. Validator smart contracts could use stake-secured inference re-execution, zkML verifiers or TEE oracles. The contracts README says the Validation Registry portion is still under active update. The learn page says the Validation Registry is not yet available. [4][5][11]" }, { "label": "Off-chain feedback JSON and proofOfPayment", "text_md": "Whereas the on-chain `giveFeedback` call requires only `agentId`, `value`, and `valueDecimals` (with `tag1`, `tag2`, `endpoint`, `feedbackURI`, and `feedbackHash` optional), in the off-chain feedback JSON file at `feedbackURI`, `agentRegistry`, `agentId`, `clientAddress`, `createdAt`, `value`, and `valueDecimals` are `MUST` while all other JSON fields (including `tag1`, `tag2`, `endpoint`, `mcp`, `a2a`, `oasf`, and `proofOfPayment` with `fromAddress`, `toAddress`, `chainId`, and `txHash` for x402 payment receipts) are `OPTIONAL`. [4]" }, { "label": "Multi-chain singletons", "text_md": "An agent registered and receiving feedback on one chain can still operate and transact on other networks. Deterministic `CREATE2` deployments share the `0x8004A169...` (`IdentityRegistry`) and `0x8004BAa1...` (`ReputationRegistry`) vanity prefixes across EVM mainnets (and `0x8004A818...` on testnets). Beyond EVM networks, the arXiv ecosystem study cites `8004-solana` (an ERC-8004 SDK for Solana), a live registration file on `anchor-x402.com` lists `solana:101:metaplex` alongside its Base Mainnet `eip155:8453` entry, and CompraBTC operates a Bitcoin DCA agent registered on the Celo Identity Registry. [4][5][7][8][10][13]" } ] } ], "v05_diagram": { "title": "Identity, Reputation, and Validation registries", "heading": "Identity, Reputation, and Validation registries", "mermaid": "flowchart LR\n Owner[Owner]\n Identity[Identity Registry]\n RegFile[Registration file]\n WellKnown[\"Optional /.well-known/agent-registration.json\"]\n Reputation[Reputation Registry]\n Validation[Validation Registry]\n ClientAddr[clientAddress]\n Validator[validatorAddress]\n Owner -->|register agentURI| Identity\n Identity -->|agentURI resolves| RegFile\n WellKnown -->|registrations match agentRegistry and agentId| Identity\n Reputation -->|initialize identityRegistry| Identity\n Validation -->|initialize identityRegistry| Identity\n ClientAddr -->|giveFeedback| Reputation\n Owner -->|validationRequest| Validation\n Validator -->|validationResponse| Validation", "caption_md": "Owner calls `register(string agentURI)`. The `agentURI` resolves to the registration file. `clientAddress` calls `giveFeedback`. Owner or operator calls `validationRequest`. `validatorAddress` calls `validationResponse`. [4]" }, "v05_wire_artifact": { "title": "ERC-8004 registration-v1 agent registration file", "heading": "ERC-8004 registration-v1 agent registration file", "lang": "jsonc", "code": "{\n \"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\",\n \"name\": \"myAgentName\",\n \"description\": \"A natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods\",\n \"image\": \"https://example.com/agentimage.png\",\n \"services\": [\n {\n \"name\": \"web\",\n \"endpoint\": \"https://web.agentxyz.com/\"\n },\n {\n \"name\": \"A2A\",\n \"endpoint\": \"https://agent.example/.well-known/agent-card.json\",\n \"version\": \"0.3.0\"\n },\n {\n \"name\": \"MCP\",\n \"endpoint\": \"https://mcp.agent.eth/\",\n \"version\": \"2025-06-18\"\n },\n {\n \"name\": \"OASF\",\n \"endpoint\": \"ipfs://{cid}\",\n \"version\": \"0.8\", // https://github.com/agntcy/oasf/tree/v0.8.0\n \"skills\": [], // OPTIONAL\n \"domains\": [] // OPTIONAL\n },\n {\n \"name\": \"ENS\",\n \"endpoint\": \"vitalik.eth\",\n \"version\": \"v1\"\n },\n {\n \"name\": \"DID\",\n \"endpoint\": \"did:method:foobar\",\n \"version\": \"v1\"\n },\n {\n \"name\": \"email\",\n \"endpoint\": \"mail@myagent.com\"\n }\n ],\n \"x402Support\": false,\n \"active\": true,\n \"registrations\": [\n {\n \"agentId\": 22,\n \"agentRegistry\": \"{namespace}:{chainId}:{identityRegistry}\" // e.g. eip155:1:0x742...\n }\n ],\n \"supportedTrust\": [\n \"reputation\",\n \"crypto-economic\",\n \"tee-attestation\"\n ]\n}", "caption_md": "Registration file with `type` `https://eips.ethereum.org/EIPS/eip-8004#registration-v1`, plus `services`, `registrations`, and `supportedTrust`. [4]" }, "v05_counterparts": { "classic_analogues": [ { "name": "EIP-721 Non-Fungible Token Standard", "spec_or_rfc": "EIP-721", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Identity Registry uses ERC-721 URIStorage: tokenId is agentId, tokenURI is agentURI, minted by register(string agentURI). [4]" }, { "name": "EIP-712 Typed Structured Data Hashing and Signing", "spec_or_rfc": "EIP-712", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "setAgentWallet requires an EIP-712 signature for an EOA; a contract wallet proves control with ERC-1271. [4]" } ], "agentic_peers": [ { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ERC-8004's example lists an A2A service at agent-card.json version 0.3.0, a discovery pointer rather than A2A messaging. [4][14]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ERC-8004's example lists a separate MCP service (endpoint and version 2025-06-18), outside the ERC-721 identity record. [4][15]" }, { "target_id": "ans", "target_name": "Agent Name Service v2 (ANS)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "ANS publishes `_ans` TXT and `_ans-badge` records; ERC-8004 uses `{namespace}:{chainId}:{identityRegistry}` plus agentId. [4][16]" }, { "target_id": "erc-8126", "target_name": "ERC-8126: AI Agent Verification", "relation_type": "depended_on_by", "relation_label": "Depended on by", "delta_md": "ERC-8126 verifies agents registered via ERC-8004, with a 0-100 risk score that can be posted to the Validation Registry. [3]" }, { "target_id": "x402", "target_name": "x402", "relation_type": "complements", "relation_label": "Complements", "delta_md": "x402 is a separate payments protocol; ERC-8004's x402Support flag treats payments as orthogonal and can enrich feedback. [4][17]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (7 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "On-chain registries, agent signers & identity issuers", "col4_header": "Registry addresses, chain set, and registration surface", "note_md": null, "rows": [ { "actor": "ERC-8004 Identity and Reputation Registries", "role": "Registry / Smart contract", "status": "Supported", "status_display": "Supported · as of 2026-10-30", "col4_md": "Ethereum mainnet IdentityRegistry `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` and ReputationRegistry `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`.", "source_md": "[erc-8004 contracts README (fetched 2026-10-30)](https://raw.githubusercontent.com/erc-8004/erc-8004-contracts/master/README.md) [5] · [8004.org, Welcome to ERC-8004 (2026-01-29)](https://www.8004.org/blog/welcome-to-8004) [6][9]" }, { "actor": "Virtuals Protocol", "role": "Identity issuer / CA", "status": "Supported", "status_display": "Supported · as of 2026-02-01", "col4_md": "Since 01 Feb 2026, graduated ACP agents auto-register and store reviews on-chain.", "source_md": "[Virtuals Protocol, ACP Changelogs (2026-02-01)](https://whitepaper.virtuals.io/acp/acp-changelogs) [18]" } ] }, "side_b": { "visible": true, "heading": "Explorers, indexers & verifier SDKs", "col4_header": "Indexed chains, verification surface, and SDK", "note_md": null, "rows": [ { "actor": "8004scan (AltLayer)", "role": "Explorer / Scanner", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Homepage covers identity, reputation, and validation across 29 chains.", "source_md": "[8004scan (fetched 2026-10-30)](https://8004scan.io/) [19]" }, { "actor": "Quicknode ERC-8004 Explorer", "role": "Explorer / Scanner", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "One JSON-RPC endpoint covers 32 EVM networks; REST bills per request in USDC.", "source_md": "[Quicknode, ERC-8004 Explorer (fetched 2026-10-30)](https://erc-8004.quicknode.com/) [20]" }, { "actor": "RNWY", "role": "Verifier SDK / Runtime", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Skill `7.5.0` posts to `https://rnwy.com/api/mcp` and covers ERC-8004.", "source_md": "[AI Rights Institute, RNWY skill.md 7.5.0 (fetched 2026-10-30)](https://rnwy.com/skill.md) [8]" }, { "actor": "Agent0 SDK", "role": "Verifier SDK / Runtime", "status": "Partial", "status_display": "Partial · checked 2026-10-30", "col4_md": "Main-branch TypeScript SDK `1.7.0` publishes MCP and A2A endpoints on ERC-8004.", "source_md": "[agent0lab, Agent0 SDK README (fetched 2026-10-30)](https://raw.githubusercontent.com/agent0lab/agent0-ts/main/README.md) [21]" }, { "actor": "ChaosChain", "role": "Verifier SDK / Runtime", "status": "Partial", "status_display": "Partial · checked 2026-10-30", "col4_md": "Main-branch RewardsDistributor V4 writes verifier accuracy to ERC-8004.", "source_md": "[ChaosChain README (fetched 2026-10-30)](https://raw.githubusercontent.com/ChaosChain/chaoschain/main/README.md) [22]" } ] }, "additional_tables": null, "censuses": [ { "label": "erc-8004 contracts README (fetched 2026-10-30)", "as_of": "2026-10-30", "value_md": "Lists 25 mainnet chain deployments (from Ethereum Mainnet through 0G Mainnet) sharing the deterministic mainnet IdentityRegistry and ReputationRegistry singleton addresses, alongside 25 testnet or devnet chain deployments (from Ethereum Sepolia through 0G Galileo Testnet) sharing the deterministic testnet singleton addresses. [5]" }, { "label": "arXiv 2606.26028 empirical study", "as_of": "2026-05-13", "value_md": "The paper reports coordinated Sybil behavior among 73.5% of reviewers on Ethereum, 59.2% on BSC, and 90.6% on Base. [10]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "erc-8183", "target_name": "ERC-8183: Agentic Commerce", "relation_label": "Depended on by", "delta": "ERC-8183 lists ERC-8004 as a prerequisite and composes its attestation hash with that reputation registry; ERC-8183 itself is EIP-20 escrow.", "item_md": "**[ERC-8183: Agentic Commerce](/protocols/erc-8183/)** (Depended on by) — ERC-8183 lists ERC-8004 as a prerequisite and composes its attestation hash with that reputation registry; ERC-8183 itself is EIP-20 escrow." }, { "target_id": "erc-8444", "target_name": "ERC-8444: Agentic Resource Discovery (ARD) Onchain", "relation_label": "Complements", "delta": "ERC-8444 anchors ARD records on chain, can point at an ERC-8004 registration, and serves them at /.well-known/ard.json.", "item_md": "**[ERC-8444: Agentic Resource Discovery (ARD) Onchain](/protocols/erc-8444/)** (Complements) — ERC-8444 anchors ARD records on chain, can point at an ERC-8004 registration, and serves them at /.well-known/ard.json." }, { "target_id": "erc-8001", "target_name": "ERC-8001: Agent Coordination Framework", "relation_label": "Complements", "delta": "ERC-8001 is the coordination contract that executes only after every party posts an EIP-712 or ERC-1271 acceptance.", "item_md": "**[ERC-8001: Agent Coordination Framework](/protocols/erc-8001/)** (Complements) — ERC-8001 is the coordination contract that executes only after every party posts an EIP-712 or ERC-1271 acceptance." }, { "target_id": "kya-os", "target_name": "KYA-OS (Know Your Agent Operating System)", "relation_label": "Peer alternative", "delta": "ERC-8004 uses an ERC-721 agentId; KYA-OS identifies the caller with did:key or did:web and a StatusList2021-revoked credential.", "item_md": "**[KYA-OS (Know Your Agent Operating System)](/protocols/kya-os/)** (Peer alternative) — ERC-8004 uses an ERC-721 agentId; KYA-OS identifies the caller with did:key or did:web and a StatusList2021-revoked credential." }, { "target_id": "erc-8226", "target_name": "ERC-8226 Regulated Agent Mandate", "relation_label": "Depended on by", "delta": "ERC-8226 treats ERC-8004 as one compatible agent identity; the mandate is IAgentMandate keyed by agent and principal.", "item_md": "**[ERC-8226 Regulated Agent Mandate](/protocols/erc-8226/)** (Depended on by) — ERC-8226 treats ERC-8004 as one compatible agent identity; the mandate is IAgentMandate keyed by agent and principal." }, { "target_id": "aip", "target_name": "Agent Identity Protocol (AIP)", "relation_label": "Peer alternative", "delta": "ERC-8004's agentId is an ERC-721 tokenId; AIP identifies the agent with did:aip from an Ed25519 key.", "item_md": "**[Agent Identity Protocol (AIP)](/protocols/aip/)** (Peer alternative) — ERC-8004's agentId is an ERC-721 tokenId; AIP identifies the agent with did:aip from an Ed25519 key." }, { "target_id": "agent-identity-document", "target_name": "The Agent Identity Document: A Hosted, Accountable Public Record for AI Agents", "relation_label": "Peer alternative", "delta": "ERC-8004 uses on-chain registries plus /.well-known/agent-registration.json; the Agent Identity Document uses /.well-known/agent-identity.json.", "item_md": "**[The Agent Identity Document: A Hosted, Accountable Public Record for AI Agents](/protocols/agent-identity-document/)** (Peer alternative) — ERC-8004 uses on-chain registries plus /.well-known/agent-registration.json; the Agent Identity Document uses /.well-known/agent-identity.json." }, { "target_id": "agent-delegation-receipts", "target_name": "Agent Delegation Receipts", "relation_label": "Complements", "delta": "ERC-8004 registers an ERC-721 agentId; a delegation receipt is the JWS or COSE_Sign1 slip binding instruction hash and scope.", "item_md": "**[Agent Delegation Receipts](/protocols/agent-delegation-receipts/)** (Complements) — ERC-8004 registers an ERC-721 agentId; a delegation receipt is the JWS or COSE_Sign1 slip binding instruction hash and scope." }, { "target_id": "erc-8196", "target_name": "ERC-8196: AI Agent Authenticated Wallet", "relation_label": "Complements", "delta": "ERC-8196 reaches the ERC-8004 agentId through ERC-8126; the ERC-4337 wallet executes only when the proof matches policy.", "item_md": "**[ERC-8196: AI Agent Authenticated Wallet](/protocols/erc-8196/)** (Complements) — ERC-8196 reaches the ERC-8004 agentId through ERC-8126; the ERC-4337 wallet executes only when the proof matches policy." }, { "item_md": "**[Identify protocols](/category/identify/)** — Category index for `identify` standards." } ], "v05_compiled_md": "---\nid: erc-8004\ntitle: \"ERC-8004: Trustless Agents\"\ntier: flagship\nlifecycle_status: active\ncategory: identify\nform: onchain-registry\nwire_archetype: payments_onchain\nspec_url: https://eips.ethereum.org/EIPS/eip-8004\nlast_checked: 2026-11-06\n---\n\n# ERC-8004: Trustless Agents\n\n**Category:** [Identify](/category/identify/) (`identify`) · **Form:** On-chain registry (`onchain-registry`) · **Last checked:** 2026-11-06\n\n> *ERC-8004 defines per-chain singleton identity, reputation, and validation registries; for the multi-registry minimal factory alternative using ERC-6909 and ERC-8048, see [ERC-8122](https://eips.ethereum.org/EIPS/eip-8122); for the job-escrow commerce layer that delegates identity and reputation to ERC-8004, see [ERC-8183](/protocols/erc-8183/); and for multi-dimensional risk-score verification of ERC-8004 agents, see [ERC-8126](/protocols/erc-8126/). [1][2][3]*\n\n> **In brief:** ERC-8004 is an Ethereum standard that gives autonomous AI agents portable on-chain identities, public reputation records, and verifiable execution proofs so services from different organizations can find and evaluate one another. Because communication protocols like MCP and A2A do not solve cross-organization discovery or trust on their own, ERC-8004 anchors each agent to an on-chain `IdentityRegistry` token pointing to an `agentURI` registration file alongside shared `ReputationRegistry` and `ValidationRegistry` contracts. [4][5]\n\n**ERC-8004 (Trustless Agents)** is a Standards Track Ethereum Request for Comments (drafted August 13, 2025 by Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel) that specifies three on-chain singleton registries (`IdentityRegistry`, `ReputationRegistry`, and `ValidationRegistry`) for discovering and evaluating autonomous agents across organizational boundaries without pre-existing trust. [4][5] Each agent is minted via `register(string agentURI)` as an ERC-721 token with `URIStorage` whose `agentURI` resolves to a registration JSON document (`\"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\"`) listing `services` entries (such as `A2A`, `MCP`, `OASF`, `ENS`, or `DID`), while binding payment addresses on-chain via `setAgentWallet`, alongside `supportedTrust` models (`reputation`, `crypto-economic`, and `tee-attestation`). Optionally, an agent can verify control of an HTTPS endpoint domain by serving a matching `registrations` entry at `/.well-known/agent-registration.json`. [4] While the EIP specification remains in `Draft` status on `eips.ethereum.org`, deterministic `CREATE2` singleton contracts for the Identity (`0x8004A169...`) and Reputation (`0x8004BAa1...`) registries launched on Ethereum Mainnet on January 29, 2026 and are deployed across peer EVM chains, whereas the Validation Registry remains under active specification update. [5][6][7][8][9]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Identify](/category/identify/) (`identify`) |\n| **Form** | On-chain registry (`onchain-registry`) |\n| **Originated by** | Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis), Jordan Ellis, and Erik Reppel; created 2025-08-13 [4] |\n| **Governed by** | Community effort: Marco De Rossi (MetaMask), Davide Crapis (EF), Jordan Ellis (Google), Erik Reppel (Coinbase). [4][5] |\n| **Track** | Community (`community`); EIP `type: Standards Track`, `category: ERC`. [4][5] |\n| **Status** | Draft (created 2025-08-13). Mainnet Identity and Reputation live since 2026-01-29; Validation Registry unavailable. [4][5][9][10][11] |\n| **Version** | Draft EIP; registration schema `eip-8004#registration-v1` (per-endpoint `version` field is `SHOULD`) [4] |\n| **Networks** | Per-chain singletons on Ethereum Mainnet and 24 peer EVM mainnets (`IdentityRegistry` `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`; `ReputationRegistry` `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`) [4][5] |\n| **Token format** | ERC-721 with URIStorage. `tokenId` is `agentId` and `tokenURI` is `agentURI`. `agentRegistry` is `{namespace}:{chainId}:{identityRegistry}`. [4] |\n| **Record format** | Registration `#registration-v1` with `services` and `registrations`; `giveFeedback` `valueDecimals` MUST be 0-18. [4] |\n| **Found at** | `/.well-known/agent-registration.json` on an HTTPS endpoint domain (optional domain proof) [4][6] |\n| **Specification** | [ERC-8004: Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004) [4][6] |\n| **Licence** | CC0 (copyright and related rights waived) [6] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Three per-chain singleton registries and the agent registration file](#three-per-chain-singleton-registries-and-the-agent-registration-file)\n3. [Reputation Registry, Validation Registry, and x402 Proof of Payment](#reputation-registry-validation-registry-and-x402-proof-of-payment)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nModel context protocol (MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent (A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. However, these agent communication protocols don't inherently cover agent discovery and trust. [4] ERC-8004 uses blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust. Across its Identity, Reputation, and Validation registries, developers can combine client-feedback reputation, stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, and trusted execution environment (TEE) oracles. [4] Payments are orthogonal to ERC-8004 and not covered by the specification. The `supportedTrust` field is OPTIONAL; if absent or empty, ERC-8004 is used only for discovery, not for trust. On `getSummary`, `clientAddresses` MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. While ERC-8004 cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. [4]\n\n### Identity, Reputation, and Validation registries\n\n```mermaid\nflowchart LR\n Owner[Owner]\n Identity[Identity Registry]\n RegFile[Registration file]\n WellKnown[\"Optional /.well-known/agent-registration.json\"]\n Reputation[Reputation Registry]\n Validation[Validation Registry]\n ClientAddr[clientAddress]\n Validator[validatorAddress]\n Owner -->|register agentURI| Identity\n Identity -->|agentURI resolves| RegFile\n WellKnown -->|registrations match agentRegistry and agentId| Identity\n Reputation -->|initialize identityRegistry| Identity\n Validation -->|initialize identityRegistry| Identity\n ClientAddr -->|giveFeedback| Reputation\n Owner -->|validationRequest| Validation\n Validator -->|validationResponse| Validation\n```\n\n*Owner calls `register(string agentURI)`. The `agentURI` resolves to the registration file. `clientAddress` calls `giveFeedback`. Owner or operator calls `validationRequest`. `validatorAddress` calls `validationResponse`. [4]*\n\n### ERC-8004 registration-v1 agent registration file\n\n```jsonc\n{\n \"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\",\n \"name\": \"myAgentName\",\n \"description\": \"A natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods\",\n \"image\": \"https://example.com/agentimage.png\",\n \"services\": [\n {\n \"name\": \"web\",\n \"endpoint\": \"https://web.agentxyz.com/\"\n },\n {\n \"name\": \"A2A\",\n \"endpoint\": \"https://agent.example/.well-known/agent-card.json\",\n \"version\": \"0.3.0\"\n },\n {\n \"name\": \"MCP\",\n \"endpoint\": \"https://mcp.agent.eth/\",\n \"version\": \"2025-06-18\"\n },\n {\n \"name\": \"OASF\",\n \"endpoint\": \"ipfs://{cid}\",\n \"version\": \"0.8\", // https://github.com/agntcy/oasf/tree/v0.8.0\n \"skills\": [], // OPTIONAL\n \"domains\": [] // OPTIONAL\n },\n {\n \"name\": \"ENS\",\n \"endpoint\": \"vitalik.eth\",\n \"version\": \"v1\"\n },\n {\n \"name\": \"DID\",\n \"endpoint\": \"did:method:foobar\",\n \"version\": \"v1\"\n },\n {\n \"name\": \"email\",\n \"endpoint\": \"mail@myagent.com\"\n }\n ],\n \"x402Support\": false,\n \"active\": true,\n \"registrations\": [\n {\n \"agentId\": 22,\n \"agentRegistry\": \"{namespace}:{chainId}:{identityRegistry}\" // e.g. eip155:1:0x742...\n }\n ],\n \"supportedTrust\": [\n \"reputation\",\n \"crypto-economic\",\n \"tee-attestation\"\n ]\n}\n```\n\n*Registration file with `type` `https://eips.ethereum.org/EIPS/eip-8004#registration-v1`, plus `services`, `registrations`, and `supportedTrust`. [4]*\n\n---\n\n## Three per-chain singleton registries and the agent registration file\n\nThree lightweight registries can be deployed on any L2 or on Mainnet as per-chain singletons: the Identity Registry, the Reputation Registry, and the Validation Registry. `agentURI` MUST resolve to the agent registration file. [4]\n\n- **Global agent identifier:** New agents can be minted by calling `register(string agentURI)`. `tokenId` is `agentId` and `tokenURI` is `agentURI`. Global `agentRegistry` is `{namespace}:{chainId}:{identityRegistry}` (example `eip155:1:0x742...`), and `eip155` is the namespace for EVM chains. The awesome list names `CAIP-10` as chain-agnostic account identification that ERC-8004 builds upon. BRC8004 writes that id as `eip155:{chainId}:{identityRegistry}`. [4][7][12]\n- **registration-v1 services:** The registration file MUST have `type` `https://eips.ethereum.org/EIPS/eip-8004#registration-v1`. `services` names `A2A`, `MCP`, `OASF`, `ENS`, and `DID` endpoints. Endpoint `version` is a SHOULD, not a MUST. `registrations` carry `agentId` and `agentRegistry`. Agents SHOULD have at least one registration. `supportedTrust` is OPTIONAL. [4]\n- **Domain verification:** An agent MAY optionally prove control of an HTTPS endpoint-domain by publishing `https://{endpoint-domain}/.well-known/agent-registration.json`, with at least a `registrations` list or the full file. Users MAY treat the endpoint-domain as verified when a `registrations` entry has `agentRegistry` and `agentId` matching the on-chain agent. [4]\n- **agentWallet:** `agentWallet` cannot be set via `setMetadata()` or during `register()`. It is the address where the agent receives payments and starts as the owner's address. To change it, the agent owner must prove control of the new wallet with a valid `EIP-712` signature for EOAs or `ERC-1271` for smart contract wallets, by calling `setAgentWallet`. A transfer clears `agentWallet`, and the new owner must re-verify it. [4]\n\n---\n\n## Reputation Registry, Validation Registry, and x402 Proof of Payment\n\nWhen deployed on a chain, the Reputation Registry and Validation Registry are initialized with the chain's `identityRegistry` address (`getIdentityRegistry()`) so that client feedback signals and validator attestations bind directly to each agent's ERC-721 `agentId`. [4]\n\n- **giveFeedback:** Any `clientAddress` other than the agent owner or an approved operator can call `giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash)`, where `valueDecimals` MUST be between `0` and `18` and `tag1`, `tag2`, `endpoint`, `feedbackURI`, and `feedbackHash` are optional on-chain parameters. The contract stores `value`, `valueDecimals`, `tag1`, `tag2`, and `isRevoked` in contract storage alongside a 1-indexed `feedbackIndex`, whereas `endpoint`, `feedbackURI`, and `feedbackHash` are emitted in `NewFeedback` events without on-chain storage. [4]\n- **Validation hooks:** `validationRequest` MUST be called by the owner or operator of `agentId`. `validationResponse` MUST be called by the `validatorAddress` specified in the original request. Validator smart contracts could use stake-secured inference re-execution, zkML verifiers or TEE oracles. The contracts README says the Validation Registry portion is still under active update. The learn page says the Validation Registry is not yet available. [4][5][11]\n- **Off-chain feedback JSON and proofOfPayment:** Whereas the on-chain `giveFeedback` call requires only `agentId`, `value`, and `valueDecimals` (with `tag1`, `tag2`, `endpoint`, `feedbackURI`, and `feedbackHash` optional), in the off-chain feedback JSON file at `feedbackURI`, `agentRegistry`, `agentId`, `clientAddress`, `createdAt`, `value`, and `valueDecimals` are `MUST` while all other JSON fields (including `tag1`, `tag2`, `endpoint`, `mcp`, `a2a`, `oasf`, and `proofOfPayment` with `fromAddress`, `toAddress`, `chainId`, and `txHash` for x402 payment receipts) are `OPTIONAL`. [4]\n- **Multi-chain singletons:** An agent registered and receiving feedback on one chain can still operate and transact on other networks. Deterministic `CREATE2` deployments share the `0x8004A169...` (`IdentityRegistry`) and `0x8004BAa1...` (`ReputationRegistry`) vanity prefixes across EVM mainnets (and `0x8004A818...` on testnets). Beyond EVM networks, the arXiv ecosystem study cites `8004-solana` (an ERC-8004 SDK for Solana), a live registration file on `anchor-x402.com` lists `solana:101:metaplex` alongside its Base Mainnet `eip155:8453` entry, and CompraBTC operates a Bitcoin DCA agent registered on the Celo Identity Registry. [4][5][7][8][10][13]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **EIP-721 Non-Fungible Token Standard** | `EIP-721` | Profiles classic standard | Identity Registry uses ERC-721 URIStorage: tokenId is agentId, tokenURI is agentURI, minted by register(string agentURI). [4] |\n| **EIP-712 Typed Structured Data Hashing and Signing** | `EIP-712` | Profiles classic standard | setAgentWallet requires an EIP-712 signature for an EOA; a contract wallet proves control with ERC-1271. [4] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Complements | ERC-8004's example lists an A2A service at agent-card.json version 0.3.0, a discovery pointer rather than A2A messaging. [4][14] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | ERC-8004's example lists a separate MCP service (endpoint and version 2025-06-18), outside the ERC-721 identity record. [4][15] |\n| **[Agent Name Service v2 (ANS)](/protocols/ans/)** | Peer alternative | ANS publishes `_ans` TXT and `_ans-badge` records; ERC-8004 uses `{namespace}:{chainId}:{identityRegistry}` plus agentId. [4][16] |\n| **[ERC-8126: AI Agent Verification](/protocols/erc-8126/)** | Depended on by | ERC-8126 verifies agents registered via ERC-8004, with a 0-100 risk score that can be posted to the Validation Registry. [3] |\n| **[x402](/protocols/x402/)** | Complements | x402 is a separate payments protocol; ERC-8004's x402Support flag treats payments as orthogonal and can enrich feedback. [4][17] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (7 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### On-chain registries, agent signers & identity issuers\n\n| Actor | Role | Status | Registry addresses, chain set, and registration surface | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **ERC-8004 Identity and Reputation Registries** | Registry / Smart contract | Supported · as of 2026-10-30 | Ethereum mainnet IdentityRegistry `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` and ReputationRegistry `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`. | [erc-8004 contracts README (fetched 2026-10-30)](https://raw.githubusercontent.com/erc-8004/erc-8004-contracts/master/README.md) [5] · [8004.org, Welcome to ERC-8004 (2026-01-29)](https://www.8004.org/blog/welcome-to-8004) [6][9] |\n| **Virtuals Protocol** | Identity issuer / CA | Supported · as of 2026-02-01 | Since 01 Feb 2026, graduated ACP agents auto-register and store reviews on-chain. | [Virtuals Protocol, ACP Changelogs (2026-02-01)](https://whitepaper.virtuals.io/acp/acp-changelogs) [18] |\n\n### Explorers, indexers & verifier SDKs\n\n| Actor | Role | Status | Indexed chains, verification surface, and SDK | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **8004scan (AltLayer)** | Explorer / Scanner | Live (HTTP 200) · checked 2026-10-30 | Homepage covers identity, reputation, and validation across 29 chains. | [8004scan (fetched 2026-10-30)](https://8004scan.io/) [19] |\n| **Quicknode ERC-8004 Explorer** | Explorer / Scanner | Live (HTTP 200) · checked 2026-10-30 | One JSON-RPC endpoint covers 32 EVM networks; REST bills per request in USDC. | [Quicknode, ERC-8004 Explorer (fetched 2026-10-30)](https://erc-8004.quicknode.com/) [20] |\n| **RNWY** | Verifier SDK / Runtime | Live (HTTP 200) · checked 2026-10-30 | Skill `7.5.0` posts to `https://rnwy.com/api/mcp` and covers ERC-8004. | [AI Rights Institute, RNWY skill.md 7.5.0 (fetched 2026-10-30)](https://rnwy.com/skill.md) [8] |\n| **Agent0 SDK** | Verifier SDK / Runtime | Partial · checked 2026-10-30 | Main-branch TypeScript SDK `1.7.0` publishes MCP and A2A endpoints on ERC-8004. | [agent0lab, Agent0 SDK README (fetched 2026-10-30)](https://raw.githubusercontent.com/agent0lab/agent0-ts/main/README.md) [21] |\n| **ChaosChain** | Verifier SDK / Runtime | Partial · checked 2026-10-30 | Main-branch RewardsDistributor V4 writes verifier accuracy to ERC-8004. | [ChaosChain README (fetched 2026-10-30)](https://raw.githubusercontent.com/ChaosChain/chaoschain/main/README.md) [22] |\n\n### Ecosystem censuses\n\n- **erc-8004 contracts README (fetched 2026-10-30)** (*as of 2026-10-30*): Lists 25 mainnet chain deployments (from Ethereum Mainnet through 0G Mainnet) sharing the deterministic mainnet IdentityRegistry and ReputationRegistry singleton addresses, alongside 25 testnet or devnet chain deployments (from Ethereum Sepolia through 0G Galileo Testnet) sharing the deterministic testnet singleton addresses. [5]\n- **arXiv 2606.26028 empirical study** (*as of 2026-05-13*): The paper reports coordinated Sybil behavior among 73.5% of reviewers on Ethereum, 59.2% on BSC, and 90.6% on Base. [10]\n\n---\n\n## See also\n\n- **[ERC-8183: Agentic Commerce](/protocols/erc-8183/)** *(Depended on by)* — ERC-8183 lists ERC-8004 as a prerequisite and composes its attestation hash with that reputation registry; ERC-8183 itself is EIP-20 escrow.\n- **[ERC-8444: Agentic Resource Discovery (ARD) Onchain](/protocols/erc-8444/)** *(Complements)* — ERC-8444 anchors ARD records on chain, can point at an ERC-8004 registration, and serves them at /.well-known/ard.json.\n- **[ERC-8001: Agent Coordination Framework](/protocols/erc-8001/)** *(Complements)* — ERC-8001 is the coordination contract that executes only after every party posts an EIP-712 or ERC-1271 acceptance.\n- **[KYA-OS (Know Your Agent Operating System)](/protocols/kya-os/)** *(Peer alternative)* — ERC-8004 uses an ERC-721 agentId; KYA-OS identifies the caller with did:key or did:web and a StatusList2021-revoked credential.\n- **[ERC-8226 Regulated Agent Mandate](/protocols/erc-8226/)** *(Depended on by)* — ERC-8226 treats ERC-8004 as one compatible agent identity; the mandate is IAgentMandate keyed by agent and principal.\n- **[Agent Identity Protocol (AIP)](/protocols/aip/)** *(Peer alternative)* — ERC-8004's agentId is an ERC-721 tokenId; AIP identifies the agent with did:aip from an Ed25519 key.\n- **[The Agent Identity Document: A Hosted, Accountable Public Record for AI Agents](/protocols/agent-identity-document/)** *(Peer alternative)* — ERC-8004 uses on-chain registries plus /.well-known/agent-registration.json; the Agent Identity Document uses /.well-known/agent-identity.json.\n- **[Agent Delegation Receipts](/protocols/agent-delegation-receipts/)** *(Complements)* — ERC-8004 registers an ERC-721 agentId; a delegation receipt is the JWS or COSE_Sign1 slip binding instruction hash and scope.\n- **[ERC-8196: AI Agent Authenticated Wallet](/protocols/erc-8196/)** *(Complements)* — ERC-8196 reaches the ERC-8004 agentId through ERC-8126; the ERC-4337 wallet executes only when the proof matches policy.\n- **Category:** [Identify protocols](/category/identify/)\n\n---\n\n## References\n\n1. Prem Makeig (@nxt3d), *ERC-8122: Minimal Agent Registry* (created 2025-12-17) — \n2. Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce* (created 2026-02-25) — \n3. Leigh Cronian (Cybercentry) and Chris Johnson (Virtuals), *ERC-8126: AI Agent Verification* (created 2026-01-15) — \n4. Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERCS/erc-8004.md (Trustless Agents)* (created 2025-08-13; fetched 2026-10-30) — \n5. erc-8004, *ERC-8004 contracts README* (fetched 2026-10-30) — \n6. Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERC-8004: Trustless Agents* (created 2025-08-13; fetched 2026-10-30) — \n7. Sudeep (sudeepb02), *Awesome ERC-8004* (fetched 2026-10-30) — \n8. AI Rights Institute, *RNWY skill.md* (version 7.5.0; fetched 2026-10-30) — \n9. ERC-8004 Community, *Welcome to ERC-8004 and the open agentic economy* (published 2026-01-29) — \n10. Xihan Xiong, Zelin Li, Wei Wei, Qin Wang, William Knottenbelt, and Zhipeng Wang, *Can Trustless Agents Be Trusted? An Empirical Study of the ERC-8004 Decentralized AI Agent Ecosystem* (submitted 2026-06-24; revised 2026-10-18 (v3)) — \n11. ERC-8004 Community, *8004 Learn* (fetched 2026-10-30) — \n12. BRC8004, *BRC8004: Trustless Agents on BNB Chain* (fetched 2026-11-06) — \n13. anchor-x402, *agent-registration.json (anchor-x402)* (fetched 2026-10-30) — \n14. A2A Protocol, *Agent2Agent (A2A) Protocol Specification* (fetched 2026-10-30) — \n15. Model Context Protocol, *Specification 2026-07-28* (version 2026-07-28) — \n16. Scott Courtney, Vineeth Sai Narajala, Ken Huang, Idan Habler, and Akram Sheriff, *draft-narajala-courtney-ansv2 — Agent Name Service v2 (ANS): A Domain-Anchored Trust Layer for Autonomous AI Agent Identity (IETF Datatracker)* (draft-narajala-courtney-ansv2-01; last updated 2026-10-15) — \n17. x402 Foundation, *X402 Protocol Specification* (protocol version 2) — \n18. Virtuals Protocol, *ACP Changelogs* (ERC-8004 release note 2026-02-01) — \n19. Alt Research, *8004scan* (fetched 2026-10-30) — \n20. Quicknode, *ERC-8004 Explorer* (fetched 2026-10-30) — \n21. agent0lab, *Agent0 SDK* (fetched 2026-10-30) — \n22. ChaosChain, *ChaosChain README* (fetched 2026-10-30) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "ERC-8183", "adoption": { "level": "observed", "by": "Virtuals Protocol (AgenticCommerceV3), Circle (AgenticCommerce on Arc Testnet), Virtuals ACP SDK (@virtuals-protocol/acp-node-v2), Virtuals ACP CLI (@virtuals-protocol/acp-cli), and Circle Wallets (Arc Testnet walkthrough)", "probe_run": null }, "aliases": [ "EIP-8183" ], "analog": "Escrow contract with a third-party inspector", "collisions": [ "Agentic Commerce Protocol (OpenAI/Stripe ACP)" ], "discovery": { "mechanism": "EVM smart-contract interface (job created on an AgenticCommerce contract deployment)", "path": "none — no well-known file; discovery is by contract address/ABI" }, "dispute": { "claims": [ "ERC-8183 abstract: 'This specification defines the Agentic Commerce Protocol: a job with escrowed budget...'", "agentic-commerce-protocol record: OpenAI/Stripe/Meta-maintained REST checkout standard of the same colloquial name" ], "summary": "The proposal's own title and abstract call the standard 'the Agentic Commerce Protocol,' the same phrase used by the unrelated OpenAI/Stripe specification tracked in this dataset as 'agentic-commerce-protocol.' The two share no governance, code, or organization; ERC-8183 is an on-chain escrow/attestation primitive on Ethereum, while ACP is an off-chain REST checkout API maintained by OpenAI, Stripe, and Meta." }, "evidence": [ { "label": "[1]", "url": "https://eips.ethereum.org/EIPS/eip-8183", "claim": "Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce*, created 2026-02-25; fetched 2026-10-31", "date": null, "quote": "This specification defines the Agentic Commerce Protocol: a job with escrowed budget / Draft Standards Track: ERC ERC-8183: Agentic Commerce / This specification defines the Agentic Commerce Protocol: a job with escrowed budget, four states (Open → Funded → Submitted → Terminal), and an evaluator who alone may mark the job completed. / Davide Crapis (@dcrapis), Bryan Lim (@ai-virtual-b), Tay Weixiong (@twx-virtuals), Chooi Zuhwa (@Zuhwa) Created 2026-02-25 / Discussion Link https://ethereum-magicians.org/t/erc-8183-agentic-commerce/27902 Requires EIP-20 / Payment SHALL use a single ERC-20 token (global for the contract or specified at creation). / Open → Funded: Client or provider calls setBudget(jobId, amount) to agree on price, then client calls fund(jobId, expectedBudget); contract pulls job.budget from client into escrow. / Funded → Submitted: Provider calls submit(jobId, deliverable); signals that work has been completed and is ready for evaluation. / Submitted Provider has submitted work. Only evaluator may complete or reject. After expiredAt, anyone may trigger refund. / A hook contract SHALL implement the IACPHook interface - just two functions / When a job has a hook set, the core contract SHALL call hook.beforeAction … and hook.afterAction … around each hookable function / claimRefund No - permissionless safety mechanism, SHALL NOT be hookable / Draft Standards Track: ERC … Created 2026-02-25 … ERC-8183: Agentic Commerce [DRAFT] / four states (Open → Funded → Submitted → Terminal) … A job has exactly one of six states … No other transitions are valid. … Four states: Open, Funded, Submitted, and Terminal (Completed, Rejected, or Expired) / (@ai-virtual-b), Tay Weixiong (@twx-virtuals), Chooi Zuhwa (@Zuhwa) Created 2026-02-25 Discussion Link https://ethereum-magicians.org/t/erc-8183-agentic-commerce/27902 Requires EIP-20 / }); Ethereum Improvement Proposals AllCoreNetworkingInterfaceERCMetaInformational ⚠️ Draft Standards Track: ERC ERC-8183: Agentic Commerce Job / Standards Track: ERC ERC-8183: Agentic Commerce Job escrow w / address(0) (no hook). Payment SHALL use a single ERC-20 token (global for the contract / Available: https://eips.ethereum.org/EIPS/eip-8183. { \"@context\": \"http://schema.org\", \"@type\": \"TechArticle\", \"headline\": \"ERC-8183: Agentic Commerce [DRAFT]\", \"name\": \"ERC-8183: / Copyright and related rights waived via CC0. / Many use cases need only: client locks funds, provider submits work, one attester (evaluator) signals \"done\" and triggers payment-or client rejects or timeout triggers refund. The Agentic Commerce Protocol specifies that minimal surface so implementations stay small and composable. / The evaluator can be the client (e.g. evaluator = client at creation) when there is no third-party attester. / A job has exactly one of six states / Open → Funded: Client or provider calls setBudget(jobId, amount) to agree on price, then client calls fund(jobId, expectedBudget); contract pulls job.budget from client into escrow. Open → Rejected: Client calls reject(jobId, reason?). Funded → Submitted: Provider calls submit(jobId, deliverable); signals that work has been completed and is ready for evaluation. Funded → Rejected: Evaluator calls reject(jobId, reason?); contract refunds client. Funded → Expired: When block.timestamp >= job.expiredAt, anyone (or client) may call claimRefund(jobId); contract sets state to Expired and refunds client. Submitted → Completed: Evaluator calls complete(jobId, reason?); contract distributes escrow to provider (and optional fee to treasury). Submitted → Rejected: Evaluator calls reject(jobId, reason?); contract refunds client. Submitted → Expired: When block.timestamp >= job.expiredAt, anyone (or client) may call claimRefund(jobId); contract sets state to Expired and refunds client. No other transitions are valid. / Once Submitted, only the evaluator can complete or reject; the client cannot pull funds back unilaterally, so the provider is protected after starting work. / Completed Terminal. Escrow released to provider (minus optional platform fee). Rejected Terminal. Escrow refunded to client. Expired Terminal. Same as Rejected; escrow refunded to client. / Agentic Commerce is intentionally minimal and does not embed a reputation system. For on-chain reputation and trust relationships between agents, implementations are RECOMMENDED to integrate with ERC-8004 (Trustless Agents). / Implementations MAY charge a platform fee (basis points) on Completed, paid to a configurable treasury. The specification does not require a fee. If present, fee SHALL be deducted only on completion (not on refund). / No dispute resolution or arbitration; reject/expire is final. / Implementations MAY support a per-job token; the specification only requires one token per contract.", "ref": 1 }, { "label": "[2]", "url": "https://web3.okx.com/learn/erc-8183", "claim": "OKX Wallet, *Co-authoring ERC-8183, the open standard for agent commerce*, published 2026-06-09; fetched 2026-10-31", "date": null, "quote": "Published on Jun 09, 2026 … Today, OKX Wallet is joining the Ethereum Foundation and Virtuals as a co-author of ERC-8183, also known as the Agentic Commerce Protocol. / 2026 5 min read Today, OKX Wallet is joining the Ethereum Foundation and Virtuals", "ref": 2 }, { "label": "[3]", "url": "https://ethereum-magicians.org/t/erc-8183-agentic-commerce/27902", "claim": "Davide Crapis, Fellowship of Ethereum Magicians, *ERC-8183: Agentic Commerce - ERCs - Fellowship of Ethereum Magicians*, topic opened 2026-03-04; fetched 2026-10-31", "date": null, "quote": "all Ethereum implementations, such as-a change to the network protocol, a change in block / ERC-8183: Agentic Commerce - ERCs - Fellowship of Ethereum Magicians { \"imports\": { \"discourse/plugins/automation\":", "ref": 3 }, { "label": "[4]", "url": "https://basescan.org/address/0x8e86FbEf4a4c927561cb6447cEd77ffFbf3B77BC#code", "claim": "BaseScan, *AgenticCommerceV3 contract source on Base*, fetched 2026-10-31", "date": null, "quote": "| ###### Cross-Chain Transactions ###### Contract Name #### AgenticCommerceV3 ###### Compiler Version ###### Optimization", "ref": 4 }, { "label": "[5]", "url": "https://www.arc.io/blog/running-an-agentic-economic-flow-on-arc-with-erc-8183", "claim": "Blessing Adesiji, Circle, *Using Arc with ERC-8183 to Run an Agentic Economic Flow*, April 7, 2026; fetched 2026-10-31", "date": null, "quote": "works on Arc Testnet with USDC and Circle Wallets, from job creation and funding", "ref": 5 }, { "label": "[6]", "url": "https://os.virtuals.io/acp/overview", "claim": "Virtuals Protocol, *What is ACP? – EconomyOS*, fetched 2026-10-31", "date": null, "quote": "Read llms.txt for a summary of the docs, or llms-full.txt for the full context. / Mainnet) Contract Address ACP Core 0x238E541BfefD82238730D00a2208E5497F1832E0 FundTransferHook 0x90717828D78731313CB350D6a58b0f91668Ea702 accept-ranges: bytes content-disposition: inline; filename=\"index.html\" / Current ACP Protocol primitive Memos - signed on-chain messages Hooks - smart contracts with / With those learnings, we proposed ERC-8183 and built ACP as its reference implementation. Earlier", "ref": 6 }, { "label": "[7]", "url": "https://docs.arc.io/arc/references/contract-addresses", "claim": "Arc Docs, *Contract addresses - Arc Docs*, fetched 2026-10-31", "date": null, "quote": "Contract addresses - Arc Docs (function(c){var P=c.primary,F=c.fallbacks,found,probes={},checks={},down,reported;window.__mintAssets=P;function / and ERC-20 interfaces share the same underlying balance. Mainnet Testnet Contract Address Notes USDC", "ref": 7 }, { "label": "[8]", "url": "https://eips.ethereum.org/EIPS/eip-20", "claim": "Fabian Vogelsteller and Vitalik Buterin (Ethereum), *ERC-20: Token Standard*, 2015-11-19", "date": "2015-11-19", "quote": "Simple Summary A standard interface for tokens.", "ref": 8 }, { "label": "[9]", "url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8004.md", "claim": "Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERCS/erc-8004.md (Trustless Agents)*, created 2025-08-13; fetched 2026-10-30", "date": null, "quote": "author: Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis) , Jordan Ellis , Erik Reppel discussions-to: https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098 status: Draft type: Standards Track category: ERC created: 2025-08-13 requires: 155, 712, 721, 1271", "ref": 9 }, { "label": "[10]", "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-operational-launch-of-x402-foundation-to-standardize-internet-native-payments-for-ai-agents-and-applications", "claim": "Linux Foundation, *Linux Foundation Announces Operational Launch of x402 Foundation to Standardize Internet-Native Payments for AI Agents and Applications*, July 14, 2026", "date": null, "quote": "SAN FRANCISCO, July 14, 2026 – The Linux Foundation , the nonprofit organization enabling mass innovation through open source, today announced the operational launch of the x402 Foundation", "ref": 10 }, { "label": "[11]", "url": "https://github.com/ethereum/ERCs/pull/1844", "claim": "thamerdridi, *Update ERC-8226: add reference implementation and refine spec*, merged 2026-06-29; fetched 2026-10-31", "date": null, "quote": "\"https://github.com/ethereum/ERCs/pull/1844.diff\", \"patch_url\": \"https://github.com/ethereum/ERCs/pull/1844.patch\", \"merged_at\": \"2026-06-29T21:55:50Z\" }, \"body\": \"this pr updates ERC-8226 (Regulated Agent", "ref": 11 }, { "label": "[12]", "url": "https://www.ietf.org/archive/id/draft-stone-vcap-02.html", "claim": "B. Stone, SwarmSync.AI, *VCAP: Verified Commerce for Agent Protocols (draft-stone-vcap-02)*, 4 September 2026; expires 8 March 2027", "date": null, "quote": "--- --- --- --- --- Stone Expires 8 March 2027 Page VCAP: Verified Commerce", "ref": 12 }, { "label": "[13]", "url": "https://basescan.org/address/0x238E541BfefD82238730D00a2208E5497F1832E0", "claim": "BaseScan, *ERC1967Proxy contract on Base*, fetched 2026-10-31", "date": null, "quote": "Logo!BaseScan Logo!BaseScan Logo ###### Developer Tools ###### Smart Contract Tools ###### Explore ###### Services![](/assets/base/images/svg/empty-token.svg?v=26.10.4.0)", "ref": 13 }, { "label": "[14]", "url": "https://explorer.testnet.arc.io/api/v2/addresses/0x0747EEf0706327138c69792bF28Cd525089e4583", "claim": "Arc Testnet Explorer, *Address 0x0747EEf0706327138c69792bF28Cd525089e4583*, fetched 2026-10-31", "date": null, "quote": "date: Sat, 31 Oct 2026 03:10:30 GMT", "ref": 14 }, { "label": "[15]", "url": "https://registry.npmjs.org/@virtuals-protocol/acp-node-v2", "claim": "Virtuals Protocol, *@virtuals-protocol/acp-node-v2*, fetched 2026-10-31", "date": null, "quote": "exit 1\",\"build\":\"tsc\",\"start\":\"node dist/index.js\",\"prepare\":\"tsc\"},\"_npmUser\":{\"name\":\"zuhwa\",\"email\":\"[email redacted]\"},\"_npmVersion\":\"10.9.2\",\"description\":\"The Agent Commerce Protocol (ACP) Node SDK v2", "ref": 15 }, { "label": "[16]", "url": "https://registry.npmjs.org/@virtuals-protocol/acp-cli", "claim": "Virtuals Protocol, *@virtuals-protocol/acp-cli*, fetched 2026-10-31", "date": null, "quote": "npm run build\"},\"_npmUser\":{\"name\":\"zuhwa\",\"email\":\"[email redacted]\"},\"repository\":{\"url\":\"git+https://github.com/Virtual-Protocol/acp-cli.git\",\"type\":\"git\"},\"_npmVersion\":\"10.9.2\",\"description\":\"CLI tool", "ref": 16 } ], "form": "onchain-registry", "governance": "Ethereum EIP/ERC process (Ethereum Magicians discussion + EIPs repository); status Draft, an ERC Standards Track proposal, not yet Final", "group": null, "history": [ { "date": "2026-09-06", "note": "verified against eips.ethereum.org/EIPS/eip-8183; flagged name collision with agentic-commerce-protocol (ACP)" }, { "date": "2026-10-29", "note": "Added verified ecosystem adoption (Virtuals Protocol on Base mainnet, Circle on Arc Testnet, OKX Wallet announced) and client implementation (Virtuals ACP SDK, Virtuals ACP CLI, Circle Wallets testnet demo)" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "erc-8183", "implementation": "shipping", "last_verified": "2026-11-12", "name": "ERC-8183: Agentic Commerce", "native_status": "Draft ERC — 'This specification defines the Agentic Commerce Protocol: a job with escrowed budget...'", "origin": { "date": "2026-02-25", "org": "Ethereum Foundation dAI team and Virtuals Protocol (Davide Crapis, Bryan Lim, Tay Weixiong, Chooi Zuhwa); OKX Wallet announced co-authorship 2026-06-09 (not yet listed on the EIP header)" }, "part_of": null, "parties": [ "agent-agent", "agent-site" ], "phase": "draft", "probe": { "method": "eth_call", "on_absent": "Absence at a given contract address only shows that specific deployment does not implement ERC-8183; there is no registry of ERC-8183 deployments to enumerate, so 'is ERC-8183 adopted' cannot be answered by any single probe.", "parse": "Contract implements the ERC-8183 job state machine functions (setBudget, fund, submit, complete, reject, claimRefund) and emits the corresponding lifecycle events; requires EIP-20 for the escrowed token", "path": "{contract_address}" }, "question": "How can two agents (a client and a provider) settle a job on-chain, with funds held in escrow and released only once an evaluator attests the work was done?", "scope": "commerce", "spec_url": "https://eips.ethereum.org/EIPS/eip-8183", "step": "pay", "summary_md": "**ERC-8183: Agentic Commerce** is a Draft Standards Track ERC that defines the Agentic Commerce Protocol: a job with an escrowed budget and an evaluator who alone may mark the job completed. The abstract summarizes four states: Open, Funded, Submitted, and Terminal. Davide Crapis (`@dcrapis`), Bryan Lim (`@ai-virtual-b`), Tay Weixiong (`@twx-virtuals`), and Chooi Zuhwa (`@Zuhwa`) created it on 2026-02-25. The header requires EIP-20 and links discussion to the Ethereum Magicians thread for this ERC. Payment SHALL use a single ERC-20 token, global for the contract or specified at creation. The client or the provider calls `setBudget`, then the client calls `fund`, and the contract pulls `job.budget` into escrow. The provider calls `submit` with a `deliverable` to move Funded to Submitted. Once Submitted, only the evaluator may `complete` or `reject`. A hook contract SHALL implement `IACPHook` with `beforeAction` and `afterAction`. When a hook is set, the core contract SHALL call both around each hookable function. `claimRefund` SHALL NOT be hookable. The specification calls that call a permissionless safety mechanism. The EIP header tracks the proposal as `ERC-8183: Agentic Commerce [DRAFT]` (`Created 2026-02-25`) on the Ethereum Standards Track. The abstract ends in Terminal. The state machine says a job has exactly one of six states and that no other transitions are valid. The rationale defines Terminal as Completed, Rejected, or Expired. On Jun 09, 2026, OKX Wallet wrote that it is joining the Ethereum Foundation and Virtuals as a co-author of ERC-8183.", "track": "community", "version": { "date": "2026-02-25", "label": "Draft, created 2026-02-25" }, "watch": [ { "type": "erc", "num": 8183 } ], "use_cases": [ "accept-agent-payments", "agent-to-agent-messaging", "audit-agent-actions" ], "audience": [ "agent-builder", "platform" ], "pairs_with": [ "erc-8004", "x402", "erc-8226", "vcap" ], "prerequisites": [ "erc-8004" ], "hatnote_md": "This page covers ERC-8183: Agentic Commerce, whose specification calls itself the Agentic Commerce Protocol. For unrelated protocols that share the acronym ACP, see OpenAI and Stripe's [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), Zed's [Agent Client Protocol](/protocols/agent-client-protocol/), AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/), IBM's [Agent Communication Protocol](/protocols/agent-communication-protocol/), and the [ACP overview](/terms/acp/).", "tier": "spec_brief", "lifecycle_status": "active_draft", "wire_archetype": "payments_onchain", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This page covers ERC-8183: Agentic Commerce, whose specification calls itself the Agentic Commerce Protocol. For unrelated protocols that share the acronym ACP, see OpenAI and Stripe's [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), Zed's [Agent Client Protocol](/protocols/agent-client-protocol/), AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/), IBM's [Agent Communication Protocol](/protocols/agent-communication-protocol/), and the [ACP overview](/terms/acp/). [1]", "v05_elevator_pitch_md": null, "v05_lead_md": "**ERC-8183: Agentic Commerce** is a Draft Standards Track ERC that defines the Agentic Commerce Protocol: a job with an escrowed budget and an evaluator who alone may mark the job completed. The abstract summarizes four states: Open, Funded, Submitted, and Terminal. [1] Davide Crapis (`@dcrapis`), Bryan Lim (`@ai-virtual-b`), Tay Weixiong (`@twx-virtuals`), and Chooi Zuhwa (`@Zuhwa`) created it on 2026-02-25. The header requires EIP-20 and links discussion to the Ethereum Magicians thread for this ERC. [1] Payment SHALL use a single ERC-20 token, global for the contract or specified at creation. The client or the provider calls `setBudget`, then the client calls `fund`, and the contract pulls `job.budget` into escrow. [1] The provider calls `submit` with a `deliverable` to move Funded to Submitted. Once Submitted, only the evaluator may `complete` or `reject`. [1] A hook contract SHALL implement `IACPHook` with `beforeAction` and `afterAction`. When a hook is set, the core contract SHALL call both around each hookable function. [1] `claimRefund` SHALL NOT be hookable. The specification calls that call a permissionless safety mechanism. [1] The EIP header tracks the proposal as `ERC-8183: Agentic Commerce [DRAFT]` (`Created 2026-02-25`) on the Ethereum Standards Track. [1] The abstract ends in Terminal. The state machine says a job has exactly one of six states and that no other transitions are valid. The rationale defines Terminal as Completed, Rejected, or Expired. [1] On Jun 09, 2026, OKX Wallet wrote that it is joining the Ethereum Foundation and Virtuals as a co-author of ERC-8183. [2]", "v05_identity_sentence_md": "**ERC-8183: Agentic Commerce** is a Draft Standards Track ERC that defines the Agentic Commerce Protocol: a job with an escrowed budget and an evaluator who alone may mark the job completed. The abstract summarizes four states: Open, Funded, Submitted, and Terminal. [1] Davide Crapis (`@dcrapis`), Bryan Lim (`@ai-virtual-b`), Tay Weixiong (`@twx-virtuals`), and Chooi Zuhwa (`@Zuhwa`) created it on 2026-02-25. The header requires EIP-20 and links discussion to the Ethereum Magicians thread for this ERC. [1]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Pay](/category/pay/) (`pay`)" }, { "label": "Form", "value_md": "On-chain registry (`onchain-registry`)" }, { "label": "Originated by", "value_md": "Davide Crapis (Ethereum Foundation dAI team) with Bryan Lim, Tay Weixiong and Chooi Zuhwa (Virtuals Protocol); OKX Wallet announced co-authorship on 2026-06-09 [1][2][3]" }, { "label": "Governed by", "value_md": "Ethereum ERC process (Standards Track: ERC, status Draft), discussed on Ethereum Magicians [1][3]" }, { "label": "Track", "value_md": "Ethereum Standards Track (ERC) [1]" }, { "label": "Status", "value_md": "Draft Standards Track ERC (created 2026-02-25; defines the Agentic Commerce Protocol for jobs with escrowed budget and evaluator attestation) [1][4]" }, { "label": "Version", "value_md": "Draft created 2026-02-25, no version number; Virtuals production contract is `AgenticCommerceV3` [1][4]" }, { "label": "Wire format", "value_md": "Solidity ABI calls and events on EVM chains, escrow in a single EIP-20 token (USDC on Arc) [1][5]" }, { "label": "Specification", "value_md": "https://eips.ethereum.org/EIPS/eip-8183 [1]" }, { "label": "Found at", "value_md": "No HTTP headers or well-known paths; contract addresses are published in operator docs [6][7]" }, { "label": "Licence", "value_md": "CC0 1.0 Universal (public domain waiver) [1]" } ], "v05_problem_md": "Many use cases need only a client locking funds, a provider submitting work, and one evaluator signaling done, or a rejection or a timeout refund. The protocol specifies that minimal surface so implementations stay small and composable. [1] A job has exactly one of six states, and no other transitions are valid. Open reaches Funded on `fund` after `setBudget`, or Rejected on the client's `reject`. Funded reaches Submitted on `submit`, Rejected on the evaluator's `reject`, or Expired on `claimRefund` after `expiredAt`. [1] Once Submitted, only the evaluator can complete or reject, so the client cannot pull funds back unilaterally. Completed pays the provider minus an optional platform fee. Rejected and Expired refund the client. [1] The specification does not embed a reputation system and implementations are RECOMMENDED to integrate with ERC-8004. A platform fee is not required. Implementations MAY charge one on Completed, and if present it SHALL be deducted only on completion, not on refund. [1] There is no dispute resolution or arbitration, and reject or expiry is final. The specification only requires one payment token per contract, and a per-job token is a MAY. [1]", "v05_mechanism_delta_md": "A job has exactly one of six states, and no other transitions are valid. Open reaches Funded on `fund` after `setBudget`, or Rejected on the client's `reject`. Funded reaches Submitted on `submit`, Rejected on the evaluator's `reject`, or Expired on `claimRefund` after `expiredAt`. [1] Once Submitted, only the evaluator can complete or reject, so the client cannot pull funds back unilaterally. Completed pays the provider minus an optional platform fee. Rejected and Expired refund the client. [1]", "v05_scope_boundary_md": "The specification does not embed a reputation system and implementations are RECOMMENDED to integrate with ERC-8004. A platform fee is not required. Implementations MAY charge one on Completed, and if present it SHALL be deducted only on completion, not on refund. [1] There is no dispute resolution or arbitration, and reject or expiry is final. The specification only requires one payment token per contract, and a per-job token is a MAY. [1]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "EIP-20: Token Standard", "spec_or_rfc": "ERC-20 (EIP-20)", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "ERC-8183 locks the job budget as an EIP-20 token and moves the job through Open, Funded, Submitted, Completed, Rejected, and Expired, until the evaluator attests completion, releasing escrow, or rejects and refunds the client. [1][8]" } ], "agentic_peers": [ { "target_id": "erc-8004", "target_name": "ERC-8004: Trustless Agents", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ERC-8183 requires only EIP-20 in its front matter and marks ERC-8004 as RECOMMENDED for optional identity and reputation composition via attestation hashes, while ERC-8183 itself is the on-chain EIP-20 job escrow contract discovered by contract address and ABI. [1][9]" }, { "target_id": "x402", "target_name": "x402", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "ERC-8183 settlement is the on-chain EIP-20 job moving through states Open, Funded, Submitted, Completed, Rejected, and Expired, while x402 settlement is an HTTP 402 PAYMENT-SIGNATURE payload verified by a facilitator. [1][10]" }, { "target_id": "erc-8226", "target_name": "ERC-8226 Regulated Agent Mandate", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ERC-8226 stores a regulated agent mandate on-chain, while ERC-8183's contract surface is the EIP-20 job escrow, including reference types AgenticCommerce.sol and IACPHook.sol, and it does not define that mandate. [1][11]" }, { "target_id": "vcap", "target_name": "VCAP: Verified Commerce for Agent Protocols", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "ERC-8183 holds the EIP-20 budget inside the job contract until the evaluator attests completion or rejects, while VCAP's escrow is an external rail released or refunded by a verification callback. [1][12]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (5 probed or cited examples; non-exhaustive).", "side_a": { "visible": true, "heading": "Sellers, platforms & payment rails", "col4_header": "Rail, Asset & Scheme", "note_md": null, "rows": [ { "actor": "Virtuals Protocol (`AgenticCommerceV3`)", "role": "Escrow platform & settlement contract (Co-author)", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · as of 2026-10-29", "col4_md": "EIP-20 token escrow & evaluator attestation contract on Base (`0x238E541BfefD82238730D00a2208E5497F1832E0` proxy to AgenticCommerceV3); 6-state job machine (Open → Funded → Submitted → Completed/Rejected/Expired), 7,630 mainnet txns as of 2026-10-29", "source_md": "[Virtuals ACP Overview (checked 2026-10-29)](https://os.virtuals.io/acp/overview) [6] · [Basescan 0x238E…32E0](https://basescan.org/address/0x238E541BfefD82238730D00a2208E5497F1832E0) [13]" }, { "actor": "Circle (`AgenticCommerce` on Arc Testnet)", "role": "Reference escrow contract", "status": "Experimental", "status_display": "Experimental · as of 2026-10-29", "col4_md": "USDC job escrow & post-evaluation settlement contract on Arc Testnet (`0x0747EEf0706327138c69792bF28Cd525089e4583`, 629,018 testnet txns as of 2026-10-29; no mainnet address)", "source_md": "[Arc Docs Contract Addresses (checked 2026-10-29)](https://docs.arc.io/arc/references/contract-addresses) [7] · [Arc Testnet Explorer](https://explorer.testnet.arc.io/api/v2/addresses/0x0747EEf0706327138c69792bF28Cd525089e4583) [14]" } ] }, "side_b": { "visible": true, "heading": "Buying agents, wallets & client SDKs", "col4_header": "Rail, Asset & Scheme", "note_md": null, "rows": [ { "actor": "Virtuals ACP SDK (`@virtuals-protocol/acp-node-v2`)", "role": "Client SDK (Co-author)", "status": "Supported", "status_display": "Supported · checked 2026-10-31", "col4_md": "Node.js SDK (v0.1.15 on npm) for programmatic agents and LLM-driven automation interacting with Virtuals' ERC-8183 escrow contracts on Base", "source_md": "[Virtuals ACP Overview (checked 2026-10-29)](https://os.virtuals.io/acp/overview) [6] · [npm @virtuals-protocol/acp-node-v2](https://registry.npmjs.org/@virtuals-protocol/acp-node-v2) [15]" }, { "actor": "Virtuals ACP CLI (`@virtuals-protocol/acp-cli`)", "role": "Client CLI (Co-author)", "status": "Supported", "status_display": "Supported · checked 2026-10-31", "col4_md": "CLI (v1.0.40 on npm) for shell-based agents, scripted workflows, and human-operated ERC-8183 job management on Base", "source_md": "[Virtuals ACP Overview (checked 2026-10-29)](https://os.virtuals.io/acp/overview) [6] · [npm @virtuals-protocol/acp-cli](https://registry.npmjs.org/@virtuals-protocol/acp-cli) [16]" }, { "actor": "Circle Wallets (Arc Testnet walkthrough)", "role": "Wallet (Testnet Demo)", "status": "Experimental", "status_display": "Experimental · checked 2026-10-31", "col4_md": "Circle programmable wallets driving the ERC-8183 USDC job escrow lifecycle on Arc Testnet", "source_md": "[Arc Blog (2026-04-07)](https://www.arc.io/blog/running-an-agentic-economic-flow-on-arc-with-erc-8183) [5]" } ] }, "additional_tables": null, "censuses": [], "footer_md": null }, "v05_see_also": [ { "target_id": "agora-commerce-protocol", "target_name": "Agora (agent marketplace protocol)", "relation_label": "Peer alternative", "delta": "Agora's escrow is AgoraEscrowV2 on Base Sepolia, called from /v1/payments/execute and /v1/x402/jobs, while ERC-8183 is a Draft Standards Track Ethereum ERC for on-chain job escrow over EIP-20 (ERC-20) tokens whose evaluator attests completion or rejects.", "item_md": "**[Agora (agent marketplace protocol)](/protocols/agora-commerce-protocol/)** (Peer alternative) — Agora's escrow is AgoraEscrowV2 on Base Sepolia, called from /v1/payments/execute and /v1/x402/jobs, while ERC-8183 is a Draft Standards Track Ethereum ERC for on-chain job escrow over EIP-20 (ERC-20) tokens whose evaluator attests completion or rejects." }, { "target_id": "erc-8001", "target_name": "ERC-8001: Agent Coordination Framework", "relation_label": "Complements", "delta": "ERC-8183 defines an on-chain Agentic Commerce job escrow state machine (Open, Funded, Submitted, Completed, Rejected, Expired) with evaluator attestation, while ERC-8001 is the EIP-712 countersigned multi-party intent coordination contract.", "item_md": "**[ERC-8001: Agent Coordination Framework](/protocols/erc-8001/)** (Complements) — ERC-8183 defines an on-chain Agentic Commerce job escrow state machine (Open, Funded, Submitted, Completed, Rejected, Expired) with evaluator attestation, while ERC-8001 is the EIP-712 countersigned multi-party intent coordination contract." }, { "item_md": "**[Pay protocols](/category/pay/)** — Category index for `pay` standards." } ], "v05_compiled_md": "---\nid: erc-8183\ntitle: \"ERC-8183: Agentic Commerce\"\ntier: spec_brief\nlifecycle_status: active_draft\ncategory: pay\nform: onchain-registry\nwire_archetype: payments_onchain\nspec_url: https://eips.ethereum.org/EIPS/eip-8183\nlast_checked: 2026-11-12\n---\n\n# ERC-8183: Agentic Commerce\n\n**Category:** [Pay](/category/pay/) (`pay`) · **Form:** On-chain registry (`onchain-registry`) · **Last checked:** 2026-11-12\n\n> *This page covers ERC-8183: Agentic Commerce, whose specification calls itself the Agentic Commerce Protocol. For unrelated protocols that share the acronym ACP, see OpenAI and Stripe's [Agentic Commerce Protocol](/protocols/agentic-commerce-protocol/), Zed's [Agent Client Protocol](/protocols/agent-client-protocol/), AGNTCY's [Agent Connect Protocol](/protocols/agent-connect-protocol/), IBM's [Agent Communication Protocol](/protocols/agent-communication-protocol/), and the [ACP overview](/terms/acp/). [1]*\n\n**ERC-8183: Agentic Commerce** is a Draft Standards Track ERC that defines the Agentic Commerce Protocol: a job with an escrowed budget and an evaluator who alone may mark the job completed. The abstract summarizes four states: Open, Funded, Submitted, and Terminal. [1] Davide Crapis (`@dcrapis`), Bryan Lim (`@ai-virtual-b`), Tay Weixiong (`@twx-virtuals`), and Chooi Zuhwa (`@Zuhwa`) created it on 2026-02-25. The header requires EIP-20 and links discussion to the Ethereum Magicians thread for this ERC. [1] Payment SHALL use a single ERC-20 token, global for the contract or specified at creation. The client or the provider calls `setBudget`, then the client calls `fund`, and the contract pulls `job.budget` into escrow. [1] The provider calls `submit` with a `deliverable` to move Funded to Submitted. Once Submitted, only the evaluator may `complete` or `reject`. [1] A hook contract SHALL implement `IACPHook` with `beforeAction` and `afterAction`. When a hook is set, the core contract SHALL call both around each hookable function. [1] `claimRefund` SHALL NOT be hookable. The specification calls that call a permissionless safety mechanism. [1] The EIP header tracks the proposal as `ERC-8183: Agentic Commerce [DRAFT]` (`Created 2026-02-25`) on the Ethereum Standards Track. [1] The abstract ends in Terminal. The state machine says a job has exactly one of six states and that no other transitions are valid. The rationale defines Terminal as Completed, Rejected, or Expired. [1] On Jun 09, 2026, OKX Wallet wrote that it is joining the Ethereum Foundation and Virtuals as a co-author of ERC-8183. [2]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Pay](/category/pay/) (`pay`) |\n| **Form** | On-chain registry (`onchain-registry`) |\n| **Originated by** | Davide Crapis (Ethereum Foundation dAI team) with Bryan Lim, Tay Weixiong and Chooi Zuhwa (Virtuals Protocol); OKX Wallet announced co-authorship on 2026-06-09 [1][2][3] |\n| **Governed by** | Ethereum ERC process (Standards Track: ERC, status Draft), discussed on Ethereum Magicians [1][3] |\n| **Track** | Ethereum Standards Track (ERC) [1] |\n| **Status** | Draft Standards Track ERC (created 2026-02-25; defines the Agentic Commerce Protocol for jobs with escrowed budget and evaluator attestation) [1][4] |\n| **Version** | Draft created 2026-02-25, no version number; Virtuals production contract is `AgenticCommerceV3` [1][4] |\n| **Wire format** | Solidity ABI calls and events on EVM chains, escrow in a single EIP-20 token (USDC on Arc) [1][5] |\n| **Specification** | https://eips.ethereum.org/EIPS/eip-8183 [1] |\n| **Found at** | No HTTP headers or well-known paths; contract addresses are published in operator docs [6][7] |\n| **Licence** | CC0 1.0 Universal (public domain waiver) [1] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [Adoption and ecosystem](#adoption-and-ecosystem)\n4. [See also](#see-also)\n5. [References](#references)\n\n---\n\n## Problem and scope\n\nMany use cases need only a client locking funds, a provider submitting work, and one evaluator signaling done, or a rejection or a timeout refund. The protocol specifies that minimal surface so implementations stay small and composable. [1] A job has exactly one of six states, and no other transitions are valid. Open reaches Funded on `fund` after `setBudget`, or Rejected on the client's `reject`. Funded reaches Submitted on `submit`, Rejected on the evaluator's `reject`, or Expired on `claimRefund` after `expiredAt`. [1] Once Submitted, only the evaluator can complete or reject, so the client cannot pull funds back unilaterally. Completed pays the provider minus an optional platform fee. Rejected and Expired refund the client. [1] The specification does not embed a reputation system and implementations are RECOMMENDED to integrate with ERC-8004. A platform fee is not required. Implementations MAY charge one on Completed, and if present it SHALL be deducted only on completion, not on refund. [1] There is no dispute resolution or arbitration, and reject or expiry is final. The specification only requires one payment token per contract, and a per-job token is a MAY. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **EIP-20: Token Standard** | `ERC-20 (EIP-20)` | Profiles classic standard | ERC-8183 locks the job budget as an EIP-20 token and moves the job through Open, Funded, Submitted, Completed, Rejected, and Expired, until the evaluator attests completion, releasing escrow, or rejects and refunds the client. [1][8] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[ERC-8004: Trustless Agents](/protocols/erc-8004/)** | Complements | ERC-8183 requires only EIP-20 in its front matter and marks ERC-8004 as RECOMMENDED for optional identity and reputation composition via attestation hashes, while ERC-8183 itself is the on-chain EIP-20 job escrow contract discovered by contract address and ABI. [1][9] |\n| **[x402](/protocols/x402/)** | Peer alternative | ERC-8183 settlement is the on-chain EIP-20 job moving through states Open, Funded, Submitted, Completed, Rejected, and Expired, while x402 settlement is an HTTP 402 PAYMENT-SIGNATURE payload verified by a facilitator. [1][10] |\n| **[ERC-8226 Regulated Agent Mandate](/protocols/erc-8226/)** | Complements | ERC-8226 stores a regulated agent mandate on-chain, while ERC-8183's contract surface is the EIP-20 job escrow, including reference types AgenticCommerce.sol and IACPHook.sol, and it does not define that mandate. [1][11] |\n| **[VCAP: Verified Commerce for Agent Protocols](/protocols/vcap/)** | Peer alternative | ERC-8183 holds the EIP-20 budget inside the job contract until the evaluator attests completion or rejects, while VCAP's escrow is an external rail released or refunded by a verification callback. [1][12] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (5 probed or cited examples; non-exhaustive).*\n\n### Sellers, platforms & payment rails\n\n| Actor | Role | Status | Rail, Asset & Scheme | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Virtuals Protocol (`AgenticCommerceV3`)** | Escrow platform & settlement contract (Co-author) | Live (HTTP 200) · as of 2026-10-29 | EIP-20 token escrow & evaluator attestation contract on Base (`0x238E541BfefD82238730D00a2208E5497F1832E0` proxy to AgenticCommerceV3); 6-state job machine (Open → Funded → Submitted → Completed/Rejected/Expired), 7,630 mainnet txns as of 2026-10-29 | [Virtuals ACP Overview (checked 2026-10-29)](https://os.virtuals.io/acp/overview) [6] · [Basescan 0x238E…32E0](https://basescan.org/address/0x238E541BfefD82238730D00a2208E5497F1832E0) [13] |\n| **Circle (`AgenticCommerce` on Arc Testnet)** | Reference escrow contract | Experimental · as of 2026-10-29 | USDC job escrow & post-evaluation settlement contract on Arc Testnet (`0x0747EEf0706327138c69792bF28Cd525089e4583`, 629,018 testnet txns as of 2026-10-29; no mainnet address) | [Arc Docs Contract Addresses (checked 2026-10-29)](https://docs.arc.io/arc/references/contract-addresses) [7] · [Arc Testnet Explorer](https://explorer.testnet.arc.io/api/v2/addresses/0x0747EEf0706327138c69792bF28Cd525089e4583) [14] |\n\n### Buying agents, wallets & client SDKs\n\n| Actor | Role | Status | Rail, Asset & Scheme | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Virtuals ACP SDK (`@virtuals-protocol/acp-node-v2`)** | Client SDK (Co-author) | Supported · checked 2026-10-31 | Node.js SDK (v0.1.15 on npm) for programmatic agents and LLM-driven automation interacting with Virtuals' ERC-8183 escrow contracts on Base | [Virtuals ACP Overview (checked 2026-10-29)](https://os.virtuals.io/acp/overview) [6] · [npm @virtuals-protocol/acp-node-v2](https://registry.npmjs.org/@virtuals-protocol/acp-node-v2) [15] |\n| **Virtuals ACP CLI (`@virtuals-protocol/acp-cli`)** | Client CLI (Co-author) | Supported · checked 2026-10-31 | CLI (v1.0.40 on npm) for shell-based agents, scripted workflows, and human-operated ERC-8183 job management on Base | [Virtuals ACP Overview (checked 2026-10-29)](https://os.virtuals.io/acp/overview) [6] · [npm @virtuals-protocol/acp-cli](https://registry.npmjs.org/@virtuals-protocol/acp-cli) [16] |\n| **Circle Wallets (Arc Testnet walkthrough)** | Wallet (Testnet Demo) | Experimental · checked 2026-10-31 | Circle programmable wallets driving the ERC-8183 USDC job escrow lifecycle on Arc Testnet | [Arc Blog (2026-04-07)](https://www.arc.io/blog/running-an-agentic-economic-flow-on-arc-with-erc-8183) [5] |\n\n---\n\n## See also\n\n- **[Agora (agent marketplace protocol)](/protocols/agora-commerce-protocol/)** *(Peer alternative)* — Agora's escrow is AgoraEscrowV2 on Base Sepolia, called from /v1/payments/execute and /v1/x402/jobs, while ERC-8183 is a Draft Standards Track Ethereum ERC for on-chain job escrow over EIP-20 (ERC-20) tokens whose evaluator attests completion or rejects.\n- **[ERC-8001: Agent Coordination Framework](/protocols/erc-8001/)** *(Complements)* — ERC-8183 defines an on-chain Agentic Commerce job escrow state machine (Open, Funded, Submitted, Completed, Rejected, Expired) with evaluator attestation, while ERC-8001 is the EIP-712 countersigned multi-party intent coordination contract.\n- **Category:** [Pay protocols](/category/pay/)\n\n---\n\n## References\n\n1. Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce* (created 2026-02-25; fetched 2026-10-31) — \n2. OKX Wallet, *Co-authoring ERC-8183, the open standard for agent commerce* (published 2026-06-09; fetched 2026-10-31) — \n3. Davide Crapis, Fellowship of Ethereum Magicians, *ERC-8183: Agentic Commerce - ERCs - Fellowship of Ethereum Magicians* (topic opened 2026-03-04; fetched 2026-10-31) — \n4. BaseScan, *AgenticCommerceV3 contract source on Base* (fetched 2026-10-31) — \n5. Blessing Adesiji, Circle, *Using Arc with ERC-8183 to Run an Agentic Economic Flow* (April 7, 2026; fetched 2026-10-31) — \n6. Virtuals Protocol, *What is ACP? – EconomyOS* (fetched 2026-10-31) — \n7. Arc Docs, *Contract addresses - Arc Docs* (fetched 2026-10-31) — \n8. Fabian Vogelsteller and Vitalik Buterin (Ethereum), *ERC-20: Token Standard* (2015-11-19) — \n9. Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERCS/erc-8004.md (Trustless Agents)* (created 2025-08-13; fetched 2026-10-30) — \n10. Linux Foundation, *Linux Foundation Announces Operational Launch of x402 Foundation to Standardize Internet-Native Payments for AI Agents and Applications* (July 14, 2026) — \n11. thamerdridi, *Update ERC-8226: add reference implementation and refine spec* (merged 2026-06-29; fetched 2026-10-31) — \n12. B. Stone, SwarmSync.AI, *VCAP: Verified Commerce for Agent Protocols (draft-stone-vcap-02)* (4 September 2026; expires 8 March 2027) — \n13. BaseScan, *ERC1967Proxy contract on Base* (fetched 2026-10-31) — \n14. Arc Testnet Explorer, *Address 0x0747EEf0706327138c69792bF28Cd525089e4583* (fetched 2026-10-31) — \n15. Virtuals Protocol, *@virtuals-protocol/acp-node-v2* (fetched 2026-10-31) — \n16. Virtuals Protocol, *@virtuals-protocol/acp-cli* (fetched 2026-10-31) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "ERC-8226", "adoption": { "level": "unmeasured", "by": null, "probe_run": null }, "aliases": [ "RAMS", "Regulated Agent Mandate Standard" ], "analog": "Power of attorney", "collisions": [], "discovery": { "mechanism": "EVM contract interface detection (ERC-165 supportsInterface for IAgentMandate)", "path": null }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8226.md", "claim": "Ludovico Rossi (@ludovicor-eth), Dario Lo Buglio (@xaler5), Thamer Dridi (@thamerdridi), and Nabil El Alami Khalifi (@nabil-brickken), *ERC-8226: Regulated Agent Mandate*, created 2026-04-12; fetched 2026-10-31", "date": null, "quote": "This standard defines a compliance delegation layer for AI agents operating on tokenized regulated assets. It specifies how a verified principal can delegate scoped, time-bounded, and financially capped authority to an on-chain agent, and how a regulated token verifies the mandate before an agent-initiated action. / author: Ludovico Rossi (@ludovicor-eth) … Nabil El Alami Khalifi (@nabil-brickken) / Any contract in the agent's execution path calls `canExecute` to verify the mandate and `recordExecution` to record use. / The principal is the holder (`from`) and the agent is the caller (`msg.sender`); a call with `msg.sender != from` is agent-initiated and MUST satisfy the `(msg.sender, from)` mandate. / All implementations MUST implement [ERC-165](./eip-165.md). / RAMS introduces no changes to any existing standard. / author: Ludovico Rossi (@ludovicor-eth) <[email redacted]>, Dario Lo Buglio (@xaler5) <[email redacted]>, Thamer Dridi (@thamerdridi) <[email redacted]>, Nabil El Alami Khalifi (@nabil-brickken) <[email redacted]> / Khalifi (@nabil-brickken) discussions-to: https://ethereum-magicians.org/t/erc-8226-regulated-agent-mandate/28208 status: Draft type: Standards Track category: ERC created: 2026-04-12 requires: / @param signature Principal signature (EIP-712, ERC-1271 supported). function revokeMandate(address agent, address principal, address asset, / and any off-chain document. Actions are signed as a bytes32[] array and written into / neither defines an agent delegation model. Agent identity standards such as [ERC-8004](./eip-8004.md) provide agent discovery and trust signals but no mandate framework, and general-purpose agent authorization standards do not address regulated assets. / RAMS defines the delegation interface, the compliance provider model, and the integration pattern with regulated token contracts. / A freeze halts evaluation but MUST NOT revoke: revocation stays with the principal / RAMS mandate validity does NOT replace token-level allowance or operator approval. / The venue is out of scope of the normative interface. / The `metadata` field is non-normative: implementations and integrators MUST NOT rely on it for enforcement decisions", "ref": 1 }, { "label": "[2]", "url": "https://eips.ethereum.org/EIPS/eip-8226", "claim": "Ludovico Rossi (@ludovicor-eth), Dario Lo Buglio (@xaler5), Thamer Dridi (@thamerdridi), and Nabil El Alami Khalifi (@nabil-brickken), *ERC-8226: Regulated Agent Mandate*, created 2026-04-12; fetched 2026-10-31", "date": null, "quote": "Ludovico Rossi (@ludovicor-eth) < [email redacted] >, Dario Lo Buglio (@xaler5) < [email redacted] >, Thamer Dridi (@thamerdridi) < [email redacted] >, Nabil El Alami Khalifi (@nabil-brickken) < [email redacted] > / ERC-8226: Regulated Agent Mandate { \"@type\": \"WebSite\", \"url\": \"https://eips.ethereum.org\", \"name\": \"Ethereum Improvement Proposals\", \"description\": / Standards Track: ERC ERC-8226: Regulated Agent Mandate A com / \"ERC-8226: Regulated Agent Mandate [DRAFT],\" Ethereum Improvement Proposals, no. 8226, April 2026. Available: https://eips.ethereum.org/EIPS/eip-8226. / over an EIP-712 typed message. Implementations MUST verify principal signatures using ERC-1271 -compatible verification. / RFC 2119 and RFC 8174. All implementations MUST implement ERC-165. Revert conditions in this / Copyright and related rights waived via CC0.", "ref": 2 }, { "label": "[3]", "url": "https://github.com/ethereum/ERCs/pull/1844", "claim": "thamerdridi, *Update ERC-8226: add reference implementation and refine spec*, merged 2026-06-29; fetched 2026-10-31", "date": null, "quote": "# 1844 # 1844 Merged eip-review-bot merged 3 commits into ethereum:masterethereum/ERCs:masterfrom thamerdridi:erc-8226-impl-updatethamerdridi/ERCs:erc-8226-impl-update Copy head / \"https://github.com/ethereum/ERCs/pull/1844.diff\", \"patch_url\": \"https://github.com/ethereum/ERCs/pull/1844.patch\", \"merged_at\": \"2026-06-29T21:55:50Z\" }, \"body\": \"this pr updates ERC-8226 (Regulated Agent / \"closed\", \"locked\": false, \"assignees\": [ ], \"milestone\": null, \"comments\": 2, \"created_at\": \"2026-06-29T14:43:22Z\", \"updated_at\": \"2026-06-29T21:55:59Z\",", "ref": 3 }, { "label": "[4]", "url": "https://eips.ethereum.org/EIPS/eip-165", "claim": "Christian Reitwiessner et al. (Ethereum), *ERC-165: Standard Interface Detection*, 2018-01-23", "date": "2018-01-23", "quote": "Specification How Interfaces are Identified", "ref": 4 }, { "label": "[5]", "url": "https://raw.githubusercontent.com/ethereum/ERCs/master/ERCS/erc-8004.md", "claim": "Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERCS/erc-8004.md (Trustless Agents)*, created 2025-08-13; fetched 2026-10-30", "date": null, "quote": "author: Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis) , Jordan Ellis , Erik Reppel discussions-to: https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098 status: Draft type: Standards Track category: ERC created: 2025-08-13 requires: 155, 712, 721, 1271", "ref": 5 }, { "label": "[6]", "url": "https://eips.ethereum.org/EIPS/eip-8183", "claim": "Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce*, created 2026-02-25; fetched 2026-10-31", "date": null, "quote": "(@ai-virtual-b), Tay Weixiong (@twx-virtuals), Chooi Zuhwa (@Zuhwa) Created 2026-02-25 Discussion Link https://ethereum-magicians.org/t/erc-8183-agentic-commerce/27902 Requires EIP-20", "ref": 6 }, { "label": "[7]", "url": "https://raw.githubusercontent.com/google-agentic-commerce/AP2/main/docs/ap2/specification.md", "claim": "Google (google-agentic-commerce), *Agentic Payment Protocol (v0.2)*, fetched 2026-10-30", "date": null, "quote": "Agentic Payment Protocol (v0.2)", "ref": 7 }, { "label": "[8]", "url": "https://github.com/ethereum/ERCs/blob/master/ERCS/erc-8196.md", "claim": "ethereum/ERCs, *ERCs/ERCS/erc-8196.md at master · ethereum/ERCs*, fetched 2026-10-31", "date": null, "quote": "\\[email redacted]\\u003e, Chris Johnson \\[email redacted]\\u003e\",\"discussions-to: https://ethereum-magicians.org/t/erc-8196-ai-agent-authenticated-wallet/27987\",\"status: Final\",\"type:", "ref": 8 } ], "form": "onchain-registry", "governance": "Ethereum ERC process (Ethereum Magicians discussion thread + ethereum/ERCs GitHub repo); not yet adopted by an EIP editor as Final", "group": null, "history": [ { "date": "2026-09-06", "note": "verified against eips.ethereum.org/EIPS/eip-8226 and github.com/ethereum/ERCs/pull/1844" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "erc-8226", "implementation": "prototype", "last_verified": "2026-11-12", "name": "ERC-8226 Regulated Agent Mandate", "native_status": "Draft, Standards Track: ERC (marked Draft on eips.ethereum.org)", "origin": { "date": "2026-04-12", "org": "Brickken (Ludovico Rossi, Dario Lo Buglio, Thamer Dridi, Nabil El Alami Khalifi)" }, "part_of": null, "parties": [ "agent-site" ], "phase": "draft", "probe": { "method": "ETH_CALL", "on_absent": "No IAgentMandate registry is deployed at the address; the asset contract carries no RAMS-conformant delegation layer", "parse": "Call reverts with false/error if no active mandate exists; a successful bool return with mandate data proves an IAgentMandate registry is deployed at {contract}", "path": "{contract}.canExecute(agent, principal, asset, action, amount) via eth_call against IAgentMandate" }, "question": "What scoped, time-bounded, and financially capped authority may an on-chain agent exercise on a regulated asset holder's behalf?", "scope": "commerce", "spec_url": "https://eips.ethereum.org/EIPS/eip-8226", "step": "permit", "summary_md": "**ERC-8226: Regulated Agent Mandate** (`ERC-8226`), the Regulated Agent Mandate Standard (`RAMS`), defines a compliance delegation layer for AI agents operating on tokenized regulated assets. It specifies how a verified principal can delegate scoped, time-bounded, and financially capped authority to an on-chain agent, and how a regulated token verifies the mandate before an agent-initiated action. The authors are Ludovico Rossi (`@ludovicor-eth`), Dario Lo Buglio (`@xaler5`), Thamer Dridi (`@thamerdridi`), and Nabil El Alami Khalifi (`@nabil-brickken`). Front matter sets `status: Draft`, `type: Standards Track`, `category: ERC`, and `created: 2026-04-12`. `IAgentMandate` is implemented by the RAMS registry. Principals interact with this contract to grant, extend, and revoke mandates. Any contract in the agent's execution path calls `canExecute` to verify the mandate and `recordExecution` to record use. A regulated token integrates RAMS by gating each function it lets an agent perform for a holder. The principal is the holder (`from`) and the agent is the caller (`msg.sender`); a call with `msg.sender!= from` is agent-initiated and MUST satisfy the `(msg.sender, from)` mandate. All implementations MUST implement ERC-165. The front matter lists `requires: 165, 712, 1271`. The EIP-712 domain separator follows EIP-712 with `name = \"RAMS\"` and `version = \"1\"`. RAMS introduces no changes to any existing standard.", "track": "community", "version": { "date": "2026-04-12", "label": "Draft, created 2026-04-12" }, "watch": [ { "type": "erc", "num": 8226 } ], "use_cases": [ "delegate-user-authority", "agent-checkout", "audit-agent-actions" ], "audience": [ "platform", "agent-builder", "standards-body" ], "pairs_with": [ "erc-8004", "erc-8183", "ap2", "erc-8196" ], "prerequisites": [ "erc-8004" ], "hatnote_md": "", "tier": "spec_brief", "lifecycle_status": "active_draft", "wire_archetype": "identity_auth_crypto", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": null, "v05_elevator_pitch_md": null, "v05_lead_md": "**ERC-8226: Regulated Agent Mandate** (`ERC-8226`), the Regulated Agent Mandate Standard (`RAMS`), defines a compliance delegation layer for AI agents operating on tokenized regulated assets. It specifies how a verified principal can delegate scoped, time-bounded, and financially capped authority to an on-chain agent, and how a regulated token verifies the mandate before an agent-initiated action. [1] The authors are Ludovico Rossi (`@ludovicor-eth`), Dario Lo Buglio (`@xaler5`), Thamer Dridi (`@thamerdridi`), and Nabil El Alami Khalifi (`@nabil-brickken`). Front matter sets `status: Draft`, `type: Standards Track`, `category: ERC`, and `created: 2026-04-12`. [1] `IAgentMandate` is implemented by the RAMS registry. Principals interact with this contract to grant, extend, and revoke mandates. Any contract in the agent's execution path calls `canExecute` to verify the mandate and `recordExecution` to record use. [1] A regulated token integrates RAMS by gating each function it lets an agent perform for a holder. The principal is the holder (`from`) and the agent is the caller (`msg.sender`); a call with `msg.sender != from` is agent-initiated and MUST satisfy the `(msg.sender, from)` mandate. [1] All implementations MUST implement ERC-165. The front matter lists `requires: 165, 712, 1271`. The EIP-712 domain separator follows EIP-712 with `name = \"RAMS\"` and `version = \"1\"`. [1] RAMS introduces no changes to any existing standard. [1]", "v05_identity_sentence_md": "**ERC-8226: Regulated Agent Mandate** (`ERC-8226`), the Regulated Agent Mandate Standard (`RAMS`), defines a compliance delegation layer for AI agents operating on tokenized regulated assets. It specifies how a verified principal can delegate scoped, time-bounded, and financially capped authority to an on-chain agent, and how a regulated token verifies the mandate before an agent-initiated action. [1] The authors are Ludovico Rossi (`@ludovicor-eth`), Dario Lo Buglio (`@xaler5`), Thamer Dridi (`@thamerdridi`), and Nabil El Alami Khalifi (`@nabil-brickken`). Front matter sets `status: Draft`, `type: Standards Track`, `category: ERC`, and `created: 2026-04-12`. [1]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Permit](/category/permit/) (`permit`)" }, { "label": "Form", "value_md": "On-chain registry (`onchain-registry`)" }, { "label": "Originated by", "value_md": "Ludovico Rossi, Dario Lo Buglio, Thamer Dridi, and Nabil El Alami Khalifi (Brickken) (2026-04-12) [1][2]" }, { "label": "Governed by", "value_md": "Ethereum Improvement Proposals (ERC Standards Track, `ethereum/ERCs`) [2][3]" }, { "label": "Track", "value_md": "Ethereum Standards Track (ERC) [2]" }, { "label": "Status", "value_md": "Draft, Standards Track: ERC (marked Draft on eips.ethereum.org) [1][2][3]" }, { "label": "Version", "value_md": "`Draft` (Created 2026-04-12; updated via PR #1844) [1][3]" }, { "label": "Wire format", "value_md": "EVM ABI-encoded smart contract calls (`IAgentMandate`, `IComplianceProvider`, `IAgentExecutor`) and EIP-712 typed structured data signatures (`EIP-712`, `ERC-1271`) [1][2]" }, { "label": "Specification", "value_md": "https://eips.ethereum.org/EIPS/eip-8226 [2]" }, { "label": "Found at", "value_md": "On-chain `ERC-165` (`erc-165`) `supportsInterface` checks; no off-chain HTTP headers or `.well-known` URIs [1][2]" }, { "label": "Licence", "value_md": "CC0 1.0 Universal (public domain waiver) [2]" } ], "v05_problem_md": "Regulated token standards such as ERC-7943 and ERC-3643 govern who may hold or transact a token, but neither defines an agent delegation model. Agent identity standards such as ERC-8004 provide agent discovery and trust signals but no mandate framework, and general-purpose agent authorization standards do not address regulated assets. [1] RAMS defines the delegation interface, the compliance provider model, and the integration pattern with regulated token contracts. Mandate storage is keyed by `(agent, principal, asset)`. Each triple has at most one active mandate. A mandate covers one asset because caps are in that asset's units. [1] A freeze halts evaluation but MUST NOT revoke: revocation stays with the principal. [1] RAMS mandate validity does NOT replace token-level allowance or operator approval. For an agent-initiated transfer to succeed, both the token-level authorization and the RAMS mandate MUST pass. [1] The venue is out of scope of the normative interface. [1] The `metadata` field is non-normative, and implementations and integrators MUST NOT rely on it for enforcement decisions. [1]", "v05_mechanism_delta_md": "RAMS defines the delegation interface, the compliance provider model, and the integration pattern with regulated token contracts. Mandate storage is keyed by `(agent, principal, asset)`. Each triple has at most one active mandate. A mandate covers one asset because caps are in that asset's units. [1] A freeze halts evaluation but MUST NOT revoke: revocation stays with the principal. [1]", "v05_scope_boundary_md": "RAMS mandate validity does NOT replace token-level allowance or operator approval. For an agent-initiated transfer to succeed, both the token-level authorization and the RAMS mandate MUST pass. [1] The venue is out of scope of the normative interface. [1] The `metadata` field is non-normative, and implementations and integrators MUST NOT rely on it for enforcement decisions. [1]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "EIP-165 Standard Interface Detection", "spec_or_rfc": "ERC-165 (EIP-165)", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "Contracts detect IAgentMandate with ERC-165 supportsInterface, and the interface exposes canExecute for a pre-flight check and recordExecution for the (agent, principal, asset) mandate. [2][4]" } ], "agentic_peers": [ { "target_id": "erc-8004", "target_name": "ERC-8004: Trustless Agents", "relation_type": "builds_on", "relation_label": "Builds on", "delta_md": "ERC-8226 names ERC-8004 as one compatible agent identity, and the mandate itself is the on-chain IAgentMandate keyed by (agent, principal, asset), with canExecute and recordExecution. [2][5]" }, { "target_id": "erc-8183", "target_name": "ERC-8183: Agentic Commerce", "relation_type": "complements", "relation_label": "Complements", "delta_md": "ERC-8183 is a job escrow with Open, Funded, Submitted, and terminal states and an evaluator attestation, while ERC-8226 is the mandate contract a regulated token consults at execution. [2][6]" }, { "target_id": "ap2", "target_name": "Agent Payments Protocol (AP2)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "AP2 mandates are off-chain checkout and payment credentials presented to a merchant or network, while an ERC-8226 mandate is an on-chain IAgentMandate record checked inside the token call. [2][7]" }, { "target_id": "erc-8196", "target_name": "ERC-8196: AI Agent Authenticated Wallet", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "ERC-8196 is an ERC-4337 wallet that requires ERC-8126, while ERC-8226 checks IAgentMandate.canExecute before a regulated-token transfer and caps quantity for ERC-20, ERC-721, or ERC-1155. [2][8]" } ] }, "v05_adoption": { "visible": false, "empty_state_note_md": null, "scope_note_md": null, "side_a": null, "side_b": null, "additional_tables": null, "censuses": [], "footer_md": null }, "v05_see_also": [ { "target_id": "erc-8001", "target_name": "ERC-8001: Agent Coordination Framework", "relation_label": "Complements", "delta": "ERC-8226 is the Regulated Agent Mandate on-chain record, while ERC-8001 is the EIP-712 coordination contract, with ERC-1271 acceptance for contract wallets, discovered by address and ABI.", "item_md": "**[ERC-8001: Agent Coordination Framework](/protocols/erc-8001/)** (Complements) — ERC-8226 is the Regulated Agent Mandate on-chain record, while ERC-8001 is the EIP-712 coordination contract, with ERC-1271 acceptance for contract wallets, discovered by address and ABI." }, { "target_id": "agent-authorization-envelope", "target_name": "Agent Authorization Envelope", "relation_label": "Peer alternative", "delta": "ERC-8226 exposes IAgentMandate.canExecute and recordExecution, detected with ERC-165 supportsInterface, while this envelope is a JWS-secured Verifiable Credential checked without that contract interface.", "item_md": "**[Agent Authorization Envelope](/protocols/agent-authorization-envelope/)** (Peer alternative) — ERC-8226 exposes IAgentMandate.canExecute and recordExecution, detected with ERC-165 supportsInterface, while this envelope is a JWS-secured Verifiable Credential checked without that contract interface." }, { "target_id": "erc-8126", "target_name": "ERC-8126: AI Agent Verification", "relation_label": "Complements", "delta": "ERC-8226 exposes IAgentMandate.canExecute for a principal's on-chain mandate and names ERC-8004 as a compatible identity, while ERC-8126 attaches the 0-100 verification score to that identity.", "item_md": "**[ERC-8126: AI Agent Verification](/protocols/erc-8126/)** (Complements) — ERC-8226 exposes IAgentMandate.canExecute for a principal's on-chain mandate and names ERC-8004 as a compatible identity, while ERC-8126 attaches the 0-100 verification score to that identity." }, { "item_md": "**[Permit protocols](/category/permit/)** — Category index for `permit` standards." } ], "v05_compiled_md": "---\nid: erc-8226\ntitle: \"ERC-8226 Regulated Agent Mandate\"\ntier: spec_brief\nlifecycle_status: active_draft\ncategory: permit\nform: onchain-registry\nwire_archetype: identity_auth_crypto\nspec_url: https://eips.ethereum.org/EIPS/eip-8226\nlast_checked: 2026-11-12\n---\n\n# ERC-8226 Regulated Agent Mandate\n\n**Category:** [Permit](/category/permit/) (`permit`) · **Form:** On-chain registry (`onchain-registry`) · **Last checked:** 2026-11-12\n\n**ERC-8226: Regulated Agent Mandate** (`ERC-8226`), the Regulated Agent Mandate Standard (`RAMS`), defines a compliance delegation layer for AI agents operating on tokenized regulated assets. It specifies how a verified principal can delegate scoped, time-bounded, and financially capped authority to an on-chain agent, and how a regulated token verifies the mandate before an agent-initiated action. [1] The authors are Ludovico Rossi (`@ludovicor-eth`), Dario Lo Buglio (`@xaler5`), Thamer Dridi (`@thamerdridi`), and Nabil El Alami Khalifi (`@nabil-brickken`). Front matter sets `status: Draft`, `type: Standards Track`, `category: ERC`, and `created: 2026-04-12`. [1] `IAgentMandate` is implemented by the RAMS registry. Principals interact with this contract to grant, extend, and revoke mandates. Any contract in the agent's execution path calls `canExecute` to verify the mandate and `recordExecution` to record use. [1] A regulated token integrates RAMS by gating each function it lets an agent perform for a holder. The principal is the holder (`from`) and the agent is the caller (`msg.sender`); a call with `msg.sender != from` is agent-initiated and MUST satisfy the `(msg.sender, from)` mandate. [1] All implementations MUST implement ERC-165. The front matter lists `requires: 165, 712, 1271`. The EIP-712 domain separator follows EIP-712 with `name = \"RAMS\"` and `version = \"1\"`. [1] RAMS introduces no changes to any existing standard. [1]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Permit](/category/permit/) (`permit`) |\n| **Form** | On-chain registry (`onchain-registry`) |\n| **Originated by** | Ludovico Rossi, Dario Lo Buglio, Thamer Dridi, and Nabil El Alami Khalifi (Brickken) (2026-04-12) [1][2] |\n| **Governed by** | Ethereum Improvement Proposals (ERC Standards Track, `ethereum/ERCs`) [2][3] |\n| **Track** | Ethereum Standards Track (ERC) [2] |\n| **Status** | Draft, Standards Track: ERC (marked Draft on eips.ethereum.org) [1][2][3] |\n| **Version** | `Draft` (Created 2026-04-12; updated via PR #1844) [1][3] |\n| **Wire format** | EVM ABI-encoded smart contract calls (`IAgentMandate`, `IComplianceProvider`, `IAgentExecutor`) and EIP-712 typed structured data signatures (`EIP-712`, `ERC-1271`) [1][2] |\n| **Specification** | https://eips.ethereum.org/EIPS/eip-8226 [2] |\n| **Found at** | On-chain `ERC-165` (`erc-165`) `supportsInterface` checks; no off-chain HTTP headers or `.well-known` URIs [1][2] |\n| **Licence** | CC0 1.0 Universal (public domain waiver) [2] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [See also](#see-also)\n4. [References](#references)\n\n---\n\n## Problem and scope\n\nRegulated token standards such as ERC-7943 and ERC-3643 govern who may hold or transact a token, but neither defines an agent delegation model. Agent identity standards such as ERC-8004 provide agent discovery and trust signals but no mandate framework, and general-purpose agent authorization standards do not address regulated assets. [1] RAMS defines the delegation interface, the compliance provider model, and the integration pattern with regulated token contracts. Mandate storage is keyed by `(agent, principal, asset)`. Each triple has at most one active mandate. A mandate covers one asset because caps are in that asset's units. [1] A freeze halts evaluation but MUST NOT revoke: revocation stays with the principal. [1] RAMS mandate validity does NOT replace token-level allowance or operator approval. For an agent-initiated transfer to succeed, both the token-level authorization and the RAMS mandate MUST pass. [1] The venue is out of scope of the normative interface. [1] The `metadata` field is non-normative, and implementations and integrators MUST NOT rely on it for enforcement decisions. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **EIP-165 Standard Interface Detection** | `ERC-165 (EIP-165)` | Profiles classic standard | Contracts detect IAgentMandate with ERC-165 supportsInterface, and the interface exposes canExecute for a pre-flight check and recordExecution for the (agent, principal, asset) mandate. [2][4] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[ERC-8004: Trustless Agents](/protocols/erc-8004/)** | Builds on | ERC-8226 names ERC-8004 as one compatible agent identity, and the mandate itself is the on-chain IAgentMandate keyed by (agent, principal, asset), with canExecute and recordExecution. [2][5] |\n| **[ERC-8183: Agentic Commerce](/protocols/erc-8183/)** | Complements | ERC-8183 is a job escrow with Open, Funded, Submitted, and terminal states and an evaluator attestation, while ERC-8226 is the mandate contract a regulated token consults at execution. [2][6] |\n| **[Agent Payments Protocol (AP2)](/protocols/ap2/)** | Peer alternative | AP2 mandates are off-chain checkout and payment credentials presented to a merchant or network, while an ERC-8226 mandate is an on-chain IAgentMandate record checked inside the token call. [2][7] |\n| **[ERC-8196: AI Agent Authenticated Wallet](/protocols/erc-8196/)** | Peer alternative | ERC-8196 is an ERC-4337 wallet that requires ERC-8126, while ERC-8226 checks IAgentMandate.canExecute before a regulated-token transfer and caps quantity for ERC-20, ERC-721, or ERC-1155. [2][8] |\n\n---\n\n## See also\n\n- **[ERC-8001: Agent Coordination Framework](/protocols/erc-8001/)** *(Complements)* — ERC-8226 is the Regulated Agent Mandate on-chain record, while ERC-8001 is the EIP-712 coordination contract, with ERC-1271 acceptance for contract wallets, discovered by address and ABI.\n- **[Agent Authorization Envelope](/protocols/agent-authorization-envelope/)** *(Peer alternative)* — ERC-8226 exposes IAgentMandate.canExecute and recordExecution, detected with ERC-165 supportsInterface, while this envelope is a JWS-secured Verifiable Credential checked without that contract interface.\n- **[ERC-8126: AI Agent Verification](/protocols/erc-8126/)** *(Complements)* — ERC-8226 exposes IAgentMandate.canExecute for a principal's on-chain mandate and names ERC-8004 as a compatible identity, while ERC-8126 attaches the 0-100 verification score to that identity.\n- **Category:** [Permit protocols](/category/permit/)\n\n---\n\n## References\n\n1. Ludovico Rossi (@ludovicor-eth), Dario Lo Buglio (@xaler5), Thamer Dridi (@thamerdridi), and Nabil El Alami Khalifi (@nabil-brickken), *ERC-8226: Regulated Agent Mandate* (created 2026-04-12; fetched 2026-10-31) — \n2. Ludovico Rossi (@ludovicor-eth), Dario Lo Buglio (@xaler5), Thamer Dridi (@thamerdridi), and Nabil El Alami Khalifi (@nabil-brickken), *ERC-8226: Regulated Agent Mandate* (created 2026-04-12; fetched 2026-10-31) — \n3. thamerdridi, *Update ERC-8226: add reference implementation and refine spec* (merged 2026-06-29; fetched 2026-10-31) — \n4. Christian Reitwiessner et al. (Ethereum), *ERC-165: Standard Interface Detection* (2018-01-23) — \n5. Marco De Rossi, Davide Crapis, Jordan Ellis, and Erik Reppel, *ERCS/erc-8004.md (Trustless Agents)* (created 2025-08-13; fetched 2026-10-30) — \n6. Davide Crapis, Bryan Lim, Tay Weixiong, and Chooi Zuhwa, *ERC-8183: Agentic Commerce* (created 2026-02-25; fetched 2026-10-31) — \n7. Google (google-agentic-commerce), *Agentic Payment Protocol (v0.2)* (fetched 2026-10-30) — \n8. ethereum/ERCs, *ERCs/ERCS/erc-8196.md at master · ethereum/ERCs* (fetched 2026-10-31) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "", "adoption": { "level": "observed", "by": "Agio Digital, BRITECITY, ScoreTail, Chrome WebMCP demos, Google Chrome, Microsoft Edge, Brave (Leo AI), OpenAI ChatGPT Desktop, and 2 other verified implementations", "probe_run": null }, "aliases": [], "analog": "In-page JavaScript API (window.* APIs)", "audience": [ "site-owner", "agent-builder", "standards-body" ], "collisions": [ "Model Context Protocol (MCP)" ], "discovery": { "mechanism": "No file or well-known URL. Tools exist only while a page is open, after its script registers them, so an agent has to load the page to find them. Chrome’s docs: \"Tool discoverability: Clients and browsers must visit a site directly to know if it has callable tools.\"", "path": "No file or well-known URL. Tools exist only while a page is open, after its script registers them, so an agent has to load the page to find them. Chrome’s docs: \"Tool discoverability: Clients and browsers must visit a site directly to know if it has callable tools.\"" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://webmachinelearning.github.io/webmcp/", "claim": "Web Machine Learning Community Group (editors Brandon Walderman, Khushal Sagar, Dominic Farolino, and Samuel Dallstream), *WebMCP*, Draft Community Group Report, 11 November 2026", "date": null, "quote": "The WebMCP API enables web applications to provide JavaScript-based tools to AI agents. / This specification was published by the Web Machine Learning Community Group. / implement tools in client-side script instead of on the backend. / Draft Community Group Report, 11 November 2026 / partial interface Document { [ SecureContext , SameObject ] readonly attribute ModelContext modelContext / required DOMString name / object inputSchema / required ToolExecuteCallback execute / Editors: Brandon Walderman ( Microsoft ) Khushal Sagar ( Google ) Dominic Farolino ( Google ) Samuel Dallstream ( Microsoft ) / This specification was published by the Web Machine Learning Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. / partial interface Document { [ SecureContext, SameObject ] readonly attribute ModelContext modelContext; / published by the Web Machine Learning Community Group under the W3C Community Contributor License Agreement (CLA) / It is not a W3C Standard nor is it on the W3C Standards Track. / The ModelContext interface provides methods for web applications to register and manage tools that can be invoked by agents. / The ModelContext interface provides methods for web applications to register and manage tools that can be invoked by agents / [ Exposed = Window , SecureContext ] interface ModelContext : EventTarget / Returns a rejected promise if a tool with the same name is already registered, if the given name or description are empty strings, or if the inputSchema is invalid. / An AbortSignal that unregisters the tool when aborted. / To unregister a tool given a ModelContext modelContext / This is used by agents to reference the tool when making tool calls. / A natural language description of the tool’s functionality. / A JSON Schema object describing the expected input parameters for the tool / The function can be asynchronous and return a promise / If true, indicates that the tool does not modify any state and only reads data. / selectively enforce mandatory user confirmation prompts before executing high-stakes tools / may enqueue steps to the AI agent queue to perform an observation given any top-level browsing context / default allowlist … 'self' / 11 November 2026", "ref": 1 }, { "label": "[2]", "url": "https://github.com/MiguelsPizza/WebMCP", "claim": "Alexander Nahas (MiguelsPizza), *WebMCP*, repository created 2025-06-13", "date": null, "quote": "MiguelsPizza/WebMCP: Bringing the power of MCP to the web … \"createdAt\":\"2025-06-13T06:00:40.000Z\" / via a native server, bridging the browser to local processes / local MCP clients (e.g., Claude Desktop, Cursor)", "ref": 2 }, { "label": "[3]", "url": "https://github.com/jasonjmcghee/WebMCP", "claim": "Jason McGhee, *WebMCP*, repository created 2025-03-04", "date": null, "quote": "this was an early WebMCP proposal / implementation. … the idea of WebMCP has since evolved and is being worked on by much more capable folks that develop the web. … \"createdAt\":\"2025-03-04T04:07:00.000Z\"", "ref": 3 }, { "label": "[4]", "url": "https://www.w3.org/2025/08/14-webmachinelearning-minutes.html", "claim": "W3C Web Machine Learning Community Group, *WebML WG teleconference minutes*, 14 August 2025", "date": null, "quote": "anssik: I also want to acknowledge two individual contributors Alex Nahas and Jason McGhee who both have developed early WebMCP prototypes", "ref": 4 }, { "label": "[5]", "url": "https://raw.githubusercontent.com/webmachinelearning/webmcp/main/README.md", "claim": "webmachinelearning/webmcp (GitHub), *WebMCP*, checked 2026-11-04", "date": null, "quote": "The web page registers one or more tools using `document.modelContext.registerTool()`. / observing the browser state through a combination of screenshots, and DOM and accessibility tree snapshots, and then interact with the page by simulating human user input / An agent connected to the page queries the browser to discover the active list of tools and their schemas. / would let the browser synthesize tool definitions from HTML `
` elements / First published August 13, 2025 / External tools integrate with each AI platform via bespoke backend integrations / A service registers its tools with an AI platform, and the platform communicates directly with the service's backend servers / JavaScript functions with natural language descriptions and structured schemas / The browser mediates the call, invokes the tool's `execute` callback with the provided arguments / but it is not part of the specification at this time. / **WebMCP** introduces a client-side alternative. It allows web developers to define tools directly in the browser page's script. This enables visually rich, cooperative interplay between a user, a web page, and an agent with shared context. / By default, WebMCP is enabled in top-level windows and its same-origin iframes, but access can be delegated to cross-origin iframes using the Permissions Policy allow=\"tools\" / tab-level lifecycle management", "ref": 5 }, { "label": "[6]", "url": "https://github.com/webmachinelearning/webmcp/blob/7edc0e1818636182e352b3b15d9203a29b18319b/README.md", "claim": "Brandon Walderman, Leo Lee, Andrew Nolan, David Bokan, Khushal Sagar, and Hannah Van Opstal, *WebMCP explainer*, first published August 13, 2025 (commit 7edc0e18)", "date": null, "quote": "First published August 13, 2025 … Brandon Walderman … Leo Lee … Andrew Nolan … David Bokan … Khushal Sagar … Hannah Van Opstal / First published August 13, 2025 … Brandon Walderman … Leo Lee … Andrew Nolan … David Bokan … Khushal Sagar … Hannah Van Opstal … [email redacted] … [email redacted] / \"createdAt\":\"2025-08-05T13:10:14.000Z\" / MCP-B's underlying protocol, also named WebMCP, extends MCP / extension transports that use Chromium's runtime messaging to make a website's MCP server available to other extension components within the browser (background, sidebar, popup), and to other external MCP clients running on the same machine", "ref": 6 }, { "label": "[7]", "url": "https://github.com/webmachinelearning/webmcp", "claim": "Web Machine Learning Community Group, *WebMCP explainer*, first published August 13, 2025", "date": null, "quote": "WebMCP is currently focused on the imperative `document.modelContext.registerTool()` API described above, which is what the specification defines. / an agent connected to the page queries the browser to discover the active list of tools / the web page registers one or more tools using document.modelContext.registerTool()", "ref": 7 }, { "label": "[8]", "url": "https://developer.chrome.com/docs/ai/webmcp", "claim": "Alexandra Klepper, François Beaufort, and Kasper Kulikowski (Chrome for Developers), *WebMCP*, published 18 May 2026; last updated 7 October 2026", "date": null, "quote": "Tool discoverability: Clients and browsers must visit a site directly to know if it has callable tools. / allows tool registration in top-level and same-origin contexts, and disables it for cross-origin iframes. / Add annotations to a standard HTML forms to create a WebMCP tool. / Chrome Extensions can query and execute WebMCP tools with content scripts / Clients and browsers must visit a site directly to know if it has callable tools. / Chrome Extensions can query and execute WebMCP tools with\n content scripts / \"dateModified\": \"2026-10-07\"", "ref": 8 }, { "label": "[9]", "url": "https://github.com/webmachinelearning/webmcp/blob/7edc0e1818636182e352b3b15d9203a29b18319b/docs/proposal.md", "claim": "Brandon Walderman, Andrew Nolan, David Bokan, Khushal Sagar, and Hannah Van Opstal, *WebMCP API proposal*, August 13, 2025", "date": null, "quote": "The `window.agent` interface is introduced to represent an abstract AI agent that is connected to the page / The `agent` object has a single method `provideContext` / August 13, 2025 / Subsequent calls clear any pre-existing tools and other context before registering the new ones. / The `window.agent` interface is introduced", "ref": 9 }, { "label": "[10]", "url": "https://github.com/webmachinelearning/webmcp/commit/41dd8292ac19db6a43ea58aefc8fcb4662742411", "claim": "Dominic Farolino, *Initialize a Navigator's modelContext member*, 19 February 2026", "date": null, "quote": "Initialize a Navigator's modelContext member", "ref": 10 }, { "label": "[11]", "url": "https://github.com/webmachinelearning/webmcp/commit/c7b5c7023f6e6a1c7a2495946136eb19b3109ae6", "claim": "Dominic Farolino, *Move the modelContext getter to Document (#184)*, 27 May 2026", "date": null, "quote": "Move the `modelContext` getter to `Document` / iframe.contentDocument.modelContext", "ref": 11 }, { "label": "[12]", "url": "https://github.com/chromium/chromium/commit/4a9fee9eafcabd675c7245cc1b0acc1ca5f17d99", "claim": "Dominic Farolino (Chromium), *WebMCP: Remove navigator.modelContext*, 9 July 2026", "date": null, "quote": "It removes navigator.modelContext in favor of document.modelContext.", "ref": 12 }, { "label": "[13]", "url": "https://github.com/webmachinelearning/webmcp/commit/14ae813cc4e9fe0d39313f4b1ee5b231746731ad", "claim": "François Beaufort, *Remove declarative API from the spec for now (#338)*, 8 October 2026", "date": null, "quote": "Remove declarative API from the spec for now", "ref": 13 }, { "label": "[14]", "url": "https://ppc.land/chrome-149-origin-trial-puts-webmcp-in-developers-hands-at-last/", "claim": "PPC Land, *Chrome 149 origin trial puts WebMCP in developers' hands at last*, checked 2026-10-30", "date": null, "quote": "MCP servers can run headlessly. WebMCP cannot.", "ref": 14 }, { "label": "[15]", "url": "https://www.spronta.com/blog/state-of-webmcp-july-2026", "claim": "Spronta, *The State of WebMCP: July 2026*, July 2026", "date": null, "quote": "added requestUserInteraction() so tools can force a human confirmation / in the 21 July spec draft / moved the API from navigator to document to reflect that tools belong to a specific page / Chrome deprecated navigator.modelContext in Chrome 150 while the origin trial still ships it / document.modelContext ?? navigator.modelContext / from Chrome 149 through 156", "ref": 15 }, { "label": "[16]", "url": "https://groups.google.com/a/chromium.org/g/blink-dev/c/gmYffo5WOE8/m/OJxuQRP3AAAJ", "claim": "blink-dev, *Intent to Experiment: WebMCP*, 15 May 2026", "date": null, "quote": "Estimated milestones Shipping on desktop 157 Origin trial desktop first 149 Origin trial desktop last 156 / Shipping on desktop 157 Origin trial desktop first 149 Origin trial desktop last 156", "ref": 16 }, { "label": "[17]", "url": "https://developer.chrome.com/blog/ai-webmcp-origin-trial", "claim": "Alexandra Klepper (Chrome for Developers), *Join the WebMCP origin trial*, published 9 June 2026", "date": null, "quote": "In Chrome 149, you can sign up for the WebMCP origin trial / In Chrome 149, you can sign up for the WebMCP origin trial.", "ref": 17 }, { "label": "[18]", "url": "https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md", "claim": "Web Machine Learning Community Group, *Browser and Agent Implementation Status*, checked 2026-11-04", "date": null, "quote": "An Origin Trial is live in Chrome 149. / An [Origin Trial](https://developer.chrome.com/blog/ai-webmcp-origin-trial) is live in Chrome 149. / enable the `about:flags#enable-webmcp-testing` flag. / An [Origin Trial](https://developer.microsoft.com/en-us/microsoft-edge/origin-trials/trials/0b76fe60-b266-458e-a285-04e375c0c31a) is live in Edge 150. / Refer to Chrome implementation status for platform support. / Experimental support is added to [Leo AI chat](https://brave.com/leo/). / Issue 55232 / WebMCP is supported in [ChatGPT Desktop](https://chatgpt.com/download/). / is coming soon, letting Meta AI on the glasses call tools registered with `document.modelContext.registerTool()`. / It is off by default and enabled per device, either in Developer Mode or for wearers in the rollout.", "ref": 18 }, { "label": "[19]", "url": "https://github.com/GoogleChromeLabs/webmcp-tools", "claim": "Google Chrome Labs, *webmcp-tools*, checked 2026-11-06", "date": null, "quote": "`` tools, `toolautosubmit` / Travel WebMCP Demo (Imperative) / Le Petit Bistro (Declarative) / A mini-site explainer of WebMCP / Model Context Tool Inspector / WebMCP Evals / WebMCP Skills / WebMCP Declarative Polyfill / toolautosubmit / respondWith()", "ref": 19 }, { "label": "[20]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification*, 2026-07-28", "date": "2026-07-28", "quote": "discovery prompts resources tools … The protocol uses JSON-RPC 2.0 messages to establish communication between: hosts: LLM applications that initiate connections clients: connectors within the host application servers: services that provide context and capabilities … stdio … Streamable HTTP", "ref": 20 }, { "label": "[21]", "url": "https://raw.githubusercontent.com/nlweb-ai/website/main/NLWEBSPEC.md", "claim": "NLWeb, *NLWeb specification*, v0.55", "date": null, "quote": "should use schema.org vocabulary … POST /ask - submit a natural language query. * POST /await - check on or cancel a promised result. … NLWeb operations can be exposed as tools within the Model Context Protocol (MCP) … \"name\": \"ask\"", "ref": 21 }, { "label": "[22]", "url": "https://github.com/wild-card-ai/agents-json/blob/master/README.md", "claim": "Wildcard AI, *agents.json*, checked 2026-10-30", "date": null, "quote": "agents.json is a JSON schema of structured contracts designed for AI agents. API providers use their existing OpenAPI spec to construct this file and agents inspect this file to run accurate series of API calls. / /.well-known/agents.json", "ref": 22 }, { "label": "[23]", "url": "https://github.com/wild-card-ai/agents-json/blob/master/agents_json/agentsJson.schema.json", "claim": "Wildcard AI, *agents.json schema*, checked 2026-10-30", "date": null, "quote": "must include an array of flows that define sequences of API operations to be executed", "ref": 23 }, { "label": "[24]", "url": "https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx", "claim": "MCP Apps contributors, *MCP Apps specification*, 2026-01-26", "date": "2026-01-26", "quote": "ui:// … text/html;profile=mcp-app … resources/read", "ref": 24 }, { "label": "[25]", "url": "https://github.com/OTA-Tech-AI/web-agent-protocol", "claim": "OTA Tech AI, *Web Agent Protocol (WAP)*, checked 2026-10-31", "date": null, "quote": "Web Agent Protocol (WAP) - record and replay user interactions in the browser … convert recorded actions into MCP servers … exact replay - exactly reproduce every action … smart-replay", "ref": 25 }, { "label": "[26]", "url": "https://www.agiodigital.com/", "claim": "Agio Digital, *Licensed Crypto Fund Administrator, Bahamas*, checked 2026-10-30", "date": null, "quote": "{document:t=Yee,enabled:n=!0}=e,r=t / e.registerTool)==`function` / r.modelContext.registerTool({name:D(e.name),description:D(e.description),inputSchema:D(e.inputSchema)", "ref": 26 }, { "label": "[27]", "url": "https://britecity.com/it-health-check", "claim": "BRITECITY, *Free IT Health Check*, checked 2026-10-30", "date": null, "quote": "navigator.modelContext / document.modelContext / mc.registerTool(t) / name: 'get_britecity_services' / name: 'lookup_knowledge' / name: 'navigate_to_page' / name: 'open_book_a_call'", "ref": 27 }, { "label": "[28]", "url": "https://scoretail.com/en/sheet-music/canon-in-d-pachelbel-johann/view", "claim": "ScoreTail, *Canon in D (Pachelbel) score page*, checked 2026-10-30", "date": null, "quote": "await (0,k.registerTools)(t,n,s.signal) / e.registerTool(t,{signal:n}) / return document.modelContext??null / \"WebMCP: tools registered\" / enableOriginTrial / meta[http-equiv=\"origin-trial\"]", "ref": 28 }, { "label": "[29]", "url": "https://chromestatus.com/api/v0/features/5117755740913664", "claim": "Chrome Platform Status, *ChromeStatus feature 5117755740913664*, checked 2026-11-04", "date": null, "quote": "\"origintrial\": false, \"prefixed\": null, \"flag\": false, \"status\": {\"text\": \"Proposed\", \"val\": 2, \"milestone_str\": \"Proposed\"} / \"desktop_first\": 149, \"android_first\": 149, \"ios_first\": null, \"webview_first\": 149, \"desktop_last\": 156 / \"web_feature\": \"document-modelcontext\" / kModelContextRegisterTool / \"id\": 5117755740913664, \"name\": \"WebMCP\" / \"search_tags\": [\"WebMCP\"], \"created\": {\"by\": \"[email redacted]\", \"when\": \"2025-07-08 19:29:42.615078\"}, \"updated\": {\"by\": \"[email redacted]\", \"when\": \"2026-11-02 16:04:35.890651\"}", "ref": 29 }, { "label": "[30]", "url": "https://developer.microsoft.com/en-us/microsoft-edge/origin-trials/trials/0b76fe60-b266-458e-a285-04e375c0c31a", "claim": "Microsoft, *WebMCP origin trial*, trial expiration 30 March 2027", "date": null, "quote": "Trial Expiration Date

March 30, 2027 / Origin trial for WebMCP, which allows websites to register tools for use by agents", "ref": 30 }, { "label": "[31]", "url": "https://blogs.windows.com/msedgedev/2026/09/21/new-in-edge-for-developers-create-better-components-and-make-your-site-agent-ready/", "claim": "Patrick Brosset (Microsoft Edge), *New in Edge for developers: create better components and make your site agent-ready*, published 21 September 2026", "date": null, "quote": "Our implementation of the WebMCP spec in Microsoft Edge is ready for testing. To get started, we created a few samples and a browser extension to run and debug your WebMCP tools.", "ref": 31 }, { "label": "[32]", "url": "https://github.com/brave/brave-browser/issues/55232", "claim": "Jay Harris (Brave), *[AI Chat]: Add support for the WebMCP protocol to Leo*, opened 5 May 2026", "date": null, "quote": "\"title\":\"[AI Chat]: Add support for the WebMCP protocol to Leo\" / This will allow associated pages to expose tools to AI Chat. / brave://flags/#enable-webmcp-testing / content-type: text/html; charset=utf-8", "ref": 32 }, { "label": "[33]", "url": "https://github.com/GoogleChromeLabs/webmcp-extension/", "claim": "Google Chrome Labs, *webmcp-extension*, checked 2026-11-06", "date": null, "quote": "document.modelContext.getTools() / ontoolchange / allow=\"tools\" / chrome://flags/#prompt-api-tool-use / This is not an officially supported Google product.", "ref": 33 } ], "form": "browser-api", "governance": "W3C Web Machine Learning Community Group, in the webmachinelearning/webmcp GitHub repository (created 2025-08-05). Editors: Brandon Walderman and Samuel Dallstream (Microsoft), Khushal Sagar and Dominic Farolino (Google)", "group": null, "hatnote_md": "This page covers the W3C Web Machine Learning Community Group's client-side `document.modelContext` browser API specification. It is distinct from two earlier community prototypes that shared the name—`jasonjmcghee/WebMCP` (created 2025-03-04) and Alex Nahas's `MiguelsPizza/WebMCP` / MCP-B (created 2025-06-13)—both acknowledged by the Community Group for early prototyping experience; for the backend JSON-RPC protocol, see [Model Context Protocol](/protocols/mcp/).", "history": [ { "date": "2026-09-06", "note": "verified against webmachinelearning.github.io/webmcp (4 Sept 2026 draft) and developer.chrome.com/docs/ai/webmcp (updated 2026-08-07)" }, { "date": "2026-10-28", "note": "Re-verified record against 27 sources on 2026-10-28: 5 production pages shipping registerTool() calls, 6 client/agent vendor statements, and 3 press sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "webmcp", "implementation": "prototype", "last_verified": "2026-11-11", "name": "WebMCP", "native_status": "Draft Community Group Report, 11 November 2026.", "origin": { "date": "2025-08-13", "org": "Microsoft and Google engineers" }, "pairs_with": [ "mcp", "nlweb", "agents-json", "mcp-apps", "web-agent-protocol" ], "part_of": null, "parties": [ "agent-site" ], "phase": "draft", "prerequisites": [], "probe": { "method": "in-page script execution (not a network probe)", "on_absent": "window.modelContext is undefined, or getTools() returns an empty map: the page exposes no WebMCP tools (this cannot be checked without executing JavaScript in a real browser context — it is not curl-probable)", "parse": "presence of a non-empty tool map returned by getTools() (or the declarative equivalent synthesized from annotated form elements)", "path": "typeof window.modelContext !== 'undefined' && window.modelContext.getTools()" }, "question": "What JavaScript tools can a web page register so an in-browser AI agent can call them directly instead of scraping the DOM?", "scope": "general", "spec_url": "https://webmachinelearning.github.io/webmcp/", "step": "act", "summary_md": "**WebMCP** is a client-side browser API specification published by the W3C Web Machine Learning Community Group that enables web applications to expose structured JavaScript tools to AI agents without relying on simulated DOM input or backend servers. First published on August 13, 2025 by Microsoft and Google engineers, the specification is maintained as a Draft Community Group Report dated 11 November 2026. In a `SecureContext`, a page script registers `ModelContextTool` definitions (`name`, `description`, `execute`, and optional `inputSchema`) via the imperative `document.modelContext.registerTool()` method on `Document`. Because tools exist only in the open page, browsers and connected agents must visit a site directly to query `document.modelContext` and invoke registered callbacks. The API surface evolved from `window.agent` and `provideContext` in the August 2025 proposal to `navigator.modelContext` (February 2026) and `document.modelContext` (May–July 2026), while a proposed declarative `` API was deferred from the specification in October 2026.", "track": "w3c", "use_cases": [ "let-agents-act-on-my-site", "expose-tools-to-agents" ], "version": { "label": "Draft Community Group Report", "date": "2026-11-11" }, "watch": [ { "type": "page", "url": "https://webmachinelearning.github.io/webmcp/", "selector": "main" }, { "type": "w3c", "shortname": "webmcp", "url": "https://webmachinelearning.github.io/webmcp/" } ], "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "browser_telemetry", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-11", "v05_hatnote_html_md": "This page covers the W3C Web Machine Learning Community Group's client-side `document.modelContext` browser API specification. It is distinct from two earlier community prototypes that shared the name—`jasonjmcghee/WebMCP` (created 2025-03-04) and Alex Nahas's `MiguelsPizza/WebMCP` / MCP-B (created 2025-06-13)—both acknowledged by the Community Group for early prototyping experience; for the backend JSON-RPC protocol, see [Model Context Protocol](/protocols/mcp/). [1][2][3][4]", "v05_elevator_pitch_md": "WebMCP is a client-side browser API that lets open web pages expose callable JavaScript functions directly to in-browser AI assistants and connected agents within the user's active tab. Instead of forcing browser agents to scrape screenshots and synthesize fragile DOM clicks—or requiring developers to stand up separate backend MCP servers—websites register structured tool schemas through `document.modelContext.registerTool()` so the browser can invoke each tool's in-page `execute` callback directly. [1][5]", "v05_lead_md": "**WebMCP** is a client-side browser API specification published by the W3C Web Machine Learning Community Group that enables web applications to expose structured JavaScript tools to AI agents without relying on simulated DOM input or backend servers. [1] First published on August 13, 2025 by Microsoft and Google engineers, the specification is maintained as a Draft Community Group Report dated 11 November 2026. [1][6] In a `SecureContext`, a page script registers `ModelContextTool` definitions (`name`, `description`, `execute`, and optional `inputSchema`) via the imperative `document.modelContext.registerTool()` method on `Document`. [1][7] Because tools exist only in the open page, browsers and connected agents must visit a site directly to query `document.modelContext` and invoke registered callbacks. [5][8] The API surface evolved from `window.agent` and `provideContext` in the August 2025 proposal to `navigator.modelContext` (February 2026) and `document.modelContext` (May–July 2026), while a proposed declarative `` API was deferred from the specification in October 2026. [5][9][10][11][12][13]", "v05_identity_sentence_md": "**WebMCP** is a client-side browser API specification published by the W3C Web Machine Learning Community Group that enables web applications to expose structured JavaScript tools to AI agents without relying on simulated DOM input or backend servers. [1] First published on August 13, 2025 by Microsoft and Google engineers, the specification is maintained as a Draft Community Group Report dated 11 November 2026. [1][6]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Act](/category/act/) (`act`)" }, { "label": "Form", "value_md": "Browser API (`browser-api`)" }, { "label": "Originated by", "value_md": "Brandon Walderman, Leo Lee, Andrew Nolan, David Bokan, Khushal Sagar, and Hannah Van Opstal (August 13, 2025). [6]" }, { "label": "Governed by", "value_md": "Web Machine Learning Community Group. Editors: Walderman, Sagar, Farolino, Dallstream. Repo created 2025-08-05. [1][6]" }, { "label": "Track", "value_md": "W3C Community Group report, not a W3C Standard and not on the W3C Standards Track [1]" }, { "label": "Status", "value_md": "Draft Community Group Report, 11 November 2026. [1]" }, { "label": "Version", "value_md": "Published draft, 11 November 2026. Main explainer: first published August 13, 2025. [1][5]" }, { "label": "Entry point", "value_md": "`document.modelContext.registerTool()` on `Document`, in a secure context [1][7]" }, { "label": "Specification", "value_md": "[WebMCP](https://webmachinelearning.github.io/webmcp/) [1]" }, { "label": "Found at", "value_md": "Tools register on the open page's `document.modelContext`. Clients must visit the site. [7][8]" }, { "label": "Licence", "value_md": "W3C Community Contributor License Agreement (CLA) [1]" } ], "v05_problem_md": "Without an in-browser tool surface, browser agents must observe page state through screenshots, DOM trees, and accessibility snapshots and then act by simulating human user input, while external tool integrations require each service to maintain bespoke backend connectors with individual AI platforms. [5] WebMCP turns an open web page into a client-side counterpart to a [Model Context Protocol](/protocols/mcp/) server: the application registers JavaScript functions with natural-language descriptions and structured schemas on `document.modelContext`, and the browser mediates agent calls by invoking each tool's in-page `execute` callback within the user's live session. [1][5] Published as a W3C Community Group report rather than a W3C Standards Track specification, WebMCP standardizes only the imperative in-page JavaScript registration API and leaves both headless backend transports and declarative HTML `` tool synthesis outside the normative specification. [1][5][14]", "v05_mechanism_delta_md": "WebMCP turns an open web page into a client-side counterpart to a [Model Context Protocol](/protocols/mcp/) server: the application registers JavaScript functions with natural-language descriptions and structured schemas on `document.modelContext`, and the browser mediates agent calls by invoking each tool's in-page `execute` callback within the user's live session. [1][5]", "v05_scope_boundary_md": "Published as a W3C Community Group report rather than a W3C Standards Track specification, WebMCP standardizes only the imperative in-page JavaScript registration API and leaves both headless backend transports and declarative HTML `` tool synthesis outside the normative specification. [1][5][14]", "v05_fuzzy_additions": [ { "id": "modelcontext-interface-tool-registration-and-permission-prompts", "heading": "ModelContext interface, tool registration, and permission prompts", "body_md": "The Draft Community Group Report's `ModelContext` interface (exposed to `Window` in a `SecureContext`) is attached to `Document` via `modelContext` (`SecureContext`, `SameObject`) and provides `registerTool()`, `getTools()`, and `executeTool()` for managing callable tools. Each `ModelContextTool` dictionary requires `name`, `description`, and an `execute` callback, and optionally includes `inputSchema` and `annotations`. [1]", "bullets": [ { "label": "registerTool and unregister steps", "text_md": "Calling `registerTool()` returns a rejected promise if a tool with the same `name` is already registered, if `name` or `description` is an empty string, or if `inputSchema` is invalid. Passing an `AbortSignal` unregisters the tool when aborted by running the specification's unregister steps for that `ModelContext` and tool name. [1]" }, { "label": "provideContext on window.agent", "text_md": "In the initial August 13, 2025 proposal, `window.agent` represented an abstract AI agent connected to the page and exposed a single `provideContext` method; subsequent calls to `provideContext()` cleared all previously registered tools and context before registering the replacement set. [9]" }, { "label": "Descriptor fields and readOnlyHint", "text_md": "Within a `ModelContextTool` descriptor, `name` identifies the tool in agent calls, `description` provides natural-language guidance on its functionality, `inputSchema` supplies a JSON Schema object for expected input parameters, `execute` runs asynchronously and can return a promise, and `readOnlyHint` indicates when true that the tool only reads data without modifying state. [1]" }, { "label": "Confirmation prompts and context boundaries", "text_md": "Agents can selectively enforce mandatory user confirmation prompts before executing high-stakes tools (a July 2026 report noted an interim `requestUserInteraction()` helper, which is absent from the 11 November 2026 report), and the user agent may enqueue observation steps on any top-level browsing context. By default, the policy-controlled `tools` permission (default allowlist `'self'`) enables WebMCP in top-level windows and same-origin iframes while blocking cross-origin iframes unless delegated via Permissions Policy `allow=\"tools\"`. [1][5][8][15]" } ] }, { "id": "move-from-navigator-modelcontext-to-document-modelcontext-and-chrome-origin-trial", "heading": "Move from navigator.modelContext to document.modelContext and Chrome Origin Trial", "body_md": "After introducing `window.agent` in the August 13, 2025 proposal and initializing `modelContext` on `Navigator` on 19 February 2026, the specification moved the `modelContext` getter to `Document` on 27 May 2026, and Chromium removed `navigator.modelContext` in favor of `document.modelContext` on 9 July 2026. [9][10][11][12]", "bullets": [ { "label": "Document and iframe modelContext", "text_md": "Moving the API from `navigator` to `document` in the July 2026 draft reflects that registered tools belong to a specific page and provides tab-level lifecycle management that standalone MCP servers lack. Because Chrome 150 deprecated `navigator.modelContext` while the origin trial still shipped it, migration code checks `document.modelContext ?? navigator.modelContext`, and parent documents access same-origin child frames through `iframe.contentDocument.modelContext`. [5][11][15]" }, { "label": "Chrome 149 through 156 origin trial", "text_md": "Chromium's May 2026 blink-dev Intent to Experiment and Chrome for Developers announcements opened the public WebMCP desktop origin trial across Chrome milestones 149 through 156, with desktop shipping estimated at milestone 157. [15][16][17][18]" }, { "label": "Declarative HTML form tools", "text_md": "Although the 8 October 2026 specification commit removed the declarative HTML `` API for now, Chrome's developer documentation and the `webmcp-tools` declarative polyfill support annotating standard HTML forms with `` and `toolautosubmit` to synthesize WebMCP tools from form markup. [5][8][13][19]" }, { "label": "External MCP clients", "text_md": "In Chrome, browser extensions can query and execute in-page WebMCP tools via content scripts, while the earlier MCP-B prototype extended MCP with Chromium runtime-messaging transports and a local native server to bridge in-tab tools to external desktop MCP clients such as Claude Desktop and Cursor. [2][6][8]" } ] } ], "v05_diagram": { "title": "WebMCP in-browser tool flow", "heading": "WebMCP in-browser tool flow", "mermaid": "sequenceDiagram\n participant Page as Running Page
index.html\n participant Agent as Browser-integrated
AI agent\n participant AI as AI agent platform\n participant Service as Third-party origin
example.com\n\n Agent->>AI: 1. Send user prompt\n AI-->>Agent: 2. Inspect or act on
the current page\n Agent->>Page: 3. Invoke page-provided
WebMCP tool\n Page->>Service: 4. Make API call as needed\n Service-->>Page: API response\n Page->>Page: 5. Update application state
and visible UI\n Page-->>Agent: 6. WebMCP tool result\n Agent-->>AI: Tool result\n Note over Page,Agent: Site-owned code performs the
action and keeps its UI in sync", "caption_md": "In-browser tool flow across the running page (`index.html`), the browser-integrated AI agent, the AI agent platform, and a third-party origin. Site-owned code performs the action and keeps its visible UI in sync. [5]" }, "v05_wire_artifact": { "title": "ModelContext", "heading": "ModelContext", "lang": "webidl", "code": "partial interface Document {\n [SecureContext, SameObject] readonly attribute ModelContext modelContext;\n};\n\n[Exposed=Window, SecureContext]\ninterface ModelContext : EventTarget {\n Promise registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});\n Promise> getTools(optional ModelContextGetToolOptions options = {});\n Promise executeTool(RegisteredTool tool, optional object inputObject, optional ModelContextExecuteToolOptions options = {});\n\n attribute EventHandler ontoolchange;\n attribute EventHandler ontoolactivated;\n attribute EventHandler ontoolcancel;\n};", "caption_md": "Normative Web IDL: `Document` exposes `modelContext`, and `ModelContext` provides `registerTool`, `getTools`, and `executeTool`. [1]" }, "v05_counterparts": { "classic_analogues": [ { "name": "Web IDL", "spec_or_rfc": "Web IDL Standard", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "WebMCP exposes `modelContext` on `Document` in a secure context; clients must visit the page to discover tools. [1][8]" } ], "agentic_peers": [ { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "WebMCP registers in-page tools on `document.modelContext`; MCP uses JSON-RPC 2.0 over stdio and Streamable HTTP. [7][20]" }, { "target_id": "nlweb", "target_name": "NLWeb", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "WebMCP needs a page visit; NLWeb uses `POST /ask` and `POST /await`, schema.org values, and MCP tool `ask`. [7][8][21]" }, { "target_id": "agents-json", "target_name": "agents.json", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "WebMCP registers tools in page script; agents.json is an OpenAPI-derived contract at `/.well-known/agents.json` with `flows`. [7][22][23]" }, { "target_id": "mcp-apps", "target_name": "MCP Apps", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "WebMCP registers in-page tools; MCP Apps returns `ui://` HTML (`text/html;profile=mcp-app`) via `resources/read`. [7][24]" }, { "target_id": "web-agent-protocol", "target_name": "Web Agent Protocol (WAP)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "WebMCP exposes page-registered tools; WAP records browser actions into MCP servers, including exact replay and smart-replay. [7][25]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (11 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Pages calling the API", "col4_header": "API member called & behavior", "note_md": null, "rows": [ { "actor": "Agio Digital", "role": "In-page caller", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Page script checks `r.modelContext.registerTool`, then calls it.", "source_md": "[Agio Digital (fetched 2026-10-30)](https://www.agiodigital.com/) [26]" }, { "actor": "BRITECITY", "role": "In-page caller", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Reads `navigator.modelContext` or `document.modelContext`, then `mc.registerTool`.", "source_md": "[BRITECITY IT health check (fetched 2026-11-04)](https://britecity.com/it-health-check) [27]" }, { "actor": "ScoreTail", "role": "In-page caller", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Calls `registerTools`, which calls `registerTool` on `document.modelContext`.", "source_md": "[ScoreTail score page (fetched 2026-10-30)](https://scoretail.com/en/sheet-music/canon-in-d-pachelbel-johann/view) [28]" }, { "actor": "Chrome WebMCP demos", "role": "Reference page demos", "status": "Experimental", "status_display": "Experimental · checked 2026-11-06", "col4_md": "Travel imperative demo and Le Petit Bistro declarative demo.", "source_md": "[webmcp-tools](https://github.com/GoogleChromeLabs/webmcp-tools) [19]" } ] }, "side_b": { "visible": true, "heading": "Engines, agents and standards positions", "col4_header": "Version, channel & standards position", "note_md": null, "rows": [ { "actor": "Google Chrome", "role": "Browser engine", "status": "Origin trial", "status_display": "Origin trial · as of 2026-11-04", "col4_md": "Origin trial in Chrome 149 (`about:flags#enable-webmcp-testing`); ChromeStatus feature 5117755740913664 lists status `Proposed` (`origintrial`: `false`; desktop trial stage 149–156).", "source_md": "[WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] · [ChromeStatus feature 5117755740913664 (fetched 2026-11-04)](https://chromestatus.com/api/v0/features/5117755740913664) [29] · [Chrome for Developers, WebMCP (updated 2026-10-07)](https://developer.chrome.com/docs/ai/webmcp) [8] · [Chrome for Developers, Join the WebMCP origin trial](https://developer.chrome.com/blog/ai-webmcp-origin-trial) [16][17]" }, { "actor": "Microsoft Edge", "role": "Browser engine", "status": "Origin trial", "status_display": "Origin trial · as of 2026-10-30", "col4_md": "Origin trial in Edge 150; expires March 30, 2027.", "source_md": "[WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] · [Microsoft, WebMCP origin trial (fetched 2026-10-30)](https://developer.microsoft.com/en-us/microsoft-edge/origin-trials/trials/0b76fe60-b266-458e-a285-04e375c0c31a) [30] · [Patrick Brosset, New in Edge for developers (2026-09-21)](https://blogs.windows.com/msedgedev/2026/09/21/new-in-edge-for-developers-create-better-components-and-make-your-site-agent-ready/) [31]" }, { "actor": "Brave (Leo AI)", "role": "AI agent", "status": "Experimental", "status_display": "Experimental · as of 2026-10-07", "col4_md": "Experimental in Leo AI chat; flag `brave://flags/#enable-webmcp-testing`.", "source_md": "[WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] · [Brave issue #55232 (API, fetched 2026-11-04)](https://github.com/brave/brave-browser/issues/55232) [32]" }, { "actor": "OpenAI ChatGPT Desktop", "role": "AI agent", "status": "Supported", "status_display": "Supported · checked 2026-11-04", "col4_md": "Status page: supported in ChatGPT Desktop; no version named.", "source_md": "[WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18]" }, { "actor": "Meta AI (Ray-Ban Display)", "role": "AI agent", "status": "Coming soon", "status_display": "Coming soon · checked 2026-11-04", "col4_md": "Coming soon on Ray-Ban Display via `document.modelContext.registerTool()`.", "source_md": "[WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18]" }, { "actor": "Chrome WebMCP developer utilities", "role": "Inspector, evals, and polyfill", "status": "Experimental", "status_display": "Experimental · checked 2026-11-06", "col4_md": "Inspector, Evals CLI, skills, and a declarative polyfill.", "source_md": "[webmcp-tools utilities](https://github.com/GoogleChromeLabs/webmcp-tools) [19]" }, { "actor": "Chrome WebMCP example extension", "role": "Reference agent extension", "status": "Experimental", "status_display": "Experimental · checked 2026-11-06", "col4_md": "Reads `document.modelContext.getTools()` and `ontoolchange`.", "source_md": "[webmcp-extension](https://github.com/GoogleChromeLabs/webmcp-extension/) [33]" } ] }, "additional_tables": null, "censuses": [ { "label": "Chrome Platform Status feature record", "as_of": "2026-11-02", "value_md": "Tracked on Chrome Platform Status as feature 5117755740913664 (`document-modelcontext`; search tag `WebMCP`, created `2025-07-08`, updated `2026-11-02`). [29]" }, { "label": "Chromium desktop origin trial milestone window (ChromeStatus feature 5117755740913664 origin-trial stage)", "as_of": "2026-11-02", "value_md": "Chrome 149–156 (`desktop_first`: 149, `desktop_last`: 156) [29]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "agent-permissions-json", "target_name": "agent-permissions.json", "relation_label": "Complements", "delta": "agent-permissions.json states which in-page actions are allowed, using resource_rules verbs and action_guidelines, while WebMCP is the browser API for agent actions and does not define that permissions file.", "item_md": "**[agent-permissions.json](/protocols/agent-permissions-json/)** (Complements) — agent-permissions.json states which in-page actions are allowed, using resource_rules verbs and action_guidelines, while WebMCP is the browser API for agent actions and does not define that permissions file." }, { "item_md": "**[Act protocols](/category/act/)** — Category index for `act` standards." } ], "v05_compiled_md": "---\nid: webmcp\ntitle: \"WebMCP\"\ntier: flagship\nlifecycle_status: active\ncategory: act\nform: browser-api\nwire_archetype: browser_telemetry\nspec_url: https://webmachinelearning.github.io/webmcp/\nlast_checked: 2026-11-11\n---\n\n# WebMCP\n\n**Category:** [Act](/category/act/) (`act`) · **Form:** Browser API (`browser-api`) · **Last checked:** 2026-11-11\n\n> *This page covers the W3C Web Machine Learning Community Group's client-side `document.modelContext` browser API specification. It is distinct from two earlier community prototypes that shared the name—`jasonjmcghee/WebMCP` (created 2025-03-04) and Alex Nahas's `MiguelsPizza/WebMCP` / MCP-B (created 2025-06-13)—both acknowledged by the Community Group for early prototyping experience; for the backend JSON-RPC protocol, see [Model Context Protocol](/protocols/mcp/). [1][2][3][4]*\n\n> **In brief:** WebMCP is a client-side browser API that lets open web pages expose callable JavaScript functions directly to in-browser AI assistants and connected agents within the user's active tab. Instead of forcing browser agents to scrape screenshots and synthesize fragile DOM clicks—or requiring developers to stand up separate backend MCP servers—websites register structured tool schemas through `document.modelContext.registerTool()` so the browser can invoke each tool's in-page `execute` callback directly. [1][5]\n\n**WebMCP** is a client-side browser API specification published by the W3C Web Machine Learning Community Group that enables web applications to expose structured JavaScript tools to AI agents without relying on simulated DOM input or backend servers. [1] First published on August 13, 2025 by Microsoft and Google engineers, the specification is maintained as a Draft Community Group Report dated 11 November 2026. [1][6] In a `SecureContext`, a page script registers `ModelContextTool` definitions (`name`, `description`, `execute`, and optional `inputSchema`) via the imperative `document.modelContext.registerTool()` method on `Document`. [1][7] Because tools exist only in the open page, browsers and connected agents must visit a site directly to query `document.modelContext` and invoke registered callbacks. [5][8] The API surface evolved from `window.agent` and `provideContext` in the August 2025 proposal to `navigator.modelContext` (February 2026) and `document.modelContext` (May–July 2026), while a proposed declarative `` API was deferred from the specification in October 2026. [5][9][10][11][12][13]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Act](/category/act/) (`act`) |\n| **Form** | Browser API (`browser-api`) |\n| **Originated by** | Brandon Walderman, Leo Lee, Andrew Nolan, David Bokan, Khushal Sagar, and Hannah Van Opstal (August 13, 2025). [6] |\n| **Governed by** | Web Machine Learning Community Group. Editors: Walderman, Sagar, Farolino, Dallstream. Repo created 2025-08-05. [1][6] |\n| **Track** | W3C Community Group report, not a W3C Standard and not on the W3C Standards Track [1] |\n| **Status** | Draft Community Group Report, 11 November 2026. [1] |\n| **Version** | Published draft, 11 November 2026. Main explainer: first published August 13, 2025. [1][5] |\n| **Entry point** | `document.modelContext.registerTool()` on `Document`, in a secure context [1][7] |\n| **Specification** | [WebMCP](https://webmachinelearning.github.io/webmcp/) [1] |\n| **Found at** | Tools register on the open page's `document.modelContext`. Clients must visit the site. [7][8] |\n| **Licence** | W3C Community Contributor License Agreement (CLA) [1] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [ModelContext interface, tool registration, and permission prompts](#modelcontext-interface-tool-registration-and-permission-prompts)\n3. [Move from navigator.modelContext to document.modelContext and Chrome Origin Trial](#move-from-navigator-modelcontext-to-document-modelcontext-and-chrome-origin-trial)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nWithout an in-browser tool surface, browser agents must observe page state through screenshots, DOM trees, and accessibility snapshots and then act by simulating human user input, while external tool integrations require each service to maintain bespoke backend connectors with individual AI platforms. [5] WebMCP turns an open web page into a client-side counterpart to a [Model Context Protocol](/protocols/mcp/) server: the application registers JavaScript functions with natural-language descriptions and structured schemas on `document.modelContext`, and the browser mediates agent calls by invoking each tool's in-page `execute` callback within the user's live session. [1][5] Published as a W3C Community Group report rather than a W3C Standards Track specification, WebMCP standardizes only the imperative in-page JavaScript registration API and leaves both headless backend transports and declarative HTML `` tool synthesis outside the normative specification. [1][5][14]\n\n### WebMCP in-browser tool flow\n\n```mermaid\nsequenceDiagram\n participant Page as Running Page
index.html\n participant Agent as Browser-integrated
AI agent\n participant AI as AI agent platform\n participant Service as Third-party origin
example.com\n\n Agent->>AI: 1. Send user prompt\n AI-->>Agent: 2. Inspect or act on
the current page\n Agent->>Page: 3. Invoke page-provided
WebMCP tool\n Page->>Service: 4. Make API call as needed\n Service-->>Page: API response\n Page->>Page: 5. Update application state
and visible UI\n Page-->>Agent: 6. WebMCP tool result\n Agent-->>AI: Tool result\n Note over Page,Agent: Site-owned code performs the
action and keeps its UI in sync\n```\n\n*In-browser tool flow across the running page (`index.html`), the browser-integrated AI agent, the AI agent platform, and a third-party origin. Site-owned code performs the action and keeps its visible UI in sync. [5]*\n\n### ModelContext\n\n```webidl\npartial interface Document {\n [SecureContext, SameObject] readonly attribute ModelContext modelContext;\n};\n\n[Exposed=Window, SecureContext]\ninterface ModelContext : EventTarget {\n Promise registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});\n Promise> getTools(optional ModelContextGetToolOptions options = {});\n Promise executeTool(RegisteredTool tool, optional object inputObject, optional ModelContextExecuteToolOptions options = {});\n\n attribute EventHandler ontoolchange;\n attribute EventHandler ontoolactivated;\n attribute EventHandler ontoolcancel;\n};\n```\n\n*Normative Web IDL: `Document` exposes `modelContext`, and `ModelContext` provides `registerTool`, `getTools`, and `executeTool`. [1]*\n\n---\n\n## ModelContext interface, tool registration, and permission prompts\n\nThe Draft Community Group Report's `ModelContext` interface (exposed to `Window` in a `SecureContext`) is attached to `Document` via `modelContext` (`SecureContext`, `SameObject`) and provides `registerTool()`, `getTools()`, and `executeTool()` for managing callable tools. Each `ModelContextTool` dictionary requires `name`, `description`, and an `execute` callback, and optionally includes `inputSchema` and `annotations`. [1]\n\n- **registerTool and unregister steps:** Calling `registerTool()` returns a rejected promise if a tool with the same `name` is already registered, if `name` or `description` is an empty string, or if `inputSchema` is invalid. Passing an `AbortSignal` unregisters the tool when aborted by running the specification's unregister steps for that `ModelContext` and tool name. [1]\n- **provideContext on window.agent:** In the initial August 13, 2025 proposal, `window.agent` represented an abstract AI agent connected to the page and exposed a single `provideContext` method; subsequent calls to `provideContext()` cleared all previously registered tools and context before registering the replacement set. [9]\n- **Descriptor fields and readOnlyHint:** Within a `ModelContextTool` descriptor, `name` identifies the tool in agent calls, `description` provides natural-language guidance on its functionality, `inputSchema` supplies a JSON Schema object for expected input parameters, `execute` runs asynchronously and can return a promise, and `readOnlyHint` indicates when true that the tool only reads data without modifying state. [1]\n- **Confirmation prompts and context boundaries:** Agents can selectively enforce mandatory user confirmation prompts before executing high-stakes tools (a July 2026 report noted an interim `requestUserInteraction()` helper, which is absent from the 11 November 2026 report), and the user agent may enqueue observation steps on any top-level browsing context. By default, the policy-controlled `tools` permission (default allowlist `'self'`) enables WebMCP in top-level windows and same-origin iframes while blocking cross-origin iframes unless delegated via Permissions Policy `allow=\"tools\"`. [1][5][8][15]\n\n---\n\n## Move from navigator.modelContext to document.modelContext and Chrome Origin Trial\n\nAfter introducing `window.agent` in the August 13, 2025 proposal and initializing `modelContext` on `Navigator` on 19 February 2026, the specification moved the `modelContext` getter to `Document` on 27 May 2026, and Chromium removed `navigator.modelContext` in favor of `document.modelContext` on 9 July 2026. [9][10][11][12]\n\n- **Document and iframe modelContext:** Moving the API from `navigator` to `document` in the July 2026 draft reflects that registered tools belong to a specific page and provides tab-level lifecycle management that standalone MCP servers lack. Because Chrome 150 deprecated `navigator.modelContext` while the origin trial still shipped it, migration code checks `document.modelContext ?? navigator.modelContext`, and parent documents access same-origin child frames through `iframe.contentDocument.modelContext`. [5][11][15]\n- **Chrome 149 through 156 origin trial:** Chromium's May 2026 blink-dev Intent to Experiment and Chrome for Developers announcements opened the public WebMCP desktop origin trial across Chrome milestones 149 through 156, with desktop shipping estimated at milestone 157. [15][16][17][18]\n- **Declarative HTML form tools:** Although the 8 October 2026 specification commit removed the declarative HTML `` API for now, Chrome's developer documentation and the `webmcp-tools` declarative polyfill support annotating standard HTML forms with `` and `toolautosubmit` to synthesize WebMCP tools from form markup. [5][8][13][19]\n- **External MCP clients:** In Chrome, browser extensions can query and execute in-page WebMCP tools via content scripts, while the earlier MCP-B prototype extended MCP with Chromium runtime-messaging transports and a local native server to bridge in-tab tools to external desktop MCP clients such as Claude Desktop and Cursor. [2][6][8]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Web IDL** | `Web IDL Standard` | Analogous to classic standard | WebMCP exposes `modelContext` on `Document` in a secure context; clients must visit the page to discover tools. [1][8] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Model Context Protocol](/protocols/mcp/)** | Peer alternative | WebMCP registers in-page tools on `document.modelContext`; MCP uses JSON-RPC 2.0 over stdio and Streamable HTTP. [7][20] |\n| **[NLWeb](/protocols/nlweb/)** | Peer alternative | WebMCP needs a page visit; NLWeb uses `POST /ask` and `POST /await`, schema.org values, and MCP tool `ask`. [7][8][21] |\n| **[agents.json](/protocols/agents-json/)** | Peer alternative | WebMCP registers tools in page script; agents.json is an OpenAPI-derived contract at `/.well-known/agents.json` with `flows`. [7][22][23] |\n| **[MCP Apps](/protocols/mcp-apps/)** | Peer alternative | WebMCP registers in-page tools; MCP Apps returns `ui://` HTML (`text/html;profile=mcp-app`) via `resources/read`. [7][24] |\n| **[Web Agent Protocol (WAP)](/protocols/web-agent-protocol/)** | Peer alternative | WebMCP exposes page-registered tools; WAP records browser actions into MCP servers, including exact replay and smart-replay. [7][25] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (11 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Pages calling the API\n\n| Actor | Role | Status | API member called & behavior | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Agio Digital** | In-page caller | Live (HTTP 200) · checked 2026-10-30 | Page script checks `r.modelContext.registerTool`, then calls it. | [Agio Digital (fetched 2026-10-30)](https://www.agiodigital.com/) [26] |\n| **BRITECITY** | In-page caller | Live (HTTP 200) · checked 2026-11-04 | Reads `navigator.modelContext` or `document.modelContext`, then `mc.registerTool`. | [BRITECITY IT health check (fetched 2026-11-04)](https://britecity.com/it-health-check) [27] |\n| **ScoreTail** | In-page caller | Live (HTTP 200) · checked 2026-10-30 | Calls `registerTools`, which calls `registerTool` on `document.modelContext`. | [ScoreTail score page (fetched 2026-10-30)](https://scoretail.com/en/sheet-music/canon-in-d-pachelbel-johann/view) [28] |\n| **Chrome WebMCP demos** | Reference page demos | Experimental · checked 2026-11-06 | Travel imperative demo and Le Petit Bistro declarative demo. | [webmcp-tools](https://github.com/GoogleChromeLabs/webmcp-tools) [19] |\n\n### Engines, agents and standards positions\n\n| Actor | Role | Status | Version, channel & standards position | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Google Chrome** | Browser engine | Origin trial · as of 2026-11-04 | Origin trial in Chrome 149 (`about:flags#enable-webmcp-testing`); ChromeStatus feature 5117755740913664 lists status `Proposed` (`origintrial`: `false`; desktop trial stage 149–156). | [WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] · [ChromeStatus feature 5117755740913664 (fetched 2026-11-04)](https://chromestatus.com/api/v0/features/5117755740913664) [29] · [Chrome for Developers, WebMCP (updated 2026-10-07)](https://developer.chrome.com/docs/ai/webmcp) [8] · [Chrome for Developers, Join the WebMCP origin trial](https://developer.chrome.com/blog/ai-webmcp-origin-trial) [16][17] |\n| **Microsoft Edge** | Browser engine | Origin trial · as of 2026-10-30 | Origin trial in Edge 150; expires March 30, 2027. | [WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] · [Microsoft, WebMCP origin trial (fetched 2026-10-30)](https://developer.microsoft.com/en-us/microsoft-edge/origin-trials/trials/0b76fe60-b266-458e-a285-04e375c0c31a) [30] · [Patrick Brosset, New in Edge for developers (2026-09-21)](https://blogs.windows.com/msedgedev/2026/09/21/new-in-edge-for-developers-create-better-components-and-make-your-site-agent-ready/) [31] |\n| **Brave (Leo AI)** | AI agent | Experimental · as of 2026-10-07 | Experimental in Leo AI chat; flag `brave://flags/#enable-webmcp-testing`. | [WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] · [Brave issue #55232 (API, fetched 2026-11-04)](https://github.com/brave/brave-browser/issues/55232) [32] |\n| **OpenAI ChatGPT Desktop** | AI agent | Supported · checked 2026-11-04 | Status page: supported in ChatGPT Desktop; no version named. | [WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] |\n| **Meta AI (Ray-Ban Display)** | AI agent | Coming soon · checked 2026-11-04 | Coming soon on Ray-Ban Display via `document.modelContext.registerTool()`. | [WebMCP implementation status (raw, fetched 2026-11-04)](https://raw.githubusercontent.com/webmachinelearning/webmcp/main/implementation-status.md) [18] |\n| **Chrome WebMCP developer utilities** | Inspector, evals, and polyfill | Experimental · checked 2026-11-06 | Inspector, Evals CLI, skills, and a declarative polyfill. | [webmcp-tools utilities](https://github.com/GoogleChromeLabs/webmcp-tools) [19] |\n| **Chrome WebMCP example extension** | Reference agent extension | Experimental · checked 2026-11-06 | Reads `document.modelContext.getTools()` and `ontoolchange`. | [webmcp-extension](https://github.com/GoogleChromeLabs/webmcp-extension/) [33] |\n\n### Ecosystem censuses\n\n- **Chrome Platform Status feature record** (*as of 2026-11-02*): Tracked on Chrome Platform Status as feature 5117755740913664 (`document-modelcontext`; search tag `WebMCP`, created `2025-07-08`, updated `2026-11-02`). [29]\n- **Chromium desktop origin trial milestone window (ChromeStatus feature 5117755740913664 origin-trial stage)** (*as of 2026-11-02*): Chrome 149–156 (`desktop_first`: 149, `desktop_last`: 156) [29]\n\n---\n\n## See also\n\n- **[agent-permissions.json](/protocols/agent-permissions-json/)** *(Complements)* — agent-permissions.json states which in-page actions are allowed, using resource_rules verbs and action_guidelines, while WebMCP is the browser API for agent actions and does not define that permissions file.\n- **Category:** [Act protocols](/category/act/)\n\n---\n\n## References\n\n1. Web Machine Learning Community Group (editors Brandon Walderman, Khushal Sagar, Dominic Farolino, and Samuel Dallstream), *WebMCP* (Draft Community Group Report, 11 November 2026) — \n2. Alexander Nahas (MiguelsPizza), *WebMCP* (repository created 2025-06-13) — \n3. Jason McGhee, *WebMCP* (repository created 2025-03-04) — \n4. W3C Web Machine Learning Community Group, *WebML WG teleconference minutes* (14 August 2025) — \n5. webmachinelearning/webmcp (GitHub), *WebMCP* (checked 2026-11-04) — \n6. Brandon Walderman, Leo Lee, Andrew Nolan, David Bokan, Khushal Sagar, and Hannah Van Opstal, *WebMCP explainer* (first published August 13, 2025 (commit 7edc0e18)) — \n7. Web Machine Learning Community Group, *WebMCP explainer* (first published August 13, 2025) — \n8. Alexandra Klepper, François Beaufort, and Kasper Kulikowski (Chrome for Developers), *WebMCP* (published 18 May 2026; last updated 7 October 2026) — \n9. Brandon Walderman, Andrew Nolan, David Bokan, Khushal Sagar, and Hannah Van Opstal, *WebMCP API proposal* (August 13, 2025) — \n10. Dominic Farolino, *Initialize a Navigator's modelContext member* (19 February 2026) — \n11. Dominic Farolino, *Move the modelContext getter to Document (#184)* (27 May 2026) — \n12. Dominic Farolino (Chromium), *WebMCP: Remove navigator.modelContext* (9 July 2026) — \n13. François Beaufort, *Remove declarative API from the spec for now (#338)* (8 October 2026) — \n14. PPC Land, *Chrome 149 origin trial puts WebMCP in developers' hands at last* (checked 2026-10-30) — \n15. Spronta, *The State of WebMCP: July 2026* (July 2026) — \n16. blink-dev, *Intent to Experiment: WebMCP* (15 May 2026) — \n17. Alexandra Klepper (Chrome for Developers), *Join the WebMCP origin trial* (published 9 June 2026) — \n18. Web Machine Learning Community Group, *Browser and Agent Implementation Status* (checked 2026-11-04) — \n19. Google Chrome Labs, *webmcp-tools* (checked 2026-11-06) — \n20. Model Context Protocol, *Specification* (2026-07-28) — \n21. NLWeb, *NLWeb specification* (v0.55) — \n22. Wildcard AI, *agents.json* (checked 2026-10-30) — \n23. Wildcard AI, *agents.json schema* (checked 2026-10-30) — \n24. MCP Apps contributors, *MCP Apps specification* (2026-01-26) — \n25. OTA Tech AI, *Web Agent Protocol (WAP)* (checked 2026-10-31) — \n26. Agio Digital, *Licensed Crypto Fund Administrator, Bahamas* (checked 2026-10-30) — \n27. BRITECITY, *Free IT Health Check* (checked 2026-10-30) — \n28. ScoreTail, *Canon in D (Pachelbel) score page* (checked 2026-10-30) — \n29. Chrome Platform Status, *ChromeStatus feature 5117755740913664* (checked 2026-11-04) — \n30. Microsoft, *WebMCP origin trial* (trial expiration 30 March 2027) — \n31. Patrick Brosset (Microsoft Edge), *New in Edge for developers: create better components and make your site agent-ready* (published 21 September 2026) — \n32. Jay Harris (Brave), *[AI Chat]: Add support for the WebMCP protocol to Leo* (opened 5 May 2026) — \n33. Google Chrome Labs, *webmcp-extension* (checked 2026-11-06) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "NLWeb", "adoption": { "level": "observed", "by": "Agent Community, World Monitor, Cloudflare (AI Search NLWeb template), and Wix", "probe_run": null }, "aliases": [ "Natural Language Web", "NLWeb" ], "analog": "HTML for machine-readable, natural-language site content", "collisions": [], "discovery": { "mechanism": "No standard discovery path; POST/GET /ask or /mcp (or /_api/nlweb/mcp on Wix)", "path": "No standard discovery path. The specification's HTTP binding is \"POST /ask — Submit a natural language query. POST /await — Check on or cancel a promised result.\"; it is \"NLWeb is designed to be transport-protocol agnostic.\" and \"NLWeb operations can be exposed as Tools within the Model Context Protocol (MCP) or other JSON-RPC-based agentic standards.\" Paths vary by deployment: the reference server and Cloudflare's Worker use /ask and /mcp; Wix uses \"Use the following MCP URL to connect to your favorite AI agent (e.g. Claude, ChatGPT or custom agents): https://www.[your-domain.com]/_api/nlweb/mcp.\"" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://raw.githubusercontent.com/nlweb-ai/website/main/NLWEBSPEC.md", "claim": "nlweb-ai/website (GitHub), *NLWeb Specification v0.55 (nlweb-ai/website NLWEBSPEC.md)*, checked 2026-10-30", "date": null, "quote": "NLWeb operations can be exposed as Tools within the Model Context Protocol (MCP) or other JSON-RPC-based agentic standards. / NLWeb Specification v0.55 / It abstracts the complexity of agentic interactions—such as tool use, long-running tasks, and rich structured data—into a unified protocol. / NLWeb supports streaming responses via Server-Sent Events (SSE) over HTTP transport. / Streaming is requested by setting prefer.streaming to true. / Clients SHOULD use this event to initialize their response handling. / Clients MUST process this event to capture session state for subsequent requests. / 202 Accepted: Promise response for long-running tasks. / POST /await — Check on or cancel a promised result. / Streaming promoted to its own section (Section 6) with formal SSE event type definitions (start, result, error, complete). / (SSE) Request: http POST /ask HTTP/1.1 Host: api.recipes.example.com Content-Type: application/json Accept: text/event-stream { \"query\": / \"method\": \"POST\", \"endpoint\": \"https://api.recipes.example.com/cart/add\", \"params\": { \"items\": [\"4 large eggs\", \"1/2 cup diced bell / The primary API/tool/skill provided by an NLWeb agent is ask, using which a caller can ask the agent for some information or to perform a task. Await is a helper API that enables asynchronous answers, which is useful for long-running requests. / Await is a helper API that enables asynchronous answers, which is useful for long-running requests. / The primary API/tool/skill provided by an NLWeb agent is ask, using which a caller can ask the agent for some information or to perform a task. / The request object consists of four sections: query, context, prefer, and meta. / Results may arrive out of order (i.e., index values are not guaranteed to be sequential). / NLWeb is designed to be transport-protocol agnostic. / Authentication and authorization are handled at the transport layer and are outside the scope of this specification. / Rate limiting is a transport-layer concern and is outside the scope of this specification.", "ref": 1 }, { "label": "[2]", "url": "https://news.microsoft.com/source/features/company-news/introducing-nlweb-bringing-conversational-interfaces-directly-to-the-web/", "claim": "Microsoft, *Microsoft News: Introducing NLWeb*, checked 2026-10-30", "date": null, "quote": "The project was conceived and developed by R.V. Guha, creator of RSS, RDF, and Schema.org, who recently joined Microsoft as CVP and Technical Fellow / NLWeb was conceived and developed by R.V. Guha, who recently joined Microsoft as CVP and Technical Fellow. Guha is the creator of widely used web standards such as RSS, RDF and Schema.org.", "ref": 2 }, { "label": "[3]", "url": "https://github.com/nlweb-ai/NLWeb/wiki/We've-moved-to-our-new-home!", "claim": "nlweb ai, *NLWeb Wiki: Repository Migration Notice*, checked 2026-10-30", "date": null, "quote": "We've migrated the repository from microsoft/NLWeb to our new independent GitHub organization at NLWeb-ai. / https://github.com/NLWeb-ai/NLWeb.git What's next This is just the beginning! Getting our GitHub org set up", "ref": 3 }, { "label": "[4]", "url": "https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/LICENSE", "claim": "nlweb-ai/NLWeb (GitHub), *nlweb-ai/NLWeb MIT License*, checked 2026-10-30", "date": null, "quote": "MIT License Copyright (c) Microsoft Corporation.", "ref": 4 }, { "label": "[5]", "url": "https://www.w3.org/community/nlweb/", "claim": "W3C, *W3C NLWeb Community Group*, checked 2026-10-30", "date": null, "quote": "This group was originally proposed on 2025-10-16 by Ramanathan Guha. / W3C's hosting of this group does not imply endorsement of the activities. / NLWeb Community Group", "ref": 5 }, { "label": "[6]", "url": "https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/README.md", "claim": "nlweb-ai/NLWeb (GitHub), *nlweb-ai/NLWeb README.md*, checked 2026-10-30", "date": null, "quote": "NLWeb provides practical implementation code-not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach. / Contributing See Contribution Guidance for more details. Contributor Wall of Fame !nlweb contributors(https://github.com/microsoft/nlweb/graphs/contributors) Trademarks / A simple protocol to interact with a site using natural language. It returns responses in JSON using Schema.org. See the NLWeb spec for details. / implementations, and community participation are all essential. NLWeb brings together protocols, Schema.org formats, and / NLWeb uses the MIT License. / NLWeb simplifies the process of building conversational interfaces for websites. / straightforward implementation that uses existing markup on sites with structured lists (e.g., products, recipes, attractions, reviews). / Schema.org and related semi-structured formats like RSS - used by over 100 million websites - have become not just de facto syndication mechanisms, but also a semantic layer for the web.", "ref": 6 }, { "label": "[7]", "url": "https://blogs.microsoft.com/blog/2025/05/19/microsoft-build-2025-the-age-of-ai-agents-and-building-the-open-agentic-web/", "claim": "Microsoft, *Microsoft Build 2025: Building the Open Agentic Web*, checked 2026-10-30", "date": null, "quote": "May 2025 10:35:23 GMT link:; rel=\"https://api.w.org/\" link:; rel=\"alternate\"; title=\"JSON\"; type=\"application/json\" link:; rel=shortlink x-powered-by: WP", "ref": 7 }, { "label": "[8]", "url": "https://github.com/nlweb-ai/NLWeb", "claim": "nlweb-ai/NLWeb (GitHub), *GitHub Repository Metadata: nlweb-ai/NLWeb*, checked 2026-10-30", "date": null, "quote": "\"releases_url\": \"https://api.github.com/repos/nlweb-ai/NLWeb/releases{/id}\", \"deployments_url\": \"https://api.github.com/repos/nlweb-ai/NLWeb/deployments\", \"created_at\": \"2025-04-28T20:44:02Z\", \"updated_at\": / \"full_name\": \"nlweb-ai/NLWeb\" / \"forks_count\": 694, \"mirror_url\": null, \"archived\": false, \"disabled\": false, \"open_issues_count\": 65, \"license\": { \"key\": \"mit\",", "ref": 8 }, { "label": "[9]", "url": "https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/docs/nlweb-rest-api.md", "claim": "nlweb-ai/NLWeb (GitHub), *NLWeb REST API Documentation (nlweb-rest-api.md)*, checked 2026-10-30", "date": null, "quote": "expires: Fri, 30 Oct 2026 22:04:36 GMT source-age: 0 NLWeb Rest API At this / At this point, NLWeb supports 2 APIs at the endpoints /ask and /mcp. The arguments are the same for both, as is most of the functionality. The /mcp endpoint returns the answers in format that MCP clients can use. The /mcp endpoint also supports the core MCP methods (list_tools, list_prompts, call_tool and get_prompt). / - An array (soon to be moved to a richer structure, starting with schema.org's / # NLWeb Rest API At this point, NLWeb supports 2 APIs at the endpoints / API At this point, NLWeb supports 2 APIs at the endpoints /ask and /mcp.", "ref": 9 }, { "label": "[10]", "url": "https://www.safeguard.sh/resources/blog/nlweb-explained-natural-language-endpoints-for-websites-mcp-and-how-to-secure-them", "claim": "Safeguard, *Safeguard: NLWeb Explained and Security Analysis*, checked 2026-10-30", "date": null, "quote": "the W3C Schema.org Community Group as its main forum since April 2015. NLWeb uses / NLWeb?\\\"}]}]\\n63:[\\\"$\\\",\\\"li\\\",\\\"is-every-nlweb-instance-an-mcp-server\\\",{\\\"children\\\":[\\\"$\\\",\\\"a\\\",null,{\\\"href\\\":\\\"#is-every-nlweb-instance-an-mcp-server\\\",\\\"className\\\":\\\"-ml-px block border-l", "ref": 10 }, { "label": "[11]", "url": "https://support.wix.com/en/article/enabling-nlweb-for-ai-agent-access", "claim": "Wix, *Wix Help Center: Enabling NLWeb for AI Agent Access*, checked 2026-10-30", "date": null, "quote": "Use the following MCP URL to connect to your favorite AI agent (e.g. Claude, ChatGPT or custom agents): https://www.[your-domain.com]/_api/nlweb/mcp.", "ref": 11 }, { "label": "[12]", "url": "https://www.rfc-editor.org/rfc/rfc4287.html", "claim": "M. Nottingham, Ed. and R. Sayre, Ed., *RFC 4287: The Atom Syndication Format*, December 2005", "date": null, "quote": "This document specifies Atom, an XML-based Web content and metadata", "ref": 12 }, { "label": "[13]", "url": "https://www.jsonrpc.org/specification", "claim": "JSON-RPC Working Group, *JSON-RPC 2.0 Specification*, 2013-01-04", "date": "2013-01-04", "quote": "Origin Date: 2010-03-26 (based on the 2009-05-24 version)", "ref": 13 }, { "label": "[14]", "url": "https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning", "claim": "Model Context Protocol (AAIF / Linux Foundation), *Versioning — Model Context Protocol Documentation*, 2026-07-28", "date": "2026-07-28", "quote": "Current : the current protocol version, which is ready for use and may continue to receive backwards compatible changes.", "ref": 14 }, { "label": "[15]", "url": "https://webmachinelearning.github.io/webmcp/", "claim": "Web Machine Learning Community Group (editors Brandon Walderman, Khushal Sagar, Dominic Farolino, and Samuel Dallstream), *WebMCP*, Draft Community Group Report, 11 November 2026", "date": null, "quote": "Draft Community Group Report, 11 November 2026", "ref": 15 }, { "label": "[16]", "url": "https://llmstxt.org", "claim": "Jeremy Howard, *The /llms.txt file, v2*, published 2024-09-03; modified 2026-08-10; HTTP last-modified 2026-09-24", "date": null, "quote": "This is v2 of the proposal … The llms.txt specification is open for community input. A GitHub repository hosts this informal overview", "ref": 16 }, { "label": "[17]", "url": "https://aaif.io/blog/a2a-joins-aaif", "claim": "Agentic AI Foundation, *A2A joins AAIF's open agentic stack*, published 2026-08-17; modified 2026-09-24", "date": null, "quote": "A2A v1.0, the first stable specification, shipped in March 2026.", "ref": 17 }, { "label": "[18]", "url": "https://agentcommunity.org/ask?query=What%20is%20AID%3F", "claim": "Agent Community, *Agent Community Live NLWeb /ask Endpoint*, checked 2026-10-30", "date": null, "quote": "site publishes.\",\"score\":10,\"schema_object\":{\"@context\":\"https://schema.org\",\"@type\":\"Article\",\"@id\":\"https://agentcommunity.org/docs\",\"name\":\"Agent Community\",\"description\":\"Documentation for Agent Community", "ref": 18 }, { "label": "[19]", "url": "https://agentcommunity.org/docs/nlweb", "claim": "Agent Community, *Agent Community NLWeb Integration Documentation*, checked 2026-10-30", "date": null, "quote": "/ask is a public-documentation answer endpoint. It uses the same deterministic extractive retrieval as the Documentation MCP: it does not call an LLM, and it returns an answer assembled from published documentation with Schema.org Article citations.", "ref": 19 }, { "label": "[20]", "url": "https://www.worldmonitor.app/ask?query=What%20is%20World%20Monitor%3F", "claim": "World Monitor, *World Monitor Live NLWeb /ask Endpoint*, checked 2026-10-30", "date": null, "quote": "{\"_meta\":{\"response_type\":\"list\",\"version\":\"0.1\"},\"query_id\":\"50ab343e-d1d5-45c8-b5d6-0e6ad61287a2\",\"query\":\"What is World Monitor?\",\"results\":[{\"url\":\"https://worldmonitor.app/llms.txt\",\"name\":\"World Monitor", "ref": 20 }, { "label": "[21]", "url": "https://www.worldmonitor.app/agents.md", "claim": "World Monitor, *World Monitor agents.md*, checked 2026-10-30", "date": null, "quote": "/openapi.json) · API catalog: https://worldmonitor.app/.well-known/api-catalog - NLWeb: POST https://www.worldmonitor.app/ask (supports SSE) for natural-language questions;", "ref": 21 }, { "label": "[22]", "url": "https://developers.cloudflare.com/ai-search/how-to/nlweb/index.md", "claim": "Cloudflare, *Cloudflare AI Search: NLWeb Guide*, checked 2026-10-30", "date": null, "quote": "Enable conversational search on your website with NLWeb and Cloudflare AI Search. This template crawls your site, indexes the content, and deploys NLWeb-standard endpoints to serve both people and AI agents.", "ref": 22 }, { "label": "[23]", "url": "https://blog.cloudflare.com/conversational-search-with-nlweb-and-autorag/", "claim": "Cloudflare, *Cloudflare Blog: Conversational Search with NLWeb and AutoRAG*, checked 2026-10-30", "date": null, "quote": "to improve retrieval quality. /mcp endpoint: Implements an MCP server that trusted AI agents", "ref": 23 } ], "form": "endpoint", "governance": "The nlweb-ai GitHub organization, with Microsoft ties still in place. The project moved its repository there: \"We've migrated the repository from microsoft/NLWeb to our new independent GitHub organization at NLWeb-ai.\" The stated aim: \"A neutral space where contributors from any company or background can collaborate\". On 2026-10-29 github.com/microsoft/NLWeb answered HTTP 301 to github.com/nlweb-ai/NLWeb. The license still reads \"MIT License Copyright (c) Microsoft Corporation.\", and the README's support contact, \"For questions about this GitHub project, please contact NLWeb Support.\", is the address NLWebSup@microsoft.com. No foundation holds the project. A W3C Community Group exists: \"Posted on: October 20, 2025 The NLWeb Community Group has been launched:\" \"This is a community initiative. This group was originally proposed on 2025-10-16 by Ramanathan Guha.\" \"W3C's hosting of this group does not imply endorsement of the activities.\" Its page lists \"Chairs None yet\"", "group": null, "hatnote_md": "This page is about NLWeb (Natural Language Web), the open project that Microsoft announced on 2025-05-19 and R.V. Guha conceived, which gives a website a natural-language `ask` interface over its own Schema.org-shaped content and runs each instance as an MCP server. For the [Model Context Protocol (MCP)](/protocols/mcp/), the open protocol that connects AI applications to external tools and data, see that page and the [NLWeb vs MCP](/compare/nlweb-vs-mcp/) comparison. For the browser API that lets a web page offer tools to an agent, see [WebMCP](/protocols/webmcp/). NLWeb is not NL Web, a French web agency: \"L'agence Web « NL Web », c'est l'histoire d'une passion pour le monde du web. Derrière ce nom, se cache un expert en développement web et applications mobiles\".", "history": [ { "date": "2026-09-06", "note": "verified against github.com/microsoft/NLWeb (redirects to github.com/nlweb-ai/NLWeb); nlweb.ai/spec confirmed unreachable" }, { "date": "2026-10-29", "note": "Re-verified record against 32 primary, live endpoint, vendor, and coverage sources." }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "nlweb", "implementation": "multi-implementation", "last_verified": "2026-11-12", "name": "NLWeb", "native_status": "Public and open to contributions; the code is framed as a demonstration: \"NLWeb provides practical implementation code—not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach.\" The latest commit on main is dated 2026-06-10. A path-traversal flaw in the reference server was reported in August 2025: \"What's worse is that it's a classic path traversal flaw, meaning it's as easy to exploit as visiting a malformed URL.\"; a later review notes \"A release note in docs/release_notes lists a fix for a \"path traversal vulnerability in static file handler\" (PR #231)\" and \"When we queried the repository's GitHub security advisories on 24 October 2026, none were published.\"", "origin": { "date": "2025-05-19", "org": "Microsoft (R.V. Guha)" }, "part_of": null, "parties": [ "agent-site" ], "phase": "draft", "probe": { "method": "POST", "on_absent": "connection refused, 404, or a non-Schema.org JSON shape means no NLWeb endpoint is present", "parse": "a JSON response using Schema.org vocabulary answering the natural-language question in the request body proves NLWeb (or an MCP-exposed equivalent) is present; every NLWeb instance also runs as an MCP server exposing an `ask` tool/method", "path": "{origin}/ask" }, "question": "How can a site expose a natural-language question-answering interface grounded in its own Schema.org-structured content, for both humans and agents?", "scope": "general", "spec_url": "https://raw.githubusercontent.com/nlweb-ai/website/main/NLWEBSPEC.md", "step": "act", "summary_md": "**NLWeb** (NLWeb Specification v0.55) defines a standardized interface for natural language interactions with agents. It abstracts the complexity of agentic interactions, such as tool use, long-running tasks, and rich structured data, into a unified protocol. The project was conceived and developed by R.V. Guha, creator of RSS, RDF, and Schema.org, CVP and Technical Fellow at Microsoft, along with contributors from Microsoft and the open-source community. NLWeb supports streaming responses via Server-Sent Events (SSE) over HTTP transport. Streaming is requested by setting prefer.streaming to true. The start event is sent once at the beginning of the stream. Clients SHOULD use this event to initialize their response handling. The complete event is sent once to signal the end of the stream. Clients MUST process this event to capture session state for subsequent requests. 202 Accepted is the promise response for long-running tasks. POST /await checks on or cancels a promised result. The specification heading is NLWeb Specification v0.55. Changes from v0.54 to v0.55 promote streaming to its own section with formal SSE event type definitions for start, result, error, and complete. The repository was migrated from microsoft/NLWeb to an independent GitHub organization at NLWeb-ai, described as a neutral space where contributors from any company or background can collaborate. The license text remains MIT License Copyright (c) Microsoft Corporation. The NLWeb Community Group was originally proposed on 2025-10-16 by Ramanathan Guha. W3C's hosting of this group does not imply endorsement of the activities. NLWeb provides practical implementation code-not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach.", "track": "community", "version": { "date": "2026-03-23", "label": "NLWeb Specification v0.55" }, "watch": [ { "type": "github", "repo": "nlweb-ai/NLWeb", "mode": "tag" } ], "use_cases": [ "let-agents-act-on-my-site", "serve-content-to-agents", "expose-tools-to-agents" ], "audience": [ "site-owner", "agent-builder" ], "pairs_with": [ "mcp", "webmcp", "llms-txt", "a2a" ], "prerequisites": [ "mcp" ], "tier": "spec_brief", "lifecycle_status": "active_draft", "wire_archetype": "harnesses_rpc_ui", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "This page is about NLWeb (Natural Language Web), the open project that Microsoft announced on 2025-05-19 and R.V. Guha conceived, which gives a website a natural-language `ask` interface over its own Schema.org-shaped content and runs each instance as an MCP server. For the [Model Context Protocol (MCP)](/protocols/mcp/), the open protocol that connects AI applications to external tools and data, see that page and the [NLWeb vs MCP](/compare/nlweb-vs-mcp/) comparison. For the browser API that lets a web page offer tools to an agent, see [WebMCP](/protocols/webmcp/). NLWeb is not NL Web, a French web agency: \"L'agence Web « NL Web », c'est l'histoire d'une passion pour le monde du web. Derrière ce nom, se cache un expert en développement web et applications mobiles\". [1]", "v05_elevator_pitch_md": null, "v05_lead_md": "**NLWeb** (NLWeb Specification v0.55) defines a standardized interface for natural language interactions with agents. It abstracts the complexity of agentic interactions, such as tool use, long-running tasks, and rich structured data, into a unified protocol. [1] The project was conceived and developed by R.V. Guha, creator of RSS, RDF, and Schema.org, CVP and Technical Fellow at Microsoft, along with contributors from Microsoft and the open-source community. [2] NLWeb supports streaming responses via Server-Sent Events (SSE) over HTTP transport. Streaming is requested by setting prefer.streaming to true. [1] The start event is sent once at the beginning of the stream. Clients SHOULD use this event to initialize their response handling. The complete event is sent once to signal the end of the stream. Clients MUST process this event to capture session state for subsequent requests. [1] 202 Accepted is the promise response for long-running tasks. POST /await checks on or cancels a promised result. [1] The specification heading is NLWeb Specification v0.55. Changes from v0.54 to v0.55 promote streaming to its own section with formal SSE event type definitions for start, result, error, and complete. [1] The repository was migrated from microsoft/NLWeb to an independent GitHub organization at NLWeb-ai, described as a neutral space where contributors from any company or background can collaborate. The license text remains MIT License Copyright (c) Microsoft Corporation. [3][4] The NLWeb Community Group was originally proposed on 2025-10-16 by Ramanathan Guha. W3C's hosting of this group does not imply endorsement of the activities. [5] NLWeb provides practical implementation code-not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach. [6]", "v05_identity_sentence_md": "**NLWeb** (NLWeb Specification v0.55) defines a standardized interface for natural language interactions with agents. It abstracts the complexity of agentic interactions, such as tool use, long-running tasks, and rich structured data, into a unified protocol. [1] The project was conceived and developed by R.V. Guha, creator of RSS, RDF, and Schema.org, CVP and Technical Fellow at Microsoft, along with contributors from Microsoft and the open-source community. [2]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Act](/category/act/) (`act`)" }, { "label": "Form", "value_md": "Endpoint (`endpoint`)" }, { "label": "Originated by", "value_md": "R.V. Guha (Microsoft CVP & Technical Fellow; creator of RSS, RDF, Schema.org) and Microsoft (19 May 2025; repo created 28 April 2025) [2][7][8]" }, { "label": "Governed by", "value_md": "`nlweb-ai` GitHub org (July 2025) and W3C NLWeb Community Group (20 October 2025; no chairs); Microsoft retains copyright and `NLWebSup@microsoft.com` [3][4][6]" }, { "label": "Track", "value_md": "Open-source community draft specification (`nlweb-ai/NLWeb`) and W3C NLWeb Community Group (non-Recommendation track) [5][8]" }, { "label": "Status", "value_md": "Public and open to contributions; the code is framed as a demonstration: \"NLWeb provides practical implementation code—not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach.\" The latest commit on main is dated 2026-06-10. A path-traversal flaw in the reference server was reported in August 2025: \"What's worse is that it's a classic path traversal flaw, meaning it's as easy to exploit as visiting a malformed URL.\"; a later review notes \"A release note in docs/release_notes lists a fix for a \"path traversal vulnerability in static file handler\" (PR #231)\" and \"When we queried the repository's GitHub security advisories on 24 October 2026, none were published.\" [1][9][10]" }, { "label": "Version", "value_md": "Spec: `NLWeb Specification v0.55` (`NLWEBSPEC.md`, `2026-03-23`, succeeding `v0.54`); Server (`nlweb-ai/NLWeb`): commit `2026-06-10` (`0` releases/tags; `/ask` and `/mcp` endpoints); PyPI `nlweb-core`: `v0.7.0` (`2026-02-19`, `v0.5`) [1][9][10]" }, { "label": "Wire format", "value_md": "JSON over HTTP (`application/json`), SSE (`text/event-stream`), and JSON-RPC 2.0 (`/mcp`) with Schema.org / JSON-LD `@context` and `@type` objects [1][6][9]" }, { "label": "Specification", "value_md": "[NLWeb Specification v0.55](https://raw.githubusercontent.com/nlweb-ai/website/main/NLWEBSPEC.md) · [NLWeb REST API](https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/docs/nlweb-rest-api.md) · [nlweb-ai/NLWeb](https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/README.md) · [W3C NLWeb CG](https://www.w3.org/community/nlweb/) [1][6][9]" }, { "label": "Found at", "value_md": "No fixed `.well-known` path; routes are `/ask`, `/await`, `/mcp`, `/who`, `/sites` (`/_api/nlweb/mcp` on Wix), advertised via `/agents.md` or `/llms.txt` [1][9][11]" }, { "label": "Licence", "value_md": "MIT License (`Copyright (c) Microsoft Corporation`) [4][6][8]" } ], "v05_problem_md": "NLWeb simplifies the process of building conversational interfaces for websites. Its straightforward implementation uses existing markup on sites with structured lists, for example products, recipes, attractions, and reviews. [6] Schema.org and related semi-structured formats like RSS, used by over 100 million websites, have become not just de facto syndication mechanisms, but also a semantic layer for the web. NLWeb leverages these to enable natural language interfaces more easily. [1][6] The primary API, tool, or skill is ask, using which a caller can ask the agent for some information or to perform a task. The request object consists of four sections: query, context, prefer, and meta. [1] Clients SHOULD use the start event to initialize their response handling. Result items may arrive out of order, and index values are not guaranteed to be sequential. [1] NLWeb is designed to be transport-protocol agnostic. [1] Authentication and authorization are handled at the transport layer and are outside the scope of the specification. Rate limiting is a transport-layer concern and is outside the scope of the specification. [1]", "v05_mechanism_delta_md": "The primary API, tool, or skill is ask, using which a caller can ask the agent for some information or to perform a task. The request object consists of four sections: query, context, prefer, and meta. [1] Clients SHOULD use the start event to initialize their response handling. Result items may arrive out of order, and index values are not guaranteed to be sequential. [1]", "v05_scope_boundary_md": "NLWeb is designed to be transport-protocol agnostic. [1] Authentication and authorization are handled at the transport layer and are outside the scope of the specification. Rate limiting is a transport-layer concern and is outside the scope of the specification. [1]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "RSS 2.0 / Atom Syndication (RFC 4287)", "spec_or_rfc": "RFC 4287", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "NLWeb reuses Schema.org and RSS markup a site already publishes and answers natural-language questions with POST /ask and POST /await, rather than by a client fetching an RSS or Atom document. [1][12]" }, { "name": "JSON-RPC 2.0 Specification", "spec_or_rfc": "JSON-RPC 2.0", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "NLWeb's specified HTTP binding is POST /ask and POST /await returning Schema.org JSON, and the same ask operation may also be exposed as an MCP tool, which is optional beside that HTTP binding rather than a required JSON-RPC session. [1][13]" } ], "agentic_peers": [ { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Per NLWEBSPEC.md §2.1, NLWeb is transport-protocol agnostic and treats MCP as an optional transport and tool binding, while its direct HTTP binding uses POST /ask and POST /await returning Schema.org JSON. [1][14]" }, { "target_id": "webmcp", "target_name": "WebMCP", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "NLWeb answers queries at an HTTP path the site operator publishes, while WebMCP tools appear only after the browser loads the page and script registers them. [1][15]" }, { "target_id": "llms-txt", "target_name": "llms.txt", "relation_type": "complements", "relation_label": "Complements", "delta_md": "llms.txt is a site document a client reads, while NLWeb accepts a natural-language query at POST /ask and can return a promised result through POST /await. [1][16]" }, { "target_id": "a2a", "target_name": "Agent2Agent Protocol (A2A)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "NLWeb serves a site's natural-language ask endpoint, while A2A sends tasks over JSON-RPC 2.0, gRPC, or HTTP+JSON to another agent identified by an Agent Card. [1][17]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (4 probed or cited examples; non-exhaustive).", "side_a": { "visible": true, "heading": "Servers, repos & skill indexes", "col4_header": "Transport & Scope", "note_md": null, "rows": [ { "actor": "Agent Community", "role": "NLWeb site", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "GET `https://agentcommunity.org/ask?query=What%20is%20AID%3F` returned status 200 JSON with `query_id` and a `results` list of Schema.org `Article` items (`url`, `name`, `site`, `score`). Docs say `/ask` is extractive retrieval over published documentation and does not call an LLM.", "source_md": "[Agent Community /ask](https://agentcommunity.org/ask?query=What%20is%20AID%3F) [18] · [Docs](https://agentcommunity.org/docs/nlweb) [19]" }, { "actor": "World Monitor", "role": "NLWeb site", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "GET `https://www.worldmonitor.app/ask?query=What%20is%20World%20Monitor%3F` returned status 200 JSON with _meta.response_type `list`, _meta.version `0.1`, `query_id`, and `results`. The agent guide says `POST https://www.worldmonitor.app/ask` supports SSE.", "source_md": "[World Monitor /ask](https://www.worldmonitor.app/ask?query=What%20is%20World%20Monitor%3F) [20] · [Agent guide](https://www.worldmonitor.app/agents.md) [21]" }, { "actor": "Cloudflare (AI Search NLWeb template)", "role": "NLWeb site", "status": "Experimental", "status_display": "Experimental · as of 2026-07-10", "col4_md": "The AI Search template crawls a site, indexes it, and deploys NLWeb endpoints. Docs (updated 2026-07-10) mark it a public preview and name `/mcp` as the NLWeb MCP server endpoint for trusted agents.", "source_md": "[Cloudflare NLWeb](https://developers.cloudflare.com/ai-search/how-to/nlweb/index.md) [22][23]" }, { "actor": "Wix", "role": "NLWeb site", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Wix documents NLWeb on hosted sites. The MCP URL pattern is `https://www.[your-domain.com]/_api/nlweb/mcp`, for an MCP-capable agent such as Claude or ChatGPT.", "source_md": "[Enabling NLWeb on Wix](https://support.wix.com/en/article/enabling-nlweb-for-ai-agent-access) [11]" } ] }, "side_b": null, "additional_tables": null, "censuses": [], "footer_md": null }, "v05_see_also": [ { "target_id": "iab-comp", "target_name": "CoMP (Content Monetization Protocols)", "relation_label": "Complements", "delta": "CoMP lists NLWeb as value 4 on the Endpoint / Delivery Format list, while NLWeb defines a standardized interface for natural language interactions with agents.", "item_md": "**[CoMP (Content Monetization Protocols)](/protocols/iab-comp/)** (Complements) — CoMP lists NLWeb as value 4 on the Endpoint / Delivery Format list, while NLWeb defines a standardized interface for natural language interactions with agents." }, { "item_md": "**[Act protocols](/category/act/)** — Category index for `act` standards." } ], "v05_compiled_md": "---\nid: nlweb\ntitle: \"NLWeb\"\ntier: spec_brief\nlifecycle_status: active_draft\ncategory: act\nform: endpoint\nwire_archetype: harnesses_rpc_ui\nspec_url: https://raw.githubusercontent.com/nlweb-ai/website/main/NLWEBSPEC.md\nlast_checked: 2026-11-12\n---\n\n# NLWeb\n\n**Category:** [Act](/category/act/) (`act`) · **Form:** Endpoint (`endpoint`) · **Last checked:** 2026-11-12\n\n> *This page is about NLWeb (Natural Language Web), the open project that Microsoft announced on 2025-05-19 and R.V. Guha conceived, which gives a website a natural-language `ask` interface over its own Schema.org-shaped content and runs each instance as an MCP server. For the [Model Context Protocol (MCP)](/protocols/mcp/), the open protocol that connects AI applications to external tools and data, see that page and the [NLWeb vs MCP](/compare/nlweb-vs-mcp/) comparison. For the browser API that lets a web page offer tools to an agent, see [WebMCP](/protocols/webmcp/). NLWeb is not NL Web, a French web agency: \"L'agence Web « NL Web », c'est l'histoire d'une passion pour le monde du web. Derrière ce nom, se cache un expert en développement web et applications mobiles\". [1]*\n\n**NLWeb** (NLWeb Specification v0.55) defines a standardized interface for natural language interactions with agents. It abstracts the complexity of agentic interactions, such as tool use, long-running tasks, and rich structured data, into a unified protocol. [1] The project was conceived and developed by R.V. Guha, creator of RSS, RDF, and Schema.org, CVP and Technical Fellow at Microsoft, along with contributors from Microsoft and the open-source community. [2] NLWeb supports streaming responses via Server-Sent Events (SSE) over HTTP transport. Streaming is requested by setting prefer.streaming to true. [1] The start event is sent once at the beginning of the stream. Clients SHOULD use this event to initialize their response handling. The complete event is sent once to signal the end of the stream. Clients MUST process this event to capture session state for subsequent requests. [1] 202 Accepted is the promise response for long-running tasks. POST /await checks on or cancels a promised result. [1] The specification heading is NLWeb Specification v0.55. Changes from v0.54 to v0.55 promote streaming to its own section with formal SSE event type definitions for start, result, error, and complete. [1] The repository was migrated from microsoft/NLWeb to an independent GitHub organization at NLWeb-ai, described as a neutral space where contributors from any company or background can collaborate. The license text remains MIT License Copyright (c) Microsoft Corporation. [3][4] The NLWeb Community Group was originally proposed on 2025-10-16 by Ramanathan Guha. W3C's hosting of this group does not imply endorsement of the activities. [5] NLWeb provides practical implementation code-not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach. [6]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Act](/category/act/) (`act`) |\n| **Form** | Endpoint (`endpoint`) |\n| **Originated by** | R.V. Guha (Microsoft CVP & Technical Fellow; creator of RSS, RDF, Schema.org) and Microsoft (19 May 2025; repo created 28 April 2025) [2][7][8] |\n| **Governed by** | `nlweb-ai` GitHub org (July 2025) and W3C NLWeb Community Group (20 October 2025; no chairs); Microsoft retains copyright and `NLWebSup@microsoft.com` [3][4][6] |\n| **Track** | Open-source community draft specification (`nlweb-ai/NLWeb`) and W3C NLWeb Community Group (non-Recommendation track) [5][8] |\n| **Status** | Public and open to contributions; the code is framed as a demonstration: \"NLWeb provides practical implementation code—not as the definitive solution, but as proof-of-concept demonstrations showing one possible approach.\" The latest commit on main is dated 2026-06-10. A path-traversal flaw in the reference server was reported in August 2025: \"What's worse is that it's a classic path traversal flaw, meaning it's as easy to exploit as visiting a malformed URL.\"; a later review notes \"A release note in docs/release_notes lists a fix for a \"path traversal vulnerability in static file handler\" (PR #231)\" and \"When we queried the repository's GitHub security advisories on 24 October 2026, none were published.\" [1][9][10] |\n| **Version** | Spec: `NLWeb Specification v0.55` (`NLWEBSPEC.md`, `2026-03-23`, succeeding `v0.54`); Server (`nlweb-ai/NLWeb`): commit `2026-06-10` (`0` releases/tags; `/ask` and `/mcp` endpoints); PyPI `nlweb-core`: `v0.7.0` (`2026-02-19`, `v0.5`) [1][9][10] |\n| **Wire format** | JSON over HTTP (`application/json`), SSE (`text/event-stream`), and JSON-RPC 2.0 (`/mcp`) with Schema.org / JSON-LD `@context` and `@type` objects [1][6][9] |\n| **Specification** | [NLWeb Specification v0.55](https://raw.githubusercontent.com/nlweb-ai/website/main/NLWEBSPEC.md) · [NLWeb REST API](https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/docs/nlweb-rest-api.md) · [nlweb-ai/NLWeb](https://raw.githubusercontent.com/nlweb-ai/NLWeb/main/README.md) · [W3C NLWeb CG](https://www.w3.org/community/nlweb/) [1][6][9] |\n| **Found at** | No fixed `.well-known` path; routes are `/ask`, `/await`, `/mcp`, `/who`, `/sites` (`/_api/nlweb/mcp` on Wix), advertised via `/agents.md` or `/llms.txt` [1][9][11] |\n| **Licence** | MIT License (`Copyright (c) Microsoft Corporation`) [4][6][8] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [Adoption and ecosystem](#adoption-and-ecosystem)\n4. [See also](#see-also)\n5. [References](#references)\n\n---\n\n## Problem and scope\n\nNLWeb simplifies the process of building conversational interfaces for websites. Its straightforward implementation uses existing markup on sites with structured lists, for example products, recipes, attractions, and reviews. [6] Schema.org and related semi-structured formats like RSS, used by over 100 million websites, have become not just de facto syndication mechanisms, but also a semantic layer for the web. NLWeb leverages these to enable natural language interfaces more easily. [1][6] The primary API, tool, or skill is ask, using which a caller can ask the agent for some information or to perform a task. The request object consists of four sections: query, context, prefer, and meta. [1] Clients SHOULD use the start event to initialize their response handling. Result items may arrive out of order, and index values are not guaranteed to be sequential. [1] NLWeb is designed to be transport-protocol agnostic. [1] Authentication and authorization are handled at the transport layer and are outside the scope of the specification. Rate limiting is a transport-layer concern and is outside the scope of the specification. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **RSS 2.0 / Atom Syndication (RFC 4287)** | `RFC 4287` | Analogous to classic standard | NLWeb reuses Schema.org and RSS markup a site already publishes and answers natural-language questions with POST /ask and POST /await, rather than by a client fetching an RSS or Atom document. [1][12] |\n| **JSON-RPC 2.0 Specification** | `JSON-RPC 2.0` | Analogous to classic standard | NLWeb's specified HTTP binding is POST /ask and POST /await returning Schema.org JSON, and the same ask operation may also be exposed as an MCP tool, which is optional beside that HTTP binding rather than a required JSON-RPC session. [1][13] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | Per NLWEBSPEC.md §2.1, NLWeb is transport-protocol agnostic and treats MCP as an optional transport and tool binding, while its direct HTTP binding uses POST /ask and POST /await returning Schema.org JSON. [1][14] |\n| **[WebMCP](/protocols/webmcp/)** | Peer alternative | NLWeb answers queries at an HTTP path the site operator publishes, while WebMCP tools appear only after the browser loads the page and script registers them. [1][15] |\n| **[llms.txt](/protocols/llms-txt/)** | Complements | llms.txt is a site document a client reads, while NLWeb accepts a natural-language query at POST /ask and can return a promised result through POST /await. [1][16] |\n| **[Agent2Agent Protocol (A2A)](/protocols/a2a/)** | Complements | NLWeb serves a site's natural-language ask endpoint, while A2A sends tasks over JSON-RPC 2.0, gRPC, or HTTP+JSON to another agent identified by an Agent Card. [1][17] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (4 probed or cited examples; non-exhaustive).*\n\n### Servers, repos & skill indexes\n\n| Actor | Role | Status | Transport & Scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Agent Community** | NLWeb site | Live (HTTP 200) · checked 2026-10-30 | GET `https://agentcommunity.org/ask?query=What%20is%20AID%3F` returned status 200 JSON with `query_id` and a `results` list of Schema.org `Article` items (`url`, `name`, `site`, `score`). Docs say `/ask` is extractive retrieval over published documentation and does not call an LLM. | [Agent Community /ask](https://agentcommunity.org/ask?query=What%20is%20AID%3F) [18] · [Docs](https://agentcommunity.org/docs/nlweb) [19] |\n| **World Monitor** | NLWeb site | Live (HTTP 200) · checked 2026-10-30 | GET `https://www.worldmonitor.app/ask?query=What%20is%20World%20Monitor%3F` returned status 200 JSON with _meta.response_type `list`, _meta.version `0.1`, `query_id`, and `results`. The agent guide says `POST https://www.worldmonitor.app/ask` supports SSE. | [World Monitor /ask](https://www.worldmonitor.app/ask?query=What%20is%20World%20Monitor%3F) [20] · [Agent guide](https://www.worldmonitor.app/agents.md) [21] |\n| **Cloudflare (AI Search NLWeb template)** | NLWeb site | Experimental · as of 2026-07-10 | The AI Search template crawls a site, indexes it, and deploys NLWeb endpoints. Docs (updated 2026-07-10) mark it a public preview and name `/mcp` as the NLWeb MCP server endpoint for trusted agents. | [Cloudflare NLWeb](https://developers.cloudflare.com/ai-search/how-to/nlweb/index.md) [22][23] |\n| **Wix** | NLWeb site | Supported · checked 2026-10-30 | Wix documents NLWeb on hosted sites. The MCP URL pattern is `https://www.[your-domain.com]/_api/nlweb/mcp`, for an MCP-capable agent such as Claude or ChatGPT. | [Enabling NLWeb on Wix](https://support.wix.com/en/article/enabling-nlweb-for-ai-agent-access) [11] |\n\n---\n\n## See also\n\n- **[CoMP (Content Monetization Protocols)](/protocols/iab-comp/)** *(Complements)* — CoMP lists NLWeb as value 4 on the Endpoint / Delivery Format list, while NLWeb defines a standardized interface for natural language interactions with agents.\n- **Category:** [Act protocols](/category/act/)\n\n---\n\n## References\n\n1. nlweb-ai/website (GitHub), *NLWeb Specification v0.55 (nlweb-ai/website NLWEBSPEC.md)* (checked 2026-10-30) — \n2. Microsoft, *Microsoft News: Introducing NLWeb* (checked 2026-10-30) — \n3. nlweb ai, *NLWeb Wiki: Repository Migration Notice* (checked 2026-10-30) — \n4. nlweb-ai/NLWeb (GitHub), *nlweb-ai/NLWeb MIT License* (checked 2026-10-30) — \n5. W3C, *W3C NLWeb Community Group* (checked 2026-10-30) — \n6. nlweb-ai/NLWeb (GitHub), *nlweb-ai/NLWeb README.md* (checked 2026-10-30) — \n7. Microsoft, *Microsoft Build 2025: Building the Open Agentic Web* (checked 2026-10-30) — \n8. nlweb-ai/NLWeb (GitHub), *GitHub Repository Metadata: nlweb-ai/NLWeb* (checked 2026-10-30) — \n9. nlweb-ai/NLWeb (GitHub), *NLWeb REST API Documentation (nlweb-rest-api.md)* (checked 2026-10-30) — \n10. Safeguard, *Safeguard: NLWeb Explained and Security Analysis* (checked 2026-10-30) — \n11. Wix, *Wix Help Center: Enabling NLWeb for AI Agent Access* (checked 2026-10-30) — \n12. M. Nottingham, Ed. and R. Sayre, Ed., *RFC 4287: The Atom Syndication Format* (December 2005) — \n13. JSON-RPC Working Group, *JSON-RPC 2.0 Specification* (2013-01-04) — \n14. Model Context Protocol (AAIF / Linux Foundation), *Versioning — Model Context Protocol Documentation* (2026-07-28) — \n15. Web Machine Learning Community Group (editors Brandon Walderman, Khushal Sagar, Dominic Farolino, and Samuel Dallstream), *WebMCP* (Draft Community Group Report, 11 November 2026) — \n16. Jeremy Howard, *The /llms.txt file, v2* (published 2024-09-03; modified 2026-08-10; HTTP last-modified 2026-09-24) — \n17. Agentic AI Foundation, *A2A joins AAIF's open agentic stack* (published 2026-08-17; modified 2026-09-24) — \n18. Agent Community, *Agent Community Live NLWeb /ask Endpoint* (checked 2026-10-30) — \n19. Agent Community, *Agent Community NLWeb Integration Documentation* (checked 2026-10-30) — \n20. World Monitor, *World Monitor Live NLWeb /ask Endpoint* (checked 2026-10-30) — \n21. World Monitor, *World Monitor agents.md* (checked 2026-10-30) — \n22. Cloudflare, *Cloudflare AI Search: NLWeb Guide* (checked 2026-10-30) — \n23. Cloudflare, *Cloudflare Blog: Conversational Search with NLWeb and AutoRAG* (checked 2026-10-30) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "", "adoption": { "level": "observed", "by": "Cloudflare, Vercel, Stripe, Claude Code, Claude.ai and Claude Desktop, Claude API, Cursor, GitHub Copilot in VS Code, and 11 other verified implementations", "probe_run": null }, "aliases": [ "Agent Skills", "SKILL.md" ], "analog": "Package README / plugin manifest", "collisions": [ "MCP \"Skills over MCP\" working group (a related but distinct proposal for discovering skills through MCP itself)" ], "discovery": { "mechanism": "Local skills directory or well-known index", "path": "In an agent's skills folder, one subfolder per skill holding its SKILL.md: for example ~/.claude/skills//SKILL.md in Claude Code and ~/.agents/skills//SKILL.md in goose; VS Code also reads ~/.copilot/skills/. On the web, the Cloudflare draft RFC (not part of the agentskills.io specification) puts an index at /.well-known/agent-skills/index.json; earlier drafts used /.well-known/skills/. The draft asks to register agent-skills as a well-known URI suffix; no documentation was found showing that agent-skills is in the IANA Well-Known URIs registry (checked 2026-10-28)" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://agentskills.io/home", "claim": "Agent Skills, *Agent Skills Overview*, checked 2026-10-30", "date": null, "quote": "The Agent Skills format was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products. / Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. / Skills solve this by packaging procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand. / Agents are increasingly capable, but often don't have the context they need to do real work reliably. / Agents load skills through progressive disclosure, in three stages: / Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant. / Activation: When a task matches a skill's description, the agent reads the full SKILL.md instructions into context. / Execution: The agent follows the instructions, optionally executing bundled code or loading referenced files as needed. / At its core, a skill is a folder containing a SKILL.md file. / portable, version-controlled folders that agents load on demand. / name:OpenCode,description:OpenCode is an open source agent that helps you write code in your terminal, IDE, or desktop. / url:https://opencode.ai/ / instructionsUrl:https://opencode.ai/docs/skills/", "ref": 1 }, { "label": "[2]", "url": "https://agentskills.io/specification", "claim": "Agent Skills, *Specification - Agent Skills*, checked 2026-10-30", "date": null, "quote": "A skill is a directory containing, at minimum, a SKILL.md file / The SKILL.md file must contain YAML frontmatter followed by Markdown content. / Must match the parent directory name / description Yes Max 1024 characters. Non-empty. Describes what the skill does and when to use it. / license No License name or reference to a bundled license file. / compatibility No Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). / metadata No Arbitrary key-value mapping for additional metadata (a map from string keys to string values). / allowed-tools No Space-separated string of pre-approved tools the skill may use. (Experimental) / scripts/ # Optional: executable code / references/ # Optional: documentation / assets/ # Optional: templates, resources / Use the skills-ref reference library to validate your skills / The complete format specification for Agent Skills. / name Yes Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. / Experimental. Support for this field may vary between agent implementations / Agents load skills *progressively*, pulling in more detail only as a task calls for it. / **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills / **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated / **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required / Agents load skills progressively, pulling in more detail only as a task calls for it. / Must be 1-64 characters / May only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-) / Must not contain consecutive hyphens (--) / name: pdf-processing name: data-analysis name: code-review / name: PDF-Processing # uppercase not allowed / name: -pdf # cannot start with hyphen / name: pdf--processing # consecutive hyphens not allowed / Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. / Agents load these on demand, so smaller files mean less use of context. / Images (diagrams, examples) Data files (lookup tables, schemas) / Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript. / Metadata (~100 tokens): The name and description fields are loaded at startup for all skills / Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated / Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files. / Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required / Space-separated string of pre-approved tools the skill may use. (Experimental) / The name and description fields are loaded at startup for all skills / The full SKILL.md body is loaded when the skill is activated", "ref": 2 }, { "label": "[3]", "url": "https://agents.md/", "claim": "AGENTS.md contributors (OpenAI Codex, Amp, Jules from Google, Cursor, and Factory), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "Agents automatically read the nearest file in the directory tree / Are there required fields? No. AGENTS.md is just standard Markdown. / The closest AGENTS.md to the edited file wins", "ref": 3 }, { "label": "[4]", "url": "https://modelcontextprotocol.io/specification/2026-07-28", "claim": "Model Context Protocol, *Specification*, version 2026-07-28", "date": null, "quote": "Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. / Model Context Protocol (MCP) is an open protocol that / The protocol uses JSON-RPC 2.0 messages to establish / Hosts : LLM applications that initiate connections / Clients : Connectors within the host application / Servers : Services that provide context and capabilities / Servers offer any of the following features to clients: / Resources : Context and data, for the user or the AI model to use / Prompts : Templated messages and workflows for users / Tools : Functions for the AI model to execute / \"title\":\"stdio\" / \"title\":\"Streamable HTTP\"", "ref": 4 }, { "label": "[5]", "url": "https://modelcontextprotocol.io/community/working-groups/skills-over-mcp", "claim": "Model Context Protocol, *Skills Over MCP Charter*, SEP-2640 Final, merged 2026-09-13; checked 2026-10-30", "date": null, "quote": "The WG maintains the official Skills extension (io.modelcontextprotocol/skills) in modelcontextprotocol/ext-skills. / SEP-2640 is Final, merged on September 13, 2026. / SEP-2640 - Skills Extension is Final. / Current work focuses on implementation support, interoperability, and evolution of the published extension.", "ref": 5 }, { "label": "[6]", "url": "https://github.com/cloudflare/agent-skills-discovery-rfc", "claim": "Cloudflare, *Agent Skills Discovery via Well-Known URIs*, draft 0.2.0, published 2026-01-17; updated 2026-03-12", "date": null, "quote": "This document defines a mechanism for discovering [Agent Skills](https://agentskills.io/) using the `.well-known` URI path prefix / /.well-known/agent-skills/index.json / Version: 0.2.0 / Updated Date: 2026-03-12 / **Status**: Draft / **Version**: 0.2.0 / **Updated Date**: 2026-03-12 / Published Date: 2026-01-17 / # Agent Skills Discovery via Well-Known URIs / rename well-known URI from `/.well-known/skills/` to `/.well-known/agent-skills/` / Register `agent-skills` as a well-known URI suffix. / clients SHALL NOT execute scripts by default / digest is now the SHA-256 of the single artifact / \"skill-md\" or \"archive\" / Clients MUST verify artifact digests after download / Clients SHALL NOT execute files under scripts/ by default / The v0.2.0 index format is not backward-compatible with v0.1.0. Key differences: v0.1.0 used files as an array of path strings with no digests. v0.2.0 removes files entirely, adds type, url, digest, and $schema. Clients MUST check the $schema field to determine how to process the index. / Prompt injection: Skill content is loaded directly into agent context. A malicious SKILL.md can inject instructions that alter agent behavior", "ref": 6 }, { "label": "[7]", "url": "https://agenticresourcediscovery.org/spec/", "claim": "Junjie Bu (Google), R.V. Guha, and Shaun Smith (Hugging Face), *ARD Specification*, v0.91, 2026-08-26", "date": null, "quote": "LLMs increasingly rely on external capabilities - MCP tools, A2A agents, skills, and other callable services", "ref": 7 }, { "label": "[8]", "url": "https://code.claude.com/docs/en/skills", "claim": "Anthropic, *Extend Claude with skills*, checked 2026-10-30", "date": null, "quote": "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it. / Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name / Claude Code-only body features, such as dynamic context injection, don't function in claude.ai chat or through the API. / Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection. / ~/.claude/skills//SKILL.md / a skill's body loads only when it's used / Manage them from Customize in the Desktop app sidebar or from the skills settings on claude.ai. / Claude.ai skill uploads, the Skills API, and packaging with package_skill.py from anthropics/skills", "ref": 8 }, { "label": "[9]", "url": "https://geminicli.com/docs/cli/skills/", "claim": "Gemini CLI, *Agent Skills*, checked 2026-10-30", "date": null, "quote": "Unlike general context files (GEMINI.md), which provide persistent workspace-wide background, Skills represent on-demand expertise. / Based on the Agent Skills open standard, a \"skill\" is a self-contained directory that packages instructions and assets into a discoverable capability. / when Gemini identifies a task matching a skill's description, it calls the activate_skill tool. / The SKILL.md body and folder structure is added to the conversation history. / Within the same tier (user or workspace), the .agents/skills/ alias takes precedence over the .gemini/skills/ directory. / Located in ~/.gemini/skills/ or the ~/.agents/skills/ alias. / injects the name and description of all enabled skills into the system prompt.", "ref": 9 }, { "label": "[10]", "url": "https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation", "claim": "Anthropic, *Donating Agent Skills to the Agentic AI Foundation*, published 2026-10-22", "date": null, "quote": "We developed skills while working on Claude Code. / Today, we're donating Agent Skills, the open standard that gives AI agents specialized knowledge and workflows, to the Agentic AI Foundation (AAIF). / to the Agentic AI Foundation (AAIF) under the Linux Foundation / \"datePublished\":\"2026-10-22T00:00:00.000Z\" / with David Soria Parra and Mahesh Murag as Lead Maintainers. / We are donating the Agent Skills name and logo, the GitHub organization, and the agentskills.io domain. / Engineers from Anthropic, Google, OpenAI, and other companies will maintain the standard as individuals / We've proposed starting with a roadmap covering versioned releases, a formal proposal process, and security guidance for people who write and install skills. / wrote loaders for Codex, Cursor, and OpenCode / and the agentskills.io domain. / More than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot, and VS Code, have integrated Agent Skills since we published the standard in December 2025. / So far, 1 million skills have been published and nearly 280 million installed.", "ref": 10 }, { "label": "[11]", "url": "https://claude.com/resources/articles/skills", "claim": "Anthropic, *Introducing Agent Skills*, published 2025-10-16; update dated 2025-12-18", "date": null, "quote": "Now, you can build your own skills and use them across Claude apps, Claude Code, and our API. / \"datePublished\":\"2025-10-16\" / published Agent Skills as an open standard for cross-platform portability. (December 18, 2025) / use them across Claude apps, Claude Code, and our API / can now be added to Messages API requests and the new /v1/skills endpoint gives developers programmatic control over custom skill versioning and management. / Skills require the Code Execution Tool beta", "ref": 11 }, { "label": "[12]", "url": "https://claude.com/resources/articles/organization-skills-and-directory", "claim": "Anthropic, *Skills for organizations, partners, the ecosystem*, published 2025-12-18", "date": null, "quote": "We're also publishing Agent Skills as an open standard. / \"datePublished\":\"2025-12-18\" / Claude Team and Enterprise plan admins can now provision skills centrally from admin settings. / A growing collection of partner-built skills is now available at claude.com/connectors.", "ref": 12 }, { "label": "[13]", "url": "https://aaif.io/blog/agent-skills-sharing-team-expertise-across-ai-agents", "claim": "Angie Jones (Agentic AI Foundation), *Agent Skills: Open Standard for Sharing AI Agent Workflows*, published 2026-10-22", "date": null, "quote": "Bringing the project to AAIF will ensure neutral governance from a multi-company Technical Steering Committee that will guide its future. / The specification is open source under Apache 2.0 and CC BY 4.0 / Agentic AI Foundation (AAIF), a Linux Foundation project / In only seven months, a million skills have been listed on the popular skills.sh registry, and these skills have been installed nearly 280 million times.", "ref": 13 }, { "label": "[14]", "url": "https://github.com/agentskills/agentskills", "claim": "agentskills, *Specification and documentation for Agent Skills*, repository created 2025-12-16; checked 2026-10-30", "date": null, "quote": "\"createdAt\":\"2025-12-16T15:47:19.000Z\" / \"spdxId\":\"Apache-2.0\",\"name\":\"Apache License 2.0\"", "ref": 14 }, { "label": "[15]", "url": "https://raw.githubusercontent.com/agentskills/agentskills/main/GOVERNANCE.md", "claim": "Agent Skills project, *Agent Skills Governance*, Adopted November 4, 2026", "date": null, "quote": "Releases of the specification will be tagged and will carry a changelog, so that implementers can declare and test against a specific version. / Membership in technical governance is for individuals, not companies.", "ref": 15 }, { "label": "[16]", "url": "https://raw.githubusercontent.com/agentskills/agentskills/main/MAINTAINERS.md", "claim": "Agent Skills project, *Agent Skills Maintainers*, Last updated November 4, 2026", "date": null, "quote": "This document lists the current role holders in the Agent Skills project. Roles and the way people are appointed to them are described in GOVERNANCE.md. Membership belongs to the individual, not the employer. / Not yet designated.", "ref": 16 }, { "label": "[17]", "url": "https://www.linuxfoundation.org/press/agentic-ai-foundation-announces-four-new-projects-agent-skills-open-responses-openenv-and-opensandbox", "claim": "The Linux Foundation, *Agentic AI Foundation Announces Four New Projects: Agent Skills, Open Responses, OpenEnv, and OpenSandbox*, published 2026-10-22; modified 2026-10-23", "date": null, "quote": "AAIF announced four new projects: Agent Skills, contributed by Anthropic; / SAN JOSE, Oct. 22, 2026", "ref": 17 }, { "label": "[18]", "url": "https://code.visualstudio.com/docs/agent-customization/agent-skills", "claim": "Visual Studio Code, *Use Agent Skills in VS Code*, checked 2026-10-30", "date": null, "quote": "~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/ / Agent Skills is an open standard that works across multiple AI agents, including GitHub Copilot in VS Code, GitHub Copilot CLI, the GitHub Copilot app, and the experimental OpenAI Codex integration. / Skills you create are portable across skills-compatible agents, but supported locations and optional features vary by agent.", "ref": 18 }, { "label": "[19]", "url": "https://docs.stripe.com/.well-known/skills/index.json", "claim": "Stripe, *skills discovery index*, checked 2026-10-30", "date": null, "quote": "x-location: https://docs.stripe.com/.well-known/skills/index.json / \"name\":\"connect-recommend\" / \"files\":[\"SKILL.md\",\"references/account-types.md\" / \"name\":\"upgrade-stripe\" / content-type: application/json / x-content-timestamp: 2026-10-30T19:35:23Z", "ref": 19 }, { "label": "[20]", "url": "https://www.iana.org/assignments/well-known-uris/well-known-uris-1.csv", "claim": "IANA, *Well-Known URIs*, registry CSV, fetched 2026-10-30", "date": null, "quote": "URI Suffix,Reference,Status,Change Controller,Related Information,Date Registered,Date Modified", "ref": 20 }, { "label": "[21]", "url": "https://learn.chatgpt.com/docs/build-skills", "claim": "OpenAI, *Build skills*, checked 2026-10-30", "date": null, "quote": "openai.yaml Optional: appearance and dependencies / Add agents/openai.yaml to configure UI metadata / Skills build on the open agent skills standard. / ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill. / Use skills.max_context_tokens to set a different budget, up to 10,000 tokens. / /etc/codex/skills / Codex CLI / $CWD/.agents/skills / $REPO_ROOT/.agents/skills / $HOME/.agents/skills", "ref": 21 }, { "label": "[22]", "url": "https://www.ietf.org/archive/id/draft-mp-agntcy-ads-03.txt", "claim": "L. Muscariello and R. Polic (Cisco), *Agent Directory Service (draft-mp-agntcy-ads-03)*, 2 November 2026", "date": null, "quote": "The system leverages the Open Agentic Schema Framework (OASF) to model agent information in a structured, extensible format. / Agent Directory Service / discovery of agent applications with specific skills for solving various problems. / OASF enables rich queries such as \"What agents can solve problem A?\" or \"What combination of skills and costs optimizes for task B?\"", "ref": 22 }, { "label": "[23]", "url": "https://developers.cloudflare.com/.well-known/agent-skills/index.json", "claim": "Cloudflare, *agent-skills discovery index*, checked 2026-10-30", "date": null, "quote": "content-type: application/json / \"$schema\": \"https://schemas.agentskills.io/discovery/0.2.0/schema.json\" / \"name\": \"agents-sdk\", \"type\": \"archive\" / \"name\": \"wrangler\", \"type\": \"archive\" / \"name\": \"durable-objects\" / \"name\": \"wrangler\" / \"url\": \"/.well-known/agent-skills/agents-sdk.tar.gz\", \"digest\": \"sha256:5eed25d32f6c889305f93448af1ff62a5dd7802995d55f1c1eced7de569c9d8a\" / \"name\": \"basin\", \"type\": \"archive\" / \"name\": \"agents-sdk\"", "ref": 23 }, { "label": "[24]", "url": "https://vercel.com/.well-known/agent-skills/index.json", "claim": "Vercel, *agent-skills discovery index*, checked 2026-10-30", "date": null, "quote": "\"$schema\":\"https://schemas.agentskills.io/discovery/0.2.0/schema.json\" / \"name\":\"deploy-to-vercel\" / \"type\":\"skill-md\",\"url\":\"https://github.com/vercel-labs/agent-skills/releases/download/ / \"type\":\"skill-md\" / \"type\":\"archive\" / content-type: application/json / \"digest\":\"sha256:418ca2a60d35c551e6cb645f4e82c1b704a8335486ffe74b1b3d0617a17504e5\" / \"name\":\"vercel-cli-with-tokens\" / \"name\":\"writing-guidelines\" / x-matched-path: /.well-known/agent-skills/index.json", "ref": 24 }, { "label": "[25]", "url": "https://schema.oasf.outshift.com/", "claim": "Cisco, *Open Agentic Schema Framework*, copyright 2025; versions 0.8.0, 1.0.0, and 1.1.0 shown; checked 2026-10-31", "date": null, "quote": "Open Agentic Schema Framework 0.8.0 1.0.0 1.1.0 / Classes Skills Domains Modules / Taxonomy view Language Processing [1] Language Understanding [101] / Open Agentic Schema Framework / 0.8.0 1.0.0 1.1.0", "ref": 25 }, { "label": "[26]", "url": "https://www.anthropic.com/research/equipping-agents-for-the-real-world-with-agent-skills", "claim": "Anthropic, *Equipping agents for the real world with Agent Skills*, published 2025-10-16; modified 2026-10-18", "date": null, "quote": "malicious skills may introduce vulnerabilities in the environment where they're used or direct Claude to exfiltrate data and take unintended actions. We recommend installing skills only from trusted sources", "ref": 26 }, { "label": "[27]", "url": "https://llmstxt.org", "claim": "Jeremy Howard, *The /llms.txt file, v2*, published 2024-09-03; modified 2026-08-10", "date": null, "quote": "We propose adding a /llms.txt markdown file to websites to provide LLM-friendly content. The file can be placed at the site root, or at any path within it, covering the pages under that path. This file offers brief background information, guidance, and links to detailed markdown files.", "ref": 27 }, { "label": "[28]", "url": "https://cursor.com/changelog/2-4", "claim": "Cursor, *Subagents, Skills, and Image Generation*, 2.4, 2026-01-22", "date": null, "quote": "2026-01-22T00:00:00.000Z / Cursor now supports Agent Skills in the editor and CLI. / 2.4 Jan 22, 2026", "ref": 28 }, { "label": "[29]", "url": "https://cursor.com/docs/skills", "claim": "Cursor, *Agent Skills*, checked 2026-10-30", "date": null, "quote": "Each skill should be a folder containing a SKILL.md file / For compatibility, Cursor also loads skills from Claude and Codex directories: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/. / Cursor does not copy ~/.agents/skills/ or unsynced local skills to cloud agents, Agents window remote SSH sessions, or self-hosted workers. / .cursor/skills/ / ~/.cursor/skills/ / scripts/ / references/ / assets/", "ref": 29 }, { "label": "[30]", "url": "https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/", "claim": "Allison (GitHub), *GitHub Copilot now supports Agent Skills*, published 2025-12-18", "date": null, "quote": "\"datePublished\":\"2025-12-18T09:26:18-08:00\" / They work across Copilot coding agent, Copilot CLI, and agent mode in Visual Studio Code Insiders.", "ref": 30 }, { "label": "[31]", "url": "https://geminicli.com/docs/changelogs/", "claim": "Gemini CLI, *Gemini CLI release notes*, v0.23.0, 2026-01-07", "date": null, "quote": "Experimental Agent Skills Support in Preview: Gemini CLI now supports Agent Skills in our preview builds. / enabled agent skills by default / v0.23.0 - 2026-01-07 / v0.26.0 - 2026-01-27 Announcements: v0.25.0", "ref": 31 }, { "label": "[32]", "url": "https://goose-docs.ai/docs/guides/context-engineering/using-skills/", "claim": "goose, *Agent Skills*, checked 2026-10-30", "date": null, "quote": "Place a SKILL.md file inside a named subdirectory. / a global skill called code-review goes in ~/.agents/skills/code-review/SKILL.md / goose also discovers skills from .goose/skills/, .claude/skills/, ~/.claude/skills/ / name and description", "ref": 32 }, { "label": "[33]", "url": "https://ampcode.com/news/agent-skills", "claim": "Amp, *Agent Skills*, published 2025-12-10", "date": null, "quote": "\"datePublished\":\"2025-12-10T00:00:00.000Z\" / Amp supports agent skills. Skills let the agent lazily-load specific instructions on how to use local tools. / Skills are installed to .agents/skills/ in your workspace by default. Amp also reads from ~/.config/agents/skills/ for user-level skills, and .claude/skills/ and ~/.claude/skills/ for compatibility with existing skills. / Agent Sandbox: Isolated execution environment / BigQuery: Expert use of the bq cli tool / Tmux: Run servers and long-running tasks", "ref": 33 }, { "label": "[34]", "url": "https://guildskills.com/", "claim": "GuildSkills, *GuildSkills cross-agent skills registry*, checked 2026-11-06", "date": null, "quote": "195,000+ SKILL.md files compatible with Hermes Agent, Cursor, OpenAI Codex, Gemini CLI, OpenCode, Goose, Letta, Roo Code, Claude Code, and 30+ more AI agent clients.", "ref": 34 }, { "label": "[35]", "url": "https://agentskill.sh/", "claim": "AgentSkill Directory, *AI Agent Skills Directory*, checked 2026-11-06", "date": null, "quote": "275,000+ skills for Claude Code, Cursor, Copilot, Windsurf, Zed, and 20+ AI tools / Find and install 275,000+ skills for Claude Code, Cursor, Copilot, Windsurf, Zed, and 20+ AI tools", "ref": 35 }, { "label": "[36]", "url": "https://github.com/anthropics/skills", "claim": "Anthropic, *anthropics/skills*, checked 2026-10-30", "date": null, "quote": "Public repository for Agent Skills / Each skill is self-contained in its own folder with a SKILL.md file containing the instructions and metadata that Claude uses. / skills/docx / skills/pdf / skills/pptx / skills/xlsx / ./spec: The Agent Skills specification / ./template: Skill template / /plugin marketplace add anthropics/skills", "ref": 36 }, { "label": "[37]", "url": "https://github.com/huggingface/skills", "claim": "Hugging Face, *huggingface/skills*, checked 2026-10-30", "date": null, "quote": "Give your agents the power of the Hugging Face ecosystem / Each folder includes a SKILL.md file with YAML frontmatter (name and description) / hf-cli / gemini-extension.json / agentsmd/AGENTS.md / GitHub - huggingface/skills: Give your agents the power of the Hugging Face ecosystem / .claude-plugin/marketplace.json and .cursor-plugin/marketplace.json / installed on demand with hf skills add", "ref": 37 }, { "label": "[38]", "url": "https://github.com/vawe-hq/awesome-agent-skills-directories/blob/main/README.md", "claim": "vawe-hq, *Awesome Agent Skills Directories*, 2026-10-29", "date": "2026-10-29", "quote": "Every row was checked on 2026-10-29. / 25,346 skills when checked / 36.5k stars when checked / feeds skills.sh / Registry with 25,346 skills when checked. / [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) | Awesome list of agent skills / The `npx skills` installer. It feeds skills.sh.", "ref": 38 }, { "label": "[39]", "url": "https://agenticskills.io", "claim": "AgenticSkills, *AgenticSkills curated skill directory*, 2026-11-06", "date": "2026-11-06", "quote": "v1.7.0 / NOV 6 2026 / 195+ / 139 MCP servers / 9 platforms / ~/.claude/skills/ / .cursor/skills/ / 195+ curated skills", "ref": 39 } ], "form": "document-format", "governance": "Agentic AI Foundation (AAIF) under the Linux Foundation since 2026-10-22; governance charter adopted 4 November 2026 requires tagged specification releases with a changelog; technical seats belong to individuals, not employers; Lead Maintainers David Soria Parra and Mahesh Murag; Core Maintainers Aiden Cline, Nick Cooper, Colin Daymond Hanna, Harald Kirschner, and Kurtis Van Gent; TSC Representative not yet designated", "group": null, "history": [ { "date": "2026-09-06", "note": "verified against agentskills.io and agentskills.io/specification" }, { "date": "2026-10-22", "note": "Anthropic donated Agent Skills to the Linux Foundation Agentic AI Foundation (AAIF); track updated to linux-foundation" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "anthropic-agent-skills-format", "implementation": "multi-implementation", "last_verified": "2026-11-11", "name": "Agent Skills", "native_status": "Open standard (2025-12-18); AAIF project since 2026-10-22; governance adopted 4 November 2026 requires tagged specification releases with a changelog", "origin": { "org": "Anthropic", "date": "2025-10-16" }, "part_of": null, "parties": [ "agent-site" ], "phase": "living", "probe": { "method": "GET", "path": "/.well-known/agent-skills/index.json", "parse": "JSON object with $schema (https://schemas.agentskills.io/discovery/0.2.0/schema.json) and a skills[] array of entries with name, type, description, url, and digest (sha256:...); local packages validate via YAML frontmatter in {skill-name}/SKILL.md", "on_absent": "404 or non-JSON at /.well-known/agent-skills/index.json means the origin does not publish a web skill discovery index; local Agent Skills packages may still be distributed via repositories or local skill directories." }, "question": "How can reusable, on-demand procedural instructions and bundled resources be packaged so any compatible agent can load and run them?", "scope": "coding-tools", "spec_url": "https://agentskills.io/specification", "step": "act", "summary_md": "**Agent Skills** is an open format, originated by Anthropic for Claude Code, that packages procedural instructions and resources into portable directories an AI agent loads on demand. Launched across Claude apps, Claude Code, and the API on 2025-10-16 and published as an open standard on 2025-12-18, it was donated to the Linux Foundation's Agentic AI Foundation (AAIF) on 2026-10-22 under a multi-company Technical Steering Committee with Lead Maintainers David Soria Parra and Mahesh Murag. Each skill directory contains a `SKILL.md` file with YAML frontmatter (required `name` matching the parent directory and `description`, plus optional `license`, `compatibility`, `metadata`, and experimental `allowed-tools`) and Markdown instructions, alongside optional `scripts/`, `references/`, and `assets/` subdirectories validated by `skills-ref`. Licensed under Apache 2.0 and CC BY 4.0 (`agentskills/agentskills`, created 2025-12-16). Companion specifications define `/.well-known/agent-skills/index.json` discovery (Cloudflare draft `0.2.0`, updated 2026-03-12) and the MCP extension `io.modelcontextprotocol/skills` (SEP-2640, merged September 13, 2026). A governance charter and maintainer roster adopted on 4 November 2026 require tagged, changelogged specification releases under individual-capacity governance, naming two Lead Maintainers and five Core Maintainers while leaving the TSC Representative seat undesignated.", "track": "linux-foundation", "version": { "label": "unversioned", "date": null }, "watch": [ { "type": "page", "url": "https://agentskills.io/specification", "selector": "main" }, { "type": "github", "repo": "agentskills/agentskills", "mode": "tag" } ], "use_cases": [ "describe-agent-capabilities", "expose-tools-to-agents" ], "audience": [ "agent-builder", "platform" ], "pairs_with": [ "agents-md", "mcp", "oasf", "llms-txt" ], "prerequisites": [], "hatnote_md": "This page covers Agent Skills, the open directory and `SKILL.md` packaging format originated by Anthropic and stewarded by the Agentic AI Foundation (AAIF) for loading procedural instructions and scripts on demand. It is distinct from [AGENTS.md](/protocols/agents-md/), a repository-wide Markdown instruction file loaded automatically from the directory tree, and the [Model Context Protocol](/protocols/mcp/), a JSON-RPC 2.0 client-server protocol for tools and resources (which also defines the companion `io.modelcontextprotocol/skills` extension). Web-hosted skill indexes at `/.well-known/agent-skills/index.json` are specified in a separate Cloudflare draft RFC, and multi-resource catalogs are covered under [Agentic Resource Discovery (ARD)](/protocols/ard/).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "harnesses_rpc_ui", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-11", "v05_hatnote_html_md": "This page covers Agent Skills, the open directory and `SKILL.md` packaging format originated by Anthropic and stewarded by the Agentic AI Foundation (AAIF) for loading procedural instructions and scripts on demand. It is distinct from [AGENTS.md](/protocols/agents-md/), a repository-wide Markdown instruction file loaded automatically from the directory tree, and the [Model Context Protocol](/protocols/mcp/), a JSON-RPC 2.0 client-server protocol for tools and resources (which also defines the companion `io.modelcontextprotocol/skills` extension). Web-hosted skill indexes at `/.well-known/agent-skills/index.json` are specified in a separate Cloudflare draft RFC, and multi-resource catalogs are covered under [Agentic Resource Discovery (ARD)](/protocols/ard/). [1][2][3][4][5][6][7]", "v05_elevator_pitch_md": "Agent Skills is a portable directory standard that lets developers package specialized workflows, domain playbooks, and helper scripts into reusable folders that AI agents load on demand. Instead of cramming every workflow into always-on workspace files like `CLAUDE.md` or `GEMINI.md` and burning context tokens on every turn, an agent reads only the brief `name` and `description` YAML fields at startup and loads the full `SKILL.md` body and bundled `scripts/` only when a task matches. [1][8][9]", "v05_lead_md": "**Agent Skills** is an open format, originated by Anthropic for Claude Code, that packages procedural instructions and resources into portable directories an AI agent loads on demand. [1][10] Launched across Claude apps, Claude Code, and the API on 2025-10-16 and published as an open standard on 2025-12-18, it was donated to the Linux Foundation's Agentic AI Foundation (AAIF) on 2026-10-22 under a multi-company Technical Steering Committee with Lead Maintainers David Soria Parra and Mahesh Murag. [10][11][12][13] Each skill directory contains a `SKILL.md` file with YAML frontmatter (required `name` matching the parent directory and `description`, plus optional `license`, `compatibility`, `metadata`, and experimental `allowed-tools`) and Markdown instructions, alongside optional `scripts/`, `references/`, and `assets/` subdirectories validated by `skills-ref`. [2] Licensed under Apache 2.0 and CC BY 4.0 (`agentskills/agentskills`, created 2025-12-16). [13][14] Companion specifications define `/.well-known/agent-skills/index.json` discovery (Cloudflare draft `0.2.0`, updated 2026-03-12) and the MCP extension `io.modelcontextprotocol/skills` (SEP-2640, merged September 13, 2026). [5][6] A governance charter and maintainer roster adopted on 4 November 2026 require tagged, changelogged specification releases under individual-capacity governance, naming two Lead Maintainers and five Core Maintainers while leaving the TSC Representative seat undesignated. [15][16]", "v05_identity_sentence_md": "**Agent Skills** is an open format, originated by Anthropic for Claude Code, that packages procedural instructions and resources into portable directories an AI agent loads on demand. [1][10] Launched across Claude apps, Claude Code, and the API on 2025-10-16 and published as an open standard on 2025-12-18, it was donated to the Linux Foundation's Agentic AI Foundation (AAIF) on 2026-10-22 under a multi-company Technical Steering Committee with Lead Maintainers David Soria Parra and Mahesh Murag. [10][11][12][13]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Act](/category/act/) (`act`)" }, { "label": "Form", "value_md": "Document format (`document-format`)" }, { "label": "Originated by", "value_md": "Anthropic; built for Claude Code, launched 2025-10-16, and published as an open standard on 2025-12-18 [10][11][12]" }, { "label": "Governed by", "value_md": "AAIF under the Linux Foundation since 2026-10-22; Lead Maintainers David Soria Parra and Mahesh Murag; Core Maintainers Aiden Cline, Nick Cooper, Colin Daymond Hanna, Harald Kirschner, and Kurtis Van Gent (4 November 2026); TSC Representative not yet designated [10][13][16]" }, { "label": "Track", "value_md": "Foundation / Consortium Specification (`linux-foundation`); Agentic AI Foundation project [13][17]" }, { "label": "Status", "value_md": "Open standard (2025-12-18); AAIF project since 2026-10-22; governance adopted 4 November 2026 requires tagged specification releases with a changelog [12][15][17]" }, { "label": "Version", "value_md": "Unversioned specification (`agentskills/agentskills`, created 2025-12-16); separate Cloudflare discovery RFC is draft `0.2.0` (published 2026-01-17, updated 2026-03-12) [2][6][14]" }, { "label": "Message format", "value_md": "Skill folder with `SKILL.md` containing YAML frontmatter (`name`, `description`; optional `license`, `compatibility`, `metadata`, `allowed-tools`) and Markdown [2]" }, { "label": "Specification", "value_md": "[Specification - Agent Skills](https://agentskills.io/specification); discovery draft [Agent Skills Discovery via Well-Known URIs](https://github.com/cloudflare/agent-skills-discovery-rfc) [2][6]" }, { "label": "Found at", "value_md": "Local skill directories (`.agents/skills/`, `~/.claude/skills/`, `~/.copilot/skills/`); web index `/.well-known/agent-skills/index.json` (legacy `/.well-known/skills/index.json`) [2][6][18][19]" }, { "label": "IANA registration", "value_md": "None in core specification; Cloudflare draft `0.2.0` proposes registering `agent-skills` as a well-known URI suffix [6][20]" }, { "label": "Licence", "value_md": "Apache License 2.0 (`agentskills/agentskills`) and CC BY 4.0 for specification documentation [13][14]" } ], "v05_problem_md": "Agents often lack the procedural context real work requires, yet keeping long reference instructions in always-on workspace files (`CLAUDE.md` or `GEMINI.md`) consumes context-window tokens on every turn. Packaging domain and team workflows into version-controlled skill folders lets an agent leave long reference material unloaded until a task requires it. [1][8][9] Agent Skills uses three-stage progressive disclosure so agents scan only lightweight `name` and `description` frontmatter at startup, read the `SKILL.md` instruction body only when a task matches a skill's description, and load companion files from `scripts/`, `references/`, or `assets/` only during execution. [1] The specification standardizes the directory and six frontmatter fields, not one shared runtime. `allowed-tools` is experimental and support may vary between agent implementations. In Claude apps, a non-spec key such as `argument-hint` fails packaging with a hard error, while Claude Code dynamic context injection does not run in `claude.ai` chat or through the API. OpenAI Codex optionally reads an `agents/openai.yaml` file, and discovery clients SHALL NOT execute scripts by default. [2][6][8][21]", "v05_mechanism_delta_md": "Agent Skills uses three-stage progressive disclosure so agents scan only lightweight `name` and `description` frontmatter at startup, read the `SKILL.md` instruction body only when a task matches a skill's description, and load companion files from `scripts/`, `references/`, or `assets/` only during execution. [1]", "v05_scope_boundary_md": "The specification standardizes the directory and six frontmatter fields, not one shared runtime. `allowed-tools` is experimental and support may vary between agent implementations. In Claude apps, a non-spec key such as `argument-hint` fails packaging with a hard error, while Claude Code dynamic context injection does not run in `claude.ai` chat or through the API. OpenAI Codex optionally reads an `agents/openai.yaml` file, and discovery clients SHALL NOT execute scripts by default. [2][6][8][21]", "v05_fuzzy_additions": [ { "id": "skill-md-package-format-and-progressive-disclosure", "heading": "`SKILL.md` package format and progressive disclosure", "body_md": "A skill package is a directory centered on a `SKILL.md` file whose YAML frontmatter declares the skill's identity and metadata before the Markdown instructions. Optional `scripts/`, `references/`, and `assets/` subdirectories remain unloaded until an activated workflow references them. [2]", "bullets": [ { "label": "Six frontmatter fields", "text_md": "YAML frontmatter defines two required fields (`name` and non-empty `description` of at most 1024 characters) and four optional fields: `license` (a license name or reference to a bundled license file), `compatibility` (at most 500 characters describing environment requirements), string-mapped `metadata`, and experimental space-separated `allowed-tools` (whose support may vary between agent implementations). [2]" }, { "label": "Name constraints, directory matching, and spec table vs. prose wording", "text_md": "Required `name` (1–64 characters) must match the parent directory name and must not start, end, or repeat hyphens (`--`); in a source-side phrasing difference within the specification, the summary table states `lowercase letters, numbers, and hyphens` whereas the field-constraints prose specifies `unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)`. `pdf-processing` and `data-analysis` are valid; `PDF-Processing`, `-pdf`, and `pdf--processing` are invalid. [2]" }, { "label": "Optional companion directories", "text_md": "`scripts/` holds executable code, `references/` holds documentation agents load on demand, and `assets/` holds templates, images, and data files such as lookup tables and schemas. Languages depend on the agent; Python, Bash, and JavaScript are common. `skills-ref` validates `SKILL.md` frontmatter and the naming rules. [2]" }, { "label": "Three-stage token budgets", "text_md": "Metadata (~100 tokens) loads `name` and `description` at startup for every skill. Instructions (under 5000 tokens recommended) load the full `SKILL.md` body on activation, and that file should stay under 500 lines. Resources in `scripts/`, `references/`, or `assets/` load only when required (also summarized as Discovery, Activation, and Execution). [1][2]" } ] }, { "id": "well-known-discovery-mcp-bridging-governance-and-security", "heading": "Well-known discovery, MCP bridging, governance, and security", "body_md": "Because the core `SKILL.md` specification defines only the local folder layout, companion proposals and foundation governance address remote publication (`/.well-known/agent-skills/index.json` with per-artifact SHA-256 `digest` values), directory queries via the IETF Agent Directory Service draft (`draft-mp-agntcy-ads-03`) and `OASF`, MCP server bridging (`io.modelcontextprotocol/skills`), and stewardship under the Linux Foundation AAIF. [2][5][6][10][22]", "bullets": [ { "label": "Well-known index and live deployments", "text_md": "Cloudflare's discovery draft `0.2.0` (published 2026-01-17, updated 2026-03-12) serves `/.well-known/agent-skills/index.json` with `type` (`skill-md` or `archive`), `url`, and a SHA-256 `digest` (`Clients MUST verify artifact digests after download`), and stipulates that clients SHALL NOT execute files under `scripts/` by default. Among sampled live origin indexes, Cloudflare's developer documentation domain (`developers.cloudflare.com`) lists 19 `archive` skills (including `agents-sdk` and `wrangler`) on schema `https://schemas.agentskills.io/discovery/0.2.0/schema.json`, Vercel (`vercel.com`) lists 9 skills (including `deploy-to-vercel`), and Stripe (`docs.stripe.com`) lists 10 skills (including `connect-recommend`) at legacy `/.well-known/skills/index.json` using the `v0.1.0` `files` array format (`v0.2.0` is not backward-compatible with `v0.1.0`, so clients MUST inspect `$schema`). [6][19][23][24]" }, { "label": "IETF draft and OASF discovery", "text_md": "`draft-mp-agntcy-ads-03` (2 November 2026) is the Agent Directory Service for discovering agents with specific skills. It uses the Open Agentic Schema Framework (`OASF`) to ask which agents, skills, and costs fit a task. OASF versions `0.8.0`, `1.0.0`, and `1.1.0` show Skills, Domains, and Modules, plus codes Language Processing `[1]` and Language Understanding `[101]`. [22][25]" }, { "label": "Skills over MCP", "text_md": "The MCP `skills-over-mcp` working group maintains the Skills extension `io.modelcontextprotocol/skills` in `ext-skills`. SEP-2640 is Final and was merged on September 13, 2026. Current work covers implementation support, interoperability, and client behavior. [5]" }, { "label": "Donation to the Linux Foundation AAIF, security, and trust boundaries", "text_md": "On 2026-10-22 Anthropic donated Agent Skills to the AAIF under the Linux Foundation, including the name, logo, GitHub organization, and `agentskills.io` domain. A multi-company Technical Steering Committee guides the work, with David Soria Parra and Mahesh Murag as Lead Maintainers. A governance charter adopted on 4 November 2026 requires tagged specification releases with a changelog. The maintainer roster names Core Maintainers Aiden Cline, Nick Cooper, Colin Daymond Hanna, Harald Kirschner, and Kurtis Van Gent alongside Lead Maintainers David Soria Parra and Mahesh Murag, and the TSC Representative seat is not yet designated. Licensing is Apache 2.0 and CC BY 4.0. Because `SKILL.md` content is loaded directly into agent context and skills may bundle executable files under `scripts/`, malicious skills can inject prompt instructions, introduce vulnerabilities, or direct an agent to exfiltrate data and take unintended actions (Anthropic recommends installing skills only from trusted sources). In the specification, `allowed-tools` is an experimental pre-approved tool list (`Space-separated string of pre-approved tools the skill may use. (Experimental)`) rather than a sandbox, the SHA-256 `digest` in `index.json` verifies artifact integrity against the same-origin index rather than cryptographic publisher signatures, third-party registries are unvetted, and the AAIF roadmap's security guidance has not yet been published as a standalone specification. [2][6][10][13][15][16][26]" } ] } ], "v05_diagram": { "title": "Progressive disclosure", "heading": "Progressive disclosure", "mermaid": "flowchart TD\n Start[\"Agent startup\"] --> Meta[\"1. Metadata for every skill\\nname and description, about 100 tokens\"]\n Meta --> Match{\"Task matches a description?\"}\n Match -->|No| Idle[\"Leave the body unloaded\"]\n Match -->|Yes| Body[\"2. Instructions\\nfull SKILL.md body, under 5000 tokens recommended\"]\n Body --> More{\"A referenced file is required?\"}\n More -->|No| Act[\"Perform the task\"]\n More -->|Yes| Files[\"3. Resources, only as needed\\nscripts/, references/, or assets/\"]\n Files --> Act", "caption_md": "Agents load skills progressively. At startup the `name` and `description` fields load for every skill. When the skill is activated, the full `SKILL.md` body loads. Files in `scripts/`, `references/`, or `assets/` load only when required. [2]" }, "v05_wire_artifact": { "title": "SKILL.md", "heading": "SKILL.md", "lang": "markdown", "code": "---\nname: pdf-processing\ndescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.\nlicense: Apache-2.0\nmetadata:\n author: example-org\n version: \"1.0\"\n---", "caption_md": "Example `SKILL.md` YAML frontmatter with optional `license` and `metadata` fields alongside required `name` and `description`. [2]" }, "v05_counterparts": { "classic_analogues": [ { "name": "Repository README.md & CONTRIBUTING.md Conventions", "spec_or_rfc": "GitHub contributing guidelines", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Agent Skills requires a directory whose SKILL.md begins with YAML frontmatter, whose name must match the parent directory, and whose name and description fields are loaded before the Markdown body. [2]" } ], "agentic_peers": [ { "target_id": "agents-md", "target_name": "AGENTS.md", "relation_type": "complements", "relation_label": "Complements", "delta_md": "`AGENTS.md` is standard repository Markdown with no required fields where the closest file to the edited file wins, whereas Agent Skills is a directory whose `SKILL.md` loads `name` and `description` at startup before activating the body. [2][3]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "MCP uses JSON-RPC 2.0 messages over `stdio` or `Streamable HTTP` so servers can expose live `Resources`, `Prompts`, and `Tools`, whereas Agent Skills packages static workflow instructions and local companion files without defining a wire transport. [2][4]" }, { "target_id": "oasf", "target_name": "Open Agentic Schema Framework", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "OASF (`0.8.0`, `1.0.0`, `1.1.0`) defines a capability taxonomy with numeric class codes (such as `1` for Language Processing and `101` for Language Understanding) under Skills, Domains, and Modules, whereas Agent Skills bundles executable task instructions, `scripts/`, and `references/` in a skill directory. [2][25]" }, { "target_id": "llms-txt", "target_name": "llms.txt", "relation_type": "complements", "relation_label": "Complements", "delta_md": "`llms.txt` places a Markdown index at a website root or subpath with brief guidance and links to detailed `.md` pages, whereas Agent Skills packages reusable procedural workflows as version-controlled local or workspace folders. [1][27]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (19 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Well-known domain skill publishers", "col4_header": "Discovery endpoint & bundled skills", "note_md": "HTTP 200 discovery index probes establish endpoint presence as of the stated check date (with Stripe serving the `v0.1.0` `files`-array schema and Cloudflare and Vercel serving the `0.2.0` schema), while third-party directory and marketplace totals in the tables and censuses below represent vendor-declared or self-reported listing and install counters rather than deduplicated or security-vetted skills. [6][26]", "rows": [ { "actor": "Cloudflare", "role": "Well-known skill publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "HTTP 200 `application/json` at `/.well-known/agent-skills/index.json` (`0.2.0` schema) listing 19 `archive` skills including `agents-sdk`, `durable-objects`, and `wrangler`.", "source_md": "[Cloudflare agent-skills index](https://developers.cloudflare.com/.well-known/agent-skills/index.json) [6][23]" }, { "actor": "Vercel", "role": "Well-known skill publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "HTTP 200 `application/json` at `/.well-known/agent-skills/index.json` (`0.2.0` schema) listing 9 skills across `skill-md` (`deploy-to-vercel`) and `archive` entries.", "source_md": "[Vercel agent-skills index](https://vercel.com/.well-known/agent-skills/index.json) [24]" }, { "actor": "Stripe", "role": "Well-known skill publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "HTTP 200 `application/json` at legacy `/.well-known/skills/index.json` listing 10 skills (including `connect-recommend`) using `v0.1.0` `files` arrays starting with `SKILL.md` (incompatible with `v0.2.0`; clients MUST check `$schema`).", "source_md": "[Stripe skills index](https://docs.stripe.com/.well-known/skills/index.json) [6][19]" } ] }, "side_b": { "visible": true, "heading": "Agent harnesses, IDEs & API runtimes", "col4_header": "Skill loading surface & scope", "note_md": null, "rows": [ { "actor": "Claude Code", "role": "CLI & IDE coding agent", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Loads `~/.claude/skills//SKILL.md` on demand and adds Claude Code extensions (subagents, invocation control, dynamic context injection).", "source_md": "[Extend Claude with skills](https://code.claude.com/docs/en/skills) [8]" }, { "actor": "Claude.ai and Claude Desktop", "role": "Web & desktop host apps", "status": "Supported", "status_display": "Supported · as of 2025-10-16", "col4_md": "Supports uploaded and admin-provisioned skills on `claude.ai` and Desktop, strictly validating the six standard `SKILL.md` frontmatter keys.", "source_md": "[Introducing Agent Skills](https://claude.com/resources/articles/skills) [11] · [Extend Claude with skills](https://code.claude.com/docs/en/skills) [8] · [Skills for organizations](https://claude.com/resources/articles/organization-skills-and-directory) [12]" }, { "actor": "Claude API", "role": "API runtime", "status": "Supported (preview)", "status_display": "Supported (preview) · as of 2025-10-16", "col4_md": "Exposes `/v1/skills` for Messages API skill versioning; requires the Code Execution Tool beta and standard `SKILL.md` frontmatter.", "source_md": "[Introducing Agent Skills](https://claude.com/resources/articles/skills) [11] · [Extend Claude with skills](https://code.claude.com/docs/en/skills) [8]" }, { "actor": "Cursor", "role": "IDE and CLI coding agent", "status": "Supported", "status_display": "Supported · as of 2026-01-22", "col4_md": "Discovers `SKILL.md` in `.agents/skills/`, `.cursor/skills/`, `~/.claude/skills/`, and `~/.codex/skills/` across editor and CLI since Cursor `2.4`.", "source_md": "[Cursor 2.4 changelog](https://cursor.com/changelog/2-4) [28] · [Cursor Agent Skills](https://cursor.com/docs/skills) [29]" }, { "actor": "GitHub Copilot in VS Code", "role": "IDE & CLI coding agent", "status": "Supported", "status_display": "Supported · as of 2025-12-18", "col4_md": "Loads skills from `~/.copilot/skills/`, `~/.claude/skills/`, and `~/.agents/skills/` across VS Code, Copilot CLI, and Copilot coding agent.", "source_md": "[GitHub Copilot now supports Agent Skills](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/) [30] · [VS Code Agent Skills](https://code.visualstudio.com/docs/agent-customization/agent-skills) [18]" }, { "actor": "OpenAI Codex", "role": "Coding agent & app", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Scans `$CWD/.agents/skills`, `$REPO_ROOT/.agents/skills`, `$HOME/.agents/skills`, and `/etc/codex/skills` for `SKILL.md` (plus optional `agents/openai.yaml`), capping startup metadata via `skills.max_context_tokens`.", "source_md": "[Build skills](https://learn.chatgpt.com/docs/build-skills) [21] · [Donating Agent Skills](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) [10]" }, { "actor": "Gemini CLI", "role": "Agent CLI", "status": "Supported", "status_display": "Supported · as of 2026-01-27", "col4_md": "Discovers `SKILL.md` in `.agents/skills/` and `.gemini/skills/`, calling `activate_skill` with user consent before injecting instructions.", "source_md": "[Gemini CLI Agent Skills](https://geminicli.com/docs/cli/skills/) [9] · [Gemini CLI release notes](https://geminicli.com/docs/changelogs/) [31]" }, { "actor": "goose", "role": "Open-source agent harness", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Loads `SKILL.md` subdirectories from `~/.agents/skills/` and compatibility paths `.goose/skills/`, `.claude/skills/`, and `~/.claude/skills/`.", "source_md": "[goose Agent Skills](https://goose-docs.ai/docs/guides/context-engineering/using-skills/) [32]" }, { "actor": "Amp", "role": "Coding agent", "status": "Supported", "status_display": "Supported · as of 2025-12-10", "col4_md": "Lazily loads skill instructions from workspace `.agents/skills/`, `~/.config/agents/skills/`, `.claude/skills/`, and `~/.claude/skills/` since `2025-12-10`.", "source_md": "[Amp Agent Skills](https://ampcode.com/news/agent-skills) [33]" }, { "actor": "OpenCode", "role": "Agent harness", "status": "Listed integration", "status_display": "Listed integration · as of 2026-10-22", "col4_md": "Listed on the `agentskills.io` client directory, which links to `https://opencode.ai/` (docs: `https://opencode.ai/docs/skills/`), and cited by Anthropic as having a community loader.", "source_md": "[Donating Agent Skills](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) [10] · [Agent Skills clients](https://agentskills.io/home) [1]" } ] }, "additional_tables": [ { "visible": true, "heading": "Reference skill repositories & registries", "col4_header": "Catalog structure & distribution", "note_md": "Directory and marketplace counts (`25,346`, `195,000+`, `275,000+`, `195+`) are vendor-declared or self-reported listing counters rather than deduplicated or security-vetted skills. [34][35]", "rows": [ { "actor": "anthropics/skills", "role": "Reference & document skill repository", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Claude reference repo and plugin marketplace bundling Apache 2.0 examples and source-available `skills/docx`, `skills/pdf`, `skills/pptx`, and `skills/xlsx`.", "source_md": "[anthropics/skills](https://github.com/anthropics/skills) [36]" }, { "actor": "Hugging Face", "role": "Skill repository & plugin bundle", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "`huggingface/skills` repository publishing `SKILL.md` folders led by `hf-cli`, with Claude, Cursor, `gemini-extension.json`, and `agentsmd/AGENTS.md` fallback manifests.", "source_md": "[huggingface/skills](https://github.com/huggingface/skills) [37]" }, { "actor": "Awesome Agent Skills Directories", "role": "Index of skill directories", "status": "Listed", "status_display": "Listed · as of 2026-10-29", "col4_md": "Directory index checked `2026-10-29`; Smithery at `25,346` (self-reported directory listing counter).", "source_md": "[Awesome Agent Skills Directories](https://github.com/vawe-hq/awesome-agent-skills-directories/blob/main/README.md) [38]" }, { "actor": "GuildSkills", "role": "Cross-agent SKILL.md registry", "status": "Listed", "status_display": "Listed · checked 2026-11-06", "col4_md": "Vendor-declared registry counter of `195,000+` SKILL.md files and `30+` clients (self-reported, not deduplicated or security-vetted).", "source_md": "[GuildSkills](https://guildskills.com/) [34]" }, { "actor": "agentskill.sh", "role": "Agent skills marketplace", "status": "Listed", "status_display": "Listed · checked 2026-11-06", "col4_md": "Vendor-declared marketplace counter listing `275,000+` skills for `20+` AI tools (self-reported, not deduplicated or security-vetted).", "source_md": "[agentskill.sh](https://agentskill.sh/) [35]" }, { "actor": "AgenticSkills", "role": "Curated SKILL.md directory", "status": "Listed", "status_display": "Listed · as of 2026-11-06", "col4_md": "Vendor-declared curated `v1.7.0` index: `195+` skills and `139` MCP servers.", "source_md": "[AgenticSkills](https://agenticskills.io) [39]" } ] } ], "censuses": [ { "label": "Anthropic and AAIF donation announcements (2026-10-22)", "as_of": "2026-10-22", "value_md": "Anthropic and the Agentic AI Foundation report that more than 70 agent platforms support Agent Skills since December 2025 (with 46 named clients listed in the agentskills.io showcase) and that over 1 million skills have been listed on the skills.sh registry with nearly 280 million cumulative installations over seven months (vendor-declared platform, listing, and cumulative installation counters, not deduplicated or security-vetted skills). [10][13]" }, { "label": "Live /.well-known/agent-skills/ and /.well-known/skills/ HTTP probes (2026-10-30)", "as_of": "2026-10-30", "value_md": "Across three sampled live publisher discovery endpoints totaling 38 skill entries, Cloudflare indexes 19 skills (agents-sdk through wrangler) as discovery v0.2.0 archive bundles, Vercel indexes 9 skills mixing v0.2.0 skill-md and archive entries (including deploy-to-vercel and writing-guidelines), and Stripe indexes 10 skills at legacy /.well-known/skills/index.json (connect-recommend through upgrade-stripe) using per-skill v0.1.0 files arrays (the v0.2.0 index format is not backward-compatible with v0.1.0; clients MUST check $schema). [6][19][23][24]" }, { "label": "Awesome Agent Skills Directories (rows checked 2026-10-29)", "as_of": "2026-10-29", "value_md": "The vawe-hq/awesome-agent-skills-directories index (with every row checked on 2026-10-29) records Smithery at 25,346 skills, indexes VoltAgent/awesome-agent-skills, and notes that vercel-labs/skills provides the npx skills installer feeding skills.sh (self-reported directory listing counters, not deduplicated or security-vetted skills). [38]" }, { "label": "GuildSkills homepage", "as_of": null, "value_md": "GuildSkills states that its registry holds 195,000+ SKILL.md files compatible with Hermes Agent, Cursor, OpenAI Codex, Gemini CLI, OpenCode, Goose, Letta, Roo Code, Claude Code, and 30+ more AI agent clients (vendor-declared homepage listing counter, not deduplicated or security-vetted skills). [34]" }, { "label": "agentskill.sh directory homepage", "as_of": null, "value_md": "The agentskill.sh marketplace reports listing 275,000+ skills for Claude Code, Cursor, Copilot, Windsurf, Zed, and 20+ AI tools (vendor-declared marketplace listing counter, not deduplicated or security-vetted skills). [35]" }, { "label": "agenticskills.io index v1.7.0 (NOV 6 2026)", "as_of": "2026-11-06", "value_md": "The AgenticSkills directory (version v1.7.0, updated November 6, 2026) reports 195+ curated skills, 139 MCP servers, and 9 platforms (vendor-declared directory counter). [39]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "okf", "target_name": "Open Knowledge Format", "relation_label": "Complements", "delta": "A skill is a SKILL.md directory with name and description; OKF's only required key is type.", "item_md": "**[Open Knowledge Format](/protocols/okf/)** (Complements) — A skill is a SKILL.md directory with name and description; OKF's only required key is type." }, { "target_id": "acip", "target_name": "Agent Context Interchange Protocol", "relation_label": "Complements", "delta": "Agent Skills stay a skill package, and ACIP's resolution receipt records when a skill file was one of the sources the host applied.", "item_md": "**[Agent Context Interchange Protocol](/protocols/acip/)** (Complements) — Agent Skills stay a skill package, and ACIP's resolution receipt records when a skill file was one of the sources the host applied." }, { "item_md": "**[Act protocols](/category/act/)** — Category index for `act` standards." } ], "v05_compiled_md": "---\nid: anthropic-agent-skills-format\ntitle: \"Agent Skills\"\ntier: flagship\nlifecycle_status: active\ncategory: act\nform: document-format\nwire_archetype: harnesses_rpc_ui\nspec_url: https://agentskills.io/specification\nlast_checked: 2026-11-11\n---\n\n# Agent Skills\n\n**Category:** [Act](/category/act/) (`act`) · **Form:** Document format (`document-format`) · **Last checked:** 2026-11-11\n\n> *This page covers Agent Skills, the open directory and `SKILL.md` packaging format originated by Anthropic and stewarded by the Agentic AI Foundation (AAIF) for loading procedural instructions and scripts on demand. It is distinct from [AGENTS.md](/protocols/agents-md/), a repository-wide Markdown instruction file loaded automatically from the directory tree, and the [Model Context Protocol](/protocols/mcp/), a JSON-RPC 2.0 client-server protocol for tools and resources (which also defines the companion `io.modelcontextprotocol/skills` extension). Web-hosted skill indexes at `/.well-known/agent-skills/index.json` are specified in a separate Cloudflare draft RFC, and multi-resource catalogs are covered under [Agentic Resource Discovery (ARD)](/protocols/ard/). [1][2][3][4][5][6][7]*\n\n> **In brief:** Agent Skills is a portable directory standard that lets developers package specialized workflows, domain playbooks, and helper scripts into reusable folders that AI agents load on demand. Instead of cramming every workflow into always-on workspace files like `CLAUDE.md` or `GEMINI.md` and burning context tokens on every turn, an agent reads only the brief `name` and `description` YAML fields at startup and loads the full `SKILL.md` body and bundled `scripts/` only when a task matches. [1][8][9]\n\n**Agent Skills** is an open format, originated by Anthropic for Claude Code, that packages procedural instructions and resources into portable directories an AI agent loads on demand. [1][10] Launched across Claude apps, Claude Code, and the API on 2025-10-16 and published as an open standard on 2025-12-18, it was donated to the Linux Foundation's Agentic AI Foundation (AAIF) on 2026-10-22 under a multi-company Technical Steering Committee with Lead Maintainers David Soria Parra and Mahesh Murag. [10][11][12][13] Each skill directory contains a `SKILL.md` file with YAML frontmatter (required `name` matching the parent directory and `description`, plus optional `license`, `compatibility`, `metadata`, and experimental `allowed-tools`) and Markdown instructions, alongside optional `scripts/`, `references/`, and `assets/` subdirectories validated by `skills-ref`. [2] Licensed under Apache 2.0 and CC BY 4.0 (`agentskills/agentskills`, created 2025-12-16). [13][14] Companion specifications define `/.well-known/agent-skills/index.json` discovery (Cloudflare draft `0.2.0`, updated 2026-03-12) and the MCP extension `io.modelcontextprotocol/skills` (SEP-2640, merged September 13, 2026). [5][6] A governance charter and maintainer roster adopted on 4 November 2026 require tagged, changelogged specification releases under individual-capacity governance, naming two Lead Maintainers and five Core Maintainers while leaving the TSC Representative seat undesignated. [15][16]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Act](/category/act/) (`act`) |\n| **Form** | Document format (`document-format`) |\n| **Originated by** | Anthropic; built for Claude Code, launched 2025-10-16, and published as an open standard on 2025-12-18 [10][11][12] |\n| **Governed by** | AAIF under the Linux Foundation since 2026-10-22; Lead Maintainers David Soria Parra and Mahesh Murag; Core Maintainers Aiden Cline, Nick Cooper, Colin Daymond Hanna, Harald Kirschner, and Kurtis Van Gent (4 November 2026); TSC Representative not yet designated [10][13][16] |\n| **Track** | Foundation / Consortium Specification (`linux-foundation`); Agentic AI Foundation project [13][17] |\n| **Status** | Open standard (2025-12-18); AAIF project since 2026-10-22; governance adopted 4 November 2026 requires tagged specification releases with a changelog [12][15][17] |\n| **Version** | Unversioned specification (`agentskills/agentskills`, created 2025-12-16); separate Cloudflare discovery RFC is draft `0.2.0` (published 2026-01-17, updated 2026-03-12) [2][6][14] |\n| **Message format** | Skill folder with `SKILL.md` containing YAML frontmatter (`name`, `description`; optional `license`, `compatibility`, `metadata`, `allowed-tools`) and Markdown [2] |\n| **Specification** | [Specification - Agent Skills](https://agentskills.io/specification); discovery draft [Agent Skills Discovery via Well-Known URIs](https://github.com/cloudflare/agent-skills-discovery-rfc) [2][6] |\n| **Found at** | Local skill directories (`.agents/skills/`, `~/.claude/skills/`, `~/.copilot/skills/`); web index `/.well-known/agent-skills/index.json` (legacy `/.well-known/skills/index.json`) [2][6][18][19] |\n| **IANA registration** | None in core specification; Cloudflare draft `0.2.0` proposes registering `agent-skills` as a well-known URI suffix [6][20] |\n| **Licence** | Apache License 2.0 (`agentskills/agentskills`) and CC BY 4.0 for specification documentation [13][14] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [`SKILL.md` package format and progressive disclosure](#skill-md-package-format-and-progressive-disclosure)\n3. [Well-known discovery, MCP bridging, governance, and security](#well-known-discovery-mcp-bridging-governance-and-security)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nAgents often lack the procedural context real work requires, yet keeping long reference instructions in always-on workspace files (`CLAUDE.md` or `GEMINI.md`) consumes context-window tokens on every turn. Packaging domain and team workflows into version-controlled skill folders lets an agent leave long reference material unloaded until a task requires it. [1][8][9] Agent Skills uses three-stage progressive disclosure so agents scan only lightweight `name` and `description` frontmatter at startup, read the `SKILL.md` instruction body only when a task matches a skill's description, and load companion files from `scripts/`, `references/`, or `assets/` only during execution. [1] The specification standardizes the directory and six frontmatter fields, not one shared runtime. `allowed-tools` is experimental and support may vary between agent implementations. In Claude apps, a non-spec key such as `argument-hint` fails packaging with a hard error, while Claude Code dynamic context injection does not run in `claude.ai` chat or through the API. OpenAI Codex optionally reads an `agents/openai.yaml` file, and discovery clients SHALL NOT execute scripts by default. [2][6][8][21]\n\n### Progressive disclosure\n\n```mermaid\nflowchart TD\n Start[\"Agent startup\"] --> Meta[\"1. Metadata for every skill\\nname and description, about 100 tokens\"]\n Meta --> Match{\"Task matches a description?\"}\n Match -->|No| Idle[\"Leave the body unloaded\"]\n Match -->|Yes| Body[\"2. Instructions\\nfull SKILL.md body, under 5000 tokens recommended\"]\n Body --> More{\"A referenced file is required?\"}\n More -->|No| Act[\"Perform the task\"]\n More -->|Yes| Files[\"3. Resources, only as needed\\nscripts/, references/, or assets/\"]\n Files --> Act\n```\n\n*Agents load skills progressively. At startup the `name` and `description` fields load for every skill. When the skill is activated, the full `SKILL.md` body loads. Files in `scripts/`, `references/`, or `assets/` load only when required. [2]*\n\n### SKILL.md\n\n```markdown\n---\nname: pdf-processing\ndescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.\nlicense: Apache-2.0\nmetadata:\n author: example-org\n version: \"1.0\"\n---\n```\n\n*Example `SKILL.md` YAML frontmatter with optional `license` and `metadata` fields alongside required `name` and `description`. [2]*\n\n---\n\n## `SKILL.md` package format and progressive disclosure\n\nA skill package is a directory centered on a `SKILL.md` file whose YAML frontmatter declares the skill's identity and metadata before the Markdown instructions. Optional `scripts/`, `references/`, and `assets/` subdirectories remain unloaded until an activated workflow references them. [2]\n\n- **Six frontmatter fields:** YAML frontmatter defines two required fields (`name` and non-empty `description` of at most 1024 characters) and four optional fields: `license` (a license name or reference to a bundled license file), `compatibility` (at most 500 characters describing environment requirements), string-mapped `metadata`, and experimental space-separated `allowed-tools` (whose support may vary between agent implementations). [2]\n- **Name constraints, directory matching, and spec table vs. prose wording:** Required `name` (1–64 characters) must match the parent directory name and must not start, end, or repeat hyphens (`--`); in a source-side phrasing difference within the specification, the summary table states `lowercase letters, numbers, and hyphens` whereas the field-constraints prose specifies `unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)`. `pdf-processing` and `data-analysis` are valid; `PDF-Processing`, `-pdf`, and `pdf--processing` are invalid. [2]\n- **Optional companion directories:** `scripts/` holds executable code, `references/` holds documentation agents load on demand, and `assets/` holds templates, images, and data files such as lookup tables and schemas. Languages depend on the agent; Python, Bash, and JavaScript are common. `skills-ref` validates `SKILL.md` frontmatter and the naming rules. [2]\n- **Three-stage token budgets:** Metadata (~100 tokens) loads `name` and `description` at startup for every skill. Instructions (under 5000 tokens recommended) load the full `SKILL.md` body on activation, and that file should stay under 500 lines. Resources in `scripts/`, `references/`, or `assets/` load only when required (also summarized as Discovery, Activation, and Execution). [1][2]\n\n---\n\n## Well-known discovery, MCP bridging, governance, and security\n\nBecause the core `SKILL.md` specification defines only the local folder layout, companion proposals and foundation governance address remote publication (`/.well-known/agent-skills/index.json` with per-artifact SHA-256 `digest` values), directory queries via the IETF Agent Directory Service draft (`draft-mp-agntcy-ads-03`) and `OASF`, MCP server bridging (`io.modelcontextprotocol/skills`), and stewardship under the Linux Foundation AAIF. [2][5][6][10][22]\n\n- **Well-known index and live deployments:** Cloudflare's discovery draft `0.2.0` (published 2026-01-17, updated 2026-03-12) serves `/.well-known/agent-skills/index.json` with `type` (`skill-md` or `archive`), `url`, and a SHA-256 `digest` (`Clients MUST verify artifact digests after download`), and stipulates that clients SHALL NOT execute files under `scripts/` by default. Among sampled live origin indexes, Cloudflare's developer documentation domain (`developers.cloudflare.com`) lists 19 `archive` skills (including `agents-sdk` and `wrangler`) on schema `https://schemas.agentskills.io/discovery/0.2.0/schema.json`, Vercel (`vercel.com`) lists 9 skills (including `deploy-to-vercel`), and Stripe (`docs.stripe.com`) lists 10 skills (including `connect-recommend`) at legacy `/.well-known/skills/index.json` using the `v0.1.0` `files` array format (`v0.2.0` is not backward-compatible with `v0.1.0`, so clients MUST inspect `$schema`). [6][19][23][24]\n- **IETF draft and OASF discovery:** `draft-mp-agntcy-ads-03` (2 November 2026) is the Agent Directory Service for discovering agents with specific skills. It uses the Open Agentic Schema Framework (`OASF`) to ask which agents, skills, and costs fit a task. OASF versions `0.8.0`, `1.0.0`, and `1.1.0` show Skills, Domains, and Modules, plus codes Language Processing `[1]` and Language Understanding `[101]`. [22][25]\n- **Skills over MCP:** The MCP `skills-over-mcp` working group maintains the Skills extension `io.modelcontextprotocol/skills` in `ext-skills`. SEP-2640 is Final and was merged on September 13, 2026. Current work covers implementation support, interoperability, and client behavior. [5]\n- **Donation to the Linux Foundation AAIF, security, and trust boundaries:** On 2026-10-22 Anthropic donated Agent Skills to the AAIF under the Linux Foundation, including the name, logo, GitHub organization, and `agentskills.io` domain. A multi-company Technical Steering Committee guides the work, with David Soria Parra and Mahesh Murag as Lead Maintainers. A governance charter adopted on 4 November 2026 requires tagged specification releases with a changelog. The maintainer roster names Core Maintainers Aiden Cline, Nick Cooper, Colin Daymond Hanna, Harald Kirschner, and Kurtis Van Gent alongside Lead Maintainers David Soria Parra and Mahesh Murag, and the TSC Representative seat is not yet designated. Licensing is Apache 2.0 and CC BY 4.0. Because `SKILL.md` content is loaded directly into agent context and skills may bundle executable files under `scripts/`, malicious skills can inject prompt instructions, introduce vulnerabilities, or direct an agent to exfiltrate data and take unintended actions (Anthropic recommends installing skills only from trusted sources). In the specification, `allowed-tools` is an experimental pre-approved tool list (`Space-separated string of pre-approved tools the skill may use. (Experimental)`) rather than a sandbox, the SHA-256 `digest` in `index.json` verifies artifact integrity against the same-origin index rather than cryptographic publisher signatures, third-party registries are unvetted, and the AAIF roadmap's security guidance has not yet been published as a standalone specification. [2][6][10][13][15][16][26]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Repository README.md & CONTRIBUTING.md Conventions** | `GitHub contributing guidelines` | Analogous to classic standard | Agent Skills requires a directory whose SKILL.md begins with YAML frontmatter, whose name must match the parent directory, and whose name and description fields are loaded before the Markdown body. [2] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[AGENTS.md](/protocols/agents-md/)** | Complements | `AGENTS.md` is standard repository Markdown with no required fields where the closest file to the edited file wins, whereas Agent Skills is a directory whose `SKILL.md` loads `name` and `description` at startup before activating the body. [2][3] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | MCP uses JSON-RPC 2.0 messages over `stdio` or `Streamable HTTP` so servers can expose live `Resources`, `Prompts`, and `Tools`, whereas Agent Skills packages static workflow instructions and local companion files without defining a wire transport. [2][4] |\n| **[Open Agentic Schema Framework](/protocols/oasf/)** | Peer alternative | OASF (`0.8.0`, `1.0.0`, `1.1.0`) defines a capability taxonomy with numeric class codes (such as `1` for Language Processing and `101` for Language Understanding) under Skills, Domains, and Modules, whereas Agent Skills bundles executable task instructions, `scripts/`, and `references/` in a skill directory. [2][25] |\n| **[llms.txt](/protocols/llms-txt/)** | Complements | `llms.txt` places a Markdown index at a website root or subpath with brief guidance and links to detailed `.md` pages, whereas Agent Skills packages reusable procedural workflows as version-controlled local or workspace folders. [1][27] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (19 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Well-known domain skill publishers\n\nHTTP 200 discovery index probes establish endpoint presence as of the stated check date (with Stripe serving the `v0.1.0` `files`-array schema and Cloudflare and Vercel serving the `0.2.0` schema), while third-party directory and marketplace totals in the tables and censuses below represent vendor-declared or self-reported listing and install counters rather than deduplicated or security-vetted skills. [6][26]\n\n| Actor | Role | Status | Discovery endpoint & bundled skills | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Cloudflare** | Well-known skill publisher | Live (HTTP 200) · checked 2026-10-30 | HTTP 200 `application/json` at `/.well-known/agent-skills/index.json` (`0.2.0` schema) listing 19 `archive` skills including `agents-sdk`, `durable-objects`, and `wrangler`. | [Cloudflare agent-skills index](https://developers.cloudflare.com/.well-known/agent-skills/index.json) [6][23] |\n| **Vercel** | Well-known skill publisher | Live (HTTP 200) · checked 2026-10-30 | HTTP 200 `application/json` at `/.well-known/agent-skills/index.json` (`0.2.0` schema) listing 9 skills across `skill-md` (`deploy-to-vercel`) and `archive` entries. | [Vercel agent-skills index](https://vercel.com/.well-known/agent-skills/index.json) [24] |\n| **Stripe** | Well-known skill publisher | Live (HTTP 200) · checked 2026-10-30 | HTTP 200 `application/json` at legacy `/.well-known/skills/index.json` listing 10 skills (including `connect-recommend`) using `v0.1.0` `files` arrays starting with `SKILL.md` (incompatible with `v0.2.0`; clients MUST check `$schema`). | [Stripe skills index](https://docs.stripe.com/.well-known/skills/index.json) [6][19] |\n\n### Agent harnesses, IDEs & API runtimes\n\n| Actor | Role | Status | Skill loading surface & scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Claude Code** | CLI & IDE coding agent | Supported · checked 2026-10-30 | Loads `~/.claude/skills//SKILL.md` on demand and adds Claude Code extensions (subagents, invocation control, dynamic context injection). | [Extend Claude with skills](https://code.claude.com/docs/en/skills) [8] |\n| **Claude.ai and Claude Desktop** | Web & desktop host apps | Supported · as of 2025-10-16 | Supports uploaded and admin-provisioned skills on `claude.ai` and Desktop, strictly validating the six standard `SKILL.md` frontmatter keys. | [Introducing Agent Skills](https://claude.com/resources/articles/skills) [11] · [Extend Claude with skills](https://code.claude.com/docs/en/skills) [8] · [Skills for organizations](https://claude.com/resources/articles/organization-skills-and-directory) [12] |\n| **Claude API** | API runtime | Supported (preview) · as of 2025-10-16 | Exposes `/v1/skills` for Messages API skill versioning; requires the Code Execution Tool beta and standard `SKILL.md` frontmatter. | [Introducing Agent Skills](https://claude.com/resources/articles/skills) [11] · [Extend Claude with skills](https://code.claude.com/docs/en/skills) [8] |\n| **Cursor** | IDE and CLI coding agent | Supported · as of 2026-01-22 | Discovers `SKILL.md` in `.agents/skills/`, `.cursor/skills/`, `~/.claude/skills/`, and `~/.codex/skills/` across editor and CLI since Cursor `2.4`. | [Cursor 2.4 changelog](https://cursor.com/changelog/2-4) [28] · [Cursor Agent Skills](https://cursor.com/docs/skills) [29] |\n| **GitHub Copilot in VS Code** | IDE & CLI coding agent | Supported · as of 2025-12-18 | Loads skills from `~/.copilot/skills/`, `~/.claude/skills/`, and `~/.agents/skills/` across VS Code, Copilot CLI, and Copilot coding agent. | [GitHub Copilot now supports Agent Skills](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/) [30] · [VS Code Agent Skills](https://code.visualstudio.com/docs/agent-customization/agent-skills) [18] |\n| **OpenAI Codex** | Coding agent & app | Supported · checked 2026-10-30 | Scans `$CWD/.agents/skills`, `$REPO_ROOT/.agents/skills`, `$HOME/.agents/skills`, and `/etc/codex/skills` for `SKILL.md` (plus optional `agents/openai.yaml`), capping startup metadata via `skills.max_context_tokens`. | [Build skills](https://learn.chatgpt.com/docs/build-skills) [21] · [Donating Agent Skills](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) [10] |\n| **Gemini CLI** | Agent CLI | Supported · as of 2026-01-27 | Discovers `SKILL.md` in `.agents/skills/` and `.gemini/skills/`, calling `activate_skill` with user consent before injecting instructions. | [Gemini CLI Agent Skills](https://geminicli.com/docs/cli/skills/) [9] · [Gemini CLI release notes](https://geminicli.com/docs/changelogs/) [31] |\n| **goose** | Open-source agent harness | Supported · checked 2026-10-30 | Loads `SKILL.md` subdirectories from `~/.agents/skills/` and compatibility paths `.goose/skills/`, `.claude/skills/`, and `~/.claude/skills/`. | [goose Agent Skills](https://goose-docs.ai/docs/guides/context-engineering/using-skills/) [32] |\n| **Amp** | Coding agent | Supported · as of 2025-12-10 | Lazily loads skill instructions from workspace `.agents/skills/`, `~/.config/agents/skills/`, `.claude/skills/`, and `~/.claude/skills/` since `2025-12-10`. | [Amp Agent Skills](https://ampcode.com/news/agent-skills) [33] |\n| **OpenCode** | Agent harness | Listed integration · as of 2026-10-22 | Listed on the `agentskills.io` client directory, which links to `https://opencode.ai/` (docs: `https://opencode.ai/docs/skills/`), and cited by Anthropic as having a community loader. | [Donating Agent Skills](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) [10] · [Agent Skills clients](https://agentskills.io/home) [1] |\n\n### Reference skill repositories & registries\n\nDirectory and marketplace counts (`25,346`, `195,000+`, `275,000+`, `195+`) are vendor-declared or self-reported listing counters rather than deduplicated or security-vetted skills. [34][35]\n\n| Actor | Role | Status | Catalog structure & distribution | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **anthropics/skills** | Reference & document skill repository | Supported · checked 2026-10-30 | Claude reference repo and plugin marketplace bundling Apache 2.0 examples and source-available `skills/docx`, `skills/pdf`, `skills/pptx`, and `skills/xlsx`. | [anthropics/skills](https://github.com/anthropics/skills) [36] |\n| **Hugging Face** | Skill repository & plugin bundle | Supported · checked 2026-10-30 | `huggingface/skills` repository publishing `SKILL.md` folders led by `hf-cli`, with Claude, Cursor, `gemini-extension.json`, and `agentsmd/AGENTS.md` fallback manifests. | [huggingface/skills](https://github.com/huggingface/skills) [37] |\n| **Awesome Agent Skills Directories** | Index of skill directories | Listed · as of 2026-10-29 | Directory index checked `2026-10-29`; Smithery at `25,346` (self-reported directory listing counter). | [Awesome Agent Skills Directories](https://github.com/vawe-hq/awesome-agent-skills-directories/blob/main/README.md) [38] |\n| **GuildSkills** | Cross-agent SKILL.md registry | Listed · checked 2026-11-06 | Vendor-declared registry counter of `195,000+` SKILL.md files and `30+` clients (self-reported, not deduplicated or security-vetted). | [GuildSkills](https://guildskills.com/) [34] |\n| **agentskill.sh** | Agent skills marketplace | Listed · checked 2026-11-06 | Vendor-declared marketplace counter listing `275,000+` skills for `20+` AI tools (self-reported, not deduplicated or security-vetted). | [agentskill.sh](https://agentskill.sh/) [35] |\n| **AgenticSkills** | Curated SKILL.md directory | Listed · as of 2026-11-06 | Vendor-declared curated `v1.7.0` index: `195+` skills and `139` MCP servers. | [AgenticSkills](https://agenticskills.io) [39] |\n\n### Ecosystem censuses\n\n- **Anthropic and AAIF donation announcements (2026-10-22)** (*as of 2026-10-22*): Anthropic and the Agentic AI Foundation report that more than 70 agent platforms support Agent Skills since December 2025 (with 46 named clients listed in the agentskills.io showcase) and that over 1 million skills have been listed on the skills.sh registry with nearly 280 million cumulative installations over seven months (vendor-declared platform, listing, and cumulative installation counters, not deduplicated or security-vetted skills). [10][13]\n- **Live /.well-known/agent-skills/ and /.well-known/skills/ HTTP probes (2026-10-30)** (*as of 2026-10-30*): Across three sampled live publisher discovery endpoints totaling 38 skill entries, Cloudflare indexes 19 skills (agents-sdk through wrangler) as discovery v0.2.0 archive bundles, Vercel indexes 9 skills mixing v0.2.0 skill-md and archive entries (including deploy-to-vercel and writing-guidelines), and Stripe indexes 10 skills at legacy /.well-known/skills/index.json (connect-recommend through upgrade-stripe) using per-skill v0.1.0 files arrays (the v0.2.0 index format is not backward-compatible with v0.1.0; clients MUST check $schema). [6][19][23][24]\n- **Awesome Agent Skills Directories (rows checked 2026-10-29)** (*as of 2026-10-29*): The vawe-hq/awesome-agent-skills-directories index (with every row checked on 2026-10-29) records Smithery at 25,346 skills, indexes VoltAgent/awesome-agent-skills, and notes that vercel-labs/skills provides the npx skills installer feeding skills.sh (self-reported directory listing counters, not deduplicated or security-vetted skills). [38]\n- **GuildSkills homepage**: GuildSkills states that its registry holds 195,000+ SKILL.md files compatible with Hermes Agent, Cursor, OpenAI Codex, Gemini CLI, OpenCode, Goose, Letta, Roo Code, Claude Code, and 30+ more AI agent clients (vendor-declared homepage listing counter, not deduplicated or security-vetted skills). [34]\n- **agentskill.sh directory homepage**: The agentskill.sh marketplace reports listing 275,000+ skills for Claude Code, Cursor, Copilot, Windsurf, Zed, and 20+ AI tools (vendor-declared marketplace listing counter, not deduplicated or security-vetted skills). [35]\n- **agenticskills.io index v1.7.0 (NOV 6 2026)** (*as of 2026-11-06*): The AgenticSkills directory (version v1.7.0, updated November 6, 2026) reports 195+ curated skills, 139 MCP servers, and 9 platforms (vendor-declared directory counter). [39]\n\n---\n\n## See also\n\n- **[Open Knowledge Format](/protocols/okf/)** *(Complements)* — A skill is a SKILL.md directory with name and description; OKF's only required key is type.\n- **[Agent Context Interchange Protocol](/protocols/acip/)** *(Complements)* — Agent Skills stay a skill package, and ACIP's resolution receipt records when a skill file was one of the sources the host applied.\n- **Category:** [Act protocols](/category/act/)\n\n---\n\n## References\n\n1. Agent Skills, *Agent Skills Overview* (checked 2026-10-30) — \n2. Agent Skills, *Specification - Agent Skills* (checked 2026-10-30) — \n3. AGENTS.md contributors (OpenAI Codex, Amp, Jules from Google, Cursor, and Factory), *AGENTS.md* (checked 2026-10-30) — \n4. Model Context Protocol, *Specification* (version 2026-07-28) — \n5. Model Context Protocol, *Skills Over MCP Charter* (SEP-2640 Final, merged 2026-09-13; checked 2026-10-30) — \n6. Cloudflare, *Agent Skills Discovery via Well-Known URIs* (draft 0.2.0, published 2026-01-17; updated 2026-03-12) — \n7. Junjie Bu (Google), R.V. Guha, and Shaun Smith (Hugging Face), *ARD Specification* (v0.91, 2026-08-26) — \n8. Anthropic, *Extend Claude with skills* (checked 2026-10-30) — \n9. Gemini CLI, *Agent Skills* (checked 2026-10-30) — \n10. Anthropic, *Donating Agent Skills to the Agentic AI Foundation* (published 2026-10-22) — \n11. Anthropic, *Introducing Agent Skills* (published 2025-10-16; update dated 2025-12-18) — \n12. Anthropic, *Skills for organizations, partners, the ecosystem* (published 2025-12-18) — \n13. Angie Jones (Agentic AI Foundation), *Agent Skills: Open Standard for Sharing AI Agent Workflows* (published 2026-10-22) — \n14. agentskills, *Specification and documentation for Agent Skills* (repository created 2025-12-16; checked 2026-10-30) — \n15. Agent Skills project, *Agent Skills Governance* (Adopted November 4, 2026) — \n16. Agent Skills project, *Agent Skills Maintainers* (Last updated November 4, 2026) — \n17. The Linux Foundation, *Agentic AI Foundation Announces Four New Projects: Agent Skills, Open Responses, OpenEnv, and OpenSandbox* (published 2026-10-22; modified 2026-10-23) — \n18. Visual Studio Code, *Use Agent Skills in VS Code* (checked 2026-10-30) — \n19. Stripe, *skills discovery index* (checked 2026-10-30) — \n20. IANA, *Well-Known URIs* (registry CSV, fetched 2026-10-30) — \n21. OpenAI, *Build skills* (checked 2026-10-30) — \n22. L. Muscariello and R. Polic (Cisco), *Agent Directory Service (draft-mp-agntcy-ads-03)* (2 November 2026) — \n23. Cloudflare, *agent-skills discovery index* (checked 2026-10-30) — \n24. Vercel, *agent-skills discovery index* (checked 2026-10-30) — \n25. Cisco, *Open Agentic Schema Framework* (copyright 2025; versions 0.8.0, 1.0.0, and 1.1.0 shown; checked 2026-10-31) — \n26. Anthropic, *Equipping agents for the real world with Agent Skills* (published 2025-10-16; modified 2026-10-18) — \n27. Jeremy Howard, *The /llms.txt file, v2* (published 2024-09-03; modified 2026-08-10) — \n28. Cursor, *Subagents, Skills, and Image Generation* (2.4, 2026-01-22) — \n29. Cursor, *Agent Skills* (checked 2026-10-30) — \n30. Allison (GitHub), *GitHub Copilot now supports Agent Skills* (published 2025-12-18) — \n31. Gemini CLI, *Gemini CLI release notes* (v0.23.0, 2026-01-07) — \n32. goose, *Agent Skills* (checked 2026-10-30) — \n33. Amp, *Agent Skills* (published 2025-12-10) — \n34. GuildSkills, *GuildSkills cross-agent skills registry* (checked 2026-11-06) — \n35. AgentSkill Directory, *AI Agent Skills Directory* (checked 2026-11-06) — \n36. Anthropic, *anthropics/skills* (checked 2026-10-30) — \n37. Hugging Face, *huggingface/skills* (checked 2026-10-30) — \n38. vawe-hq, *Awesome Agent Skills Directories* (2026-10-29) — \n39. AgenticSkills, *AgenticSkills curated skill directory* (2026-11-06) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "", "adoption": { "level": "observed", "by": "Anthropic (Claude API docs), OpenAI (Developer Platform docs), Google AI (Gemini API docs), Cloudflare (Developer docs), Stripe (Documentation), Chrome Lighthouse, Claude Code, VS Code PagePilot Extension, and 17 other verified implementations", "probe_run": null }, "aliases": [], "analog": "sitemap.xml / a README for a site's documentation", "collisions": [], "discovery": { "mechanism": "Markdown file at the site root or any subpath", "path": "/llms.txt or any subpath" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://llmstxt.org", "claim": "Jeremy Howard, *The /llms.txt file, v2*, published 2024-09-03; modified 2026-08-10; HTTP last-modified 2026-09-24", "date": null, "quote": "A proposal to standardise on using an /llms.txt file to provide information to help agents use a website. / A proposal to standardise on using an /llms.txt file to provide information to help agents use a website. … We propose adding a /llms.txt markdown file to websites to provide LLM-friendly content. The file can be placed at the site root, or at any path within it, covering the pages under that path. This file offers brief background information, guidance, and links to detailed markdown files. / An HTML page wraps its information in navigation, ads, and JavaScript, and converting it back into clean text is difficult and imprecise. Context windows, while larger than they were, are still too small for most websites in their entirety, and every wasted token costs time and money. … sitemap.xml is a list of all the indexable human-readable information available on a site. This isn't a substitute for llms.txt since it: Often won't have the LLM-readable versions of pages listed Doesn't include URLs to external sites, even though they might be helpful to understand the information Will generally cover documents that in aggregate will be too large to fit in an LLM context window, and will include a lot of information that isn't necessary to understand the site. / The llms.txt file spec is for files named llms.txt, at the root path /llms.txt of a website or at any subpath (e.g. /docs/llms.txt). / Author Jeremy Howard Published September 3, 2024 Modified August 10, 2026 … Jeremy Howard 2024-09-03 / We furthermore propose that pages with information that agents might need provide a clean markdown version of those pages at the same URL as the original page, either with .md appended (page.html.md) or with the extension replaced by .md (page.md). (URLs without file names should append index.html.md or index.md instead.) … The llms.txt file spec is for files named llms.txt, at the root path /llms.txt of a website or at any subpath (e.g. /docs/llms.txt). A file covers the URLs under its path, and where more than one file applies, agents should use the most specific one. / To help clients find these files, we recommend using standard link relations: rel=\"alternate\" type=\"text/markdown\" points to the markdown version of a page, and rel=\"describedby\" points to the llms.txt file that covers it. … These links can be provided as HTML elements, or as an HTTP Link: response header. The header form also works for non-HTML resources, such as the markdown files themselves, and can be added in web server or CDN configuration without modifying any pages. / Author Jeremy Howard Published September 3, 2024 Modified August 10, 2026 … Jeremy Howard 2024-09-03 … This is v2 of the proposal … The llms.txt specification is open for community input. A GitHub repository hosts this informal overview, allowing for version control and public discussion. / Author Jeremy Howard Published September 3, 2024 / The llms.txt specification is open for community input. A GitHub repository hosts this informal overview, allowing for version control and public discussion. / The llms.txt specification is open for community input. A GitHub repository hosts this informal overview / This is v2 of the proposal … The llms.txt specification is open for community input. A GitHub repository hosts this informal overview / Published September 3, 2024 Modified August 10, 2026 … This is v2 of the proposal / At the moment the most widely and easily understood format for language models is Markdown. … An H1 with the name of the project or site. This is the only required section A blockquote with a short summary of the project … Zero or more markdown sections delimited by H2 headers, containing \"file lists\" of URLs where further detail is available / rel=\"alternate\" type=\"text/markdown\" points to the markdown version of a page, and rel=\"describedby\" points to the llms.txt file that covers it. … These links can be provided as HTML elements, or as an HTTP Link: response header. / The /llms.txt file, v2 / Agents are expected to view or search llms.txt to find the information they need, then follow the relevant links. The links in an llms.txt file should therefore point to LLM-friendly content, such as the markdown versions of pages described above. The file itself stays small enough to fit in context. The detail lives behind the links, and is fetched only when needed. / robots.txt lets automated tools know what access to a site is considered acceptable, such as for search indexing bots. llms.txt information is instead used on demand, when an agent needs information about a topic while assisting a user. Our expectation was that llms.txt would mainly be useful for inference rather than training … An alternative would be the Well-Known URIs standard (RFC 8615), which reserves the /.well-known/ prefix for metadata files like this one. But well-known URIs exist only at the origin root, and many authors control only a path on a shared host: a GitHub Pages project site, for example, can publish files in its own directory but can never add one to the host's /.well-known/. / Here's an example of llms.txt, in this case a cut down version of the file used for the FastHTML project (see also the full version): / llms.txt markdown is human and LLM readable, but is also in a precise format allowing fixed processing methods (i.e. classical programming techniques such as parsers and regex). / The llms.txt file is unusual in that it uses Markdown to structure the information rather than a classic structured format such as XML. The reason for this is that we expect many of these files to be read by language models and agents. Having said that, the information in llms.txt follows a specific format and can be read using standard programmatic-based tools. / A file following the spec contains the following sections as markdown, in the specific order: An optional byte-order mark (BOM) An H1 with the name of the project or site. This is the only required section A blockquote with a short summary of the project, containing key information necessary for understanding the rest of the file Zero or more markdown sections (e.g. paragraphs, lists, etc) of any type except headings, containing more detailed information about the project and how to interpret the provided files Zero or more markdown sections delimited by H2 headers, containing \"file lists\" of URLs where further detail is available / Zero or more markdown sections delimited by H2 headers, containing \"file lists\" of URLs where further detail is available Each \"file list\" is a markdown list, containing a required markdown hyperlink [name](url), then optionally a : and notes about the file. Here is a mock example: # Title … ## Section name - [Link title](https://link_url): Optional link details ## Optional - [Link title](https://link_url) / Important notes: - Although parts of its API are inspired by FastAPI, it is *not* compatible with FastAPI syntax and is not targeted at creating API services … ## Docs - FastHTML quick start: A brief overview of many FastHTML features … ## Examples … ## Optional - Starlette full documentation: A subset of the Starlette documentation useful for FastHTML development. / Each \"file list\" is a markdown list, containing a required markdown hyperlink [name](url), then optionally a : and notes about the file. Here is a mock example: # Title … ## Section name - [Link title](https://link_url): Optional link details ## Optional - [Link title](https://link_url) / The \"Optional\" section is used, by convention, for secondary information: links an agent can skip when a shorter context is needed. … ## Optional - Starlette full documentation: A subset of the Starlette documentation useful for FastHTML development. … ## Docs - FastHTML quick start: A brief overview of many FastHTML features / The links in an llms.txt file should therefore point to LLM-friendly content, such as the markdown versions of pages described above. … (An llms.txt file describes all pages under its path, so /docs/llms.txt covers everything in /docs/.) … The FastHTML project follows these two proposals for its documentation. For instance, here is the FastHTML docs llms.txt, placed at /docs/ to cover just the documentation pages. And here is an example of a regular HTML docs page, along with exact same URL but with a .md extension. / URLs without file names should append index.html.md or index.md instead. … Note that all nbdev projects now create .md versions of all pages by default. All Answer.AI and fast.ai software projects using nbdev have had their docs regenerated with this feature. / For example: Link: ; rel=\"alternate\"; type=\"text/markdown\", ; rel=\"describedby\" … rel=\"alternate\" type=\"text/markdown\" points to the markdown version of a page, and rel=\"describedby\" points to the llms.txt file that covers it. … These links can be provided as HTML elements, or as an HTTP Link: response header. The header form also works for non-HTML resources, such as the markdown files themselves, and can be added in web server or CDN configuration without modifying any pages. / Code Python module & CLI Python source JavaScript … JavaScript Implementation - Sample JavaScript implementation vitepress-plugin-llms - VitePress plugin that automatically generates LLM-friendly documentation for the website following the llms.txt specification … llms-txt-php - A library for writing and reading llms.txt Markdown files … server-llm-txt - MCP server that lets agents fetch and search llms.txt files / robots.txt lets automated tools know what access to a site is considered acceptable, such as for search indexing bots. llms.txt information is instead used on demand, when an agent needs information about a topic while assisting a user. / While sitemaps list all pages for search engines, llms.txt offers a curated overview for LLMs. … sitemap.xml is a list of all the indexable human-readable information available on a site. / pages with information that agents might need provide a clean markdown version of those pages at the same URL as the original page, either with .md appended (page.html.md) or with the extension replaced by .md (page.md). … rel=\"alternate\" type=\"text/markdown\" points to the markdown version of a page / The file can be placed at the site root, or at any path within it, covering the pages under that path. / rel=\"describedby\" points to the llms.txt file that covers it. … well-known URIs exist only at the origin root / Agents are expected to view or search llms.txt to find the information they need, then follow the relevant links. / And various libraries and plugins are available to integrate the llms.txt specification into your workflow: … VS Code PagePilot Extension - PagePilot is a VS Code Chat participant that automatically loads external context (documentation, APIs, README files) to provide enhanced responses. / server-llm-txt - MCP server that lets agents fetch and search llms.txt files / Mintlify - Docs platform that generates llms.txt and markdown page versions for every site it hosts / GitBook - Serves an llms.txt file for published docs sites / A proposal to standardise on using an /llms.txt file … Yoast SEO - WordPress plugin that generates and maintains an llms.txt file / AIOSEO - WordPress plugin with an llms.txt generator / A proposal to standardise on using an /llms.txt file … Wix - Generates an llms.txt file for every Wix site", "ref": 1 }, { "label": "[2]", "url": "https://ahrefs.com/blog/llmstxt-study/", "claim": "Louise Linehan (Ahrefs), *We Analyzed 137K Sites: 97% of llms.txt Files Never Get Read*, published 2026-06-15; modified 2026-08-27; data: May 2026", "date": null, "quote": "Proposed by Jeremy Howard, co-founder of Answer.AI and fast.ai, in 2024 / And despite the filename, it is not a robots.txt-style directive: it controls nothing and blocks nothing. / adopted llms.txt, despite the fact that no major AI platform has ever committed to reading it. / of those files received zero traffic in May 2026. Nothing fetched them at all. / 96% of the requests that did reach llms.txt files came from bots. 19.5% of fetches came from named AI tools (of the 3% of files that weren't ignored). GPTBot is top and Claude-Code is second, ahead of every AI search and assistant bot. … Aside from statespace-indexer and GPTBot, Claude-Code (Anthropic's coding agent), out-fetched every AI retrieval bot, every AI assistant, and every AI training crawler. / 28% of the 137K domains using Ahrefs Web Analytics publish an llms.txt file. 97% of those files received zero traffic in May 2026. Nothing fetched them at all. 96% of the requests that did reach llms.txt files came from bots. 19.5% of fetches came from named AI tools (of the 3% of files that weren't ignored). GPTBot is top and Claude-Code is second, ahead of every AI search and assistant bot. 12% of fetches come from the industry studying itself: GEO/AEO tools, llms.txt checker tools, and researchers. Zero requests came from AI bots for llms.txt files that don't exist. / SEO audit tools … 4,776 21.7% Other and unidentified … 3,278 14.9% General web crawlers … 2,871 13.1% Tech profiling tools … 2,546 11.6% AI agents & agentic infrastructure … 2,302 10.5% GEO/AEO tools … 1,278 5.8% AI training crawlers … 1,179 5.3% llms.txt discoverability bots … 793 3.6% Service and social bots … 645 2.9% Research bots … 585 2.7% AI assistants … 559 2.5% AI retrieval bots … 233 1.1% / SEO audit tools includes Ahrefs' own crawlers (SiteAuditBot, Ahrefs Bot, and Ahrefs Site Audit), which together account for 2,334 requests (10.6% of total). … Bot categories sum to 96% of total requests; the remaining 4% (930 requests) came from humans. / The bot traffic splits into three stories: AI bots consuming the file (19.5%) A long tail of anonymous scrapers (14.9%) An industry auditing it (12.1%) … Aside from statespace-indexer and GPTBot, Claude-Code (Anthropic's coding agent), out-fetched every AI retrieval bot, every AI assistant, and every AI training crawler.", "ref": 2 }, { "label": "[3]", "url": "https://llmstxt.org/changes.html", "claim": "Jeremy Howard, *Changes*, August 2026; HTTP last-modified 2026-09-24", "date": null, "quote": "v2 (August 2026) … v1 specified one URL form for markdown versions, .md appended to the full page URL (page.html.md). Some publishing tools instead replace the extension (page.md), so v2 allows both. … v1 said nothing about how llms.txt should be consumed, and described the llms_txt2ctx tool for expanding a file into an LLM context. … The context-expansion tooling is no longer part of the proposal / Changes v2 (August 2026) / The context-expansion tooling is no longer part of the proposal, and with it goes the special meaning of the Optional section, which told those tools what to omit. Optional sections are still allowed, and remain a useful convention for secondary links, but they no longer carry mechanical semantics. / v1 specified one URL form for markdown versions, .md appended to the full page URL (page.html.md). Some publishing tools instead replace the extension (page.md), so v2 allows both. / described the llms_txt2ctx tool for expanding a file into an LLM context. v2 instead states the expectation directly: agents view or search the llms.txt to find what they need, then follow the relevant links, which should point to LLM-friendly content. The context-expansion tooling is no longer part of the proposal, and with it goes the special meaning of the Optional section, which told those tools what to omit.", "ref": 3 }, { "label": "[4]", "url": "https://getpublii.com/blog/llms-txt-complete-guide.html", "claim": "Publii, *The complete guide to llms.txt*, BuiltWith reading 17 October 2026; fetched 2026-11-06", "date": null, "quote": "You may also come across llms-full.txt. It is exactly what the name suggests: the documentation gathered into one large file. That can be handy when someone deliberately loads the whole thing into an AI tool. It can also become enormous and go stale quickly / 14,586,789 is the kind of number / BuiltWith reported when we checked on October 17, 2026. Our October 2025 snapshot showed 844,473.", "ref": 4 }, { "label": "[5]", "url": "https://installmap.com/research/llms-txt-statistics.csv", "claim": "Installmap, *llms.txt statistics (CSV)*, crawls through September 2026; fetched 2026-11-06", "date": null, "quote": "16 of the 695 valid llms.txt files on Tranco top-7,755 domains on September 23, 2026 (2.3%) contain instructions that steer what an AI assistant recommends / In Installmap's crawl, 695 of the 7,749 domains in the Tranco top 7,755 (9.0%) served a valid llms.txt at the bare domain on September 23, 2026; 2,147 did not answer the request, so the share of domains that answered is 12.4%. / 16 of the 695 valid llms.txt files on Tranco top-7,755 domains on September 23, 2026 (2.3%) contain instructions that steer / Counting only llms.txt files with no plugin or Shopify signature, 19.0% of Inc 5000 domains have one, against 28.3% of unicorns and 10.7% of the Fortune 500, in Installmap's September 2026 crawl. / 36.2% of the 1,261 Y Combinator companies from the 2025 and 2026 batches serve an llms.txt, against 23.3% of the 909 companies from the 2012 to 2017 batches, in Installmap's September 2026 crawl. / Originality.ai's tracker counted 4,088 llms.txt files in June 2025 and 36,120 in May 2026, 8.8 times as many. / llms-full.txt files grew from 23 to 2,463 between June 2025 and May 2026", "ref": 5 }, { "label": "[6]", "url": "https://installmap.com/research/llms-txt-ai-instructions", "claim": "Installmap, *Everyone is hilariously prompt-injecting AI via llms.txt and you aren't*, 2026-09-23; fetched 2026-11-11", "date": null, "quote": "16 of the 695 llms.txt files we read at bare domains (2.3%) carry steering instructions. Another 29 (4.2%) tell assistants to send users to the company's own pages or not to guess facts, and 49 (7.1%) set usage, licensing or agent-integration terms. / None of the 7,749 homepages hid text addressed to AI, and no file said \"ignore previous instructions\".", "ref": 6 }, { "label": "[7]", "url": "https://ai.pydantic.dev/llms.txt", "claim": "Pydantic, *Pydantic AI*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "Load a repo's AGENTS.md and CLAUDE.md instruction files into a Pydantic AI agent / HTTP 200 ... content-type: text/plain; charset=utf-8 ... x-pydantic-site-worker: 1 ... ## Querying This Documentation ... agent query parameters (`intent`, `stack` and `harness`) ... ?intent=&stack=&harness= ... # Pydantic AI > GenAI Agent Framework, the Pydantic way ... [Pydantic AI](https://pydantic.dev/docs/ai/overview/index.md)", "ref": 7 }, { "label": "[8]", "url": "https://www.rfc-editor.org/rfc/rfc9727.html", "claim": "K. Smith (Vodafone), *api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs*, published June 2025", "date": null, "quote": "This document defines the \"api-catalog\" well-known URI and link relation. It is intended to facilitate automated discovery and usage of published Application Programming Interfaces (APIs).", "ref": 8 }, { "label": "[9]", "url": "https://developers.openai.com/api/docs/bots", "claim": "OpenAI, *Overview of OpenAI Crawlers*, fetched 2026-11-03", "date": null, "quote": "OpenAI uses OAI-SearchBot and GPTBot robots.txt tags to enable webmasters to manage how their sites and content work with AI.", "ref": 9 }, { "label": "[10]", "url": "https://developers.google.com/search/docs/fundamentals/ai-optimization-guide", "claim": "Google Search Central, *Google's Guide to Optimizing for Generative AI Features on Google Search*, updated 2026-07-10", "date": null, "quote": "LLMS.txt files and other \"special\" markup: You don't need to create new machine readable files, AI text files, markup, or Markdown to appear in Google Search (including its generative AI capabilities), as Google Search itself doesn't use them.", "ref": 10 }, { "label": "[11]", "url": "https://platform.claude.com/llms.txt", "claim": "Anthropic, *platform.claude.com/llms.txt*, HTTP 200; fetched 2026-10-30", "date": null, "quote": "# Anthropic Developer Documentation … https://platform.claude.com/docs/mcp (Streamable HTTP transport) … https://platform.claude.com/docs/sdk-versions.json … English (en) - 826 pages - /docs … llms-full.txt … content-type: text/plain; charset=utf-8", "ref": 11 }, { "label": "[12]", "url": "https://developers.openai.com/llms.txt", "claim": "OpenAI, *developers.openai.com/llms.txt*, HTTP 200; fetched 2026-10-30", "date": null, "quote": "# OpenAI Developers … Product indexes route to detailed pages; documentation indexes also provide Markdown pages and full-document exports. … [OpenAI API guides and reference](https://developers.openai.com/api/llms.txt) … [Codex developer tools](https://developers.openai.com/codex/llms.txt) … [Agentic Commerce Protocol](https://developers.openai.com/commerce/llms.txt) … [OpenAI Cookbook examples](https://developers.openai.com/cookbook/llms.txt) … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 12 }, { "label": "[13]", "url": "https://ai.google.dev/gemini-api/docs/llms.txt", "claim": "Google AI, *Gemini API llms.txt*, HTTP 200; fetched 2026-10-30", "date": null, "quote": "# Gemini API Gemini API Docs and API Reference … /gemini-api/docs/ … Environments in managed agents … content-type: text/markdown; charset=utf-8", "ref": 13 }, { "label": "[14]", "url": "https://developers.cloudflare.com/llms.txt", "claim": "Cloudflare, *developers.cloudflare.com/llms.txt*, HTTP 200; fetched 2026-10-30", "date": null, "quote": "# Cloudflare Developer Documentation … Each product below links to its own llms.txt, which contains a full index of that product's documentation pages … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 14 }, { "label": "[15]", "url": "https://docs.stripe.com/llms.txt", "claim": "Stripe, *docs.stripe.com/llms.txt*, HTTP 200; fetched 2026-10-30", "date": null, "quote": "# Stripe Documentation … check the npm registry … https://www.npmjs.com/package/stripe … https://pypi.org/project/stripe/ … [sandboxes](https://docs.stripe.com/sandboxes.md) … content-type: text/markdown; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 15 }, { "label": "[16]", "url": "https://cursor.com/llms.txt", "claim": "Cursor, *Cursor Documentation*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "Content-Type: text/plain; charset=utf-8 … Link: ; rel=\"describedby\"; type=\"text/plain\"; title=\"llms.txt\", ; rel=\"sitemap\"; type=\"application/xml\" … # Cursor Documentation … https://cursor.com/docs/get-started/quickstart.md", "ref": 16 }, { "label": "[17]", "url": "https://vercel.com/llms.txt", "claim": "Vercel, *Vercel*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "Content-Type: text/plain; charset=utf-8 … # Vercel … ## When to use Vercel … ## How agents should use Vercel … [Vercel REST API OpenAPI description](https://vercel.com/openapi.json) … ## Optional … [Agent resource catalog](https://vercel.com/.well-known/ai-catalog.json) … [Product taxonomy](https://vercel.com/docs/taxonomy.json) … [Documentation graph](https://vercel.com/docs/graph.json)", "ref": 17 }, { "label": "[18]", "url": "https://supabase.com/docs/llms.txt", "claim": "Supabase (Docs), *Supabase Docs*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "Content-Type: text/plain; charset=utf-8 … # Supabase Docs … For the complete documentation in a single file, see [Full Documentation](https://supabase.com/llms-full.txt). … [Supabase - AI & Vectors](https://supabase.com/docs/guides/ai.md) … [Supabase Management API OpenAPI spec](https://supabase.com/openapi.json) … [Supabase MCP server](https://mcp.supabase.com/mcp)", "ref": 18 }, { "label": "[19]", "url": "https://modelcontextprotocol.io/llms.txt", "claim": "Model Context Protocol (MCP), *Model Context Protocol*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Model Context Protocol ... [What is the Model Context Protocol (MCP)?](https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro.md)", "ref": 19 }, { "label": "[20]", "url": "https://docs.cdp.coinbase.com/llms.txt", "claim": "Coinbase Developer Platform, *Coinbase Developer Documentation*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Coinbase Developer Documentation ... [Docs (526 pages)](https://docs.cdp.coinbase.com/_llms/docs.txt) ... [API Reference (906 pages)](https://docs.cdp.coinbase.com/_llms/api-reference.txt) ... [SDKs (1523 pages)](https://docs.cdp.coinbase.com/_llms/sdks.txt) ... [Settle customer stablecoins as USD](https://docs.cdp.coinbase.com/recipes/settle-customer-stablecoins-as-usd.md)", "ref": 20 }, { "label": "[21]", "url": "https://svelte.dev/llms.txt", "claim": "Svelte, *Svelte Documentation for LLMs*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Svelte Documentation for LLMs ... [Abridged documentation](https://svelte.dev/llms-medium.txt) ... [Compressed documentation](https://svelte.dev/llms-small.txt) ... [Complete documentation](https://svelte.dev/llms-full.txt)", "ref": 21 }, { "label": "[22]", "url": "https://bun.sh/llms.txt", "claim": "Bun, *Bun*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Bun ... [Welcome to Bun](https://bun.com/docs/index.md)", "ref": 22 }, { "label": "[23]", "url": "https://docs.langchain.com/llms.txt", "claim": "LangChain, *Docs by LangChain*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Docs by LangChain > Documentation for LangSmith, Fleet, and our open source packages. ... [AGENT DEVELOPMENT LIFECYCLE (1518 pages)](https://docs.langchain.com/_llms/agent-development-lifecycle.txt) ... [PRODUCTS AND SETUP (223 pages)](https://docs.langchain.com/_llms/products-and-setup.txt)", "ref": 23 }, { "label": "[24]", "url": "https://clerk.com/llms.txt", "claim": "Clerk, *Clerk*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Clerk > Clerk is user management for developers ... Append `.md` to any `/docs`, `/articles`, `/blog`, `/changelog`, or `/glossary` URL ... [Backend API](https://clerk.com/openapi.json)", "ref": 24 }, { "label": "[25]", "url": "https://neon.tech/llms.txt", "claim": "Neon, *Neon Postgres*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... x-nextjs-rewritten-path: /docs/llms.txt ... # Neon Postgres > Neon is a complete set of cloud backend primitives built around Lakebase Postgres ... [Claimable Neon](https://neon.com/auth.md) ... neon init ... Append `.md` to any doc URL", "ref": 25 }, { "label": "[26]", "url": "https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt", "claim": "Chrome for Developers, *llms.txt*, updated 2026-05-05", "date": null, "quote": "Lighthouse flags the pages if a server error occurs when attempting to retrieve the llms.txt file. If the file is not provided by the server (resulting in a 404), the audit is marked as Not Applicable (N/A), as providing the file is optional at the moment. … /llms.txt … Last updated 2026-05-05 UTC.", "ref": 26 }, { "label": "[27]", "url": "https://mintlify.com/docs/llms.txt", "claim": "Mintlify, *Mintlify*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/plain; charset=utf-8 ... # Mintlify > Mintlify is a platform for building and hosting documentation websites. ... mint agent setup ... [Fix llms.txt returning 404 while llms-full.txt works](https://www.mintlify.com/docs/help-center/llms-txt-returns-404-but-llms-full-txt-works.md) ... [openapi](/docs/openapi.json) ... [admin-openapi](/docs/admin-openapi.json)", "ref": 27 }, { "label": "[28]", "url": "https://directory.llmstxt.cloud/", "claim": "llms.txt cloud directory, *llms.txt directory*, checked 2026-11-04", "date": null, "quote": "Mintlify / 4,092 Websites 1,960 Products 870 Developer tools 560 AI 409 Finance 293 … Websites listed 4,092 Total llms.txt tokens 51M Total llms-full.txt tokens 390M", "ref": 28 }, { "label": "[29]", "url": "https://docs.gitbook.com/llms.txt", "claim": "GitBook, *GitBook Documentation*, HTTP 200; fetched 2026-11-04", "date": null, "quote": "HTTP 200 ... content-type: text/markdown; charset=utf-8 ... # GitBook Documentation ... [LLM-ready docs](https://gitbook.com/docs/getting-started/llm-ready-docs.md)", "ref": 29 }, { "label": "[30]", "url": "https://llmstxt.site/", "claim": "llms.txt directory, *llms.txt directory - Find llms.txt files across the web*, checked 2026-11-04", "date": null, "quote": "GitBook", "ref": 30 }, { "label": "[31]", "url": "https://www.rankability.com/blog/llms-txt-adoption/", "claim": "Rankability, *llms.txt Adoption Research Report*, published 2026-09-18", "date": null, "quote": "9.3% of the top 1,000 domains serve a confirmed llms.txt or llms-full.txt file. / This is a snapshot of root-level file availability, not a full specification audit or proof that an AI platform uses the file.", "ref": 31 }, { "label": "[32]", "url": "https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents", "claim": "Vercel and Ora, *Make your site readable by AI agents*, published 2026-08-28; modified 2026-09-03", "date": null, "quote": "we observed 1,033 agent runs across 25 sites and ran 190 controlled fetch probes. / The trace results are observational and run-weighted. / Agents reached llms.txt through links in 356 of 416 attributed fetches, or 86%. Of the 329 runs that reached it, 325 had a scorable steering result. Of those 325 runs, 117, or 36%, later fetched a page it listed. Across all 329 reaching runs, 120, or 36%, grounded the final answer in its content.", "ref": 32 }, { "label": "[33]", "url": "https://llmtxt.info/llms-txt-adoption/", "claim": "LLMtxt Adoption Directory, *llms.txt adoption panel*, latest run 2026-10-05; fetched 2026-11-06", "date": null, "quote": "a fixed panel of 219 notable hosts across eight sectors / Latest run: 2026-10-05. / of 217 tested hosts serve llms.txt / 14.0 KB / verified live files in the directory / | Developer tools | 61 | 44 | 72.1% | / | SaaS | 47 | 32 | 68.1% | / | Media | 14 | 2 | 14.3% |", "ref": 33 }, { "label": "[34]", "url": "https://www.chris-green.net/post/million-websites-in-search-of-llms-txt", "claim": "Chris Green, *A million websites in search of llms.txt*, February 2025 crawl; May 2025 edit; fetched 2026-11-06", "date": null, "quote": "llmstxt.site lists roughly 170 sites. … directory.llmstxt.cloud claims around 684 sites. … I crawled the Majestic Million - representing a large cross-section of popular websites - and found only 0.015% (approximately 15 sites) had a valid LLMs.txt file in Feb 2025. … a proxy measurement using robots.txt files indicated around 210,000 valid files … Using this as a baseline, LLMs.txt adoption is around 0.007% / May 2025 data suggests there are 105 valid LLMs.txt now found", "ref": 34 }, { "label": "[35]", "url": "https://doi.org/10.5281/zenodo.22859104", "claim": "Jacob Ezra Gerrish (SEMPITE), *The llms.txt corpus: ecosystem health, file contents, and the Shopify platform default*, published 20 September 2026 (v1.1.0, version DOI 10.5281/zenodo.22862258)", "date": null, "quote": "All 1,563 llms.txt files registered / Published September 20, 2026 / 15.7% of listed files are broken at file level / re-fetched on 20 September 2026 / 265 files broken (17.0%), up from 245 (15.7%)", "ref": 35 }, { "label": "[36]", "url": "https://zenodo.org/api/records/22862258", "claim": "Jacob Ezra Gerrish (SEMPITE / Zenodo API), *Zenodo Record 22862258 Metadata (v1.1.0, concept DOI 10.5281/zenodo.22859104)*, 2026-09-20 (v1.1.0)", "date": null, "quote": "\"doi\": \"10.5281/zenodo.22862258\", \"conceptdoi\": \"10.5281/zenodo.22859104\"", "ref": 36 } ], "form": "document-format", "governance": "Open for community input; a GitHub repository hosts the informal overview", "group": null, "history": [ { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "llms-txt", "implementation": "multi-implementation", "last_verified": "2026-11-11", "name": "llms.txt", "native_status": "v2 of the proposal; informal overview, open for community input", "origin": { "org": "Jeremy Howard", "date": "2024-09-03" }, "part_of": null, "parties": [ "agent-site" ], "phase": "draft", "probe": { "method": "GET", "on_absent": "No llms.txt at this path; a more specific subpath file (e.g. /docs/llms.txt) may still exist and take precedence for that subpath", "parse": "200 response beginning with an H1 heading (`# `) followed by a blockquote summary, per the llms.txt v2 grammar", "path": "{origin}/llms.txt" }, "question": "Where can an agent find a concise, curated map of a site's content, written for language models rather than browsers?", "scope": "general", "spec_url": "https://llmstxt.org", "step": "read", "summary_md": "**llms.txt** is a community proposal originated by Jeremy Howard (co-founder of Answer.AI and fast.ai) on September 3, 2024 (`2024-09-03`) that standardizes a Markdown file named `llms.txt` at `/llms.txt` or a subpath such as `/docs/llms.txt`. The file gives reading agents brief background context, guidance, and curated links to detailed Markdown pages under that path. Alongside `llms.txt` (where agents use the most specific file when multiple paths apply), pages expose a clean Markdown companion at the same URL with `.md` appended (`page.html.md`), the extension replaced (`page.md`), or `index.html.md` / `index.md` for directory URLs. Clients discover the Markdown companion via `rel=\"alternate\"` `type=\"text/markdown\"` and the covering `llms.txt` via `rel=\"describedby\"` in HTML `` elements or HTTP `Link:` response headers. Revision `v2` (modified August 10, 2026) broadened Markdown companion URLs beyond v1's single appended-extension form and retired the v1 `llms_txt2ctx` context-expansion tool and mechanical `Optional` omission semantics.", "track": "community", "version": { "label": "v2", "date": "2026-08-10" }, "watch": [ { "type": "page", "url": "https://llmstxt.org", "selector": "main", "cadence": "weekly" }, { "type": "github", "repo": "AnswerDotAI/llms-txt", "mode": "release", "version": false }, { "type": "page", "url": "https://llmstxt.org/", "selector": "main" } ], "use_cases": [ "serve-content-to-agents", "discover-my-api" ], "audience": [ "site-owner", "agent-builder" ], "pairs_with": [ "agents-md", "cloudflare-markdown-for-agents", "api-catalog-rfc9727", "ai-crawler-tokens-robots", "knowledge-linkset", "nlweb" ], "prerequisites": [], "hatnote_md": "Not to be confused with [AGENTS.md](/protocols/agents-md/) (repository coding-agent instructions) or [ai.txt](/protocols/ai-txt/) (AI usage permissions). For the glossary entry, see [llms.txt file](/terms/llms-txt-file/).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "web_discovery", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-11", "v05_hatnote_html_md": "Not to be confused with [AGENTS.md](/protocols/agents-md/) (repository coding-agent instructions) or [ai.txt](/protocols/ai-txt/) (AI usage permissions). For the glossary entry, see [llms.txt file](/terms/llms-txt-file/). [1]", "v05_elevator_pitch_md": "`llms.txt` is a website index convention that gives AI assistants and coding agents a concise, human-curated map of a site's documentation and key resources via `/llms.txt` or subpath files like `/docs/llms.txt`. Instead of scraping noisy HTML pages cluttered with navigation, scripts, and layout markup—or ingesting an uncurated `sitemap.xml`—agents read one compact Markdown overview and fetch linked `.md` companion pages only when needed. [1]", "v05_lead_md": "**llms.txt** is a community proposal originated by Jeremy Howard (co-founder of Answer.AI and fast.ai) on September 3, 2024 (`2024-09-03`) that standardizes a Markdown file named `llms.txt` at `/llms.txt` or a subpath such as `/docs/llms.txt`. The file gives reading agents brief background context, guidance, and curated links to detailed Markdown pages under that path. [1][2] Alongside `llms.txt` (where agents use the most specific file when multiple paths apply), pages expose a clean Markdown companion at the same URL with `.md` appended (`page.html.md`), the extension replaced (`page.md`), or `index.html.md` / `index.md` for directory URLs. Clients discover the Markdown companion via `rel=\"alternate\"` `type=\"text/markdown\"` and the covering `llms.txt` via `rel=\"describedby\"` in HTML `` elements or HTTP `Link:` response headers. [1] Revision `v2` (modified August 10, 2026) broadened Markdown companion URLs beyond v1's single appended-extension form and retired the v1 `llms_txt2ctx` context-expansion tool and mechanical `Optional` omission semantics. [1][3]", "v05_identity_sentence_md": "**llms.txt** is a community proposal originated by Jeremy Howard (co-founder of Answer.AI and fast.ai) on September 3, 2024 (`2024-09-03`) that standardizes a Markdown file named `llms.txt` at `/llms.txt` or a subpath such as `/docs/llms.txt`. The file gives reading agents brief background context, guidance, and curated links to detailed Markdown pages under that path. [1][2]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Read](/category/read/) (`read`)" }, { "label": "Form", "value_md": "Document format (`document-format`)" }, { "label": "Originated by", "value_md": "Jeremy Howard (Answer.AI / fast.ai), published 2024-09-03 [1][2]" }, { "label": "Governed by", "value_md": "Jeremy Howard; open for community input via public GitHub repository [1]" }, { "label": "Track", "value_md": "Vendor / Spec-Site Standard (informal community overview) [1]" }, { "label": "Status", "value_md": "v2 proposal (informal overview, open for community input) [1]" }, { "label": "Version", "value_md": "v2 (modified 2026-08-10; v1 published 2024-09-03) [1]" }, { "label": "Message format", "value_md": "Markdown (required H1 title, optional summary blockquote, and H2 link lists) [1]" }, { "label": "Headers", "value_md": "HTML `` or HTTP `Link:` with `rel=\"alternate\"` `type=\"text/markdown\"` and `rel=\"describedby\"` [1]" }, { "label": "Specification", "value_md": "[The /llms.txt file, v2](https://llmstxt.org) ([v2 Changes](https://llmstxt.org/changes.html)) [1][3]" }, { "label": "Found at", "value_md": "`/llms.txt` at the site root or any subpath (e.g., `/docs/llms.txt`) [1]" } ], "v05_problem_md": "An HTML page wraps its information in navigation, ads, and JavaScript, so converting it back into clean text is difficult and imprecise, and every wasted token costs time and money while context windows are still too small for most websites. `sitemap.xml` lists indexable human-readable URLs, but it often lacks the LLM-readable versions, omits helpful external URLs, and is too large to stand in for a curated overview. [1] The site instead publishes a small `llms.txt` that agents view or search, with links aimed at LLM-friendly Markdown versions of pages. The file stays small enough to fit in context; the detail lives behind the links and is fetched only when needed. [1] `/robots.txt` tells automated tools what access is considered acceptable, such as for search indexing bots, whereas `llms.txt` is read on demand while an agent assists a user and was expected to help inference rather than training. It is also not a root-only `/.well-known/` URI under RFC 8615: an author who controls only a path, such as a GitHub Pages project site, can still publish a file there. [1]", "v05_mechanism_delta_md": "The site instead publishes a small `llms.txt` that agents view or search, with links aimed at LLM-friendly Markdown versions of pages. The file stays small enough to fit in context; the detail lives behind the links and is fetched only when needed. [1]", "v05_scope_boundary_md": "`/robots.txt` tells automated tools what access is considered acceptable, such as for search indexing bots, whereas `llms.txt` is read on demand while an agent assists a user and was expected to help inference rather than training. It is also not a root-only `/.well-known/` URI under RFC 8615: an author who controls only a path, such as a GitHub Pages project site, can still publish a file there. [1]", "v05_fuzzy_additions": [ { "id": "section-order-and-file-list-syntax", "heading": "Section order and file-list syntax", "body_md": "Markdown, rather than XML, provides the structure so language models and agents can read `llms.txt` directly while classical parsers and regular expressions process its fixed section order. Both the canonical FastHTML specimen (`fastht.ml/docs/`) and the minimal reference mock in the specification follow the same sequence: an H1 title, a summary blockquote, non-heading notes, and H2 file lists. [1]", "bullets": [ { "label": "Required H1 and summary header", "text_md": "An optional byte-order mark (`BOM`) may precede the H1, which names the project or site and is the only required section. A blockquote then holds the key summary, followed by zero or more non-heading paragraphs or lists with project detail before any H2 section begins. [1]" }, { "label": "H2 section file lists", "text_md": "Each H2 heading opens a file list of URLs where further detail is available: the specification's minimal reference mock uses `## Section name` and `## Optional`, while the canonical FastHTML specimen uses `## Docs`, `## Examples`, and `## Optional`. Pre-H2 project notes—such as the FastAPI compatibility bullet under `Important notes:`—stay above `## Docs` rather than appearing as file-link entries. [1]" }, { "label": "Entry link and colon description", "text_md": "Every list item starts with a required Markdown hyperlink `[name](url)`, optionally followed by `:` and notes about the file. In the specification's reference mock, `- [Link title](https://link_url): Optional link details` includes anchor text, a URL, and a colon description, whereas the `## Optional` mock entry `- [Link title](https://link_url)` omits the colon and description. [1]" }, { "label": "Secondary links under ## Optional", "text_md": "The `## Optional` section holds secondary links an agent can skip when a shorter context is needed—in the FastHTML specimen, the Starlette documentation subset rather than the quick start under `## Docs`. Revision `v2` retains `## Optional` as a convention for secondary links, but it no longer carries mechanical semantics telling expansion tools what to omit. [1][3]" } ] }, { "id": "companion-markdown-pages-and-context-expansion", "heading": "Companion Markdown pages and context expansion", "body_md": "Links in `llms.txt` should point at LLM-friendly Markdown pages. `/docs/llms.txt` covers everything in `/docs/`. FastHTML's `llms.txt` sits at `/docs/` for its documentation, and a docs page is also published at the same URL with a `.md` extension. [1]", "bullets": [ { "label": "Why both .md spellings exist", "text_md": "v1 allowed one spelling: `.md` appended, producing `page.html.md`. Tools that replace the extension emit `page.md`, which `v2` also allows. URLs with no file name append `index.html.md` or `index.md`. `nbdev` creates `.md` versions of every page by default, including the regenerated Answer.AI and fast.ai docs. [1][3]" }, { "label": "One Link header names both", "text_md": "The example header is `Link: ; rel=\"alternate\"; type=\"text/markdown\", ; rel=\"describedby\"`. `rel=\"alternate\"` with `type=\"text/markdown\"` names the Markdown page; `rel=\"describedby\"` names the covering `llms.txt`. The same relations work as HTML `` elements, and the header can be set on the `.md` files from a CDN without editing pages. [1]" }, { "label": "llms_txt2ctx and llms-full.txt", "text_md": "`llms_txt2ctx` expanded an `llms.txt` into an LLM context and used the Optional section to decide what to omit. v2 instead has agents view or search the `llms.txt` and follow links to LLM-friendly content. Sites still publish `llms-full.txt`, one large gathered file for a deliberate full load, which can become enormous and go stale quickly. [3][4]" }, { "label": "Python, CLI, and JavaScript readers, and untrusted publisher content", "text_md": "The `Code` menu on `llmstxt.org` lists `Python module & CLI`, `Python source`, and `JavaScript`, plus a sample `JavaScript Implementation`. `llms-txt-php` writes and reads `llms.txt` files, `vitepress-plugin-llms` generates documentation that follows the specification, and `server-llm-txt` lets agents fetch and search those files. Because `llms.txt` is a self-declared, unverified publisher file that neither grants nor denies access (unlike `/robots.txt`), consuming agents should treat retrieved `llms.txt` content as untrusted input. Installmap's 23 September 2026 crawl read 695 bare-domain `llms.txt` files: 16 (2.3%) carry overt brand or recommendation-steering instructions, another 29 (4.2%) tell assistants to send users to the company's own pages or not to guess facts, and 49 (7.1%) set usage, licensing, or agent-integration terms. None of the 7,749 homepages hid text addressed to AI, and no file said \"ignore previous instructions\". [1][5][6]" } ] } ], "v05_diagram": null, "v05_wire_artifact": { "title": "Canonical `llms.txt` specimen (FastHTML, cut down)", "heading": "Canonical `llms.txt` specimen (FastHTML, cut down)", "lang": "markdown", "code": "# FastHTML\n\n> FastHTML is a python library which brings together Starlette, Uvicorn, HTMX, and fastcore's `FT` \"FastTags\" into a library for creating server-rendered hypermedia applications.\n\nImportant notes:\n\n- Although parts of its API are inspired by FastAPI, it is *not* compatible with FastAPI syntax and is not targeted at creating API services\n- FastHTML is compatible with JS-native web components and any vanilla JS library, but not with React, Vue, or Svelte.\n\n## Docs\n\n- [FastHTML quick start](https://fastht.ml/docs/tutorials/quickstart_for_web_devs.html.md): A brief overview of many FastHTML features\n- [HTMX reference](https://github.com/bigskysoftware/htmx/blob/master/www/content/reference.md): Brief description of all HTMX attributes, CSS classes, headers, events, extensions, js lib methods, and config options\n\n## Examples\n\n- [Todo list application](https://github.com/AnswerDotAI/fasthtml/blob/main/examples/adv_app.py): Detailed walk-thru of a complete CRUD app in FastHTML showing idiomatic use of FastHTML and HTMX patterns.\n\n## Optional\n\n- [Starlette full documentation](https://gist.githubusercontent.com/jph00/809e4a4808d4510be0e3dc9565e9cbd3/raw/9b717589ca44cedc8aaf00b2b8cacef922964c0f/starlette-sml.md): A subset of the Starlette documentation useful for FastHTML development.", "caption_md": "Cut-down FastHTML `llms.txt` from the specification, with an H1, a summary blockquote, and H2 file lists `## Docs`, `## Examples`, and `## Optional`. [1]" }, "v05_counterparts": { "classic_analogues": [ { "name": "Sitemaps XML (sitemaps.org)", "spec_or_rfc": "sitemaps.org", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Lists publisher-supplied URLs for discovery, without llms.txt's annotated Markdown guide structure. [1]" }, { "name": "robots.txt (RFC 9309)", "spec_or_rfc": "RFC 9309", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Declares automated crawler access rules at `/robots.txt`, whereas `/llms.txt` provides an on-demand Markdown content guide during inference. [1]" } ], "agentic_peers": [ { "target_id": "agents-md", "target_name": "AGENTS.md", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Supplies repository-level coding instructions via `AGENTS.md`, whereas `/llms.txt` indexes published web documentation at the site root or a subpath. [1][7]" }, { "target_id": "cloudflare-markdown-for-agents", "target_name": "Markdown for Agents", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Negotiates Markdown representations on existing URLs, whereas `/llms.txt` links static `.md` page twins via `rel=\"alternate\"` `type=\"text/markdown\"`. [1]" }, { "target_id": "api-catalog-rfc9727", "target_name": "api-catalog (RFC 9727)", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Publishes machine-readable API discovery documents at the origin-root `/.well-known/api-catalog` URI (`RFC 9727`), whereas `/llms.txt` indexes Markdown documentation at the site root or any subpath. [1][8]" }, { "target_id": "ai-crawler-tokens-robots", "target_name": "AI crawler tokens in robots.txt", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Governs AI crawler access using `robots.txt` product tokens like `GPTBot` and `OAI-SearchBot`, whereas `/llms.txt` curates links without access controls. [2][9]" }, { "target_id": "knowledge-linkset", "target_name": "The 'knowledge-linkset' Well-Known URI for Publishing Knowledge Artefacts", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Serves a JSON linkset at origin-root `/.well-known/knowledge-linkset`, whereas `/llms.txt` serves subpath-capable Markdown advertised via `rel=\"describedby\"`. [1]" }, { "target_id": "nlweb", "target_name": "NLWeb", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Exposes a conversational query endpoint over site content, whereas `/llms.txt` serves a static Markdown index that agents read and follow. [1]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (25 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Documentation origins publishing /llms.txt", "col4_header": "Published artifacts & companions", "note_md": "Publishing ≠ consumption: The producers table lists publishers that serve an `/llms.txt` endpoint as of the stated check date, not evidence that major AI search engines or assistant providers automatically fetch third-party `/llms.txt` files during retrieval (Google Search states it does not use `LLMS.txt`, and Ahrefs observed that 97% of HTTP-200 `/llms.txt` files received zero requests in May 2026). [2][10]", "rows": [ { "actor": "Anthropic (Claude API docs)", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `https://platform.claude.com/llms.txt` as `text/plain` (`# Anthropic Developer Documentation`), indexing 826 `/docs` pages, `llms-full.txt`, and `https://platform.claude.com/docs/mcp`.", "source_md": "[Anthropic, platform.claude.com/llms.txt (checked 2026-10-30)](https://platform.claude.com/llms.txt) [11]" }, { "actor": "OpenAI (Developer Platform docs)", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `https://developers.openai.com/llms.txt` as `text/plain` (`# OpenAI Developers`), indexing API, Codex, Agentic Commerce, and Cookbook `llms.txt` files.", "source_md": "[OpenAI, developers.openai.com/llms.txt (checked 2026-10-30)](https://developers.openai.com/llms.txt) [12]" }, { "actor": "Google AI (Gemini API docs)", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `https://ai.google.dev/gemini-api/docs/llms.txt` as `text/markdown` (`# Gemini API`), indexing Gemini API docs, API reference, and managed-agent environment pages.", "source_md": "[Google AI, Gemini API llms.txt (checked 2026-10-30)](https://ai.google.dev/gemini-api/docs/llms.txt) [13]" }, { "actor": "Cloudflare (Developer docs)", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `https://developers.cloudflare.com/llms.txt` as `text/plain` (`# Cloudflare Developer Documentation`), linking each Cloudflare product to its own `llms.txt` index.", "source_md": "[Cloudflare, developers.cloudflare.com/llms.txt (checked 2026-10-30)](https://developers.cloudflare.com/llms.txt) [14]" }, { "actor": "Stripe (Documentation)", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `https://docs.stripe.com/llms.txt` as `text/markdown` (`# Stripe Documentation`), linking `.md` page twins and npm/PyPI package registries.", "source_md": "[Stripe, docs.stripe.com/llms.txt (checked 2026-10-30)](https://docs.stripe.com/llms.txt) [15]" }, { "actor": "Cursor", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://cursor.com/llms.txt` as `text/plain` (`# Cursor Documentation`) with a `Link` header (`; rel=\"describedby\"; type=\"text/plain\"; title=\"llms.txt\"`).", "source_md": "[Cursor Documentation, cursor.com/llms.txt (checked 2026-11-04)](https://cursor.com/llms.txt) [16]" }, { "actor": "Vercel", "role": "Product site", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://vercel.com/llms.txt` as `text/plain` (`# Vercel`), with an Optional section linking `/.well-known/ai-catalog.json`.", "source_md": "[Vercel, vercel.com/llms.txt (checked 2026-11-04)](https://vercel.com/llms.txt) [17]" }, { "actor": "Supabase (Docs)", "role": "Docs platform", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://supabase.com/docs/llms.txt` as `text/plain` (`# Supabase Docs`) under `/docs/`, linking `llms-full.txt`, OpenAPI spec, and MCP server.", "source_md": "[Supabase Docs, supabase.com/docs/llms.txt (checked 2026-11-04)](https://supabase.com/docs/llms.txt) [18]" }, { "actor": "Model Context Protocol", "role": "Specification & docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://modelcontextprotocol.io/llms.txt` (`# Model Context Protocol`, `text/plain`), indexing versioned `2026-07-28` specification and SDK `.md` pages.", "source_md": "[modelcontextprotocol.io/llms.txt](https://modelcontextprotocol.io/llms.txt) [19]" }, { "actor": "Coinbase Developer Platform", "role": "Developer docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://docs.cdp.coinbase.com/llms.txt` (`# Coinbase Developer Documentation`, `text/plain`), linking `/_llms/` sub-indexes, `.md` recipes, and OpenAPI specs.", "source_md": "[docs.cdp.coinbase.com/llms.txt](https://docs.cdp.coinbase.com/llms.txt) [20]" }, { "actor": "Pydantic AI", "role": "Framework docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://ai.pydantic.dev/llms.txt` (`# Pydantic AI`, `text/plain`), requesting `intent`, `stack`, and `harness` query parameters on fetches.", "source_md": "[ai.pydantic.dev/llms.txt](https://ai.pydantic.dev/llms.txt) [7]" }, { "actor": "Svelte", "role": "Framework docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://svelte.dev/llms.txt` (`# Svelte Documentation for LLMs`, `text/plain`), linking `llms-small.txt`, `llms-medium.txt`, and `llms-full.txt` bundles.", "source_md": "[svelte.dev/llms.txt](https://svelte.dev/llms.txt) [21]" }, { "actor": "Bun", "role": "Runtime docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://bun.sh/llms.txt` (`# Bun`, `text/plain`), indexing runtime, package manager, bundler, and TypeScript `.md` documentation pages.", "source_md": "[bun.sh/llms.txt](https://bun.sh/llms.txt) [22]" }, { "actor": "LangChain", "role": "Framework docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://docs.langchain.com/llms.txt` (`# Docs by LangChain`, `text/plain`), linking recursive `/_llms/` sub-indexes and OpenAPI specs.", "source_md": "[docs.langchain.com/llms.txt](https://docs.langchain.com/llms.txt) [23]" }, { "actor": "Clerk", "role": "Developer docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://clerk.com/llms.txt` (`# Clerk`, `text/plain`), documenting `.md` URL suffixes and linking Backend and Frontend OpenAPI specs.", "source_md": "[clerk.com/llms.txt](https://clerk.com/llms.txt) [24]" }, { "actor": "Neon", "role": "Database docs origin", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves `https://neon.tech/llms.txt` (`# Neon Postgres`, `text/plain`), rewritten from `/docs/llms.txt` with `neon init` agent setup instructions.", "source_md": "[neon.tech/llms.txt](https://neon.tech/llms.txt) [25]" } ] }, "side_b": { "visible": true, "heading": "Consuming harnesses, IDEs & validators", "col4_header": "Discovery & ingestion behavior", "note_md": null, "rows": [ { "actor": "Chrome Lighthouse", "role": "Validator / CLI", "status": "Supported", "status_display": "Supported · as of 2026-05-05", "col4_md": "Agentic browsing audit fetches `llms.txt` and flags server errors; 404 is marked Not Applicable (updated 2026-05-05).", "source_md": "[Chrome for Developers, llms.txt (Lighthouse, updated 2026-05-05)](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt) [26]" }, { "actor": "Claude Code", "role": "Coding agent / IDE", "status": "Observed fetching", "status_display": "Observed fetching · as of 2026-05", "col4_md": "Observed fetching (`Claude-Code` trailed `GPTBot` and `statespace-indexer` among named AI fetchers in Ahrefs study); automatic discovery, parsing, and answer use unconfirmed.", "source_md": "[Ahrefs, llms.txt study (May 2026 dataset)](https://ahrefs.com/blog/llmstxt-study/) [2]" }, { "actor": "VS Code PagePilot Extension", "role": "Coding agent / IDE", "status": "Listed integration", "status_display": "Listed integration · as of 2026-08-10", "col4_md": "Listed integration on `llmstxt.org` for VS Code context; implementation behavior not independently verified.", "source_md": "[The /llms.txt file, v2 — Integrations](https://llmstxt.org) [1]" }, { "actor": "server-llm-txt", "role": "MCP server / harness", "status": "Listed integration", "status_display": "Listed integration · as of 2026-08-10", "col4_md": "Listed integration on `llmstxt.org` exposing `llms.txt` over MCP; implementation behavior not independently verified.", "source_md": "[The /llms.txt file, v2 — Integrations](https://llmstxt.org) [1]" } ] }, "additional_tables": [ { "visible": true, "heading": "CMS platforms, documentation engines & SEO plugins", "col4_header": "Generated paths & build mode", "note_md": null, "rows": [ { "actor": "Mintlify", "role": "Documentation engine", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Automatically generates `llms.txt`, `llms-full.txt`, and `.md` pages for hosted sites; serves `https://mintlify.com/docs/llms.txt` (`# Mintlify`, `text/plain`).", "source_md": "[mintlify.com/docs/llms.txt](https://mintlify.com/docs/llms.txt) [27] · [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] · [directory.llmstxt.cloud](https://directory.llmstxt.cloud/) [28]" }, { "actor": "GitBook", "role": "Documentation engine", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Automatically serves `llms.txt` and `.md` pages for published documentation sites, including `https://docs.gitbook.com/llms.txt` (`# GitBook Documentation`, `text/markdown`).", "source_md": "[docs.gitbook.com/llms.txt](https://docs.gitbook.com/llms.txt) [29] · [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] · [llmstxt.site](https://llmstxt.site/) [30]" }, { "actor": "Yoast SEO", "role": "WordPress SEO plugin", "status": "Supported", "status_display": "Supported · as of 2026-08-10", "col4_md": "WordPress plugin documented on `llmstxt.org` that automatically generates and maintains an `llms.txt` file.", "source_md": "[Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1]" }, { "actor": "AIOSEO", "role": "WordPress SEO plugin", "status": "Supported", "status_display": "Supported · as of 2026-08-10", "col4_md": "WordPress plugin documented on `llmstxt.org` that ships a built-in `llms.txt` generator.", "source_md": "[Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1]" }, { "actor": "Wix", "role": "Hosted CMS platform", "status": "Supported", "status_display": "Supported · as of 2026-08-10", "col4_md": "Hosted website builder documented on `llmstxt.org` that generates an `llms.txt` file for every Wix site.", "source_md": "[Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1]" } ] } ], "censuses": [ { "label": "Confirmed root-file availability under Rankability's response/content checks", "as_of": "2026-09-18", "value_md": "9.3% of the top 1,000 Tranco domains (93 confirmed adopters, 433 with no file, 474 inconclusive/blocked) and 8.3% of the top 10,000 Tranco domains (830 confirmed adopters, 4,959 with no file, 4,211 inconclusive/blocked) served a root llms.txt or llms-full.txt file under Rankability's response and content checks on 18 September 2026 (where llms-full.txt availability is not proof of index-grammar conformance), with 16 top-1,000 domains (1.6%) and 119 top-10,000 domains (1.2%) publishing both files. [31]" }, { "label": "HTTP-200 publication & bot traffic (Ahrefs Web Analytics study)", "as_of": "2026-05", "value_md": "28% (~38,000) of 137,210 domains using Ahrefs Web Analytics published a root /llms.txt returning HTTP 200 in May 2026 (an upper bound that did not test spec well-formedness), but 97% of those files received zero requests; across the 3% (~1,100 domains, ~22,000 requests) that received traffic, 4% (930 requests) came from humans and 96% of total requests came from twelve bot categories (one-decimal category shares): SEO audit tools (21.7% of total requests, including 10.6% from Ahrefs' own crawlers), other and unidentified bots (14.9%), general web crawlers (13.1%), tech profiling tools (11.6%), named AI tools (19.5% combined: 10.5% AI agents and agentic infrastructure led by statespace-indexer and Claude-Code, 5.3% AI training crawlers led by GPTBot, 2.5% AI assistants, and 1.1% AI retrieval bots), an industry-auditing-itself group (12.1% combined: 5.8% GEO/AEO tools, 3.6% llms.txt discoverability bots, and 2.7% research bots), and service and social bots (2.9%)—while zero AI bot requests targeted non-existent (HTTP 404) /llms.txt paths. [2]" }, { "label": "Observational, run-weighted trace analysis: 1,033 runs across 25 sites (Vercel study)", "as_of": "2026-08-28", "value_md": "In an observational, run-weighted trace analysis of 1,033 agent runs across 25 sites, agents reached llms.txt through in-page links in 356 of 416 attributed fetches (86%); among the 329 runs that reached an llms.txt file, 117 of 325 scorable runs (36%) subsequently fetched a page listed in the file, and 120 of 329 runs (36%) grounded their final answer in its content. [32]" }, { "label": "Directory-reported website listings & token totals (directory.llmstxt.cloud)", "as_of": "2026-11-04", "value_md": "4,092 listed websites across Websites (1,960), Products (870), Developer tools (560), AI (409), and Finance (293), indexing 51 million total llms.txt tokens and 390 million total llms-full.txt tokens as of 4 November 2026. [28]" }, { "label": "Installmap multi-cohort crawl & Originality.ai series", "as_of": "2026-09-23", "value_md": "In Installmap's 23 September 2026 crawl, 695 of 7,749 Tranco top-7,755 domains (9.0%) served a valid bare-domain llms.txt; 2,147 did not answer, so the share among domains that answered was 12.4%. Of those 695 valid files, 16 (2.3%) contained recommendation-steering instructions. Counting only llms.txt files with no plugin or Shopify signature, Installmap's September 2026 crawl found 19.0% of 4,931 Inc. 5000 domains, 28.3% of 1,058 unicorns, and 10.7% of 459 Fortune 500 domains. In Installmap's September 2026 crawl, 36.2% of 1,261 reachable Y Combinator companies from the 2025 and 2026 batches served an llms.txt, against 23.3% of 909 reachable companies from the 2012 to 2017 batches. Installmap quotes Originality.ai's tracker of more than 3 million websites: 4,088 llms.txt files in June 2025 and 36,120 in May 2026, while llms-full.txt grew from 23 to 2,463 over the same window. [5]" }, { "label": "llmtxt.info adoption panel", "as_of": "2026-10-05", "value_md": "llmtxt.info's fixed panel of 219 notable hosts, fetched weekly, recorded on 2026-10-05 that 57.6% of 217 tested hosts served a qualifying llms.txt (125 verified files; median 14.0 KB). Sector rates in that run included developer tools 44/61 (72.1%), SaaS 32/47 (68.1%), and media 2/14 (14.3%). Unreachable hosts are excluded from the base. [33]" }, { "label": "Early historical baseline — Chris Green Majestic Million crawl", "as_of": "2025-02", "value_md": "Early historical baseline: Chris Green wrote that his February 2025 crawl of the Majestic Million found \"only 0.015% (approximately 15 sites)\" with a valid LLMs.txt file—a source-side percentage/count discrepancy, since 0.015% of 1,000,000 is 150 sites whereas 15 sites is 0.0015% (against his ~210,000 valid robots.txt baseline, he reported ~0.007% adoption). At that time llmstxt.site listed roughly 170 sites and directory.llmstxt.cloud claimed around 684; a May 2025 edit on the same page reported 105 valid files. [34]" }, { "label": "Publii reading of BuiltWith", "as_of": "2026-10-17", "value_md": "Publii reports that BuiltWith showed 844,473 live sites in Publii's October 2025 reading and 14,586,789 live websites when Publii checked on 17 October 2026. The page presents this as BuiltWith's detection of the file, not as evidence that an agent read it. [4]" }, { "label": "SEMPITE llms.txt corpus (Zenodo)", "as_of": "2026-09-20", "value_md": "SEMPITE's Zenodo deposit (version 1.1.0, published 20 September 2026; concept DOI 10.5281/zenodo.22859104, version-pinned DOI 10.5281/zenodo.22862258) fetched all 1,563 llms.txt files registered in llmstxt.site, directory.llmstxt.cloud, and llmstxthub.com. A 5 August 2026 run found 15.7% broken at file level; the 20 September 2026 re-fetch found 265 files broken (17.0%), up from 245. [35][36]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "vercel-agent-readability", "target_name": "Agent Readability Spec", "relation_label": "Complements", "delta": "The guide treats /llms.txt as a readability artifact, while llms.txt is the Markdown file at /llms.txt or a subpath with a required H1, an optional blockquote, and H2 link sections.", "item_md": "**[Agent Readability Spec](/protocols/vercel-agent-readability/)** (Complements) — The guide treats /llms.txt as a readability artifact, while llms.txt is the Markdown file at /llms.txt or a subpath with a required H1, an optional blockquote, and H2 link sections." }, { "target_id": "osi", "target_name": "Apache Ossie (formerly Open Semantic Interchange)", "relation_label": "Complements", "delta": "Ossie has no fixed web path, while llms.txt is a file at /llms.txt or a subpath.", "item_md": "**[Apache Ossie (formerly Open Semantic Interchange)](/protocols/osi/)** (Complements) — Ossie has no fixed web path, while llms.txt is a file at /llms.txt or a subpath." }, { "target_id": "okf", "target_name": "Open Knowledge Format", "relation_label": "Peer alternative", "delta": "llms.txt is one Markdown file whose only required section is an H1; OKF is a multi-file directory.", "item_md": "**[Open Knowledge Format](/protocols/okf/)** (Peer alternative) — llms.txt is one Markdown file whose only required section is an H1; OKF is a multi-file directory." }, { "target_id": "agents-txt", "target_name": "agents.txt", "relation_label": "Complements", "delta": "agents.txt names protocol support at /agents.txt, including MCP, A2A, and x402, while llms.txt is the Markdown file at /llms.txt or a subpath with a required H1 and H2 link sections.", "item_md": "**[agents.txt](/protocols/agents-txt/)** (Complements) — agents.txt names protocol support at /agents.txt, including MCP, A2A, and x402, while llms.txt is the Markdown file at /llms.txt or a subpath with a required H1 and H2 link sections." }, { "target_id": "anthropic-agent-skills-format", "target_name": "Agent Skills", "relation_label": "Complements", "delta": "llms.txt proposes adding a Markdown file to websites, placed at the site root or at any path within it, with brief background information, guidance, and links to detailed Markdown files, while Agent Skills is a folder containing a SKILL.md file that agents load through progressive disclosure.", "item_md": "**[Agent Skills](/protocols/anthropic-agent-skills-format/)** (Complements) — llms.txt proposes adding a Markdown file to websites, placed at the site root or at any path within it, with brief background information, guidance, and links to detailed Markdown files, while Agent Skills is a folder containing a SKILL.md file that agents load through progressive disclosure." }, { "item_md": "**[Read protocols](/category/read/)** — Category index for `read` standards." } ], "v05_compiled_md": "---\nid: llms-txt\ntitle: \"llms.txt\"\ntier: flagship\nlifecycle_status: active\ncategory: read\nform: document-format\nwire_archetype: web_discovery\nspec_url: https://llmstxt.org\nlast_checked: 2026-11-11\n---\n\n# llms.txt\n\n**Category:** [Read](/category/read/) (`read`) · **Form:** Document format (`document-format`) · **Last checked:** 2026-11-11\n\n> *Not to be confused with [AGENTS.md](/protocols/agents-md/) (repository coding-agent instructions) or [ai.txt](/protocols/ai-txt/) (AI usage permissions). For the glossary entry, see [llms.txt file](/terms/llms-txt-file/). [1]*\n\n> **In brief:** `llms.txt` is a website index convention that gives AI assistants and coding agents a concise, human-curated map of a site's documentation and key resources via `/llms.txt` or subpath files like `/docs/llms.txt`. Instead of scraping noisy HTML pages cluttered with navigation, scripts, and layout markup—or ingesting an uncurated `sitemap.xml`—agents read one compact Markdown overview and fetch linked `.md` companion pages only when needed. [1]\n\n**llms.txt** is a community proposal originated by Jeremy Howard (co-founder of Answer.AI and fast.ai) on September 3, 2024 (`2024-09-03`) that standardizes a Markdown file named `llms.txt` at `/llms.txt` or a subpath such as `/docs/llms.txt`. The file gives reading agents brief background context, guidance, and curated links to detailed Markdown pages under that path. [1][2] Alongside `llms.txt` (where agents use the most specific file when multiple paths apply), pages expose a clean Markdown companion at the same URL with `.md` appended (`page.html.md`), the extension replaced (`page.md`), or `index.html.md` / `index.md` for directory URLs. Clients discover the Markdown companion via `rel=\"alternate\"` `type=\"text/markdown\"` and the covering `llms.txt` via `rel=\"describedby\"` in HTML `` elements or HTTP `Link:` response headers. [1] Revision `v2` (modified August 10, 2026) broadened Markdown companion URLs beyond v1's single appended-extension form and retired the v1 `llms_txt2ctx` context-expansion tool and mechanical `Optional` omission semantics. [1][3]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Read](/category/read/) (`read`) |\n| **Form** | Document format (`document-format`) |\n| **Originated by** | Jeremy Howard (Answer.AI / fast.ai), published 2024-09-03 [1][2] |\n| **Governed by** | Jeremy Howard; open for community input via public GitHub repository [1] |\n| **Track** | Vendor / Spec-Site Standard (informal community overview) [1] |\n| **Status** | v2 proposal (informal overview, open for community input) [1] |\n| **Version** | v2 (modified 2026-08-10; v1 published 2024-09-03) [1] |\n| **Message format** | Markdown (required H1 title, optional summary blockquote, and H2 link lists) [1] |\n| **Headers** | HTML `` or HTTP `Link:` with `rel=\"alternate\"` `type=\"text/markdown\"` and `rel=\"describedby\"` [1] |\n| **Specification** | [The /llms.txt file, v2](https://llmstxt.org) ([v2 Changes](https://llmstxt.org/changes.html)) [1][3] |\n| **Found at** | `/llms.txt` at the site root or any subpath (e.g., `/docs/llms.txt`) [1] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Section order and file-list syntax](#section-order-and-file-list-syntax)\n3. [Companion Markdown pages and context expansion](#companion-markdown-pages-and-context-expansion)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nAn HTML page wraps its information in navigation, ads, and JavaScript, so converting it back into clean text is difficult and imprecise, and every wasted token costs time and money while context windows are still too small for most websites. `sitemap.xml` lists indexable human-readable URLs, but it often lacks the LLM-readable versions, omits helpful external URLs, and is too large to stand in for a curated overview. [1] The site instead publishes a small `llms.txt` that agents view or search, with links aimed at LLM-friendly Markdown versions of pages. The file stays small enough to fit in context; the detail lives behind the links and is fetched only when needed. [1] `/robots.txt` tells automated tools what access is considered acceptable, such as for search indexing bots, whereas `llms.txt` is read on demand while an agent assists a user and was expected to help inference rather than training. It is also not a root-only `/.well-known/` URI under RFC 8615: an author who controls only a path, such as a GitHub Pages project site, can still publish a file there. [1]\n\n### Canonical `llms.txt` specimen (FastHTML, cut down)\n\n```markdown\n# FastHTML\n\n> FastHTML is a python library which brings together Starlette, Uvicorn, HTMX, and fastcore's `FT` \"FastTags\" into a library for creating server-rendered hypermedia applications.\n\nImportant notes:\n\n- Although parts of its API are inspired by FastAPI, it is *not* compatible with FastAPI syntax and is not targeted at creating API services\n- FastHTML is compatible with JS-native web components and any vanilla JS library, but not with React, Vue, or Svelte.\n\n## Docs\n\n- [FastHTML quick start](https://fastht.ml/docs/tutorials/quickstart_for_web_devs.html.md): A brief overview of many FastHTML features\n- [HTMX reference](https://github.com/bigskysoftware/htmx/blob/master/www/content/reference.md): Brief description of all HTMX attributes, CSS classes, headers, events, extensions, js lib methods, and config options\n\n## Examples\n\n- [Todo list application](https://github.com/AnswerDotAI/fasthtml/blob/main/examples/adv_app.py): Detailed walk-thru of a complete CRUD app in FastHTML showing idiomatic use of FastHTML and HTMX patterns.\n\n## Optional\n\n- [Starlette full documentation](https://gist.githubusercontent.com/jph00/809e4a4808d4510be0e3dc9565e9cbd3/raw/9b717589ca44cedc8aaf00b2b8cacef922964c0f/starlette-sml.md): A subset of the Starlette documentation useful for FastHTML development.\n```\n\n*Cut-down FastHTML `llms.txt` from the specification, with an H1, a summary blockquote, and H2 file lists `## Docs`, `## Examples`, and `## Optional`. [1]*\n\n---\n\n## Section order and file-list syntax\n\nMarkdown, rather than XML, provides the structure so language models and agents can read `llms.txt` directly while classical parsers and regular expressions process its fixed section order. Both the canonical FastHTML specimen (`fastht.ml/docs/`) and the minimal reference mock in the specification follow the same sequence: an H1 title, a summary blockquote, non-heading notes, and H2 file lists. [1]\n\n- **Required H1 and summary header:** An optional byte-order mark (`BOM`) may precede the H1, which names the project or site and is the only required section. A blockquote then holds the key summary, followed by zero or more non-heading paragraphs or lists with project detail before any H2 section begins. [1]\n- **H2 section file lists:** Each H2 heading opens a file list of URLs where further detail is available: the specification's minimal reference mock uses `## Section name` and `## Optional`, while the canonical FastHTML specimen uses `## Docs`, `## Examples`, and `## Optional`. Pre-H2 project notes—such as the FastAPI compatibility bullet under `Important notes:`—stay above `## Docs` rather than appearing as file-link entries. [1]\n- **Entry link and colon description:** Every list item starts with a required Markdown hyperlink `[name](url)`, optionally followed by `:` and notes about the file. In the specification's reference mock, `- [Link title](https://link_url): Optional link details` includes anchor text, a URL, and a colon description, whereas the `## Optional` mock entry `- [Link title](https://link_url)` omits the colon and description. [1]\n- **Secondary links under ## Optional:** The `## Optional` section holds secondary links an agent can skip when a shorter context is needed—in the FastHTML specimen, the Starlette documentation subset rather than the quick start under `## Docs`. Revision `v2` retains `## Optional` as a convention for secondary links, but it no longer carries mechanical semantics telling expansion tools what to omit. [1][3]\n\n---\n\n## Companion Markdown pages and context expansion\n\nLinks in `llms.txt` should point at LLM-friendly Markdown pages. `/docs/llms.txt` covers everything in `/docs/`. FastHTML's `llms.txt` sits at `/docs/` for its documentation, and a docs page is also published at the same URL with a `.md` extension. [1]\n\n- **Why both .md spellings exist:** v1 allowed one spelling: `.md` appended, producing `page.html.md`. Tools that replace the extension emit `page.md`, which `v2` also allows. URLs with no file name append `index.html.md` or `index.md`. `nbdev` creates `.md` versions of every page by default, including the regenerated Answer.AI and fast.ai docs. [1][3]\n- **One Link header names both:** The example header is `Link: ; rel=\"alternate\"; type=\"text/markdown\", ; rel=\"describedby\"`. `rel=\"alternate\"` with `type=\"text/markdown\"` names the Markdown page; `rel=\"describedby\"` names the covering `llms.txt`. The same relations work as HTML `` elements, and the header can be set on the `.md` files from a CDN without editing pages. [1]\n- **llms_txt2ctx and llms-full.txt:** `llms_txt2ctx` expanded an `llms.txt` into an LLM context and used the Optional section to decide what to omit. v2 instead has agents view or search the `llms.txt` and follow links to LLM-friendly content. Sites still publish `llms-full.txt`, one large gathered file for a deliberate full load, which can become enormous and go stale quickly. [3][4]\n- **Python, CLI, and JavaScript readers, and untrusted publisher content:** The `Code` menu on `llmstxt.org` lists `Python module & CLI`, `Python source`, and `JavaScript`, plus a sample `JavaScript Implementation`. `llms-txt-php` writes and reads `llms.txt` files, `vitepress-plugin-llms` generates documentation that follows the specification, and `server-llm-txt` lets agents fetch and search those files. Because `llms.txt` is a self-declared, unverified publisher file that neither grants nor denies access (unlike `/robots.txt`), consuming agents should treat retrieved `llms.txt` content as untrusted input. Installmap's 23 September 2026 crawl read 695 bare-domain `llms.txt` files: 16 (2.3%) carry overt brand or recommendation-steering instructions, another 29 (4.2%) tell assistants to send users to the company's own pages or not to guess facts, and 49 (7.1%) set usage, licensing, or agent-integration terms. None of the 7,749 homepages hid text addressed to AI, and no file said \"ignore previous instructions\". [1][5][6]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **Sitemaps XML (sitemaps.org)** | `sitemaps.org` | Analogous to classic standard | Lists publisher-supplied URLs for discovery, without llms.txt's annotated Markdown guide structure. [1] |\n| **robots.txt (RFC 9309)** | `RFC 9309` | Analogous to classic standard | Declares automated crawler access rules at `/robots.txt`, whereas `/llms.txt` provides an on-demand Markdown content guide during inference. [1] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[AGENTS.md](/protocols/agents-md/)** | Complements | Supplies repository-level coding instructions via `AGENTS.md`, whereas `/llms.txt` indexes published web documentation at the site root or a subpath. [1][7] |\n| **[Markdown for Agents](/protocols/cloudflare-markdown-for-agents/)** | Peer alternative | Negotiates Markdown representations on existing URLs, whereas `/llms.txt` links static `.md` page twins via `rel=\"alternate\"` `type=\"text/markdown\"`. [1] |\n| **[api-catalog (RFC 9727)](/protocols/api-catalog-rfc9727/)** | Complements | Publishes machine-readable API discovery documents at the origin-root `/.well-known/api-catalog` URI (`RFC 9727`), whereas `/llms.txt` indexes Markdown documentation at the site root or any subpath. [1][8] |\n| **[AI crawler tokens in robots.txt](/protocols/ai-crawler-tokens-robots/)** | Complements | Governs AI crawler access using `robots.txt` product tokens like `GPTBot` and `OAI-SearchBot`, whereas `/llms.txt` curates links without access controls. [2][9] |\n| **[The 'knowledge-linkset' Well-Known URI for Publishing Knowledge Artefacts](/protocols/knowledge-linkset/)** | Peer alternative | Serves a JSON linkset at origin-root `/.well-known/knowledge-linkset`, whereas `/llms.txt` serves subpath-capable Markdown advertised via `rel=\"describedby\"`. [1] |\n| **[NLWeb](/protocols/nlweb/)** | Complements | Exposes a conversational query endpoint over site content, whereas `/llms.txt` serves a static Markdown index that agents read and follow. [1] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (25 probed or cited examples across 3 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Documentation origins publishing /llms.txt\n\nPublishing ≠ consumption: The producers table lists publishers that serve an `/llms.txt` endpoint as of the stated check date, not evidence that major AI search engines or assistant providers automatically fetch third-party `/llms.txt` files during retrieval (Google Search states it does not use `LLMS.txt`, and Ahrefs observed that 97% of HTTP-200 `/llms.txt` files received zero requests in May 2026). [2][10]\n\n| Actor | Role | Status | Published artifacts & companions | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Anthropic (Claude API docs)** | Docs platform | Live (HTTP 200) · checked 2026-10-30 | Serves `https://platform.claude.com/llms.txt` as `text/plain` (`# Anthropic Developer Documentation`), indexing 826 `/docs` pages, `llms-full.txt`, and `https://platform.claude.com/docs/mcp`. | [Anthropic, platform.claude.com/llms.txt (checked 2026-10-30)](https://platform.claude.com/llms.txt) [11] |\n| **OpenAI (Developer Platform docs)** | Docs platform | Live (HTTP 200) · checked 2026-10-30 | Serves `https://developers.openai.com/llms.txt` as `text/plain` (`# OpenAI Developers`), indexing API, Codex, Agentic Commerce, and Cookbook `llms.txt` files. | [OpenAI, developers.openai.com/llms.txt (checked 2026-10-30)](https://developers.openai.com/llms.txt) [12] |\n| **Google AI (Gemini API docs)** | Docs platform | Live (HTTP 200) · checked 2026-10-30 | Serves `https://ai.google.dev/gemini-api/docs/llms.txt` as `text/markdown` (`# Gemini API`), indexing Gemini API docs, API reference, and managed-agent environment pages. | [Google AI, Gemini API llms.txt (checked 2026-10-30)](https://ai.google.dev/gemini-api/docs/llms.txt) [13] |\n| **Cloudflare (Developer docs)** | Docs platform | Live (HTTP 200) · checked 2026-10-30 | Serves `https://developers.cloudflare.com/llms.txt` as `text/plain` (`# Cloudflare Developer Documentation`), linking each Cloudflare product to its own `llms.txt` index. | [Cloudflare, developers.cloudflare.com/llms.txt (checked 2026-10-30)](https://developers.cloudflare.com/llms.txt) [14] |\n| **Stripe (Documentation)** | Docs platform | Live (HTTP 200) · checked 2026-10-30 | Serves `https://docs.stripe.com/llms.txt` as `text/markdown` (`# Stripe Documentation`), linking `.md` page twins and npm/PyPI package registries. | [Stripe, docs.stripe.com/llms.txt (checked 2026-10-30)](https://docs.stripe.com/llms.txt) [15] |\n| **Cursor** | Docs platform | Live (HTTP 200) · checked 2026-11-04 | Serves `https://cursor.com/llms.txt` as `text/plain` (`# Cursor Documentation`) with a `Link` header (`; rel=\"describedby\"; type=\"text/plain\"; title=\"llms.txt\"`). | [Cursor Documentation, cursor.com/llms.txt (checked 2026-11-04)](https://cursor.com/llms.txt) [16] |\n| **Vercel** | Product site | Live (HTTP 200) · checked 2026-11-04 | Serves `https://vercel.com/llms.txt` as `text/plain` (`# Vercel`), with an Optional section linking `/.well-known/ai-catalog.json`. | [Vercel, vercel.com/llms.txt (checked 2026-11-04)](https://vercel.com/llms.txt) [17] |\n| **Supabase (Docs)** | Docs platform | Live (HTTP 200) · checked 2026-11-04 | Serves `https://supabase.com/docs/llms.txt` as `text/plain` (`# Supabase Docs`) under `/docs/`, linking `llms-full.txt`, OpenAPI spec, and MCP server. | [Supabase Docs, supabase.com/docs/llms.txt (checked 2026-11-04)](https://supabase.com/docs/llms.txt) [18] |\n| **Model Context Protocol** | Specification & docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://modelcontextprotocol.io/llms.txt` (`# Model Context Protocol`, `text/plain`), indexing versioned `2026-07-28` specification and SDK `.md` pages. | [modelcontextprotocol.io/llms.txt](https://modelcontextprotocol.io/llms.txt) [19] |\n| **Coinbase Developer Platform** | Developer docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://docs.cdp.coinbase.com/llms.txt` (`# Coinbase Developer Documentation`, `text/plain`), linking `/_llms/` sub-indexes, `.md` recipes, and OpenAPI specs. | [docs.cdp.coinbase.com/llms.txt](https://docs.cdp.coinbase.com/llms.txt) [20] |\n| **Pydantic AI** | Framework docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://ai.pydantic.dev/llms.txt` (`# Pydantic AI`, `text/plain`), requesting `intent`, `stack`, and `harness` query parameters on fetches. | [ai.pydantic.dev/llms.txt](https://ai.pydantic.dev/llms.txt) [7] |\n| **Svelte** | Framework docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://svelte.dev/llms.txt` (`# Svelte Documentation for LLMs`, `text/plain`), linking `llms-small.txt`, `llms-medium.txt`, and `llms-full.txt` bundles. | [svelte.dev/llms.txt](https://svelte.dev/llms.txt) [21] |\n| **Bun** | Runtime docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://bun.sh/llms.txt` (`# Bun`, `text/plain`), indexing runtime, package manager, bundler, and TypeScript `.md` documentation pages. | [bun.sh/llms.txt](https://bun.sh/llms.txt) [22] |\n| **LangChain** | Framework docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://docs.langchain.com/llms.txt` (`# Docs by LangChain`, `text/plain`), linking recursive `/_llms/` sub-indexes and OpenAPI specs. | [docs.langchain.com/llms.txt](https://docs.langchain.com/llms.txt) [23] |\n| **Clerk** | Developer docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://clerk.com/llms.txt` (`# Clerk`, `text/plain`), documenting `.md` URL suffixes and linking Backend and Frontend OpenAPI specs. | [clerk.com/llms.txt](https://clerk.com/llms.txt) [24] |\n| **Neon** | Database docs origin | Live (HTTP 200) · checked 2026-11-04 | Serves `https://neon.tech/llms.txt` (`# Neon Postgres`, `text/plain`), rewritten from `/docs/llms.txt` with `neon init` agent setup instructions. | [neon.tech/llms.txt](https://neon.tech/llms.txt) [25] |\n\n### Consuming harnesses, IDEs & validators\n\n| Actor | Role | Status | Discovery & ingestion behavior | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Chrome Lighthouse** | Validator / CLI | Supported · as of 2026-05-05 | Agentic browsing audit fetches `llms.txt` and flags server errors; 404 is marked Not Applicable (updated 2026-05-05). | [Chrome for Developers, llms.txt (Lighthouse, updated 2026-05-05)](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt) [26] |\n| **Claude Code** | Coding agent / IDE | Observed fetching · as of 2026-05 | Observed fetching (`Claude-Code` trailed `GPTBot` and `statespace-indexer` among named AI fetchers in Ahrefs study); automatic discovery, parsing, and answer use unconfirmed. | [Ahrefs, llms.txt study (May 2026 dataset)](https://ahrefs.com/blog/llmstxt-study/) [2] |\n| **VS Code PagePilot Extension** | Coding agent / IDE | Listed integration · as of 2026-08-10 | Listed integration on `llmstxt.org` for VS Code context; implementation behavior not independently verified. | [The /llms.txt file, v2 — Integrations](https://llmstxt.org) [1] |\n| **server-llm-txt** | MCP server / harness | Listed integration · as of 2026-08-10 | Listed integration on `llmstxt.org` exposing `llms.txt` over MCP; implementation behavior not independently verified. | [The /llms.txt file, v2 — Integrations](https://llmstxt.org) [1] |\n\n### CMS platforms, documentation engines & SEO plugins\n\n| Actor | Role | Status | Generated paths & build mode | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Mintlify** | Documentation engine | Live (HTTP 200) · checked 2026-11-04 | Automatically generates `llms.txt`, `llms-full.txt`, and `.md` pages for hosted sites; serves `https://mintlify.com/docs/llms.txt` (`# Mintlify`, `text/plain`). | [mintlify.com/docs/llms.txt](https://mintlify.com/docs/llms.txt) [27] · [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] · [directory.llmstxt.cloud](https://directory.llmstxt.cloud/) [28] |\n| **GitBook** | Documentation engine | Live (HTTP 200) · checked 2026-11-04 | Automatically serves `llms.txt` and `.md` pages for published documentation sites, including `https://docs.gitbook.com/llms.txt` (`# GitBook Documentation`, `text/markdown`). | [docs.gitbook.com/llms.txt](https://docs.gitbook.com/llms.txt) [29] · [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] · [llmstxt.site](https://llmstxt.site/) [30] |\n| **Yoast SEO** | WordPress SEO plugin | Supported · as of 2026-08-10 | WordPress plugin documented on `llmstxt.org` that automatically generates and maintains an `llms.txt` file. | [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] |\n| **AIOSEO** | WordPress SEO plugin | Supported · as of 2026-08-10 | WordPress plugin documented on `llmstxt.org` that ships a built-in `llms.txt` generator. | [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] |\n| **Wix** | Hosted CMS platform | Supported · as of 2026-08-10 | Hosted website builder documented on `llmstxt.org` that generates an `llms.txt` file for every Wix site. | [Howard, The /llms.txt file, v2 (published 2024-09-03; modified 2026-08-10)](https://llmstxt.org) [1] |\n\n### Ecosystem censuses\n\n- **Confirmed root-file availability under Rankability's response/content checks** (*as of 2026-09-18*): 9.3% of the top 1,000 Tranco domains (93 confirmed adopters, 433 with no file, 474 inconclusive/blocked) and 8.3% of the top 10,000 Tranco domains (830 confirmed adopters, 4,959 with no file, 4,211 inconclusive/blocked) served a root llms.txt or llms-full.txt file under Rankability's response and content checks on 18 September 2026 (where llms-full.txt availability is not proof of index-grammar conformance), with 16 top-1,000 domains (1.6%) and 119 top-10,000 domains (1.2%) publishing both files. [31]\n- **HTTP-200 publication & bot traffic (Ahrefs Web Analytics study)** (*as of 2026-05*): 28% (~38,000) of 137,210 domains using Ahrefs Web Analytics published a root /llms.txt returning HTTP 200 in May 2026 (an upper bound that did not test spec well-formedness), but 97% of those files received zero requests; across the 3% (~1,100 domains, ~22,000 requests) that received traffic, 4% (930 requests) came from humans and 96% of total requests came from twelve bot categories (one-decimal category shares): SEO audit tools (21.7% of total requests, including 10.6% from Ahrefs' own crawlers), other and unidentified bots (14.9%), general web crawlers (13.1%), tech profiling tools (11.6%), named AI tools (19.5% combined: 10.5% AI agents and agentic infrastructure led by statespace-indexer and Claude-Code, 5.3% AI training crawlers led by GPTBot, 2.5% AI assistants, and 1.1% AI retrieval bots), an industry-auditing-itself group (12.1% combined: 5.8% GEO/AEO tools, 3.6% llms.txt discoverability bots, and 2.7% research bots), and service and social bots (2.9%)—while zero AI bot requests targeted non-existent (HTTP 404) /llms.txt paths. [2]\n- **Observational, run-weighted trace analysis: 1,033 runs across 25 sites (Vercel study)** (*as of 2026-08-28*): In an observational, run-weighted trace analysis of 1,033 agent runs across 25 sites, agents reached llms.txt through in-page links in 356 of 416 attributed fetches (86%); among the 329 runs that reached an llms.txt file, 117 of 325 scorable runs (36%) subsequently fetched a page listed in the file, and 120 of 329 runs (36%) grounded their final answer in its content. [32]\n- **Directory-reported website listings & token totals (directory.llmstxt.cloud)** (*as of 2026-11-04*): 4,092 listed websites across Websites (1,960), Products (870), Developer tools (560), AI (409), and Finance (293), indexing 51 million total llms.txt tokens and 390 million total llms-full.txt tokens as of 4 November 2026. [28]\n- **Installmap multi-cohort crawl & Originality.ai series** (*as of 2026-09-23*): In Installmap's 23 September 2026 crawl, 695 of 7,749 Tranco top-7,755 domains (9.0%) served a valid bare-domain llms.txt; 2,147 did not answer, so the share among domains that answered was 12.4%. Of those 695 valid files, 16 (2.3%) contained recommendation-steering instructions. Counting only llms.txt files with no plugin or Shopify signature, Installmap's September 2026 crawl found 19.0% of 4,931 Inc. 5000 domains, 28.3% of 1,058 unicorns, and 10.7% of 459 Fortune 500 domains. In Installmap's September 2026 crawl, 36.2% of 1,261 reachable Y Combinator companies from the 2025 and 2026 batches served an llms.txt, against 23.3% of 909 reachable companies from the 2012 to 2017 batches. Installmap quotes Originality.ai's tracker of more than 3 million websites: 4,088 llms.txt files in June 2025 and 36,120 in May 2026, while llms-full.txt grew from 23 to 2,463 over the same window. [5]\n- **llmtxt.info adoption panel** (*as of 2026-10-05*): llmtxt.info's fixed panel of 219 notable hosts, fetched weekly, recorded on 2026-10-05 that 57.6% of 217 tested hosts served a qualifying llms.txt (125 verified files; median 14.0 KB). Sector rates in that run included developer tools 44/61 (72.1%), SaaS 32/47 (68.1%), and media 2/14 (14.3%). Unreachable hosts are excluded from the base. [33]\n- **Early historical baseline — Chris Green Majestic Million crawl** (*as of 2025-02*): Early historical baseline: Chris Green wrote that his February 2025 crawl of the Majestic Million found \"only 0.015% (approximately 15 sites)\" with a valid LLMs.txt file—a source-side percentage/count discrepancy, since 0.015% of 1,000,000 is 150 sites whereas 15 sites is 0.0015% (against his ~210,000 valid robots.txt baseline, he reported ~0.007% adoption). At that time llmstxt.site listed roughly 170 sites and directory.llmstxt.cloud claimed around 684; a May 2025 edit on the same page reported 105 valid files. [34]\n- **Publii reading of BuiltWith** (*as of 2026-10-17*): Publii reports that BuiltWith showed 844,473 live sites in Publii's October 2025 reading and 14,586,789 live websites when Publii checked on 17 October 2026. The page presents this as BuiltWith's detection of the file, not as evidence that an agent read it. [4]\n- **SEMPITE llms.txt corpus (Zenodo)** (*as of 2026-09-20*): SEMPITE's Zenodo deposit (version 1.1.0, published 20 September 2026; concept DOI 10.5281/zenodo.22859104, version-pinned DOI 10.5281/zenodo.22862258) fetched all 1,563 llms.txt files registered in llmstxt.site, directory.llmstxt.cloud, and llmstxthub.com. A 5 August 2026 run found 15.7% broken at file level; the 20 September 2026 re-fetch found 265 files broken (17.0%), up from 245. [35][36]\n\n---\n\n## See also\n\n- **[Agent Readability Spec](/protocols/vercel-agent-readability/)** *(Complements)* — The guide treats /llms.txt as a readability artifact, while llms.txt is the Markdown file at /llms.txt or a subpath with a required H1, an optional blockquote, and H2 link sections.\n- **[Apache Ossie (formerly Open Semantic Interchange)](/protocols/osi/)** *(Complements)* — Ossie has no fixed web path, while llms.txt is a file at /llms.txt or a subpath.\n- **[Open Knowledge Format](/protocols/okf/)** *(Peer alternative)* — llms.txt is one Markdown file whose only required section is an H1; OKF is a multi-file directory.\n- **[agents.txt](/protocols/agents-txt/)** *(Complements)* — agents.txt names protocol support at /agents.txt, including MCP, A2A, and x402, while llms.txt is the Markdown file at /llms.txt or a subpath with a required H1 and H2 link sections.\n- **[Agent Skills](/protocols/anthropic-agent-skills-format/)** *(Complements)* — llms.txt proposes adding a Markdown file to websites, placed at the site root or at any path within it, with brief background information, guidance, and links to detailed Markdown files, while Agent Skills is a folder containing a SKILL.md file that agents load through progressive disclosure.\n- **Category:** [Read protocols](/category/read/)\n\n---\n\n## References\n\n1. Jeremy Howard, *The /llms.txt file, v2* (published 2024-09-03; modified 2026-08-10; HTTP last-modified 2026-09-24) — \n2. Louise Linehan (Ahrefs), *We Analyzed 137K Sites: 97% of llms.txt Files Never Get Read* (published 2026-06-15; modified 2026-08-27; data: May 2026) — \n3. Jeremy Howard, *Changes* (August 2026; HTTP last-modified 2026-09-24) — \n4. Publii, *The complete guide to llms.txt* (BuiltWith reading 17 October 2026; fetched 2026-11-06) — \n5. Installmap, *llms.txt statistics (CSV)* (crawls through September 2026; fetched 2026-11-06) — \n6. Installmap, *Everyone is hilariously prompt-injecting AI via llms.txt and you aren't* (2026-09-23; fetched 2026-11-11) — \n7. Pydantic, *Pydantic AI* (HTTP 200; fetched 2026-11-04) — \n8. K. Smith (Vodafone), *api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs* (published June 2025) — \n9. OpenAI, *Overview of OpenAI Crawlers* (fetched 2026-11-03) — \n10. Google Search Central, *Google's Guide to Optimizing for Generative AI Features on Google Search* (updated 2026-07-10) — \n11. Anthropic, *platform.claude.com/llms.txt* (HTTP 200; fetched 2026-10-30) — \n12. OpenAI, *developers.openai.com/llms.txt* (HTTP 200; fetched 2026-10-30) — \n13. Google AI, *Gemini API llms.txt* (HTTP 200; fetched 2026-10-30) — \n14. Cloudflare, *developers.cloudflare.com/llms.txt* (HTTP 200; fetched 2026-10-30) — \n15. Stripe, *docs.stripe.com/llms.txt* (HTTP 200; fetched 2026-10-30) — \n16. Cursor, *Cursor Documentation* (HTTP 200; fetched 2026-11-04) — \n17. Vercel, *Vercel* (HTTP 200; fetched 2026-11-04) — \n18. Supabase (Docs), *Supabase Docs* (HTTP 200; fetched 2026-11-04) — \n19. Model Context Protocol (MCP), *Model Context Protocol* (HTTP 200; fetched 2026-11-04) — \n20. Coinbase Developer Platform, *Coinbase Developer Documentation* (HTTP 200; fetched 2026-11-04) — \n21. Svelte, *Svelte Documentation for LLMs* (HTTP 200; fetched 2026-11-04) — \n22. Bun, *Bun* (HTTP 200; fetched 2026-11-04) — \n23. LangChain, *Docs by LangChain* (HTTP 200; fetched 2026-11-04) — \n24. Clerk, *Clerk* (HTTP 200; fetched 2026-11-04) — \n25. Neon, *Neon Postgres* (HTTP 200; fetched 2026-11-04) — \n26. Chrome for Developers, *llms.txt* (updated 2026-05-05) — \n27. Mintlify, *Mintlify* (HTTP 200; fetched 2026-11-04) — \n28. llms.txt cloud directory, *llms.txt directory* (checked 2026-11-04) — \n29. GitBook, *GitBook Documentation* (HTTP 200; fetched 2026-11-04) — \n30. llms.txt directory, *llms.txt directory - Find llms.txt files across the web* (checked 2026-11-04) — \n31. Rankability, *llms.txt Adoption Research Report* (published 2026-09-18) — \n32. Vercel and Ora, *Make your site readable by AI agents* (published 2026-08-28; modified 2026-09-03) — \n33. LLMtxt Adoption Directory, *llms.txt adoption panel* (latest run 2026-10-05; fetched 2026-11-06) — \n34. Chris Green, *A million websites in search of llms.txt* (February 2025 crawl; May 2025 edit; fetched 2026-11-06) — \n35. Jacob Ezra Gerrish (SEMPITE), *The llms.txt corpus: ecosystem health, file contents, and the Shopify platform default* (published 20 September 2026 (v1.1.0, version DOI 10.5281/zenodo.22862258)) — \n36. Jacob Ezra Gerrish (SEMPITE / Zenodo API), *Zenodo Record 22862258 Metadata (v1.1.0, concept DOI 10.5281/zenodo.22859104)* (2026-09-20 (v1.1.0)) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "", "adoption": { "level": "observed", "by": "vercel/next.js, microsoft/vscode, apache/airflow, pandas-dev/pandas, astral-sh/uv, OpenAI Codex, GitHub Copilot, Cursor, and 15 other verified implementations", "probe_run": null }, "aliases": [], "analog": "CONTRIBUTING.md / a repository's contributor instructions, but written for an agent instead of a human contributor", "collisions": [], "discovery": { "mechanism": "AGENTS.md at the repository root; nested AGENTS.md files allowed in subdirectories", "path": "AGENTS.md at the repository root; nested AGENTS.md files allowed in subdirectories" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://agents.md/", "claim": "AGENTS.md (Agentic AI Foundation), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project. / README.md files are for humans: quick starts, project descriptions, and contribution guidelines. AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren't relevant to human contributors. / AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory. / Are there required fields? No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide. / Create an AGENTS.md file at the root of the repository. / Place another AGENTS.md inside each package. / Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. / The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything. / AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation. / A simple, open format for guiding coding agents / Are there required fields? No. AGENTS.md is just standard Markdown. / AGENTS.md A simple, open format for guiding coding agents / Create an AGENTS.md file at the root of the repository. … Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence / Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. / README.md files are for humans: quick starts, project descriptions, and contribution guidelines. / Provide precise, agent-focused guidance that complements existing README and docs. / # AGENTS.md ## Setup commands - Install deps: pnpm install - Start dev server: pnpm dev - Run tests: pnpm test ## Code style - TypeScript strict mode - Single quotes, no semicolons - Use functional patterns where possible / Add sections that help an agent work effectively with your project. Popular choices: Project overview Build and test commands Code style guidelines Testing instructions Security considerations / For example, at time of writing the main OpenAI repo has 88 AGENTS.md files. / The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task. / Install deps: pnpm install - Start dev server: pnpm dev - Run tests: pnpm test / Always run pnpm lint and pnpm test before committing. / After moving files or changing imports, run pnpm lint --filter / Treat AGENTS.md as living documentation. / # AGENTS.md ## Setup commands - Install deps: pnpm install / ## Code style - TypeScript strict mode / Your agent definitions are compatible with a growing ecosystem of AI coding agents and tools / One AGENTS.md works across many agents / Rename existing files to AGENTS.md and create symbolic links for backward compatibility: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md / Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project. … Create an AGENTS.md file at the root of the repository. / How do I configure Aider? Configure Aider to use AGENTS.md in .aider.conf.yml: read: AGENTS.md / How do I configure Gemini CLI? Configure Gemini CLI to use AGENTS.md in .gemini/settings.json: { \"context\": { \"fileName\": \"AGENTS.md\" }, } / AGENTS.md … Your agent definitions are compatible with a growing ecosystem of AI coding agents and tools: Codexfrom OpenAI Julesfrom Google Factory Aider goose opencode Zed Warp VS Code / AGENTS.md … Coding agentfrom GitHub Copilot Ona Windsurffrom Cognition Augment Code / AGENTS.md … Your agent definitions are compatible with a growing ecosystem of AI coding agents and tools: Codexfrom OpenAI Julesfrom Google Factory Aider goose opencode Zed / A simple, open format for guiding coding agents, used by over 60k open-source projects.", "ref": 1 }, { "label": "[2]", "url": "https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions", "claim": "GitHub, *Adding repository custom instructions for GitHub Copilot*, checked 2026-10-30", "date": null, "quote": "adding a .github/copilot-instructions.md file in the repository / Alternatively, you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository. / You can create one or more AGENTS.md files, stored anywhere within the repository. When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence. / These are specified in a copilot-instructions.md file in the .github directory of the repository. … These are specified in one or more NAME.instructions.md files within or below the .github/instructions directory in the repository. … You can create one or more AGENTS.md files, stored anywhere within the repository. When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence. … Alternatively, you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository.", "ref": 2 }, { "label": "[3]", "url": "https://arxiv.org/html/2602.14690v5", "claim": "Matthias Galster, Seyedmoein Mohsenimofidi, Jai Lal Lulla, Muhammad Auwal Abubakar, Christoph Treude, and Sebastian Baltes, *Harness Engineering for Agentic AI Coding Tools: An Exploratory Study*, arXiv:2602.14690v5, revised 2026-06-30", "date": null, "quote": "Cursor deprecated .cursorrules and now suggests using AGENTS.md instead. / Copilot also supports CLAUDE.md, AGENTS.md, and GEMINI.md / Our results show convergence on AGENTS.md as a tool-agnostic configuration file. / a skill whose directory contains SKILL.md alongside scripts, references, and assets). Context files such as AGENTS.md or CLAUDE.md act as \"READMEs for agents\" with context-specific information about build commands, coding conventions, and rules for CI/CD pipelines / Context Files Markdown file loaded into the context each session. CLAUDE.md .github/ { copilot-instructions.md | instructions/*.md }a AGENTS.md, AGENTS.override.md AGENTS.md, .cursorrulesc GEMINI.md / arXiv:2602.14690v5 [cs.SE] 30 Jun 2026 … We then cloned the remaining 32,564 repositories and applied heuristics based on file names and file paths to detect the usage of AI coding tools and configuration mechanisms (see Table 1). … This resulted in 2,853 repositories that use one or more AI coding tools … Of the 2,853 repositories, 2,015 (70.6%) adopted a single tool, while 295 (10.3%) configured two tools, and 50 (1.8%) configured three or more. An additional 493 repositories (17.3%) used AGENTS.md as a tool-agnostic standard without any tool-specific configuration artifact", "ref": 3 }, { "label": "[4]", "url": "https://ampcode.com/news/AGENTS.md", "claim": "Amp, *From AGENT.md to AGENTS.md*, published 2025-08-20", "date": null, "quote": "August 20, 2025 From AGENT.md to AGENTS.md In May we added support for AGENT.md files to Amp. Not long after, OpenAI picked AGENTS.md (plural) for their agent / August 20, 2025 From AGENT.md to AGENTS.md In May we added support for AGENT.md files to Amp. Not long after, OpenAI picked AGENTS.md (plural) for their agent … our condition: if OpenAI can get the agents.md domain, we'll switch. And that condition has now been met. True to our word, and as of today, Amp will look for AGENTS.md files / True to our word, and as of today, Amp will look for AGENTS.md files / \"datePublished\":\"2025-08-20T00:00:00.000Z\" … True to our word, and as of today, Amp will look for AGENTS.md files (while staying backwards compatible with existing AGENT.md files, of course) … Globs in AGENTS.md Include context files dynamically with glob mentions and filters", "ref": 4 }, { "label": "[5]", "url": "https://web.archive.org/web/20261022165127/https://openai.com/index/introducing-codex/", "claim": "OpenAI, *Introducing Codex*, published 2025-05-16", "date": null, "quote": "May 16, 2025 … Codex can be guided by AGENTS.md files placed within your repository.", "ref": 5 }, { "label": "[6]", "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation", "claim": "The Linux Foundation, *Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF), Anchored by New Project Contributions Including Model Context Protocol (MCP), goose and AGENTS.md*, published 2025-12-09; modified 2026-02-24", "date": null, "quote": "SAN FRANCISCO, Dec. 9, 2025 - The Linux Foundation, the nonprofit organization enabling mass innovation through open source, today announced the formation of the Agentic AI Foundation (AAIF), and founding contributions of three leading projects driving innovation in open source AI; Anthropic's Model Context Protocol (MCP), Block's goose, and OpenAI's AGENTS.md. / Released by OpenAI in August 2025, AGENTS.md is a simple, universal standard that gives AI coding agents a consistent source of project-specific guidance / MCP has rapidly become the universal standard protocol for connecting AI models to tools, data and applications / founding contributions of three leading projects driving innovation in open source AI; Anthropic's Model Context Protocol (MCP), Block's goose, and OpenAI's AGENTS.md. … MCP has rapidly become the universal standard protocol for connecting AI models to tools, data and applications / SAN FRANCISCO, Dec. 9, 2025 - The Linux Foundation, the nonprofit organization enabling mass innovation through open source, today announced the formation of the Agentic AI Foundation (AAIF) … AGENTS.md has already been adopted by more than 60,000 open source projects and agent frameworks including Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code among others.", "ref": 6 }, { "label": "[7]", "url": "https://raw.githubusercontent.com/agentsmd/agents.md/main/LICENSE", "claim": "AGENTS.md, *agentsmd/agents.md Repository LICENSE (MIT)*, fetched 2026-11-12", "date": null, "quote": "MIT License\n\nCopyright (c) 2025 OpenAI", "ref": 7 }, { "label": "[8]", "url": "https://docs.factory.com/harness/agents-md", "claim": "Factory, *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "SKILL.md Reusable workflows, checklists, or domain expertise that should load only when relevant. / When Droid later reads files under apps/web/, it can discover apps/web/AGENTS.md and apply the more specific guidance to that directory tree. / The current user request takes priority over standing instructions. Nested project files refine root project files for a specific directory tree. Project files should override personal defaults. / ~/.factory/ Your default Droid preferences across projects. / When a git root is present, Droid searches from the current working directory up to the git root. / CLAUDE.md Compatibility with existing Claude-oriented instructions. / .agent/ Compatibility with singular agent folder conventions. / .agents/ Compatibility with shared agent folder conventions. / Use AGENTS.md for new guidance. Droid also reads compatible filenames so existing instruction files from other coding tools keep working. / AGENTS.md and compatible names Always-on coding instructions, commands, repository conventions, and safety rules. Loaded as coding guidelines at startup and during dynamic discovery. … SKILL.md Reusable workflows, checklists, or domain expertise that should load only when relevant. Discovered as a skill. The full body loads when invoked. / AGENTS.md gives Droid the project briefing it should carry into every session: how to install, run, test, edit, verify, and stay inside your repository's boundaries. … When a git root is present, Droid searches from the current working directory up to the git root. At each level, it checks the directory itself and these context directories: Context directory Common use .factory/ Factory-specific project instructions. .agents/ Compatibility with shared agent folder conventions. .agent/ Compatibility with singular agent folder conventions. Droid also checks personal instruction directories in your home folder: Personal directory Common use ~/.factory/ Your default Droid preferences across projects. ~/.agents/ Compatible personal instructions. ~/.agent/ Compatible personal instructions. … Nested project files refine root project files for a specific directory tree. … Initial AGENTS-style guideline load 80,000 characters Dynamic Read-path guideline discovery 40,000 characters", "ref": 8 }, { "label": "[9]", "url": "https://www.stride.page/research/agents-md-claude-md-study-2026", "claim": "Stride, *What 7,370 popular GitHub repositories put in AGENTS.md and CLAUDE.md*, published 2026-09-27", "date": null, "quote": "The open format this study measures: plain Markdown with no required fields, read by many coding agents. / Of the 7,370 active public repositories on GitHub with 5,000 or more stars, 1,864 (25.3%) had an AGENTS.md at the root on 27 September 2026, and 33.4% had at least one instruction file for coding agents. The share rises with popularity, to 41.8% of repositories with 50,000+ stars. … In our census, 25.9% of the 1,013 repositories with both files do none of these. … the median AGENTS.md in our census is 819 words, and only 13.4% fall between 200 and 400. … 73.5% name a test, build or lint command, 39.3% mention security or secrets, and 10.6% state a rule against leaking secrets. … Of the repositories with both files, 35.5% use the import and 36.2% a symlink", "ref": 9 }, { "label": "[10]", "url": "https://cursor.com/docs/rules", "claim": "Cursor, *Rules*, checked 2026-10-30", "date": null, "quote": "A plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter to specify description, globs, and alwaysApply. If you prefer plain markdown, use AGENTS.md instead. / Unlike Project Rules, AGENTS.md is a plain markdown file without metadata or complex configurations. / Cursor supports AGENTS.md in the project root and subdirectories. / AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to .cursor/rules for straightforward use cases. / Project rules live in .cursor/rules as .mdc files and are version-controlled. … Unlike Project Rules, AGENTS.md is a plain markdown file without metadata or complex configurations. … Cursor supports AGENTS.md in the project root and subdirectories. … Instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence.", "ref": 10 }, { "label": "[11]", "url": "https://code.claude.com/docs/en/memory", "claim": "Anthropic (Claude Code), *How Claude remembers your project*, modified 2026-11-02", "date": null, "quote": "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a / PreToolUse hook / .claude/AGENTS.md / claude-md-or-agents-md / Project instructions / By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it. / Count, so Claude reads them instead of AGENTS.md: a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it / Reading AGENTS.md directly requires Claude Code v2.1.277 or later. / A CLAUDE.md containing @AGENTS.md: you can leave it. Keeping the import never makes Claude read AGENTS.md twice / If you don't need Claude-specific content, a symlink also works: ln -s AGENTS.md CLAUDE.md / claude-md-and-agents-md Your CLAUDE.md and AGENTS.md files together / so one that your CLAUDE.md imports or symlinks to isn't read twice / \"dateModified\":\"2026-11-02T21:30:31.529Z\" … Reading AGENTS.md directly requires Claude Code v2.1.277 or later. … By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it. … a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it … At session start: every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it. … As Claude works in subdirectories: a subdirectory’s AGENTS.md, when Claude opens a file there with the Read tool and that subdirectory has none of the three CLAUDE.md files of its own … Not read: AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory … set Project instructions to claude-md-and-agents-md. … type /config in a Claude Code session to open the settings panel, then set Project instructions to one of these values: Value What Claude reads claude-md-or-agents-md", "ref": 11 }, { "label": "[12]", "url": "https://learn.chatgpt.com/docs/agent-configuration/agents-md", "claim": "OpenAI, *Custom instructions with AGENTS.md*, checked 2026-10-30", "date": null, "quote": "Starting at the project root (typically the Git root), Codex walks down to your current working directory. If Codex cannot find a project root, it only checks the current directory. / In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames. Codex includes at most one file per directory. / Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt. / Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default). / Edit your Codex configuration: # ~/.codex/config.toml project_doc_fallback_filenames = [\"TEAM_GUIDE.md\", \".agents.md\"] project_doc_max_bytes = 65536 / Codex reads AGENTS.md files before doing any work. … In your Codex home directory (defaults to ~/.codex, unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists. Otherwise, Codex reads AGENTS.md. … Starting at the project root (typically the Git root), Codex walks down to your current working directory. … In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames. Codex includes at most one file per directory. Merge order: Codex concatenates files from the root down, joining them with blank lines.", "ref": 12 }, { "label": "[13]", "url": "https://code.visualstudio.com/updates/v1_104", "claim": "Microsoft, *Visual Studio Code August 2025 (version 1.104)*, August 2025", "date": null, "quote": "An AGENTS.md file lets you provide context and instructions to the agent. Starting from this release, when you have an AGENTS.md file in your workspace root(s), it is automatically picked up as context for chat requests. / Support for AGENTS.md files is enabled by default and can be controlled with the chat.useAgentsMdFile / August 2025 (version 1.104) … Support for AGENTS.md files (Experimental) Setting: chat.useAgentsMdFile … Starting from this release, when you have an AGENTS.md file in your workspace root(s), it is automatically picked up as context for chat requests. … Support for AGENTS.md files is enabled by default and can be controlled with the chat.useAgentsMdFile", "ref": 13 }, { "label": "[14]", "url": "https://jules.google/docs/changelog/2025-06-20/", "claim": "Google (Jules), *Jules Agent Update: Faster, Smarter, More Reliable*, published 2025-06-20", "date": null, "quote": "Smarter context. Jules reads from AGENTS.md if it's in your repo. / June 20, 2025 We've shipped a big upgrade to the Jules agent under the hood. What's new: Smarter context. Jules reads from AGENTS.md if it's in your repo.", "ref": 14 }, { "label": "[15]", "url": "https://docs.devin.ai/onboard-devin/agents-md", "claim": "Cognition (Devin), *AGENTS.md files for Devin*, modified 2026-09-25", "date": null, "quote": "Just put an AGENTS.md file in your project root (or anywhere else). Devin will look for the file before it starts coding. / Devin automatically includes up to 16 KiB (16,384 bytes) from the beginning of each AGENTS.md file in its context. / \"dateModified\":\"2026-09-25T15:07:47.850Z\" … Devin supports AGENTS.md - a simple, open standard for providing context and instructions to AI agents. … Devin will look for the file before it starts coding. Devin automatically includes up to 16 KiB (16,384 bytes) from the beginning of each AGENTS.md file in its context. For longer files, Devin receives a truncation notice and can read the full file on demand, but instructions after the limit are not included automatically.", "ref": 15 }, { "label": "[16]", "url": "https://zed.dev/blog/bring-your-own-agent-to-zed", "claim": "Zed (Nathan Sobo), *Bring Your Own Agent to Zed*, published 2025-08-27", "date": null, "quote": "we created the Agent Client Protocol (ACP), and we've partnered with Google to integrate Gemini CLI as the initial reference implementation.", "ref": 16 }, { "label": "[17]", "url": "https://zed.dev/blog/jetbrains-on-acp", "claim": "Zed (Franciska Dethlefsen), *ACP Brings JetBrains on Board*, published 2025-10-06", "date": null, "quote": "JetBrains has announced it will co-develop the Agent Client Protocol with us. They plan to bring ACP support to their entire IDE lineup", "ref": 17 }, { "label": "[18]", "url": "https://blog.jetbrains.com/ai/2025/10/jetbrains-zed-open-interoperability-for-ai-coding-agents-in-your-ide/", "claim": "JetBrains, *JetBrains × Zed: Open Interoperability for AI Coding Agents in Your IDE*, published 2025-10-06", "date": null, "quote": "we're collaborating with Zed on the Agent Client Protocol (ACP) - an open protocol that lets AI coding agents work inside editors, including JetBrains IDEs, if both are ACP-compatible.", "ref": 18 }, { "label": "[19]", "url": "https://raw.githubusercontent.com/vercel/next.js/HEAD/AGENTS.md", "claim": "Vercel (vercel/next.js), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "# Next.js Development Guide … This is a pnpm monorepo containing the Next.js framework and related packages. next.js/ ├── packages/ # Published npm packages ├── turbopack/ # Turbopack bundler (Rust) - git subtree ├── crates/ # Rust crates for Next.js SWC bindings ├── test/ # All test suites … Before editing or creating files in any subdirectory (e.g., packages/*, crates/*), read all README.md files in the directory path from the repo root up to and including the target file's directory. … See test/AGENTS.md. … content-length: 31539 … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 19 }, { "label": "[20]", "url": "https://raw.githubusercontent.com/microsoft/vscode/HEAD/AGENTS.md", "claim": "Microsoft (microsoft/vscode), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "# VS Code Agents Instructions This file provides instructions for AI coding agents working with the VS Code codebase. For detailed project overview, architecture, coding guidelines, and validation steps, see the Copilot Instructions. … content-length: 271 … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 20 }, { "label": "[21]", "url": "https://raw.githubusercontent.com/apache/airflow/HEAD/AGENTS.md", "claim": "Apache Software Foundation (apache/airflow), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "# AGENTS instructions ## Naming Write Dag (title case) in all prose. … ## Environment Setup … ## Commands … ## Repository Structure … ## Architecture Boundaries … ## Security Model … ## Coding Standards … ## Testing Standards … content-length: 23160 … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 21 }, { "label": "[22]", "url": "https://raw.githubusercontent.com/pandas-dev/pandas/HEAD/AGENTS.md", "claim": "pandas (pandas-dev/pandas), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "# AGENTS.md pandas is a BSD-licensed Python library for data analysis, built from Python, Cython, and C/C++ sources with Meson. ## Interactions on GitHub … ## Required tooling … ## Repository map … ## References … content-length: 2752 … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 22 }, { "label": "[23]", "url": "https://raw.githubusercontent.com/astral-sh/uv/HEAD/AGENTS.md", "claim": "Astral (astral-sh/uv), *AGENTS.md*, checked 2026-10-30", "date": null, "quote": "- Read CONTRIBUTING.md for guidelines on how to run tools … PREFER insta snapshots following patterns in nearby tests over substring assertions - PREFER uv_snapshot! for command output … When making changes for Windows from Unix, use cargo xwin clippy to check compilation … AVOID using panic!, unreachable!, .unwrap(), unsafe code, and clippy rule ignores … content-length: 3746 … content-type: text/plain; charset=utf-8 … date: Fri, 30 Oct 2026", "ref": 23 }, { "label": "[24]", "url": "https://raw.githubusercontent.com/temporalio/sdk-java/master/AGENTS.md", "claim": "Temporal (temporalio/sdk-java), *AGENTS.md*, checked 2026-11-04", "date": null, "quote": "HTTP 200 ... content-length: 2391 ... content-type: text/plain; charset=utf-8 ... # Contributor Quickstart Guide ## Repository Layout - temporal-sdk: core SDK implementation. - temporal-testing: utilities to help write workflow and activity tests. - temporal-test-server: in-memory Temporal server for fast tests. - temporal-serviceclient: gRPC client for communicating with the service. ... - ./gradlew spotlessCheck must pass. - All tests from ./gradlew test must succeed. ... For more details see CONTRIBUTING.md in the repository root.", "ref": 24 }, { "label": "[25]", "url": "https://raw.githubusercontent.com/pydantic/pydantic-ai/main/AGENTS.md", "claim": "Pydantic (pydantic/pydantic-ai), *AGENTS.md*, checked 2026-11-04", "date": null, "quote": "HTTP 200 ... content-length: 19537 ... content-type: text/plain; charset=utf-8 ... Welcome to the repository for [Pydantic AI](https://pydantic.dev/docs/ai/) ... # Your primary responsibility is to the project and its users ... [docs/AGENTS.md](docs/AGENTS.md) ... [pydantic_ai_slim/pydantic_ai/AGENTS.md](pydantic_ai_slim/pydantic_ai/AGENTS.md) ... [src/pydantic_ai_harness/AGENTS.md](src/pydantic_ai_harness/AGENTS.md) ... [tests/AGENTS.md](tests/AGENTS.md) ... [tests/harness/AGENTS.md](tests/harness/AGENTS.md)", "ref": 25 }, { "label": "[26]", "url": "https://raw.githubusercontent.com/oven-sh/bun/main/AGENTS.md", "claim": "Oven (oven-sh/bun), *AGENTS.md*, checked 2026-11-04", "date": null, "quote": "HTTP 200 ... content-length: 9 ... content-type: text/plain; charset=utf-8 ... CLAUDE.md", "ref": 26 }, { "label": "[27]", "url": "https://arxiv.org/html/2610.31715", "claim": "Pawel Zarzycki, *What Open-Source Projects Tell Their Coding Agents: A Census of AGENTS.md and CLAUDE.md*, arXiv:2610.31715v2, revised 2026-10-26", "date": null, "quote": "arXiv:2610.31715v2 [cs.SE] 26 Oct 2026 … We enumerated public GitHub repositories that, on 2026-10-16, had at least 1,000 stars, had been pushed to within the preceding 90 days, were neither forks nor archived, and had one of thirteen primary languages … GitHub’s search API returned 22,854 such repositories. … Of the 22,854 repositories, 6,006 (26.3%) have a root AGENTS.md, a root CLAUDE.md, or both. Adoption rises from 23.2% in the lowest star tier to 59.6% of the 89 repositories with the most stars … 2,566 adopters have only AGENTS.md, 1,052 only CLAUDE.md, and 2,388 both. Of those with both, most point one file at the other: CLAUDE.md defers to AGENTS.md through a link, an import or a pointer in 1,540 repositories, the reverse in 182, and only 598 keep two files with content of their own. … any of the above 6,652 29.1%", "ref": 27 }, { "label": "[28]", "url": "https://agentsmd.formachines.ai/", "claim": "AGENTS.md Tracker (agentsmd.formachines.ai), *AGENTS.md adoption tracker*, scan 2026-11-06; fetched 2026-11-06", "date": null, "quote": "546 of 1,922 / 28.4 % / 677 (35.2 %) have at least one agent-instruction file / Latest published scan: 2026-11-06", "ref": 28 }, { "label": "[29]", "url": "https://repoagentkit.com/agents-md-adoption", "claim": "RepoAgentKit, *AGENTS.md adoption in GitHub's top 100 repositories*, snapshot 2026-09-01; fetched 2026-11-06", "date": null, "quote": "Snapshot · 2026-09-01 · 100 pinned commits / 39 of GitHub / 29 of 39 files mention testing / 112 Median lines / Nested AGENTS.md files are not counted when the root file is absent.", "ref": 29 }, { "label": "[30]", "url": "https://arxiv.org/html/2606.24429v1", "claim": "Arsham Khosravani and Audris Mockus, *Detecting AI Coding Agents in Open Source: A Validated Multi-Method Census of 180 Million Repositories*, 2026-06-23", "date": "2026-06-23", "quote": "AGENTS.md, 134,810 blobs / CLAUDE.md (151,390) / We caution that cross-snapshot counts conflate genuine adoption growth", "ref": 30 } ], "form": "document-format", "governance": "Agentic AI Foundation (AAIF), under the Linux Foundation", "group": null, "history": [ { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "agents-md", "implementation": "multi-implementation", "last_verified": "2026-11-12", "name": "AGENTS.md", "native_status": "Open format stewarded by the Agentic AI Foundation under the Linux Foundation; announced as an AAIF founding contribution on 2025-12-09", "origin": { "date": "2025-08", "org": "OpenAI Codex, Amp, Jules (Google), Cursor, and Factory; released by OpenAI" }, "part_of": null, "parties": [ "agent-site" ], "phase": "living", "probe": { "method": "GET", "on_absent": "No repository-level agent instructions are declared; an agent falls back to inferring conventions from the codebase or README", "parse": "200 response containing markdown text; presence alone is the signal since there are no required fields or schema", "path": "{origin}/AGENTS.md (repository-root fetch, e.g. raw.githubusercontent.com///HEAD/AGENTS.md)" }, "question": "What build, test, and convention instructions should a coding agent follow in this repository?", "scope": "coding-tools", "spec_url": "https://agents.md/", "step": "read", "summary_md": "**AGENTS.md** is an open, tool-agnostic Markdown format for guiding coding agents—providing a dedicated, predictable repository location for build steps, test commands, and project conventions that would clutter a human `README.md`. Maintainers place standard Markdown `AGENTS.md` files (with no required fields or mandatory frontmatter) at the repository root and optionally inside nested packages. Coding agents automatically read the nearest `AGENTS.md` in the directory tree so the closest file to the edited path takes precedence, while explicit user chat prompts override everything. First documented in OpenAI's May 16, 2025 Codex launch and consolidated across OpenAI Codex, Amp (which switched from singular `AGENT.md` to `AGENTS.md` on August 20, 2025, `2025-08-20`), Google Jules, Cursor, and Factory in August 2025, `AGENTS.md` was contributed as a founding project of the Linux Foundation's Agentic AI Foundation (AAIF) on December 9, 2025 (`2025-12-09`) alongside Anthropic's Model Context Protocol (MCP) and Block's goose.", "track": "linux-foundation", "version": { "date": null, "label": "No numbered versions published" }, "watch": [ { "type": "page", "url": "https://agents.md", "selector": "main", "cadence": "weekly" }, { "type": "github", "repo": "agentsmd/agents.md", "mode": "tag" } ], "use_cases": [ "serve-content-to-agents", "describe-agent-capabilities" ], "audience": [ "agent-builder", "site-owner" ], "pairs_with": [ "anthropic-agent-skills-format", "llms-txt", "mcp", "agent-client-protocol" ], "prerequisites": [], "hatnote_md": "Not to be confused with [llms.txt](/protocols/llms-txt/) (HTTP-served web documentation index) or [Agent Skills](/protocols/anthropic-agent-skills-format/) (packaged `SKILL.md` workflow directories).", "tier": "flagship", "lifecycle_status": "active", "wire_archetype": "web_discovery", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-12", "v05_hatnote_html_md": "Not to be confused with [llms.txt](/protocols/llms-txt/) (HTTP-served web documentation index) or [Agent Skills](/protocols/anthropic-agent-skills-format/) (packaged `SKILL.md` workflow directories). [1]", "v05_elevator_pitch_md": "`AGENTS.md` is a vendor-neutral repository instruction file that gives AI coding agents (such as OpenAI Codex, Cursor, Google Jules, and Amp) a predictable place to find build commands, test workflows, and codebase conventions alongside a human `README.md`. Instead of duplicating project rules across tool-specific files like `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, and `.github/copilot-instructions.md`, maintainers check in plain Markdown `AGENTS.md` files at the repo root or inside subdirectories so every coding agent reads the nearest file automatically. [1][2][3]", "v05_lead_md": "**AGENTS.md** is an open, tool-agnostic Markdown format for guiding coding agents—providing a dedicated, predictable repository location for build steps, test commands, and project conventions that would clutter a human `README.md`. [1] Maintainers place standard Markdown `AGENTS.md` files (with no required fields or mandatory frontmatter) at the repository root and optionally inside nested packages. Coding agents automatically read the nearest `AGENTS.md` in the directory tree so the closest file to the edited path takes precedence, while explicit user chat prompts override everything. [1] First documented in OpenAI's May 16, 2025 Codex launch and consolidated across OpenAI Codex, Amp (which switched from singular `AGENT.md` to `AGENTS.md` on August 20, 2025, `2025-08-20`), Google Jules, Cursor, and Factory in August 2025, `AGENTS.md` was contributed as a founding project of the Linux Foundation's Agentic AI Foundation (AAIF) on December 9, 2025 (`2025-12-09`) alongside Anthropic's Model Context Protocol (MCP) and Block's goose. [1][4][5][6]", "v05_identity_sentence_md": "**AGENTS.md** is an open, tool-agnostic Markdown format for guiding coding agents—providing a dedicated, predictable repository location for build steps, test commands, and project conventions that would clutter a human `README.md`. [1]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Read](/category/read/) (`read`)" }, { "label": "Form", "value_md": "Repository Markdown instruction file (`document-format`)" }, { "label": "Originated by", "value_md": "OpenAI Codex (`AGENTS.md` documented May 16, 2025), Amp (`AGENT.md`, May 2025), Jules (Google), Cursor, and Factory; described as released by OpenAI in August 2025 in the Linux Foundation AAIF announcement [1][4][5][6]" }, { "label": "Governed by", "value_md": "Agentic AI Foundation (AAIF), under the Linux Foundation (donated 2025-12-09) [1][6]" }, { "label": "Track", "value_md": "Foundation / Consortium Specification (Agentic AI Foundation / Linux Foundation) [1]" }, { "label": "Status", "value_md": "Open format; AAIF founding contribution (announced 2025-12-09) [1][6]" }, { "label": "Version", "value_md": "Unversioned open Markdown format (no required fields or version header) [1]" }, { "label": "Message format", "value_md": "Standard Markdown (no required fields or fixed headings) [1]" }, { "label": "Specification", "value_md": "[AGENTS.md](https://agents.md/) [1]" }, { "label": "Found at", "value_md": "Repository-root `AGENTS.md` and optional nested package/subdirectory `AGENTS.md` files (nearest file in directory tree wins) [1]" }, { "label": "Licence", "value_md": "MIT License (`agentsmd/agents.md`) [7]" } ], "v05_problem_md": "Human `README.md` files are for quick starts, project descriptions, and contribution guidelines. The extra build steps, tests, and conventions coding agents need can clutter that README. The same guidance is often split again across `CLAUDE.md`, a `.github/copilot-instructions.md` file, deprecated `.cursorrules`, and `GEMINI.md`. [1][2][3] `AGENTS.md` collects that agent context in one tool-agnostic Markdown file with no required fields. Nested files follow nearest-directory precedence: the closest `AGENTS.md` in the directory tree takes precedence, so each package can ship its own commands and conventions. [1][3] `README.md` remains the human guide for quick starts, project descriptions, and contribution guidelines. `AGENTS.md` is the checked-in Markdown file coding agents read for repository instructions. `SKILL.md` packages reusable workflows that load only when relevant. The Model Context Protocol connects AI models to tools, data, and applications. [1][6][8]", "v05_mechanism_delta_md": "`AGENTS.md` collects that agent context in one tool-agnostic Markdown file with no required fields. Nested files follow nearest-directory precedence: the closest `AGENTS.md` in the directory tree takes precedence, so each package can ship its own commands and conventions. [1][3]", "v05_scope_boundary_md": "`README.md` remains the human guide for quick starts, project descriptions, and contribution guidelines. `AGENTS.md` is the checked-in Markdown file coding agents read for repository instructions. `SKILL.md` packages reusable workflows that load only when relevant. The Model Context Protocol connects AI models to tools, data, and applications. [1][6][8]", "v05_fuzzy_additions": [ { "id": "file-structure-directory-precedence-and-instruction-hierarchy", "heading": "File structure, directory precedence, and instruction hierarchy", "body_md": "An `AGENTS.md` file is just standard Markdown with no required fields and no mandatory frontmatter. Any headings are allowed; the agent parses the text the repository provides. Stride calls the format plain Markdown with no required fields. Files in `.cursor/rules` need frontmatter for `description`, `globs`, and `alwaysApply`. `AGENTS.md` is the plain-markdown file used instead. [1][9][10]", "bullets": [ { "label": "Nested monorepo precedence", "text_md": "Maintainers may place another `AGENTS.md` inside each package. The nearest file in the directory tree takes precedence, so the subproject ships its own instructions. The main OpenAI repo had 88 `AGENTS.md` files. Copilot uses that nearest-file rule. Factory can load a nested `apps/web/AGENTS.md` for that tree. [1][2][8]" }, { "label": "Chat prompts override files", "text_md": "The closest `AGENTS.md` to the edited file wins, and explicit user chat prompts override everything. For Droid, the current user request outranks standing instructions, nested files refine the root file, and project files override personal defaults in `~/.factory/`. [1][8]" }, { "label": "Setup, lint, and test commands", "text_md": "If testing commands are listed, the agent will attempt to execute those programmatic checks and fix failures before finishing. The homepage code sample above lists `pnpm install`, `pnpm dev`, and `pnpm test`, while separate `agents.md` example rules instruct agents to run `pnpm lint` and `pnpm test` before committing and `pnpm lint --filter` after moving files or changing imports. Because repository instruction files are repo-controlled text listing commands agents attempt to run, harnesses such as Claude Code treat them as context rather than enforced configuration and direct users to hooks (such as a `PreToolUse hook`) to block actions regardless of what the agent decides. [1][11]" }, { "label": "Plain Markdown, no required schema", "text_md": "No field schema is required; `agents.md` describes `AGENTS.md` as living documentation. A plain `.md` file in `.cursor/rules` is ignored when it lacks frontmatter for `description`, `globs`, and `alwaysApply`. The `agents.md` homepage sample opens with `# AGENTS.md`, `## Setup commands`, and `## Code style`. [1][10]" } ] }, { "id": "cross-harness-loading-configuration-hooks-and-compatibility", "heading": "Cross-harness loading, configuration hooks, and compatibility", "body_md": "One `AGENTS.md` is shared across coding agents. The project site names Codex, Jules, Factory, Cursor, Zed, VS Code, Devin, and GitHub Copilot in that compatible set. Discovery order, fallback names, import or symlink bridges, and byte caps still vary by harness. [1]", "bullets": [ { "label": "Codex discovery and byte caps", "text_md": "Codex walks from the Git root down to the current directory. Each directory contributes `AGENTS.override.md`, else `AGENTS.md`, else one `project_doc_fallback_filenames` entry. Closer files override earlier text. The join stops at `project_doc_max_bytes` (32 KiB by default). `~/.codex/config.toml` sets fallbacks such as `TEAM_GUIDE.md` and `.agents.md`, and can raise the cap to `65536`. [12]" }, { "label": "Claude Code imports and symlinks", "text_md": "Claude reads `AGENTS.md` (or `.claude/AGENTS.md`) directly only when `CLAUDE.md`, `.claude/CLAUDE.md`, and `CLAUDE.local.md` are absent from the working directory upward (`claude-md-or-agents-md`), which needs Claude Code v2.1.277 or later; users can also change the `Project instructions` setting to `claude-md-and-agents-md` so Claude reads both files together. Otherwise repositories can bridge the files with an `@AGENTS.md` import or `ln -s AGENTS.md CLAUDE.md` symlink. The `claude-md-and-agents-md` guide notes that Claude loads both and does not read an imported or symlinked `AGENTS.md` twice. [11]" }, { "label": "IDE and agent loading", "text_md": "Cursor loads `AGENTS.md` in the root and subdirectories as an alternative to `.cursor/rules`. VS Code reads a workspace-root file when `chat.useAgentsMdFile` is on, the default. Copilot applies the nearest `AGENTS.md` in the directory tree, or lets a repository commit a single root `CLAUDE.md` or `GEMINI.md` as an alternative. Jules reads `AGENTS.md` in the repo. Devin injects the first `16 KiB` (`16,384` bytes). Factory walks up to the git root and also accepts `CLAUDE.md`. Zed is on the site's agent list. [1][2][8][10][13][14][15]" }, { "label": "Singular AGENT.md migration", "text_md": "On August 20, 2025 Amp switched from `AGENT.md` to `AGENTS.md` while retaining backward compatibility with existing `AGENT.md` files, and `agents.md` documents renaming with `mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md` so older `AGENT.md` paths continue to resolve. Factory still checks `.agent/` and `.agents/`, and recommends `AGENTS.md` for new guidance. [1][4][8]" } ] } ], "v05_diagram": { "title": "Nearest AGENTS.md precedence", "heading": "Nearest AGENTS.md precedence", "mermaid": "flowchart TD\n A[\"Conflict while editing a file\"] --> B{\"Explicit user chat prompt?\"}\n B -->|yes| C[\"User prompt wins\"]\n B -->|no| D[\"Walk from the edited file toward the repository root\"]\n D --> E[\"Nearest AGENTS.md on that path\"]\n E --> F[\"That file's instructions apply\"]\n F --> G[\"A nested package file overrides the root AGENTS.md\"]", "caption_md": "Per the `agents.md` FAQ convention, the closest `AGENTS.md` to the edited file wins, and explicit user chat prompts override everything. Agents otherwise read the nearest file in the directory tree (while exact traversal, byte limits, and fallback rules vary by harness). [1]" }, "v05_wire_artifact": { "title": "Canonical `AGENTS.md` specimen", "heading": "Canonical `AGENTS.md` specimen", "lang": "markdown", "code": "# AGENTS.md\n\n## Setup commands\n\n- Install deps: `pnpm install`\n- Start dev server: `pnpm dev`\n- Run tests: `pnpm test`\n\n## Code style\n\n- TypeScript strict mode\n- Single quotes, no semicolons\n- Use functional patterns where possible", "caption_md": "Homepage `AGENTS.md` sample: setup commands `pnpm install`, `pnpm dev`, and `pnpm test`, then a code-style section. [1]" }, "v05_counterparts": { "classic_analogues": [ { "name": "README.md", "spec_or_rfc": "README.md", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "Provides human-facing quick starts, project descriptions, and contributor overviews, whereas `AGENTS.md` isolates agent-specific build commands, test workflows, and directory-scoped coding rules. [1]" } ], "agentic_peers": [ { "target_id": "anthropic-agent-skills-format", "target_name": "Agent Skills", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Packages reusable workflows and domain expertise as on-demand skill directories containing `SKILL.md` (alongside scripts and assets), whereas `AGENTS.md` provides always-on repository coding guidelines. [3][8]" }, { "target_id": "llms-txt", "target_name": "llms.txt", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Publishes an HTTP-served web documentation index at `/llms.txt` for external reading agents, whereas `AGENTS.md` is committed inside a source repository to guide coding agents modifying the codebase. [1]" }, { "target_id": "mcp", "target_name": "Model Context Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Connects AI models to external tools, data, and applications over a runtime protocol (co-founded in the AAIF alongside `AGENTS.md`), whereas `AGENTS.md` is a static Markdown convention for repository-specific guidance. [6]" }, { "target_id": "agent-client-protocol", "target_name": "Agent Client Protocol", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Defines an editor-to-agent runtime protocol so compatible coding agents can run inside IDEs such as Zed and JetBrains, whereas `AGENTS.md` is the repository Markdown file those agents read for project instructions. [16][17][18]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (23 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Reference repositories publishing AGENTS.md", "col4_header": "Artifact path & directory scope", "note_md": null, "rows": [ { "actor": "vercel/next.js", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves root `AGENTS.md` (`# Next.js Development Guide`, `text/plain`) covering the pnpm monorepo and nested `test/AGENTS.md`.", "source_md": "[Next.js, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/vercel/next.js/HEAD/AGENTS.md) [19]" }, { "actor": "microsoft/vscode", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves root `AGENTS.md` (`# VS Code Agents Instructions`, `text/plain`) routing agents to `.github/copilot-instructions.md`.", "source_md": "[VS Code, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/microsoft/vscode/HEAD/AGENTS.md) [20]" }, { "actor": "apache/airflow", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves root `AGENTS.md` (`# AGENTS instructions`, `text/plain`) covering `Dag` naming, Breeze commands, and architecture boundaries.", "source_md": "[Apache Airflow, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/apache/airflow/HEAD/AGENTS.md) [21]" }, { "actor": "pandas-dev/pandas", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves root `AGENTS.md` (`# AGENTS.md`, `text/plain`) covering Meson Cython/C++ builds, GitHub interaction rules, and repository map.", "source_md": "[pandas, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/pandas-dev/pandas/HEAD/AGENTS.md) [22]" }, { "actor": "astral-sh/uv", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves heading-free root `AGENTS.md` (`text/plain`), opening with bulleted rules referencing `CONTRIBUTING.md` and `insta` snapshots.", "source_md": "[uv, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/astral-sh/uv/HEAD/AGENTS.md) [23]" }, { "actor": "temporalio/sdk-java", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves root `AGENTS.md` (`# Contributor Quickstart Guide`, `text/plain`) with Gradle layout, `./gradlew spotlessCheck`, and `./gradlew test` rules.", "source_md": "[temporalio/sdk-java, AGENTS.md (checked 2026-11-04)](https://raw.githubusercontent.com/temporalio/sdk-java/master/AGENTS.md) [24]" }, { "actor": "pydantic/pydantic-ai", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves root `AGENTS.md` (`text/plain`, 19,537 bytes) linking 18 nested `AGENTS.md` files across `docs/`, `pydantic_ai_slim/`, and `tests/`.", "source_md": "[pydantic/pydantic-ai, AGENTS.md (checked 2026-11-04)](https://raw.githubusercontent.com/pydantic/pydantic-ai/main/AGENTS.md) [25]" }, { "actor": "oven-sh/bun", "role": "Repo publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-11-04", "col4_md": "Serves a 9-byte root `AGENTS.md` (`text/plain`) containing only `CLAUDE.md` as a cross-file pointer.", "source_md": "[oven-sh/bun, AGENTS.md (checked 2026-11-04)](https://raw.githubusercontent.com/oven-sh/bun/main/AGENTS.md) [26]" } ] }, "side_b": { "visible": true, "heading": "Coding agents, IDEs & CLI harnesses", "col4_header": "Discovery & hierarchy precedence", "note_md": null, "rows": [ { "actor": "OpenAI Codex", "role": "Coding agent", "status": "Supported", "status_display": "Supported · as of 2025-05-16", "col4_md": "Guided by repository `AGENTS.md` files since `2025-05-16`; in configuration docs (checked `2026-10-30`), reads `~/.codex` and walks root-to-CWD loading `AGENTS.override.md` or `AGENTS.md`, concatenating closer files last.", "source_md": "[OpenAI, Introducing Codex (2025-05-16)](https://web.archive.org/web/20261022165127/https://openai.com/index/introducing-codex/) [5] · [OpenAI, Custom instructions with AGENTS.md (checked 2026-10-30)](https://learn.chatgpt.com/docs/agent-configuration/agents-md) [12]" }, { "actor": "GitHub Copilot", "role": "Coding agent", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Loads one or more `AGENTS.md` files anywhere in the repository; nearest file in the directory tree takes precedence.", "source_md": "[GitHub Docs, Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) [2]" }, { "actor": "Cursor", "role": "IDE / Coding agent", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Loads plain-Markdown `AGENTS.md` in root and subdirectories, combining parent files with subdirectory precedence.", "source_md": "[Cursor Docs, Rules](https://cursor.com/docs/rules) [10]" }, { "actor": "Factory (Droid)", "role": "Coding agent / CLI", "status": "Supported", "status_display": "Supported · checked 2026-10-30", "col4_md": "Searches CWD-to-Git-root and dynamic Read paths for `AGENTS.md`, refining root rules with nested files.", "source_md": "[Factory Documentation, AGENTS.md](https://docs.factory.com/harness/agents-md) [8]" }, { "actor": "Amp", "role": "Coding agent", "status": "Supported", "status_display": "Supported · as of 2025-08-20", "col4_md": "Adopted `AGENTS.md` as standard filename on 2025-08-20 with glob mentions and `AGENT.md` backward compatibility.", "source_md": "[Amp, From AGENT.md to AGENTS.md (2025-08-20)](https://ampcode.com/news/AGENTS.md) [4]" }, { "actor": "Google Jules", "role": "Coding agent", "status": "Supported", "status_display": "Supported · as of 2025-06-20", "col4_md": "Reads context from `AGENTS.md` automatically when present in a repository (shipped 2025-06-20).", "source_md": "[Jules Changelog, Jules Agent Update (2025-06-20)](https://jules.google/docs/changelog/2025-06-20/) [14]" }, { "actor": "Visual Studio Code", "role": "IDE / Editor", "status": "Experimental", "status_display": "Experimental · as of 2025-08", "col4_md": "Picks up workspace-root `AGENTS.md` for chat requests under default-enabled experimental `chat.useAgentsMdFile` setting (v1.104).", "source_md": "[Microsoft, VS Code August 2025 (version 1.104)](https://code.visualstudio.com/updates/v1_104) [13]" }, { "actor": "Anthropic (Claude Code)", "role": "Coding agent / CLI", "status": "Partial", "status_display": "Partial · as of 2026-11-02", "col4_md": "Reads `AGENTS.md` and `.claude/AGENTS.md` by default only when no `CLAUDE.md` exists in or above CWD.", "source_md": "[Claude Code Docs, How Claude remembers your project (modified 2026-11-02)](https://code.claude.com/docs/en/memory) [11]" }, { "actor": "Cognition (Devin)", "role": "Coding agent", "status": "Partial", "status_display": "Partial · as of 2026-09-25", "col4_md": "Automatically injects up to 16 KiB (16,384 bytes) per `AGENTS.md` before coding; longer files truncate.", "source_md": "[Devin Docs, AGENTS.md files for Devin (modified 2026-09-25)](https://docs.devin.ai/onboard-devin/agents-md) [15]" }, { "actor": "Aider", "role": "Coding agent / CLI", "status": "Partial", "status_display": "Partial · checked 2026-10-30", "col4_md": "Documented in the `agents.md` FAQ as requiring explicit `read: AGENTS.md` configuration in `.aider.conf.yml`.", "source_md": "[AGENTS.md FAQ, How do I configure Aider?](https://agents.md/) [1]" }, { "actor": "Google Gemini CLI", "role": "Coding agent / CLI", "status": "Partial", "status_display": "Partial · as of 2026-06-30", "col4_md": "Uses `GEMINI.md` by default; `agents.md` FAQ documents configuring `AGENTS.md` via `.gemini/settings.json`.", "source_md": "[AGENTS.md FAQ, How do I configure Gemini CLI?](https://agents.md/) [1] · [Galster et al., arXiv:2602.14690v5 (Table 1)](https://arxiv.org/html/2602.14690v5) [3]" }, { "actor": "Zed", "role": "IDE / Editor", "status": "Listed", "status_display": "Listed · checked 2026-10-30", "col4_md": "Named in the compatible coding-agent roster on `agents.md`.", "source_md": "[AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1]" }, { "actor": "Windsurf (Cognition)", "role": "IDE / Coding agent", "status": "Listed", "status_display": "Listed · checked 2026-10-30", "col4_md": "Named in the compatible coding-agent roster on `agents.md`.", "source_md": "[AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1]" }, { "actor": "Block (goose)", "role": "Coding agent / CLI", "status": "Listed", "status_display": "Listed · checked 2026-10-30", "col4_md": "Named in the compatible coding-agent roster on `agents.md`.", "source_md": "[AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1]" }, { "actor": "opencode", "role": "Coding agent / CLI", "status": "Listed", "status_display": "Listed · checked 2026-10-30", "col4_md": "Named in the compatible coding-agent roster on `agents.md`.", "source_md": "[AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1]" } ] }, "additional_tables": null, "censuses": [ { "label": "Project-reported open-source repository lower bound (agents.md & Linux Foundation AAIF)", "as_of": "2025-12-09", "value_md": "Over 60,000 open-source projects reported as using AGENTS.md on the agents.md specification site (which links a live GitHub code search for path:AGENTS.md NOT is:fork NOT is:archived) and in the Linux Foundation's 9 December 2025 Agentic AI Foundation (AAIF) formation announcement. [1][6]" }, { "label": "High-star active GitHub census: 7,370 repositories with >=5,000 stars (Stride study)", "as_of": "2026-09-27", "value_md": "In Stride's 27 September 2026 census of all 7,370 active public GitHub repositories with 5,000 or more stars, 1,864 repositories (25.3%) had a root AGENTS.md file (rising to 41.8% among repositories with 50,000+ stars) and 33.4% had at least one coding-agent instruction file; across adopted AGENTS.md files, the median length was 819 words (with 13.4% between 200 and 400 words), 73.5% named a test, build, or lint command, 39.3% mentioned security or secrets, and among the 1,013 repositories carrying both AGENTS.md and CLAUDE.md, 36.2% joined them via a symlink, 35.5% used an @AGENTS.md import, and 25.9% linked neither. [9]" }, { "label": "13-language GitHub census of 22,854 active >=1,000-star repositories (Zarzycki, arXiv:2610.31715v2)", "as_of": "2026-10-26", "value_md": "Across 22,854 non-fork, non-archived public GitHub repositories with at least 1,000 stars and a push within 90 days in 13 languages (enumerated 16 October 2026), 6,006 repositories (26.3%, rising from 23.2% in the lowest star tier to 59.6% of the 89 most-starred repositories) published a root AGENTS.md, a root CLAUDE.md, or both—consisting of 2,566 repositories with only AGENTS.md, 1,052 with only CLAUDE.md, and 2,388 with both (of those with both, most point one file at the other: CLAUDE.md defers to AGENTS.md via a link, import, or pointer in 1,540 repositories, the reverse in 182, and only 598 keep two files with content of their own); counting additional one-level-deep formats (.github/copilot-instructions.md, .github/instructions/, /GEMINI.md, .claude/CLAUDE.md, /.cursorrules, /.windsurfrules) raised total adoption to 6,652 repositories (29.1%). [27]" }, { "label": "Pre-2024 engineered software study: 2,853 tool-configuring repos out of 32,564 engineered projects (Galster et al., arXiv:2602.14690v5)", "as_of": "2026-06-30", "value_md": "From 32,564 engineered open-source GitHub repositories created before 1 January 2024 and active since 1 June 2025, 2,853 repositories (8.8%) configured at least one agentic coding tool—partitioned into 2,015 single-tool repositories (70.6%), 295 two-tool repositories (10.3%), 50 three-or-more-tool repositories (1.8%), and 493 repositories (17.3% of the 2,853 tool-configuring repositories) that used AGENTS.md alone as a tool-agnostic standard without any tool-specific configuration artifact. [3]" }, { "label": "AGENTS.md Tracker (agentsmd.formachines.ai)", "as_of": "2026-11-06", "value_md": "The AGENTS.md Tracker scan published 2026-11-06 found a root AGENTS.md in 546 of 1,922 repositories (28.4%), and at least one of eight tracked instruction files in 677 of 1,922 (35.2%), measuring file presence on the default branch. [28]" }, { "label": "RepoAgentKit top-100 snapshot", "as_of": "2026-09-01", "value_md": "RepoAgentKit's 2026-09-01 snapshot, covering 100 pinned commits, found a case-sensitive root AGENTS.md in 39 of GitHub's top 100 repositories (excluding nested-only files), reporting a median of 112 lines and 29 of 39 files mentioning testing. [29]" }, { "label": "World of Code V2604 configuration-file census", "as_of": "2026-04", "value_md": "The World of Code V2604 configuration-file census records 134,810 AGENTS.md blobs and 151,390 CLAUDE.md blobs. The paper warns that cross-snapshot counts mix adoption with a growing corpus and should be read as coarse upper-bound trends, not adoption rates. [30]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "vercel-agent-readability", "target_name": "Agent Readability Spec", "relation_label": "Complements", "delta": "The guide treats /AGENTS.md as a readability artifact, while AGENTS.md is the instruction file for coding agents.", "item_md": "**[Agent Readability Spec](/protocols/vercel-agent-readability/)** (Complements) — The guide treats /AGENTS.md as a readability artifact, while AGENTS.md is the instruction file for coding agents." }, { "target_id": "okf", "target_name": "Open Knowledge Format", "relation_label": "Peer alternative", "delta": "AGENTS.md is one README for coding agents; OKF is a directory of Markdown files with YAML frontmatter.", "item_md": "**[Open Knowledge Format](/protocols/okf/)** (Peer alternative) — AGENTS.md is one README for coding agents; OKF is a directory of Markdown files with YAML frontmatter." }, { "target_id": "acip", "target_name": "Agent Context Interchange Protocol", "relation_label": "Complements", "delta": "ACIP reads YAML at .agents/agent-context.yaml with a precedence algorithm and a resolution receipt, and it is paired with AGENTS.md prose rather than replacing that file format.", "item_md": "**[Agent Context Interchange Protocol](/protocols/acip/)** (Complements) — ACIP reads YAML at .agents/agent-context.yaml with a precedence algorithm and a resolution receipt, and it is paired with AGENTS.md prose rather than replacing that file format." }, { "item_md": "**[Read protocols](/category/read/)** — Category index for `read` standards." } ], "v05_compiled_md": "---\nid: agents-md\ntitle: \"AGENTS.md\"\ntier: flagship\nlifecycle_status: active\ncategory: read\nform: document-format\nwire_archetype: web_discovery\nspec_url: https://agents.md/\nlast_checked: 2026-11-12\n---\n\n# AGENTS.md\n\n**Category:** [Read](/category/read/) (`read`) · **Form:** Repository Markdown instruction file (`document-format`) · **Last checked:** 2026-11-12\n\n> *Not to be confused with [llms.txt](/protocols/llms-txt/) (HTTP-served web documentation index) or [Agent Skills](/protocols/anthropic-agent-skills-format/) (packaged `SKILL.md` workflow directories). [1]*\n\n> **In brief:** `AGENTS.md` is a vendor-neutral repository instruction file that gives AI coding agents (such as OpenAI Codex, Cursor, Google Jules, and Amp) a predictable place to find build commands, test workflows, and codebase conventions alongside a human `README.md`. Instead of duplicating project rules across tool-specific files like `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, and `.github/copilot-instructions.md`, maintainers check in plain Markdown `AGENTS.md` files at the repo root or inside subdirectories so every coding agent reads the nearest file automatically. [1][2][3]\n\n**AGENTS.md** is an open, tool-agnostic Markdown format for guiding coding agents—providing a dedicated, predictable repository location for build steps, test commands, and project conventions that would clutter a human `README.md`. [1] Maintainers place standard Markdown `AGENTS.md` files (with no required fields or mandatory frontmatter) at the repository root and optionally inside nested packages. Coding agents automatically read the nearest `AGENTS.md` in the directory tree so the closest file to the edited path takes precedence, while explicit user chat prompts override everything. [1] First documented in OpenAI's May 16, 2025 Codex launch and consolidated across OpenAI Codex, Amp (which switched from singular `AGENT.md` to `AGENTS.md` on August 20, 2025, `2025-08-20`), Google Jules, Cursor, and Factory in August 2025, `AGENTS.md` was contributed as a founding project of the Linux Foundation's Agentic AI Foundation (AAIF) on December 9, 2025 (`2025-12-09`) alongside Anthropic's Model Context Protocol (MCP) and Block's goose. [1][4][5][6]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Read](/category/read/) (`read`) |\n| **Form** | Repository Markdown instruction file (`document-format`) |\n| **Originated by** | OpenAI Codex (`AGENTS.md` documented May 16, 2025), Amp (`AGENT.md`, May 2025), Jules (Google), Cursor, and Factory; described as released by OpenAI in August 2025 in the Linux Foundation AAIF announcement [1][4][5][6] |\n| **Governed by** | Agentic AI Foundation (AAIF), under the Linux Foundation (donated 2025-12-09) [1][6] |\n| **Track** | Foundation / Consortium Specification (Agentic AI Foundation / Linux Foundation) [1] |\n| **Status** | Open format; AAIF founding contribution (announced 2025-12-09) [1][6] |\n| **Version** | Unversioned open Markdown format (no required fields or version header) [1] |\n| **Message format** | Standard Markdown (no required fields or fixed headings) [1] |\n| **Specification** | [AGENTS.md](https://agents.md/) [1] |\n| **Found at** | Repository-root `AGENTS.md` and optional nested package/subdirectory `AGENTS.md` files (nearest file in directory tree wins) [1] |\n| **Licence** | MIT License (`agentsmd/agents.md`) [7] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [File structure, directory precedence, and instruction hierarchy](#file-structure-directory-precedence-and-instruction-hierarchy)\n3. [Cross-harness loading, configuration hooks, and compatibility](#cross-harness-loading-configuration-hooks-and-compatibility)\n4. [Counterparts and related standards](#counterparts-and-related-standards)\n5. [Adoption and ecosystem](#adoption-and-ecosystem)\n6. [See also](#see-also)\n7. [References](#references)\n\n---\n\n## Problem and scope\n\nHuman `README.md` files are for quick starts, project descriptions, and contribution guidelines. The extra build steps, tests, and conventions coding agents need can clutter that README. The same guidance is often split again across `CLAUDE.md`, a `.github/copilot-instructions.md` file, deprecated `.cursorrules`, and `GEMINI.md`. [1][2][3] `AGENTS.md` collects that agent context in one tool-agnostic Markdown file with no required fields. Nested files follow nearest-directory precedence: the closest `AGENTS.md` in the directory tree takes precedence, so each package can ship its own commands and conventions. [1][3] `README.md` remains the human guide for quick starts, project descriptions, and contribution guidelines. `AGENTS.md` is the checked-in Markdown file coding agents read for repository instructions. `SKILL.md` packages reusable workflows that load only when relevant. The Model Context Protocol connects AI models to tools, data, and applications. [1][6][8]\n\n### Nearest AGENTS.md precedence\n\n```mermaid\nflowchart TD\n A[\"Conflict while editing a file\"] --> B{\"Explicit user chat prompt?\"}\n B -->|yes| C[\"User prompt wins\"]\n B -->|no| D[\"Walk from the edited file toward the repository root\"]\n D --> E[\"Nearest AGENTS.md on that path\"]\n E --> F[\"That file's instructions apply\"]\n F --> G[\"A nested package file overrides the root AGENTS.md\"]\n```\n\n*Per the `agents.md` FAQ convention, the closest `AGENTS.md` to the edited file wins, and explicit user chat prompts override everything. Agents otherwise read the nearest file in the directory tree (while exact traversal, byte limits, and fallback rules vary by harness). [1]*\n\n### Canonical `AGENTS.md` specimen\n\n```markdown\n# AGENTS.md\n\n## Setup commands\n\n- Install deps: `pnpm install`\n- Start dev server: `pnpm dev`\n- Run tests: `pnpm test`\n\n## Code style\n\n- TypeScript strict mode\n- Single quotes, no semicolons\n- Use functional patterns where possible\n```\n\n*Homepage `AGENTS.md` sample: setup commands `pnpm install`, `pnpm dev`, and `pnpm test`, then a code-style section. [1]*\n\n---\n\n## File structure, directory precedence, and instruction hierarchy\n\nAn `AGENTS.md` file is just standard Markdown with no required fields and no mandatory frontmatter. Any headings are allowed; the agent parses the text the repository provides. Stride calls the format plain Markdown with no required fields. Files in `.cursor/rules` need frontmatter for `description`, `globs`, and `alwaysApply`. `AGENTS.md` is the plain-markdown file used instead. [1][9][10]\n\n- **Nested monorepo precedence:** Maintainers may place another `AGENTS.md` inside each package. The nearest file in the directory tree takes precedence, so the subproject ships its own instructions. The main OpenAI repo had 88 `AGENTS.md` files. Copilot uses that nearest-file rule. Factory can load a nested `apps/web/AGENTS.md` for that tree. [1][2][8]\n- **Chat prompts override files:** The closest `AGENTS.md` to the edited file wins, and explicit user chat prompts override everything. For Droid, the current user request outranks standing instructions, nested files refine the root file, and project files override personal defaults in `~/.factory/`. [1][8]\n- **Setup, lint, and test commands:** If testing commands are listed, the agent will attempt to execute those programmatic checks and fix failures before finishing. The homepage code sample above lists `pnpm install`, `pnpm dev`, and `pnpm test`, while separate `agents.md` example rules instruct agents to run `pnpm lint` and `pnpm test` before committing and `pnpm lint --filter` after moving files or changing imports. Because repository instruction files are repo-controlled text listing commands agents attempt to run, harnesses such as Claude Code treat them as context rather than enforced configuration and direct users to hooks (such as a `PreToolUse hook`) to block actions regardless of what the agent decides. [1][11]\n- **Plain Markdown, no required schema:** No field schema is required; `agents.md` describes `AGENTS.md` as living documentation. A plain `.md` file in `.cursor/rules` is ignored when it lacks frontmatter for `description`, `globs`, and `alwaysApply`. The `agents.md` homepage sample opens with `# AGENTS.md`, `## Setup commands`, and `## Code style`. [1][10]\n\n---\n\n## Cross-harness loading, configuration hooks, and compatibility\n\nOne `AGENTS.md` is shared across coding agents. The project site names Codex, Jules, Factory, Cursor, Zed, VS Code, Devin, and GitHub Copilot in that compatible set. Discovery order, fallback names, import or symlink bridges, and byte caps still vary by harness. [1]\n\n- **Codex discovery and byte caps:** Codex walks from the Git root down to the current directory. Each directory contributes `AGENTS.override.md`, else `AGENTS.md`, else one `project_doc_fallback_filenames` entry. Closer files override earlier text. The join stops at `project_doc_max_bytes` (32 KiB by default). `~/.codex/config.toml` sets fallbacks such as `TEAM_GUIDE.md` and `.agents.md`, and can raise the cap to `65536`. [12]\n- **Claude Code imports and symlinks:** Claude reads `AGENTS.md` (or `.claude/AGENTS.md`) directly only when `CLAUDE.md`, `.claude/CLAUDE.md`, and `CLAUDE.local.md` are absent from the working directory upward (`claude-md-or-agents-md`), which needs Claude Code v2.1.277 or later; users can also change the `Project instructions` setting to `claude-md-and-agents-md` so Claude reads both files together. Otherwise repositories can bridge the files with an `@AGENTS.md` import or `ln -s AGENTS.md CLAUDE.md` symlink. The `claude-md-and-agents-md` guide notes that Claude loads both and does not read an imported or symlinked `AGENTS.md` twice. [11]\n- **IDE and agent loading:** Cursor loads `AGENTS.md` in the root and subdirectories as an alternative to `.cursor/rules`. VS Code reads a workspace-root file when `chat.useAgentsMdFile` is on, the default. Copilot applies the nearest `AGENTS.md` in the directory tree, or lets a repository commit a single root `CLAUDE.md` or `GEMINI.md` as an alternative. Jules reads `AGENTS.md` in the repo. Devin injects the first `16 KiB` (`16,384` bytes). Factory walks up to the git root and also accepts `CLAUDE.md`. Zed is on the site's agent list. [1][2][8][10][13][14][15]\n- **Singular AGENT.md migration:** On August 20, 2025 Amp switched from `AGENT.md` to `AGENTS.md` while retaining backward compatibility with existing `AGENT.md` files, and `agents.md` documents renaming with `mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md` so older `AGENT.md` paths continue to resolve. Factory still checks `.agent/` and `.agents/`, and recommends `AGENTS.md` for new guidance. [1][4][8]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **README.md** | `README.md` | Analogous to classic standard | Provides human-facing quick starts, project descriptions, and contributor overviews, whereas `AGENTS.md` isolates agent-specific build commands, test workflows, and directory-scoped coding rules. [1] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[Agent Skills](/protocols/anthropic-agent-skills-format/)** | Complements | Packages reusable workflows and domain expertise as on-demand skill directories containing `SKILL.md` (alongside scripts and assets), whereas `AGENTS.md` provides always-on repository coding guidelines. [3][8] |\n| **[llms.txt](/protocols/llms-txt/)** | Complements | Publishes an HTTP-served web documentation index at `/llms.txt` for external reading agents, whereas `AGENTS.md` is committed inside a source repository to guide coding agents modifying the codebase. [1] |\n| **[Model Context Protocol](/protocols/mcp/)** | Complements | Connects AI models to external tools, data, and applications over a runtime protocol (co-founded in the AAIF alongside `AGENTS.md`), whereas `AGENTS.md` is a static Markdown convention for repository-specific guidance. [6] |\n| **[Agent Client Protocol](/protocols/agent-client-protocol/)** | Complements | Defines an editor-to-agent runtime protocol so compatible coding agents can run inside IDEs such as Zed and JetBrains, whereas `AGENTS.md` is the repository Markdown file those agents read for project instructions. [16][17][18] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (23 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Reference repositories publishing AGENTS.md\n\n| Actor | Role | Status | Artifact path & directory scope | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **vercel/next.js** | Repo publisher | Live (HTTP 200) · checked 2026-10-30 | Serves root `AGENTS.md` (`# Next.js Development Guide`, `text/plain`) covering the pnpm monorepo and nested `test/AGENTS.md`. | [Next.js, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/vercel/next.js/HEAD/AGENTS.md) [19] |\n| **microsoft/vscode** | Repo publisher | Live (HTTP 200) · checked 2026-10-30 | Serves root `AGENTS.md` (`# VS Code Agents Instructions`, `text/plain`) routing agents to `.github/copilot-instructions.md`. | [VS Code, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/microsoft/vscode/HEAD/AGENTS.md) [20] |\n| **apache/airflow** | Repo publisher | Live (HTTP 200) · checked 2026-10-30 | Serves root `AGENTS.md` (`# AGENTS instructions`, `text/plain`) covering `Dag` naming, Breeze commands, and architecture boundaries. | [Apache Airflow, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/apache/airflow/HEAD/AGENTS.md) [21] |\n| **pandas-dev/pandas** | Repo publisher | Live (HTTP 200) · checked 2026-10-30 | Serves root `AGENTS.md` (`# AGENTS.md`, `text/plain`) covering Meson Cython/C++ builds, GitHub interaction rules, and repository map. | [pandas, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/pandas-dev/pandas/HEAD/AGENTS.md) [22] |\n| **astral-sh/uv** | Repo publisher | Live (HTTP 200) · checked 2026-10-30 | Serves heading-free root `AGENTS.md` (`text/plain`), opening with bulleted rules referencing `CONTRIBUTING.md` and `insta` snapshots. | [uv, AGENTS.md (checked 2026-10-30)](https://raw.githubusercontent.com/astral-sh/uv/HEAD/AGENTS.md) [23] |\n| **temporalio/sdk-java** | Repo publisher | Live (HTTP 200) · checked 2026-11-04 | Serves root `AGENTS.md` (`# Contributor Quickstart Guide`, `text/plain`) with Gradle layout, `./gradlew spotlessCheck`, and `./gradlew test` rules. | [temporalio/sdk-java, AGENTS.md (checked 2026-11-04)](https://raw.githubusercontent.com/temporalio/sdk-java/master/AGENTS.md) [24] |\n| **pydantic/pydantic-ai** | Repo publisher | Live (HTTP 200) · checked 2026-11-04 | Serves root `AGENTS.md` (`text/plain`, 19,537 bytes) linking 18 nested `AGENTS.md` files across `docs/`, `pydantic_ai_slim/`, and `tests/`. | [pydantic/pydantic-ai, AGENTS.md (checked 2026-11-04)](https://raw.githubusercontent.com/pydantic/pydantic-ai/main/AGENTS.md) [25] |\n| **oven-sh/bun** | Repo publisher | Live (HTTP 200) · checked 2026-11-04 | Serves a 9-byte root `AGENTS.md` (`text/plain`) containing only `CLAUDE.md` as a cross-file pointer. | [oven-sh/bun, AGENTS.md (checked 2026-11-04)](https://raw.githubusercontent.com/oven-sh/bun/main/AGENTS.md) [26] |\n\n### Coding agents, IDEs & CLI harnesses\n\n| Actor | Role | Status | Discovery & hierarchy precedence | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **OpenAI Codex** | Coding agent | Supported · as of 2025-05-16 | Guided by repository `AGENTS.md` files since `2025-05-16`; in configuration docs (checked `2026-10-30`), reads `~/.codex` and walks root-to-CWD loading `AGENTS.override.md` or `AGENTS.md`, concatenating closer files last. | [OpenAI, Introducing Codex (2025-05-16)](https://web.archive.org/web/20261022165127/https://openai.com/index/introducing-codex/) [5] · [OpenAI, Custom instructions with AGENTS.md (checked 2026-10-30)](https://learn.chatgpt.com/docs/agent-configuration/agents-md) [12] |\n| **GitHub Copilot** | Coding agent | Supported · checked 2026-10-30 | Loads one or more `AGENTS.md` files anywhere in the repository; nearest file in the directory tree takes precedence. | [GitHub Docs, Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) [2] |\n| **Cursor** | IDE / Coding agent | Supported · checked 2026-10-30 | Loads plain-Markdown `AGENTS.md` in root and subdirectories, combining parent files with subdirectory precedence. | [Cursor Docs, Rules](https://cursor.com/docs/rules) [10] |\n| **Factory (Droid)** | Coding agent / CLI | Supported · checked 2026-10-30 | Searches CWD-to-Git-root and dynamic Read paths for `AGENTS.md`, refining root rules with nested files. | [Factory Documentation, AGENTS.md](https://docs.factory.com/harness/agents-md) [8] |\n| **Amp** | Coding agent | Supported · as of 2025-08-20 | Adopted `AGENTS.md` as standard filename on 2025-08-20 with glob mentions and `AGENT.md` backward compatibility. | [Amp, From AGENT.md to AGENTS.md (2025-08-20)](https://ampcode.com/news/AGENTS.md) [4] |\n| **Google Jules** | Coding agent | Supported · as of 2025-06-20 | Reads context from `AGENTS.md` automatically when present in a repository (shipped 2025-06-20). | [Jules Changelog, Jules Agent Update (2025-06-20)](https://jules.google/docs/changelog/2025-06-20/) [14] |\n| **Visual Studio Code** | IDE / Editor | Experimental · as of 2025-08 | Picks up workspace-root `AGENTS.md` for chat requests under default-enabled experimental `chat.useAgentsMdFile` setting (v1.104). | [Microsoft, VS Code August 2025 (version 1.104)](https://code.visualstudio.com/updates/v1_104) [13] |\n| **Anthropic (Claude Code)** | Coding agent / CLI | Partial · as of 2026-11-02 | Reads `AGENTS.md` and `.claude/AGENTS.md` by default only when no `CLAUDE.md` exists in or above CWD. | [Claude Code Docs, How Claude remembers your project (modified 2026-11-02)](https://code.claude.com/docs/en/memory) [11] |\n| **Cognition (Devin)** | Coding agent | Partial · as of 2026-09-25 | Automatically injects up to 16 KiB (16,384 bytes) per `AGENTS.md` before coding; longer files truncate. | [Devin Docs, AGENTS.md files for Devin (modified 2026-09-25)](https://docs.devin.ai/onboard-devin/agents-md) [15] |\n| **Aider** | Coding agent / CLI | Partial · checked 2026-10-30 | Documented in the `agents.md` FAQ as requiring explicit `read: AGENTS.md` configuration in `.aider.conf.yml`. | [AGENTS.md FAQ, How do I configure Aider?](https://agents.md/) [1] |\n| **Google Gemini CLI** | Coding agent / CLI | Partial · as of 2026-06-30 | Uses `GEMINI.md` by default; `agents.md` FAQ documents configuring `AGENTS.md` via `.gemini/settings.json`. | [AGENTS.md FAQ, How do I configure Gemini CLI?](https://agents.md/) [1] · [Galster et al., arXiv:2602.14690v5 (Table 1)](https://arxiv.org/html/2602.14690v5) [3] |\n| **Zed** | IDE / Editor | Listed · checked 2026-10-30 | Named in the compatible coding-agent roster on `agents.md`. | [AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1] |\n| **Windsurf (Cognition)** | IDE / Coding agent | Listed · checked 2026-10-30 | Named in the compatible coding-agent roster on `agents.md`. | [AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1] |\n| **Block (goose)** | Coding agent / CLI | Listed · checked 2026-10-30 | Named in the compatible coding-agent roster on `agents.md`. | [AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1] |\n| **opencode** | Coding agent / CLI | Listed · checked 2026-10-30 | Named in the compatible coding-agent roster on `agents.md`. | [AGENTS.md, One AGENTS.md works across many agents](https://agents.md/) [1] |\n\n### Ecosystem censuses\n\n- **Project-reported open-source repository lower bound (agents.md & Linux Foundation AAIF)** (*as of 2025-12-09*): Over 60,000 open-source projects reported as using AGENTS.md on the agents.md specification site (which links a live GitHub code search for path:AGENTS.md NOT is:fork NOT is:archived) and in the Linux Foundation's 9 December 2025 Agentic AI Foundation (AAIF) formation announcement. [1][6]\n- **High-star active GitHub census: 7,370 repositories with >=5,000 stars (Stride study)** (*as of 2026-09-27*): In Stride's 27 September 2026 census of all 7,370 active public GitHub repositories with 5,000 or more stars, 1,864 repositories (25.3%) had a root AGENTS.md file (rising to 41.8% among repositories with 50,000+ stars) and 33.4% had at least one coding-agent instruction file; across adopted AGENTS.md files, the median length was 819 words (with 13.4% between 200 and 400 words), 73.5% named a test, build, or lint command, 39.3% mentioned security or secrets, and among the 1,013 repositories carrying both AGENTS.md and CLAUDE.md, 36.2% joined them via a symlink, 35.5% used an @AGENTS.md import, and 25.9% linked neither. [9]\n- **13-language GitHub census of 22,854 active >=1,000-star repositories (Zarzycki, arXiv:2610.31715v2)** (*as of 2026-10-26*): Across 22,854 non-fork, non-archived public GitHub repositories with at least 1,000 stars and a push within 90 days in 13 languages (enumerated 16 October 2026), 6,006 repositories (26.3%, rising from 23.2% in the lowest star tier to 59.6% of the 89 most-starred repositories) published a root AGENTS.md, a root CLAUDE.md, or both—consisting of 2,566 repositories with only AGENTS.md, 1,052 with only CLAUDE.md, and 2,388 with both (of those with both, most point one file at the other: CLAUDE.md defers to AGENTS.md via a link, import, or pointer in 1,540 repositories, the reverse in 182, and only 598 keep two files with content of their own); counting additional one-level-deep formats (.github/copilot-instructions.md, .github/instructions/, /GEMINI.md, .claude/CLAUDE.md, /.cursorrules, /.windsurfrules) raised total adoption to 6,652 repositories (29.1%). [27]\n- **Pre-2024 engineered software study: 2,853 tool-configuring repos out of 32,564 engineered projects (Galster et al., arXiv:2602.14690v5)** (*as of 2026-06-30*): From 32,564 engineered open-source GitHub repositories created before 1 January 2024 and active since 1 June 2025, 2,853 repositories (8.8%) configured at least one agentic coding tool—partitioned into 2,015 single-tool repositories (70.6%), 295 two-tool repositories (10.3%), 50 three-or-more-tool repositories (1.8%), and 493 repositories (17.3% of the 2,853 tool-configuring repositories) that used AGENTS.md alone as a tool-agnostic standard without any tool-specific configuration artifact. [3]\n- **AGENTS.md Tracker (agentsmd.formachines.ai)** (*as of 2026-11-06*): The AGENTS.md Tracker scan published 2026-11-06 found a root AGENTS.md in 546 of 1,922 repositories (28.4%), and at least one of eight tracked instruction files in 677 of 1,922 (35.2%), measuring file presence on the default branch. [28]\n- **RepoAgentKit top-100 snapshot** (*as of 2026-09-01*): RepoAgentKit's 2026-09-01 snapshot, covering 100 pinned commits, found a case-sensitive root AGENTS.md in 39 of GitHub's top 100 repositories (excluding nested-only files), reporting a median of 112 lines and 29 of 39 files mentioning testing. [29]\n- **World of Code V2604 configuration-file census** (*as of 2026-04*): The World of Code V2604 configuration-file census records 134,810 AGENTS.md blobs and 151,390 CLAUDE.md blobs. The paper warns that cross-snapshot counts mix adoption with a growing corpus and should be read as coarse upper-bound trends, not adoption rates. [30]\n\n---\n\n## See also\n\n- **[Agent Readability Spec](/protocols/vercel-agent-readability/)** *(Complements)* — The guide treats /AGENTS.md as a readability artifact, while AGENTS.md is the instruction file for coding agents.\n- **[Open Knowledge Format](/protocols/okf/)** *(Peer alternative)* — AGENTS.md is one README for coding agents; OKF is a directory of Markdown files with YAML frontmatter.\n- **[Agent Context Interchange Protocol](/protocols/acip/)** *(Complements)* — ACIP reads YAML at .agents/agent-context.yaml with a precedence algorithm and a resolution receipt, and it is paired with AGENTS.md prose rather than replacing that file format.\n- **Category:** [Read protocols](/category/read/)\n\n---\n\n## References\n\n1. AGENTS.md (Agentic AI Foundation), *AGENTS.md* (checked 2026-10-30) — \n2. GitHub, *Adding repository custom instructions for GitHub Copilot* (checked 2026-10-30) — \n3. Matthias Galster, Seyedmoein Mohsenimofidi, Jai Lal Lulla, Muhammad Auwal Abubakar, Christoph Treude, and Sebastian Baltes, *Harness Engineering for Agentic AI Coding Tools: An Exploratory Study* (arXiv:2602.14690v5, revised 2026-06-30) — \n4. Amp, *From AGENT.md to AGENTS.md* (published 2025-08-20) — \n5. OpenAI, *Introducing Codex* (published 2025-05-16) — \n6. The Linux Foundation, *Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF), Anchored by New Project Contributions Including Model Context Protocol (MCP), goose and AGENTS.md* (published 2025-12-09; modified 2026-02-24) — \n7. AGENTS.md, *agentsmd/agents.md Repository LICENSE (MIT)* (fetched 2026-11-12) — \n8. Factory, *AGENTS.md* (checked 2026-10-30) — \n9. Stride, *What 7,370 popular GitHub repositories put in AGENTS.md and CLAUDE.md* (published 2026-09-27) — \n10. Cursor, *Rules* (checked 2026-10-30) — \n11. Anthropic (Claude Code), *How Claude remembers your project* (modified 2026-11-02) — \n12. OpenAI, *Custom instructions with AGENTS.md* (checked 2026-10-30) — \n13. Microsoft, *Visual Studio Code August 2025 (version 1.104)* (August 2025) — \n14. Google (Jules), *Jules Agent Update: Faster, Smarter, More Reliable* (published 2025-06-20) — \n15. Cognition (Devin), *AGENTS.md files for Devin* (modified 2026-09-25) — \n16. Zed (Nathan Sobo), *Bring Your Own Agent to Zed* (published 2025-08-27) — \n17. Zed (Franciska Dethlefsen), *ACP Brings JetBrains on Board* (published 2025-10-06) — \n18. JetBrains, *JetBrains × Zed: Open Interoperability for AI Coding Agents in Your IDE* (published 2025-10-06) — \n19. Vercel (vercel/next.js), *AGENTS.md* (checked 2026-10-30) — \n20. Microsoft (microsoft/vscode), *AGENTS.md* (checked 2026-10-30) — \n21. Apache Software Foundation (apache/airflow), *AGENTS.md* (checked 2026-10-30) — \n22. pandas (pandas-dev/pandas), *AGENTS.md* (checked 2026-10-30) — \n23. Astral (astral-sh/uv), *AGENTS.md* (checked 2026-10-30) — \n24. Temporal (temporalio/sdk-java), *AGENTS.md* (checked 2026-11-04) — \n25. Pydantic (pydantic/pydantic-ai), *AGENTS.md* (checked 2026-11-04) — \n26. Oven (oven-sh/bun), *AGENTS.md* (checked 2026-11-04) — \n27. Pawel Zarzycki, *What Open-Source Projects Tell Their Coding Agents: A Census of AGENTS.md and CLAUDE.md* (arXiv:2610.31715v2, revised 2026-10-26) — \n28. AGENTS.md Tracker (agentsmd.formachines.ai), *AGENTS.md adoption tracker* (scan 2026-11-06; fetched 2026-11-06) — \n29. RepoAgentKit, *AGENTS.md adoption in GitHub's top 100 repositories* (snapshot 2026-09-01; fetched 2026-11-06) — \n30. Arsham Khosravani and Audris Mockus, *Detecting AI Coding Agents in Open Source: A Validated Multi-Method Census of 180 Million Repositories* (2026-06-23) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "AIPREF", "adoption": { "level": "observed", "by": "SpinXO, Launchpad, Ubuntu Changelogs, They Said So, follow.it, Nuxt Robots, PEAC Protocol, Cloudflare Content Signals Policy, and 3 other verified implementations", "probe_run": null }, "aliases": [ "draft-ietf-aipref-attach" ], "analog": "robots.txt plus HTTP representation metadata", "collisions": [], "discovery": { "mechanism": "A `Content-Usage:` line inside a user-agent group of /robots.txt, and a `Content-Usage` HTTP response header", "path": null }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt", "claim": "Gary Illyes (Google) and Martin Thomson (Mozilla), *Associating AI Usage Preferences with Content in HTTP (draft-ietf-aipref-attach-05)*, dated 2026-08-19", "date": null, "quote": "draft-ietf-aipref-attach-05 / A Content-Usage header field for HTTP / A Content-Usage directive for the Robots Exclusion Protocol (colloquially known as \"robots.txt\") / This document defines attachment methods using the Robots Exclusion Protocol and HTTP header fields. / Content-Usage: train-ai=n This is some content. / User-Agent: * Allow: / Content-Usage: train-ai=n … The Content-Usage field is a structured field dictionary, as defined in Section 3.2 of [FIELDS]. This field follows the vocabulary and processing rules in [VOCAB]. / 19 August 2026 … Updates: 9309 (if approved) … This document updates RFC 9309 to allow for the inclusion of usage preferences. … This Internet-Draft will expire on 20 February 2027. / Gary Illyes … Google … Martin Thomson … Mozilla / Discussion of this document takes place on the AI Preferences Working Group mailing list (mailto:ai-control@ietf.org) / Source for this draft and an issue tracker can be found at https://github.com/ietf-wg-aipref/drafts. / Intended status: Standards Track / 19 August 2026 / This Internet-Draft will expire on 20 February 2027. / The Content-Usage field is a structured field dictionary, as defined in Section 3.2 of [FIELDS]. This field follows the vocabulary and processing rules in [VOCAB]. / Field Name: Content-Usage Status: permanent Structured Type: Dictionary / registry established in Section 18.4 of HTTP / Associating AI Usage Preferences with Content in HTTP / User-Agent: * Allow: / Content-Usage: train-ai=n / Copyright (c) 2026 IETF Trust / Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions / The Allow and Disallow rules determine what resources can be crawled / This creates a two-stage arrangement that distinguishes acquisition and usage. Acquisition relies on Allow/Disallow rules; usage preference relies on Content-Usage rules. / This document only defines how the strings or byte sequences are conveyed so that statements of preference can be associated with content. / The Content-Usage field does not have any special effect on caching. / Usage preferences apply only to those resources that can be crawled according to Allow/Disallow rules; no preferences are implied for resources that are disallowed. / This document updates RFC 9309 to allow for the inclusion of usage preferences. / A Content-Usage rule is added to the set of potential rules that can be included in a Group for \"robots.txt\". / Content-Usage: train-ai=n / RFC 9110 / This field follows the vocabulary and processing rules in [VOCAB]. / Each group in the file applies to a set of crawlers, identified by product token", "ref": 1 }, { "label": "[2]", "url": "https://datatracker.ietf.org/wg/aipref/about/", "claim": "IETF, *AI Preferences (aipref) working group*, fetched 2026-10-30", "date": null, "quote": "AI Preferences (aipref) / Chairs … Mark Nottingham, Suresh Krishnan / Area Director … Mike Bishop / The AI Preferences Working Group will standardize building blocks / Standard track document(s) describing means of attaching or associating those preferences with content / ai-control@ietf.org / Standard track protocol specification(s) to associate the AI-related preferences to the IESG for publication … draft-ietf-aipref-attach", "ref": 2 }, { "label": "[3]", "url": "https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt", "claim": "Paul Keller (Open Future) and Martin Thomson (Mozilla, editor), *A Vocabulary For Expressing AI Usage Preferences (draft-ietf-aipref-vocab-08)*, dated 2026-09-14", "date": null, "quote": "draft-ietf-aipref-vocab-08 / train-ai=y, search=n / This document defines a vocabulary for expressing preferences regarding how digital assets are used by automated processing systems. / | AI Training | train-ai | / | Search | search | / | AI Training | train-ai | Section 4.1 | / | Search | search | Section 4.3 | / any unknown labels MUST be ignored / | AI Use | ai-use | Section 4.2 |", "ref": 3 }, { "label": "[4]", "url": "https://blog.cloudflare.com/content-signals-policy/", "claim": "Will Allen (Cloudflare), *Giving users choice with Cloudflare's new Content Signals Policy*, published 2025-09-24; modified 2026-07-15", "date": null, "quote": "This policy defines three content signals - search, ai-input, and ai-train / User-Agent: * Content-Signal: search=yes, ai-train=no", "ref": 4 }, { "label": "[5]", "url": "https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/", "claim": "Laurent Le Meur (EDRLab), *TDM Reservation Protocol (TDMRep)*, Final Community Group Report 2024-05-10", "date": null, "quote": "TDM Reservation Protocol (TDMRep) / defines a JSON file named tdmrep.json, which MUST be hosted in the /.well-known repository of a Web server. / tdm-reservation is an boolean value. / 1 TDM rights are reserved. / tdm-policy / / TDM Metadata in HTML Content / TDM Metadata in EPUB 2 files", "ref": 5 }, { "label": "[6]", "url": "https://developers.openai.com/api/docs/bots", "claim": "OpenAI, *Overview of OpenAI Crawlers*, fetched 2026-10-30", "date": null, "quote": "OpenAI uses OAI-SearchBot and GPTBot robots.txt tags", "ref": 6 }, { "label": "[7]", "url": "https://www.rfc-editor.org/rfc/rfc9309.html", "claim": "M. Koster, G. Illyes, H. Zeller, and L. Sassman, *Robots Exclusion Protocol*, RFC 9309, September 2022", "date": null, "quote": "product token MUST contain only uppercase and lowercase letters / RFC 9309: Robots Exclusion Protocol", "ref": 7 }, { "label": "[8]", "url": "https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/history/", "claim": "IETF Datatracker, *draft-ietf-aipref-attach — History (IETF Datatracker)*, fetched 2026-10-30", "date": null, "quote": "2026-08-18 | 05 | Martin Thomson | New version available: draft-ietf-aipref-attach-05.txt … 2026-05-01 | 04 | (System) | Document has expired / 2025-06-15 … WG -00 approved / 2025-09-04 … IETF WG state changed to In WG Last Call from WG Document / 2025-11-03 … IETF WG state changed to WG Document from In WG Last Call / 2026-05-01 … Document has expired / 2026-08-18 … New version available: draft-ietf-aipref-attach-05.txt", "ref": 8 }, { "label": "[9]", "url": "https://www.ietf.org/archive/id/draft-it-aipref-attachment-00.txt", "claim": "Gary Illyes (Google) and Martin Thomson (Mozilla), *Indicating Preferences Regarding Content Usage (draft-it-aipref-attachment-00)*, dated 2025-05-28", "date": null, "quote": "G. Illyes … Google … M. Thomson … Mozilla / 28 May 2025 / draft-it-aipref-attachment-00 / Indicating Preferences Regarding Content Usage", "ref": 9 }, { "label": "[10]", "url": "https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/", "claim": "IETF Datatracker, *draft-ietf-aipref-attach — Associating AI Usage Preferences with Content in HTTP (IETF Datatracker)*, last updated 2026-08-18", "date": null, "quote": "Authors … Gary Illyes, Martin Thomson / Replaces … draft-it-aipref-attachment / Intended RFC status … Proposed Standard / Active Internet-Draft (aipref WG) / WG state … WG Document / IESG state … I-D Exists / Last updated … 2026-08-18", "ref": 10 }, { "label": "[11]", "url": "https://datatracker.ietf.org/api/v1/doc/document/?group__acronym=aipref&type=rfc&format=json", "claim": "IETF Datatracker API, *RFC documents in the aipref working group*, fetched 2026-10-30", "date": null, "quote": "\"total_count\": 0", "ref": 11 }, { "label": "[12]", "url": "https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-aipref-attach/?format=json", "claim": "IETF Datatracker API, *IETF Datatracker document record for draft-ietf-aipref-attach*, rev 05 at 2026-08-19", "date": null, "quote": "\"rev\": \"05\" / \"time\": \"2026-08-19T04:25:16Z\" / \"expires\": \"2027-02-20T04:25:16Z\"", "ref": 12 }, { "label": "[13]", "url": "https://mailarchive.ietf.org/arch/msg/ai-control/LF4qTxITge4ID8QPsjOcNUUrDO4/", "claim": "Mark Nottingham via Datatracker, *WG Last Call: draft-ietf-aipref-attach-03 (Ends 2025-09-18)*, 2025-09-04", "date": "2025-09-04", "quote": "This message starts a 2-week WG Last Call for this document. / Thu, 04 Sep 2025", "ref": 13 }, { "label": "[14]", "url": "https://datatracker.ietf.org/wg/aipref/history/", "claim": "IETF Datatracker, *AI Preferences (aipref) working group history*, fetched 2026-10-30", "date": null, "quote": "2025-09-23 … set due date to August 2026 from August 2025", "ref": 14 }, { "label": "[15]", "url": "https://www.ietf.org/blog/ai-pref-update/", "claim": "IETF, *Enabling Publishers to Express Preferences for AI Crawlers: An Update on the AIPREF Working Group*, 2025-10-30", "date": "2025-10-30", "quote": "30 Oct 2025 / The response was not one we anticipated: several participants raised fundamental issues about the nature of the Internet-Drafts (I-Ds), forcing the group to reconsider its approach.", "ref": 15 }, { "label": "[16]", "url": "https://www.iana.org/assignments/http-fields/http-fields.txt", "claim": "IANA, *Hypertext Transfer Protocol (HTTP) Field Name Registry*, last updated 2026-10-09", "date": null, "quote": "Hypertext Transfer Protocol (HTTP) Field Name Registry / Last Updated 2026-10-09", "ref": 16 }, { "label": "[17]", "url": "https://ietf-wg-aipref.github.io/drafts/draft-ietf-aipref-attach.html", "claim": "IETF AI Preferences working group, *Associating AI Usage Preferences with Content in HTTP*, fetched 2026-10-30", "date": null, "quote": "Associating AI Usage Preferences with Content in HTTP", "ref": 17 }, { "label": "[18]", "url": "https://spawning.substack.com/p/aitxt-a-new-way-for-websites-to-set", "claim": "Cullen Miller (Spawning), *ai.txt: A new way for websites to set permissions for AI*, published 2023-05-30", "date": null, "quote": "Ai.txt is a file placed at the root of a website", "ref": 18 }, { "label": "[19]", "url": "https://github.com/kaylacar/ai-txt/blob/master/ietf/draft-car-ai-txt-wellknown-00.md", "claim": "Kayla Cardillo, *draft-car-ai-txt-wellknown-00*, fetched 2026-10-30", "date": null, "quote": "/ai.txt / .well-known/ai.txt / training, scraping, indexing, caching", "ref": 19 }, { "label": "[20]", "url": "https://www.spinxo.com/robots.txt", "claim": "SpinXO, *robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: train-ai=y, search=y / # AI usage preference (draft-ietf-aipref-attach)", "ref": 20 }, { "label": "[21]", "url": "https://www.spinxo.com/", "claim": "SpinXO, *SpinXO home page response headers*, fetched 2026-10-30", "date": null, "quote": "content-usage: train-ai=y, search=y", "ref": 21 }, { "label": "[22]", "url": "https://launchpad.net/robots.txt", "claim": "Launchpad, *robots.txt*, fetched 2026-10-30", "date": null, "quote": "User-agent: * DisallowAITraining: / Content-Usage: ai=n Content-Signal: ai-train=no, search=yes, ai-input=no / # Source: https://robotstxt.com/ai", "ref": 22 }, { "label": "[23]", "url": "https://bugs.launchpad.net/robots.txt", "claim": "Launchpad, *bugs.launchpad.net robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: ai=n", "ref": 23 }, { "label": "[24]", "url": "https://code.launchpad.net/robots.txt", "claim": "Launchpad, *code.launchpad.net robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: ai=n", "ref": 24 }, { "label": "[25]", "url": "https://answers.launchpad.net/robots.txt", "claim": "Launchpad, *answers.launchpad.net robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: ai=n / Content-Signal: ai-train=no, search=yes, ai-input=no", "ref": 25 }, { "label": "[26]", "url": "https://changelogs.ubuntu.com/robots.txt", "claim": "Ubuntu, *changelogs.ubuntu.com robots.txt*, fetched 2026-10-30", "date": null, "quote": "User-Agent: * DisallowAITraining: / Content-Usage: ai=n / # Source: https://robotstxt.com/ai", "ref": 26 }, { "label": "[27]", "url": "https://theysaidso.com/robots.txt", "claim": "They Said So, *robots.txt*, fetched 2026-10-30", "date": null, "quote": "User-Agent: * DisallowAITraining: / Content-Usage: ai=n Content-Signal: search=yes, ai-input=no, ai-train=no / # Source: https://robotstxt.com/ai", "ref": 27 }, { "label": "[28]", "url": "https://follow.it/robots.txt", "claim": "Follow.it Feed Service, *robots.txt*, fetched 2026-10-30", "date": null, "quote": "# START nuxt-robots (indexable) User-agent: * Content-Usage: bots=y, train-ai=n Content-Signal: ai-train=no, search=yes / # START nuxt-robots (indexable) / Content-Usage: bots=y, train-ai=n", "ref": 28 }, { "label": "[29]", "url": "https://gazzettadelsud.it/robots.txt", "claim": "Gazzetta del Sud, *robots.txt*, fetched 2026-10-30", "date": null, "quote": "User-Agent: * DisallowAITraining: / Content-Usage: ai=n / # Source: https://robotstxt.com/ai", "ref": 29 }, { "label": "[30]", "url": "https://dri.es/", "claim": "Dries Buytaert, *dri.es home page response headers*, fetched 2026-10-30", "date": null, "quote": "content-signal: ai-train=yes, search=yes, ai-input=yes content-usage: ai=y", "ref": 30 }, { "label": "[31]", "url": "https://blamejs.com/ai-pref", "claim": "blamejs, *Ai Pref, blamejs*, 2026-11-06", "date": "2026-11-06", "quote": "the IETF AIPREF `Content-Usage` HTTP response header (draft-ietf-aipref-attach-04, deadline 2026-08) / the matching robots.txt grammar / Pay-Per-Crawl (HTTP 402) / Operators declare train / infer / snippet preferences once / the middleware emits both the `Content-Usage` header and Cloudflare's `CF-Content-Signals`", "ref": 31 }, { "label": "[32]", "url": "https://nuxtseo.com/docs/robots/guides/ai-directives", "claim": "Harlan Wilton (Nuxt SEO), *AI Directives*, last updated 2026-07-16", "date": null, "quote": "Last updated Jul 16, 2026 / Two standards are supported: Content-Usage - IETF standard with broader automation categories / The Content-Usage directive follows the IETF AI Preferences specification / Content-Usage: bots=y, train-ai=n", "ref": 32 }, { "label": "[33]", "url": "https://www.peacprotocol.org/integrations/content-signals", "claim": "PEAC Protocol, *Content Signals*, fetched 2026-10-30", "date": null, "quote": "The Content-Usage header is parsed as an RFC 9651 Structured Fields Dictionary. / PEAC records these signals as evidence but does not enforce them. / draft-ietf-aipref-attach-04 / RFC 9651 / 2026-06-01", "ref": 33 }, { "label": "[34]", "url": "https://mailarchive.ietf.org/arch/msg/ai-control/EANb9b9bljOanLBFm5FRerYlxyI/", "claim": "Michael Tremante, *Cloudflare's Content Signal Policy*, 2025-09-24", "date": "2025-09-24", "quote": "Wed, 24 September 2025 / Cloudflare's Content Signal Policy / We see this as an interim measure to address immediate needs / hope we can achieve a consensus position and will revisit our policy once that has happened", "ref": 34 }, { "label": "[35]", "url": "https://blog.cloudflare.com/accountable-mixed-use-ai-crawlers/", "claim": "Bryan Becker (Cloudflare), *Have it both ways: stay discoverable in search while disallowing AI training*, published 2026-09-15", "date": null, "quote": "Bryan Becker / September 15, 2026 / As standards such as ai-prefs mature, we will revisit this approach. / 2026-09-15", "ref": 35 }, { "label": "[36]", "url": "https://www.cloudflare.com/press/press-releases/2026/cloudflare-helps-end-the-search-or-ai-training-tradeoff/", "claim": "Cloudflare, *Cloudflare Helps End the Search-or-AI-Training Tradeoff*, 2026-09-15", "date": "2026-09-15", "quote": "a specification under development / Today's controls are designed to work alongside these emerging standards. / ai-prefs", "ref": 36 }, { "label": "[37]", "url": "https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec", "claim": "Google, *How Google Interprets the robots.txt Specification*, last updated 2026-10-23", "date": null, "quote": "Last updated 2026-10-23 UTC. / Google supports the following fields (other fields such as crawl-delay aren't supported): user-agent: identifies which crawler the rules apply to. allow: a URL path that may be crawled. disallow: a URL path that may not be crawled. sitemap:", "ref": 37 } ], "form": "http-header", "governance": "IETF AI Preferences (aipref) working group: \"Chairs Mark Nottingham, Suresh Krishnan Area Director Mike Bishop\". The charter asks for \"Standard track document(s) describing means of attaching or associating those preferences with content in IETF-defined protocols and formats, including but not limited to using Well-Known URIs (RFC 8615) such as the Robots Exclusion Protocol (RFC 9309), and HTTP response header fields\". Discussion is on the ai-control@ietf.org list and the source is in the GitHub repository ietf-wg-aipref/drafts", "group": "AIPREF", "history": [ { "date": "2026-10-29", "note": "Verified record against draft-ietf-aipref-attach-05, IETF Datatracker, ai-control mailing list, and live robots.txt / Content-Usage header deployments" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "aipref-content-usage-attachment", "implementation": "prototype", "last_verified": "2026-11-06", "name": "AIPREF Content-Usage Attachment", "native_status": "Active Internet-Draft, not an RFC: \"Document Type Active Internet-Draft (aipref WG) Authors Gary Illyes, Martin Thomson Last updated 2026-08-18 Replaces draft-it-aipref-attachment\" \"IESG state I-D Exists\". The Datatracker API lists no aipref RFC (checked 2026-10-29). Working-group last call on -03 began on 2025-09-04 (\"This message starts a 2-week WG Last Call for this document.\") and the draft went back to WG Document on 2025-11-03; the chairs wrote: \"The response was not one we anticipated: several participants raised fundamental issues about the nature of the Internet-Drafts (I-Ds), forcing the group to reconsider its approach.\". -04 lapsed (\"Expires: 1 May 2026\"; \"2026-05-01 04 (System) Document has expired\") and -05 renewed it: \"2026-08-18 05 Martin Thomson New version available: draft-ietf-aipref-attach-05.txt\". The charter milestone was \"2026-08-31 Aug 2026 Standard track protocol specification(s) to associate the AI-related preferences to the IESG for publication draft-ietf-aipref-attach\", moved from August 2025 on 2025-09-23; on 2026-10-29 the Datatracker still showed the IESG state \"I-D Exists\". The Content-Usage header field is requested as permanent (\"Field Name: Content-Usage Status: permanent Structured Type: Dictionary\") but was not in the IANA HTTP Field Name registry on 2026-10-29", "origin": { "date": "2025-05-28", "org": "Gary Illyes (Google) and Martin Thomson (Mozilla)" }, "part_of": null, "parties": [ "agent-site" ], "phase": "working-group", "probe": { "method": "GET", "on_absent": "Publisher has not attached machine-readable AI-use preferences via either attachment method; no inference can be drawn about actual policy", "parse": "Presence of a 'Content-Usage' line in a robots.txt group, or a Content-Usage HTTP response header on the fetched resource itself", "path": "{origin}/robots.txt" }, "question": "How does a publisher attach its AI-use preferences to content served over HTTP, so an automated system can find them?", "scope": "general", "spec_url": "https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt", "step": "permit", "summary_md": "**AIPREF Content-Usage Attachment** is the IETF Internet-Draft `draft-ietf-aipref-attach`, which defines `Content-Usage` attachment methods for usage preferences using the Robots Exclusion Protocol and HTTP header fields. The example response carries `Content-Usage: train-ai=n` before the message body. The `Content-Usage` field is a structured field dictionary and follows the vocabulary draft's processing rules. A `robots.txt` group can carry the same preference beside `User-Agent: *` and `Allow: /`. If approved, `draft-ietf-aipref-attach` updates RFC 9309 to allow usage preferences in `robots.txt`. Datatracker history records that revision 04 expired on `2026-05-01` and that revision 05 was posted on `2026-08-18`. The text is dated 19 August 2026 and expires on 20 February 2027.", "track": "ietf", "version": { "date": "2026-08-19", "label": "draft-ietf-aipref-attach-05" }, "watch": [ { "type": "ietf", "doc": "draft-ietf-aipref-attach" } ], "use_cases": [ "control-ai-crawling" ], "audience": [ "site-owner", "standards-body", "platform" ], "pairs_with": [ "aipref-vocabulary", "ai-crawler-tokens-robots", "cloudflare-content-signals-policy", "tdmrep", "ai-txt" ], "prerequisites": [ "aipref-vocabulary" ], "hatnote_md": "This page is about draft-ietf-aipref-attach, the IETF AI Preferences (aipref) working-group Internet-Draft that says where a usage preference is published: in a Content-Usage HTTP response header and in a Content-Usage rule in robots.txt. It is not the [AIPREF vocabulary](/protocols/aipref-vocabulary/) (draft-ietf-aipref-vocab), which defines labels such as train-ai and search. It is not Cloudflare's [Content Signals Policy](/protocols/cloudflare-content-signals-policy/), which uses its own Content-Signal line with the signals search, ai-input, and ai-train; not the W3C community group's [TDMRep](/protocols/tdmrep/); and not [AI crawler user-agent tokens in robots.txt](/protocols/ai-crawler-tokens-robots/), which allow or block named crawlers rather than state a use preference. Each has its own page.", "ietf_tracker": { "doc": "draft-ietf-aipref-attach", "rev": "05", "state": "active", "stream": "IETF", "group_type": "WG", "wg": "aipref", "replaced_by": null, "posted_utc": "2026-08-19", "expires_utc": "2027-02-20", "as_of": "2026-11-06", "source": "https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/", "source_label": "per IETF Datatracker" }, "tier": "spec_brief", "lifecycle_status": "active_draft", "wire_archetype": "crawler_policy", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-11-06", "v05_hatnote_html_md": "This page is about draft-ietf-aipref-attach, the IETF AI Preferences (aipref) working-group Internet-Draft that says where a usage preference is published: in a Content-Usage HTTP response header and in a Content-Usage rule in robots.txt. It is not the [AIPREF vocabulary](/protocols/aipref-vocabulary/) (draft-ietf-aipref-vocab), which defines labels such as train-ai and search. It is not Cloudflare's [Content Signals Policy](/protocols/cloudflare-content-signals-policy/), which uses its own Content-Signal line with the signals search, ai-input, and ai-train; not the W3C community group's [TDMRep](/protocols/tdmrep/); and not [AI crawler user-agent tokens in robots.txt](/protocols/ai-crawler-tokens-robots/), which allow or block named crawlers rather than state a use preference. Each has its own page. [1][2][3][4][5][6][7]", "v05_elevator_pitch_md": null, "v05_lead_md": "**AIPREF Content-Usage Attachment** is the IETF Internet-Draft `draft-ietf-aipref-attach`, which defines `Content-Usage` attachment methods for usage preferences using the Robots Exclusion Protocol and HTTP header fields. [1] The example response carries `Content-Usage: train-ai=n` before the message body. The `Content-Usage` field is a structured field dictionary and follows the vocabulary draft's processing rules. A `robots.txt` group can carry the same preference beside `User-Agent: *` and `Allow: /`. [1] If approved, `draft-ietf-aipref-attach` updates RFC 9309 to allow usage preferences in `robots.txt`. Datatracker history records that revision 04 expired on `2026-05-01` and that revision 05 was posted on `2026-08-18`. The text is dated 19 August 2026 and expires on 20 February 2027. [1][8]", "v05_identity_sentence_md": "**AIPREF Content-Usage Attachment** is the IETF Internet-Draft `draft-ietf-aipref-attach`, which defines `Content-Usage` attachment methods for usage preferences using the Robots Exclusion Protocol and HTTP header fields. [1]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Permit](/category/permit/) (`permit`)" }, { "label": "Form", "value_md": "HTTP header (`http-header`)" }, { "label": "Originated by", "value_md": "Gary Illyes (Google) and Martin Thomson (Mozilla). Individual draft `draft-it-aipref-attachment-00` is dated 28 May 2025. Working-group `-00` was approved on 2025-06-15. [1][8][9][10]" }, { "label": "Governed by", "value_md": "IETF AI Preferences (aipref) working group. Chairs Mark Nottingham and Suresh Krishnan; Area Director Mike Bishop. Discussion is on ai-control@ietf.org. The source repository is ietf-wg-aipref/drafts. [1][2]" }, { "label": "Track", "value_md": "IETF; intended status Standards Track [1][10]" }, { "label": "IETF tracker", "value_md": "[draft-ietf-aipref-attach](https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/) [1][10]" }, { "label": "Status", "value_md": "Active Internet-Draft (aipref WG Document; intended status Proposed Standard; no WG RFCs published yet). Revision -05 is dated 19 August 2026 and expires 20 February 2027. A 2-week working-group last call on -03 started 4 September 2025 and returned to WG Document on 2025-11-03; -04 expired 2026-05-01 and -05 was posted 2026-08-18. [1][2][8][10][11][12][13][14][15]" }, { "label": "Version", "value_md": "`draft-ietf-aipref-attach-05`, dated 19 August 2026 (Datatracker revision 05). [1][12]" }, { "label": "Headers", "value_md": "`Content-Usage` HTTP response header. The draft's example is `Content-Usage: train-ai=n`. [1]" }, { "label": "Message format", "value_md": "Structured field dictionary, following the vocabulary draft's processing rules. [1]" }, { "label": "IANA registration", "value_md": "Requested Field Name `Content-Usage`, Status permanent, Structured Type Dictionary. The fetched IANA HTTP Field Name Registry was last updated 2026-10-09 and does not contain a Content-Usage entry. [1][16]" }, { "label": "Specification", "value_md": "[Associating AI Usage Preferences with Content in HTTP](https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt) (`draft-ietf-aipref-attach-05`) [1]" }, { "label": "Found at", "value_md": "A `Content-Usage` rule inside a robots.txt group, and a `Content-Usage` HTTP response header. The working-group editor's copy is the GitHub Pages HTML for the attachment draft. [1][17]" }, { "label": "Licence", "value_md": "Copyright 2026 IETF Trust and the document authors. Code components extracted from the draft must include Revised BSD License text (Trust Legal Provisions Section 4.e). [1]" } ], "v05_problem_md": "The `Allow` and `Disallow` rules determine what resources can be crawled. This creates a two-stage arrangement that distinguishes acquisition and usage: acquisition relies on `Allow/Disallow` rules, and usage preference relies on `Content-Usage` rules. [1] `draft-ietf-aipref-attach` only defines how the strings or byte sequences are conveyed so that statements of preference can be associated with content. `draft-ietf-aipref-vocab` defines a vocabulary for expressing preferences regarding how digital assets are used by automated processing systems. [1][3] The `Content-Usage` field does not have any special effect on caching. Usage preferences apply only to those resources that can be crawled according to `Allow/Disallow` rules; no preferences are implied for resources that are disallowed. [1]", "v05_mechanism_delta_md": "`draft-ietf-aipref-attach` only defines how the strings or byte sequences are conveyed so that statements of preference can be associated with content. `draft-ietf-aipref-vocab` defines a vocabulary for expressing preferences regarding how digital assets are used by automated processing systems. [1][3]", "v05_scope_boundary_md": "The `Content-Usage` field does not have any special effect on caching. Usage preferences apply only to those resources that can be crawled according to `Allow/Disallow` rules; no preferences are implied for resources that are disallowed. [1]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "robots.txt (RFC 9309)", "spec_or_rfc": "RFC 9309", "relation_type": "profiles_classic", "relation_label": "Profiles classic standard", "delta_md": "draft-ietf-aipref-attach adds a Content-Usage rule, such as Content-Usage: train-ai=n, inside a robots.txt group and says it updates RFC 9309 so the group can carry usage preferences as well as Allow and Disallow. [1][7]" }, { "name": "HTTP Semantics (RFC 9110)", "spec_or_rfc": "RFC 9110", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "draft-ietf-aipref-attach defines a Content-Usage HTTP response header, with an example of Content-Usage: train-ai=n, and requests permanent registration of Field Name Content-Usage in the HTTP Field Name registry established in Section 18.4 of HTTP (RFC 9110). The IANA registry text fetched with this page was last updated 2026-10-09 and does not contain a Content-Usage entry. [1][16]" } ], "agentic_peers": [ { "target_id": "aipref-vocabulary", "target_name": "AIPREF Vocabulary (A Vocabulary For Expressing AI Usage Preferences)", "relation_type": "builds_on", "relation_label": "Builds on", "delta_md": "The attachment draft places vocabulary tokens such as train-ai and search on the wire, and the vocabulary draft itself defines those tokens with no robots.txt rule or HTTP header. [1][3]" }, { "target_id": "ai-crawler-tokens-robots", "target_name": "AI crawler tokens in robots.txt", "relation_type": "complements", "relation_label": "Complements", "delta_md": "Content-Usage is an additional rule inside a user-agent group, such as train-ai=n, while AI crawler tokens are the User-agent product tokens that select the group. [1][6][7]" }, { "target_id": "cloudflare-content-signals-policy", "target_name": "Content Signals Policy", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Content-Usage carries tokens such as train-ai=n in a robots.txt rule and in a Content-Usage HTTP header, while Content-Signal carries search, ai-input, and ai-train only as a robots.txt directive inside a User-agent group. [1][4]" }, { "target_id": "tdmrep", "target_name": "TDMRep (TDM Reservation Protocol)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Content-Usage is a robots.txt rule plus a response header carrying tokens such as train-ai=n, while TDMRep uses /.well-known/tdmrep.json, tdm-reservation set to 1, tdm-policy, HTML meta, and EPUB or PDF metadata. [1][5]" }, { "target_id": "ai-txt", "target_name": "ai.txt", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Content-Usage extends /robots.txt and the HTTP response with tokens such as train-ai=n, while ai.txt is a separate file at /ai.txt or /.well-known/ai.txt with Training, Scraping, Indexing, and Caching. [1][18][19]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (12 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Origins serving `Content-Usage` in `robots.txt` or HTTP headers", "col4_header": "Attachment surface, observed statement & vocabulary fit", "note_md": null, "rows": [ { "actor": "SpinXO", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Both surfaces serve the same statement. In robots.txt the `User-agent: *` group carries `Content-Usage: train-ai=y, search=y` under the comment that this is the AI usage preference (draft-ietf-aipref-attach), and the same line is repeated on later crawler groups. The home page responds with the header `content-usage: train-ai=y, search=y`. Vocab-08 Table 1 maps AI Training to `train-ai` (Section 4.1) and Search to `search` (Section 4.3).", "source_md": "[spinxo.com/robots.txt](https://www.spinxo.com/robots.txt) [20] · [spinxo.com response headers](https://www.spinxo.com/) [21] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "Launchpad", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "robots.txt on launchpad.net, bugs.launchpad.net, code.launchpad.net, and answers.launchpad.net each serves `Content-Usage: ai=n` in the `User-agent: *` group, with the comment `# Source: https://robotstxt.com/ai` and an adjacent `Content-Signal: ai-train=no, search=yes, ai-input=no`. The label ai is not a vocab-08 Table 1 label (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored.", "source_md": "[launchpad.net/robots.txt](https://launchpad.net/robots.txt) [22] · [bugs.launchpad.net/robots.txt](https://bugs.launchpad.net/robots.txt) [23] · [code.launchpad.net/robots.txt](https://code.launchpad.net/robots.txt) [24] · [answers.launchpad.net/robots.txt](https://answers.launchpad.net/robots.txt) [25] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "Ubuntu Changelogs", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "robots.txt serves `Content-Usage: ai=n` in the `User-Agent: *` group, with the comment `# Source: https://robotstxt.com/ai`. This file has no Content-Signal line. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored.", "source_md": "[changelogs.ubuntu.com/robots.txt](https://changelogs.ubuntu.com/robots.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "They Said So", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "robots.txt serves `Content-Usage: ai=n` in the `User-Agent: *` group, beside `Content-Signal: search=yes, ai-input=no, ai-train=no`, with the comment `# Source: https://robotstxt.com/ai`. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored.", "source_md": "[theysaidso.com/robots.txt](https://theysaidso.com/robots.txt) [27] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "follow.it", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "robots.txt is marked `# START nuxt-robots (indexable)`. The `User-agent: *` group serves `Content-Usage: bots=y, train-ai=n` and `Content-Signal: ai-train=no, search=yes`. `bots` is not a vocab-08 Table 1 label (`train-ai`, `ai-use`, `search`), and any unknown labels MUST be ignored. The label that remains, `train-ai`, is the Table 1 label for AI Training.", "source_md": "[follow.it/robots.txt](https://follow.it/robots.txt) [28] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "Gazzetta del Sud", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "robots.txt serves `Content-Usage: ai=n` in the `User-Agent: *` group, with the comment `# Source: https://robotstxt.com/ai`. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored.", "source_md": "[gazzettadelsud.it/robots.txt](https://gazzettadelsud.it/robots.txt) [29] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "dri.es", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "The home-page response carries the header `content-usage: ai=y` beside `content-signal: ai-train=yes, search=yes, ai-input=yes`. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored.", "source_md": "[dri.es response headers](https://dri.es/) [30] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3]" }, { "actor": "blamejs", "role": "Middleware", "status": "Development", "status_display": "Development · checked 2026-11-06", "col4_md": "Documents support for the IETF AIPREF `Content-Usage` HTTP response header (citing `draft-ietf-aipref-attach-04` and the WG's `2026-08` milestone target), the matching robots.txt grammar, and Cloudflare Content Signals plus Pay-Per-Crawl (HTTP 402). Operators declare train / infer / snippet preferences once; the middleware emits both the `Content-Usage` header and `CF-Content-Signals`.", "source_md": "[blamejs AI preferences](https://blamejs.com/ai-pref) [31]" } ] }, "side_b": { "visible": true, "heading": "Generators, parsers, platforms & crawler specifications", "col4_header": "Coverage, behavior & specification status", "note_md": null, "rows": [ { "actor": "Nuxt Robots", "role": "Generator", "status": "Supported", "status_display": "Supported · as of 2026-07-16", "col4_md": "The AI Directives guide, last updated Jul 16, 2026, says two standards are supported and names `Content-Usage` as the IETF one. It says the Content-Usage directive follows the IETF AI Preferences specification. One documented example is `Content-Usage: bots=y, train-ai=n`, the same line follow.it serves inside `# START nuxt-robots (indexable)`.", "source_md": "[Nuxt Robots AI Directives](https://nuxtseo.com/docs/robots/guides/ai-directives) [32] · [follow.it/robots.txt](https://follow.it/robots.txt) [28]" }, { "actor": "PEAC Protocol", "role": "Parser", "status": "Partial", "status_display": "Partial · as of 2026-06-01", "col4_md": "Coverage is the Content-Usage HTTP header, identified on the page with `draft-ietf-aipref-attach-04` and Structured Fields per `RFC 9651`. The page says the `Content-Usage` header is parsed as an RFC 9651 Structured Fields Dictionary, and that PEAC records these signals as evidence but does not enforce them. Page `dateModified` is 2026-06-01.", "source_md": "[PEAC Content Signals](https://www.peacprotocol.org/integrations/content-signals) [33]" }, { "actor": "Cloudflare Content Signals Policy", "role": "Platform", "status": "Development", "status_display": "Development · as of 2026-09-15", "col4_md": "Michael Tremante's note of 24 September 2025 on Cloudflare's Content Signal Policy calls the policy an interim measure and says they will revisit the policy once the working group reaches a consensus position. Bryan Becker's post of September 15, 2026 says that as standards such as `ai-prefs` mature, they will revisit this approach (`datePublished` 2026-09-15). The same day's press release calls `ai-prefs` a specification under development and says today's controls are designed to work alongside these emerging standards.", "source_md": "[ai-control, Tremante, 24 September 2025](https://mailarchive.ietf.org/arch/msg/ai-control/EANb9b9bljOanLBFm5FRerYlxyI/) [34] · [Have it both ways (Becker)](https://blog.cloudflare.com/accountable-mixed-use-ai-crawlers/) [35] · [Press release, September 15, 2026](https://www.cloudflare.com/press/press-releases/2026/cloudflare-helps-end-the-search-or-ai-training-tradeoff/) [36]" }, { "actor": "Google robots.txt specification", "role": "Crawler operator", "status": "Does not request", "status_display": "Does not request · as of 2026-10-23", "col4_md": "Last updated 2026-10-23 UTC. Google supports the fields `user-agent`, `allow`, `disallow`, and `sitemap`, and says other fields such as `crawl-delay` aren't supported. Google's specification page does not name Content-Usage.", "source_md": "[How Google interprets the robots.txt specification](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec) [37]" } ] }, "additional_tables": null, "censuses": [ { "label": "IETF Datatracker documents API (group aipref, type rfc)", "as_of": "2026-10-30", "value_md": "0 published RFCs in the IETF Datatracker for the `aipref` working group. [11]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "rsl", "target_name": "Really Simple Licensing", "relation_label": "Complements", "delta": "AIPREF puts Content-Usage in robots.txt and an HTTP header. RSL points a License URI or Link header at XML.", "item_md": "**[Really Simple Licensing](/protocols/rsl/)** (Complements) — AIPREF puts Content-Usage in robots.txt and an HTTP header. RSL points a License URI or Link header at XML." }, { "item_md": "**[Permit protocols](/category/permit/)** — Category index for `permit` standards." } ], "v05_compiled_md": "---\nid: aipref-content-usage-attachment\ntitle: \"AIPREF Content-Usage Attachment\"\ntier: spec_brief\nlifecycle_status: active_draft\ncategory: permit\nform: http-header\nwire_archetype: crawler_policy\nspec_url: https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt\nlast_checked: 2026-11-06\n---\n\n# AIPREF Content-Usage Attachment\n\n**Category:** [Permit](/category/permit/) (`permit`) · **Form:** HTTP header (`http-header`) · **Last checked:** 2026-11-06\n\n> *This page is about draft-ietf-aipref-attach, the IETF AI Preferences (aipref) working-group Internet-Draft that says where a usage preference is published: in a Content-Usage HTTP response header and in a Content-Usage rule in robots.txt. It is not the [AIPREF vocabulary](/protocols/aipref-vocabulary/) (draft-ietf-aipref-vocab), which defines labels such as train-ai and search. It is not Cloudflare's [Content Signals Policy](/protocols/cloudflare-content-signals-policy/), which uses its own Content-Signal line with the signals search, ai-input, and ai-train; not the W3C community group's [TDMRep](/protocols/tdmrep/); and not [AI crawler user-agent tokens in robots.txt](/protocols/ai-crawler-tokens-robots/), which allow or block named crawlers rather than state a use preference. Each has its own page. [1][2][3][4][5][6][7]*\n\n**AIPREF Content-Usage Attachment** is the IETF Internet-Draft `draft-ietf-aipref-attach`, which defines `Content-Usage` attachment methods for usage preferences using the Robots Exclusion Protocol and HTTP header fields. [1] The example response carries `Content-Usage: train-ai=n` before the message body. The `Content-Usage` field is a structured field dictionary and follows the vocabulary draft's processing rules. A `robots.txt` group can carry the same preference beside `User-Agent: *` and `Allow: /`. [1] If approved, `draft-ietf-aipref-attach` updates RFC 9309 to allow usage preferences in `robots.txt`. Datatracker history records that revision 04 expired on `2026-05-01` and that revision 05 was posted on `2026-08-18`. The text is dated 19 August 2026 and expires on 20 February 2027. [1][8]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Permit](/category/permit/) (`permit`) |\n| **Form** | HTTP header (`http-header`) |\n| **Originated by** | Gary Illyes (Google) and Martin Thomson (Mozilla). Individual draft `draft-it-aipref-attachment-00` is dated 28 May 2025. Working-group `-00` was approved on 2025-06-15. [1][8][9][10] |\n| **Governed by** | IETF AI Preferences (aipref) working group. Chairs Mark Nottingham and Suresh Krishnan; Area Director Mike Bishop. Discussion is on ai-control@ietf.org. The source repository is ietf-wg-aipref/drafts. [1][2] |\n| **Track** | IETF; intended status Standards Track [1][10] |\n| **IETF tracker** | [draft-ietf-aipref-attach](https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/) [1][10] |\n| **Status** | Active Internet-Draft (aipref WG Document; intended status Proposed Standard; no WG RFCs published yet). Revision -05 is dated 19 August 2026 and expires 20 February 2027. A 2-week working-group last call on -03 started 4 September 2025 and returned to WG Document on 2025-11-03; -04 expired 2026-05-01 and -05 was posted 2026-08-18. [1][2][8][10][11][12][13][14][15] |\n| **Version** | `draft-ietf-aipref-attach-05`, dated 19 August 2026 (Datatracker revision 05). [1][12] |\n| **Headers** | `Content-Usage` HTTP response header. The draft's example is `Content-Usage: train-ai=n`. [1] |\n| **Message format** | Structured field dictionary, following the vocabulary draft's processing rules. [1] |\n| **IANA registration** | Requested Field Name `Content-Usage`, Status permanent, Structured Type Dictionary. The fetched IANA HTTP Field Name Registry was last updated 2026-10-09 and does not contain a Content-Usage entry. [1][16] |\n| **Specification** | [Associating AI Usage Preferences with Content in HTTP](https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt) (`draft-ietf-aipref-attach-05`) [1] |\n| **Found at** | A `Content-Usage` rule inside a robots.txt group, and a `Content-Usage` HTTP response header. The working-group editor's copy is the GitHub Pages HTML for the attachment draft. [1][17] |\n| **Licence** | Copyright 2026 IETF Trust and the document authors. Code components extracted from the draft must include Revised BSD License text (Trust Legal Provisions Section 4.e). [1] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [Adoption and ecosystem](#adoption-and-ecosystem)\n4. [See also](#see-also)\n5. [References](#references)\n\n---\n\n## Problem and scope\n\nThe `Allow` and `Disallow` rules determine what resources can be crawled. This creates a two-stage arrangement that distinguishes acquisition and usage: acquisition relies on `Allow/Disallow` rules, and usage preference relies on `Content-Usage` rules. [1] `draft-ietf-aipref-attach` only defines how the strings or byte sequences are conveyed so that statements of preference can be associated with content. `draft-ietf-aipref-vocab` defines a vocabulary for expressing preferences regarding how digital assets are used by automated processing systems. [1][3] The `Content-Usage` field does not have any special effect on caching. Usage preferences apply only to those resources that can be crawled according to `Allow/Disallow` rules; no preferences are implied for resources that are disallowed. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **robots.txt (RFC 9309)** | `RFC 9309` | Profiles classic standard | draft-ietf-aipref-attach adds a Content-Usage rule, such as Content-Usage: train-ai=n, inside a robots.txt group and says it updates RFC 9309 so the group can carry usage preferences as well as Allow and Disallow. [1][7] |\n| **HTTP Semantics (RFC 9110)** | `RFC 9110` | Analogous to classic standard | draft-ietf-aipref-attach defines a Content-Usage HTTP response header, with an example of Content-Usage: train-ai=n, and requests permanent registration of Field Name Content-Usage in the HTTP Field Name registry established in Section 18.4 of HTTP (RFC 9110). The IANA registry text fetched with this page was last updated 2026-10-09 and does not contain a Content-Usage entry. [1][16] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[AIPREF Vocabulary (A Vocabulary For Expressing AI Usage Preferences)](/protocols/aipref-vocabulary/)** | Builds on | The attachment draft places vocabulary tokens such as train-ai and search on the wire, and the vocabulary draft itself defines those tokens with no robots.txt rule or HTTP header. [1][3] |\n| **[AI crawler tokens in robots.txt](/protocols/ai-crawler-tokens-robots/)** | Complements | Content-Usage is an additional rule inside a user-agent group, such as train-ai=n, while AI crawler tokens are the User-agent product tokens that select the group. [1][6][7] |\n| **[Content Signals Policy](/protocols/cloudflare-content-signals-policy/)** | Peer alternative | Content-Usage carries tokens such as train-ai=n in a robots.txt rule and in a Content-Usage HTTP header, while Content-Signal carries search, ai-input, and ai-train only as a robots.txt directive inside a User-agent group. [1][4] |\n| **[TDMRep (TDM Reservation Protocol)](/protocols/tdmrep/)** | Peer alternative | Content-Usage is a robots.txt rule plus a response header carrying tokens such as train-ai=n, while TDMRep uses /.well-known/tdmrep.json, tdm-reservation set to 1, tdm-policy, HTML meta, and EPUB or PDF metadata. [1][5] |\n| **[ai.txt](/protocols/ai-txt/)** | Peer alternative | Content-Usage extends /robots.txt and the HTTP response with tokens such as train-ai=n, while ai.txt is a separate file at /ai.txt or /.well-known/ai.txt with Training, Scraping, Indexing, and Caching. [1][18][19] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (12 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Origins serving `Content-Usage` in `robots.txt` or HTTP headers\n\n| Actor | Role | Status | Attachment surface, observed statement & vocabulary fit | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **SpinXO** | Publisher | Live (HTTP 200) · checked 2026-10-30 | Both surfaces serve the same statement. In robots.txt the `User-agent: *` group carries `Content-Usage: train-ai=y, search=y` under the comment that this is the AI usage preference (draft-ietf-aipref-attach), and the same line is repeated on later crawler groups. The home page responds with the header `content-usage: train-ai=y, search=y`. Vocab-08 Table 1 maps AI Training to `train-ai` (Section 4.1) and Search to `search` (Section 4.3). | [spinxo.com/robots.txt](https://www.spinxo.com/robots.txt) [20] · [spinxo.com response headers](https://www.spinxo.com/) [21] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **Launchpad** | Publisher | Live (HTTP 200) · checked 2026-10-30 | robots.txt on launchpad.net, bugs.launchpad.net, code.launchpad.net, and answers.launchpad.net each serves `Content-Usage: ai=n` in the `User-agent: *` group, with the comment `# Source: https://robotstxt.com/ai` and an adjacent `Content-Signal: ai-train=no, search=yes, ai-input=no`. The label ai is not a vocab-08 Table 1 label (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored. | [launchpad.net/robots.txt](https://launchpad.net/robots.txt) [22] · [bugs.launchpad.net/robots.txt](https://bugs.launchpad.net/robots.txt) [23] · [code.launchpad.net/robots.txt](https://code.launchpad.net/robots.txt) [24] · [answers.launchpad.net/robots.txt](https://answers.launchpad.net/robots.txt) [25] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **Ubuntu Changelogs** | Publisher | Live (HTTP 200) · checked 2026-10-30 | robots.txt serves `Content-Usage: ai=n` in the `User-Agent: *` group, with the comment `# Source: https://robotstxt.com/ai`. This file has no Content-Signal line. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored. | [changelogs.ubuntu.com/robots.txt](https://changelogs.ubuntu.com/robots.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **They Said So** | Publisher | Live (HTTP 200) · checked 2026-10-30 | robots.txt serves `Content-Usage: ai=n` in the `User-Agent: *` group, beside `Content-Signal: search=yes, ai-input=no, ai-train=no`, with the comment `# Source: https://robotstxt.com/ai`. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored. | [theysaidso.com/robots.txt](https://theysaidso.com/robots.txt) [27] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **follow.it** | Publisher | Live (HTTP 200) · checked 2026-10-30 | robots.txt is marked `# START nuxt-robots (indexable)`. The `User-agent: *` group serves `Content-Usage: bots=y, train-ai=n` and `Content-Signal: ai-train=no, search=yes`. `bots` is not a vocab-08 Table 1 label (`train-ai`, `ai-use`, `search`), and any unknown labels MUST be ignored. The label that remains, `train-ai`, is the Table 1 label for AI Training. | [follow.it/robots.txt](https://follow.it/robots.txt) [28] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **Gazzetta del Sud** | Publisher | Live (HTTP 200) · checked 2026-10-30 | robots.txt serves `Content-Usage: ai=n` in the `User-Agent: *` group, with the comment `# Source: https://robotstxt.com/ai`. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored. | [gazzettadelsud.it/robots.txt](https://gazzettadelsud.it/robots.txt) [29] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **dri.es** | Publisher | Live (HTTP 200) · checked 2026-10-30 | The home-page response carries the header `content-usage: ai=y` beside `content-signal: ai-train=yes, search=yes, ai-input=yes`. The label ai is not in vocab-08 Table 1 (`train-ai`, `ai-use`, `search`); any unknown labels MUST be ignored. | [dri.es response headers](https://dri.es/) [30] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [3] |\n| **blamejs** | Middleware | Development · checked 2026-11-06 | Documents support for the IETF AIPREF `Content-Usage` HTTP response header (citing `draft-ietf-aipref-attach-04` and the WG's `2026-08` milestone target), the matching robots.txt grammar, and Cloudflare Content Signals plus Pay-Per-Crawl (HTTP 402). Operators declare train / infer / snippet preferences once; the middleware emits both the `Content-Usage` header and `CF-Content-Signals`. | [blamejs AI preferences](https://blamejs.com/ai-pref) [31] |\n\n### Generators, parsers, platforms & crawler specifications\n\n| Actor | Role | Status | Coverage, behavior & specification status | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Nuxt Robots** | Generator | Supported · as of 2026-07-16 | The AI Directives guide, last updated Jul 16, 2026, says two standards are supported and names `Content-Usage` as the IETF one. It says the Content-Usage directive follows the IETF AI Preferences specification. One documented example is `Content-Usage: bots=y, train-ai=n`, the same line follow.it serves inside `# START nuxt-robots (indexable)`. | [Nuxt Robots AI Directives](https://nuxtseo.com/docs/robots/guides/ai-directives) [32] · [follow.it/robots.txt](https://follow.it/robots.txt) [28] |\n| **PEAC Protocol** | Parser | Partial · as of 2026-06-01 | Coverage is the Content-Usage HTTP header, identified on the page with `draft-ietf-aipref-attach-04` and Structured Fields per `RFC 9651`. The page says the `Content-Usage` header is parsed as an RFC 9651 Structured Fields Dictionary, and that PEAC records these signals as evidence but does not enforce them. Page `dateModified` is 2026-06-01. | [PEAC Content Signals](https://www.peacprotocol.org/integrations/content-signals) [33] |\n| **Cloudflare Content Signals Policy** | Platform | Development · as of 2026-09-15 | Michael Tremante's note of 24 September 2025 on Cloudflare's Content Signal Policy calls the policy an interim measure and says they will revisit the policy once the working group reaches a consensus position. Bryan Becker's post of September 15, 2026 says that as standards such as `ai-prefs` mature, they will revisit this approach (`datePublished` 2026-09-15). The same day's press release calls `ai-prefs` a specification under development and says today's controls are designed to work alongside these emerging standards. | [ai-control, Tremante, 24 September 2025](https://mailarchive.ietf.org/arch/msg/ai-control/EANb9b9bljOanLBFm5FRerYlxyI/) [34] · [Have it both ways (Becker)](https://blog.cloudflare.com/accountable-mixed-use-ai-crawlers/) [35] · [Press release, September 15, 2026](https://www.cloudflare.com/press/press-releases/2026/cloudflare-helps-end-the-search-or-ai-training-tradeoff/) [36] |\n| **Google robots.txt specification** | Crawler operator | Does not request · as of 2026-10-23 | Last updated 2026-10-23 UTC. Google supports the fields `user-agent`, `allow`, `disallow`, and `sitemap`, and says other fields such as `crawl-delay` aren't supported. Google's specification page does not name Content-Usage. | [How Google interprets the robots.txt specification](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec) [37] |\n\n### Ecosystem censuses\n\n- **IETF Datatracker documents API (group aipref, type rfc)** (*as of 2026-10-30*): 0 published RFCs in the IETF Datatracker for the `aipref` working group. [11]\n\n---\n\n## See also\n\n- **[Really Simple Licensing](/protocols/rsl/)** *(Complements)* — AIPREF puts Content-Usage in robots.txt and an HTTP header. RSL points a License URI or Link header at XML.\n- **Category:** [Permit protocols](/category/permit/)\n\n---\n\n## References\n\n1. Gary Illyes (Google) and Martin Thomson (Mozilla), *Associating AI Usage Preferences with Content in HTTP (draft-ietf-aipref-attach-05)* (dated 2026-08-19) — \n2. IETF, *AI Preferences (aipref) working group* (fetched 2026-10-30) — \n3. Paul Keller (Open Future) and Martin Thomson (Mozilla, editor), *A Vocabulary For Expressing AI Usage Preferences (draft-ietf-aipref-vocab-08)* (dated 2026-09-14) — \n4. Will Allen (Cloudflare), *Giving users choice with Cloudflare's new Content Signals Policy* (published 2025-09-24; modified 2026-07-15) — \n5. Laurent Le Meur (EDRLab), *TDM Reservation Protocol (TDMRep)* (Final Community Group Report 2024-05-10) — \n6. OpenAI, *Overview of OpenAI Crawlers* (fetched 2026-10-30) — \n7. M. Koster, G. Illyes, H. Zeller, and L. Sassman, *Robots Exclusion Protocol* (RFC 9309, September 2022) — \n8. IETF Datatracker, *draft-ietf-aipref-attach — History (IETF Datatracker)* (fetched 2026-10-30) — \n9. Gary Illyes (Google) and Martin Thomson (Mozilla), *Indicating Preferences Regarding Content Usage (draft-it-aipref-attachment-00)* (dated 2025-05-28) — \n10. IETF Datatracker, *draft-ietf-aipref-attach — Associating AI Usage Preferences with Content in HTTP (IETF Datatracker)* (last updated 2026-08-18) — \n11. IETF Datatracker API, *RFC documents in the aipref working group* (fetched 2026-10-30) — \n12. IETF Datatracker API, *IETF Datatracker document record for draft-ietf-aipref-attach* (rev 05 at 2026-08-19) — \n13. Mark Nottingham via Datatracker, *WG Last Call: draft-ietf-aipref-attach-03 (Ends 2025-09-18)* (2025-09-04) — \n14. IETF Datatracker, *AI Preferences (aipref) working group history* (fetched 2026-10-30) — \n15. IETF, *Enabling Publishers to Express Preferences for AI Crawlers: An Update on the AIPREF Working Group* (2025-10-30) — \n16. IANA, *Hypertext Transfer Protocol (HTTP) Field Name Registry* (last updated 2026-10-09) — \n17. IETF AI Preferences working group, *Associating AI Usage Preferences with Content in HTTP* (fetched 2026-10-30) — \n18. Cullen Miller (Spawning), *ai.txt: A new way for websites to set permissions for AI* (published 2023-05-30) — \n19. Kayla Cardillo, *draft-car-ai-txt-wellknown-00* (fetched 2026-10-30) — \n20. SpinXO, *robots.txt* (fetched 2026-10-30) — \n21. SpinXO, *SpinXO home page response headers* (fetched 2026-10-30) — \n22. Launchpad, *robots.txt* (fetched 2026-10-30) — \n23. Launchpad, *bugs.launchpad.net robots.txt* (fetched 2026-10-30) — \n24. Launchpad, *code.launchpad.net robots.txt* (fetched 2026-10-30) — \n25. Launchpad, *answers.launchpad.net robots.txt* (fetched 2026-10-30) — \n26. Ubuntu, *changelogs.ubuntu.com robots.txt* (fetched 2026-10-30) — \n27. They Said So, *robots.txt* (fetched 2026-10-30) — \n28. Follow.it Feed Service, *robots.txt* (fetched 2026-10-30) — \n29. Gazzetta del Sud, *robots.txt* (fetched 2026-10-30) — \n30. Dries Buytaert, *dri.es home page response headers* (fetched 2026-10-30) — \n31. blamejs, *Ai Pref, blamejs* (2026-11-06) — \n32. Harlan Wilton (Nuxt SEO), *AI Directives* (last updated 2026-07-16) — \n33. PEAC Protocol, *Content Signals* (fetched 2026-10-30) — \n34. Michael Tremante, *Cloudflare's Content Signal Policy* (2025-09-24) — \n35. Bryan Becker (Cloudflare), *Have it both ways: stay discoverable in search while disallowing AI training* (published 2026-09-15) — \n36. Cloudflare, *Cloudflare Helps End the Search-or-AI-Training Tradeoff* (2026-09-15) — \n37. Google, *How Google Interprets the robots.txt Specification* (last updated 2026-10-23) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "AIPREF", "adoption": { "level": "observed", "by": "SpinXO, Launchpad, Ubuntu Changelogs, They Said So, and Cloudflare Content Signals Policy", "probe_run": null }, "aliases": [], "analog": "Controlled metadata vocabulary (like Dublin Core terms)", "collisions": [], "discovery": { "mechanism": "Nowhere by itself: the charter asks for the vocabulary \"A standard track document covering vocabulary for expressing AI-related preferences, independent of how those preferences are associated with content.\" The attachment draft (draft-ietf-aipref-attach-05, 19 August 2026, by G. Illyes of Google and M. Thomson of Mozilla) defines a Content-Usage robots.txt rule and a Content-Usage HTTP header field: \"Methods are defined for associating usage preferences with content that is obtained using the HTTP protocol. This document defines attachment methods using the Robots Exclusion Protocol and HTTP header fields.\" \"This document updates RFC 9309 to allow for the inclusion of usage preferences.\" Revision -04 of that draft expired on 2026-05-01 and was revived with -05", "path": null }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt", "claim": "P. Keller (Open Future) and M. Thomson, Ed. (Mozilla), *A Vocabulary For Expressing AI Usage Preferences (draft-ietf-aipref-vocab-08)*, 14 September 2026", "date": null, "quote": "This document defines a vocabulary for expressing preferences regarding how digital assets are used by automated processing systems. / 4.1. AI Training Using an asset to modify the learned parameters of a generative AI model. / 4.2. AI Use Using an asset as input to a generative AI model, where the asset is not directly provided by the user. / 4.3. Search Using an asset in an application where the primary purpose of the application is to select assets and direct users to the location of those assets. / This process results in one of three potential answers: allow, disallow, and unknown. / A Vocabulary For Expressing AI Usage Preferences / The format relies on the Dictionary type defined in Section 3.2 of [FIELDS]. ... For example, the following states a preference to allow model training (Section 4.1), disallow search (Section 4.3), with the preference for other categories being unknown: ... train-ai=y, search=n / The format defined in this document is only an exemplary way to represent preferences. The data model described in Section 3 can be used without this serialization. / Its contents DO NOT REFLECT CONSENSUS of the Working Group either in whole or part. / P. Keller / Open Future / M. Thomson, Ed. / 14 September 2026 / draft-ietf-aipref-vocab-08 / Source for this draft and an issue tracker can be found at https://github.com/ietf-wg-aipref/drafts. / Intended status: Standards Track / Expires: 18 March 2027 / The format relies on the Dictionary type defined in Section 3.2 of [FIELDS]. / The format defined in this document is only an exemplary way to represent preferences. / | AI Training | train-ai | Section 4.1 | / | AI Use | ai-use | Section 4.2 | / | Search | search | Section 4.3 | / These are mapped to single byte Tokens (Section 3.3.4 of [FIELDS]) of y and n, respectively. / train-ai=y, search=n / This document has no IANA actions. / The data model described in Section 3 can be used without this serialization. / Copyright (c) 2026 IETF Trust and the persons identified as the document authors. / This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents / Code Components extracted from this document must include Revised BSD License text / If any statement of preference indicates that the usage is disallowed, the result is that the usage is disallowed. ... This process ensures that the most restrictive preference applies. / This category does not include the use of assets to generate summaries. ... Allowed processing therefore includes the training of AI models using the assets and the use of those models provided that the resulting models and their outputs are used exclusively in ways that meet the above conditions regarding referencing and excerpts. ... This category of use overrides any usage that falls into other categories, including AI Training (Section 4.1) and AI Use (Section 4.2). / An entity that receives usage preferences has a choice whether to follow those preferences. / should understand that it does not: ... ensure that preferences are followed ... Preferences are not a security mechanism. / The vocabulary is intended to be used in jurisdictions where expressing preferences results in legal obligations, as well as where there are no associated legal obligations. / expressing preferences is without prejudice to applicable laws, including the applicability of exceptions and limitations to copyright. / address technical, legal, contractual, or other mechanisms that might create a stronger requirement to follow or not follow preferences / of y and n, respectively. / Table 1: Mappings for Categories", "ref": 1 }, { "label": "[2]", "url": "https://datatracker.ietf.org/wg/aipref/about/", "claim": "IETF Datatracker, *AI Preferences (aipref) working group*, charter charter-ietf-aipref-01 Approved", "date": null, "quote": "A standard track document covering vocabulary for expressing AI-related preferences, independent of how those preferences are associated with content. / Web and Internet Transport (wit) / State | | Active / charter-ietf-aipref-01 Approved / Mark Nottingham, Suresh Krishnan / Area Director | | Mike Bishop / ai-control@ietf.org / The AI Preferences Working Group will standardize building blocks / 2026-08-31Aug 2026 / Aug 2026 A standard track specification describing vocabulary for expressing AI-related preferences to the IESG for publication / independent of how those preferences are associated with content. / The following topics are out of scope for this charter: Technical enforcement of preferences", "ref": 2 }, { "label": "[3]", "url": "https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt", "claim": "G. Illyes (Google) and M. Thomson (Mozilla), *Associating AI Usage Preferences with Content in HTTP (draft-ietf-aipref-attach-05)*, 19 August 2026", "date": null, "quote": "The Content-Usage field is a structured field dictionary, as defined in Section 3.2 of [FIELDS]. / This document defines attachment methods using the Robots Exclusion Protocol and HTTP header fields. / This document updates RFC 9309 to allow for the inclusion of usage preferences. / draft-ietf-aipref-attach-05 / G. Illyes / 19 August 2026 / Associating AI Usage Preferences with Content in HTTP / This field follows the vocabulary and processing rules in [VOCAB]. / Content-Usage: train-ai=n", "ref": 3 }, { "label": "[4]", "url": "https://www.rfc-editor.org/rfc/rfc9309.html", "claim": "M. Koster, G. Illyes, H. Zeller, and L. Sassman, *Robots Exclusion Protocol*, RFC 9309, September 2022", "date": null, "quote": "This document specifies and extends the \"Robots Exclusion Protocol\" method / September 2022 / Robots Exclusion Protocol / The product token MUST contain only uppercase and lowercase letters / The \"Allow\" and \"Disallow\" Lines", "ref": 4 }, { "label": "[5]", "url": "https://blog.cloudflare.com/content-signals-policy/", "claim": "Will Allen, Cloudflare Blog, *Giving users choice with Cloudflare's new Content Signals Policy*, published 2025-09-24; modified 2026-07-15", "date": null, "quote": "This policy defines three content signals - search, ai-input, and ai-train - and their relevance to crawlers. / Will Allen / September 24, 2025 / Giving users choice with Cloudflare's new Content Signals Policy", "ref": 5 }, { "label": "[6]", "url": "https://rslstandard.org/rsl", "claim": "RSL Technical Steering Committee, *Really Simple Licensing (RSL) 1.0 Specification*, published 2025-12-10", "date": null, "quote": "Really Simple Licensing (RSL) 1.0 Specification / ODRL Information Model 2.2 / February 2018 / Published 2025-12-10 / The media type associated with RSL documents is: application/rsl+xml / An RSL document, also called a license, defines machine-readable licensing terms / prohibits any use by AI systems, including model training or reuse of the content in grounding, retrieval, or generative search summaries. / ai-all / The element states the price in euros / 49.00", "ref": 6 }, { "label": "[7]", "url": "https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/", "claim": "Laurent Le Meur (EDRLab), W3C TDMRep Community Group, *TDM Reservation Protocol (TDMRep)*, Final Community Group Report, 10 May 2024", "date": null, "quote": "TDM Reservation Protocol (TDMRep) / profile of the Open Digital Rights Language 2.2 / Final Community Group Report 10 May 2024 / Laurent Le Meur / EDRLab / tdm-reservation is an boolean value. / 1 TDM rights are reserved. / tdm-policy: an optional TDM Policy value associated with the current pattern.", "ref": 7 }, { "label": "[8]", "url": "https://datatracker.ietf.org/api/v1/doc/newrevisiondocevent/?doc__name=draft-ietf-aipref-vocab&format=json&limit=50", "claim": "IETF Datatracker API, *New-revision events for draft-ietf-aipref-vocab*, nine revisions; -08 published 2026-09-14", "date": null, "quote": "New version available: draft-ietf-aipref-vocab-08.txt ... \"time\": \"2026-09-14T06:18:02Z\" / New version available: draft-ietf-aipref-vocab-08.txt", "ref": 8 }, { "label": "[9]", "url": "https://datatracker.ietf.org/doc/draft-keller-aipref-vocab/", "claim": "IETF Datatracker, *draft-keller-aipref-vocab — Proposal for an Opt-Out Vocabulary (IETF Datatracker)*, latest revision 2025-03-30; last updated 2025-04-10", "date": null, "quote": "P. Keller Internet-Draft Open Future / Author | | Paul Keller / Last updated | 2025-04-10 (Latest revision 2025-03-30) / Replaced by | | draft-ietf-aipref-vocab", "ref": 9 }, { "label": "[10]", "url": "https://mailarchive.ietf.org/arch/msg/ai-control/LuWDC12gjlQ6Yj5eKN7ZkgbxopA/", "claim": "Mark Nottingham, *[ai-control] Adoption of draft-keller-aipref-vocab-01*, 26 April 2025", "date": null, "quote": "Sat, 26 April 2025 / Mark Nottingham / rough consensus to adopt draft-keller-aipref-vocab-01 as the starting point of our vocabulary work. / we appoint Paul Keller and Martin Thomson as editors.", "ref": 10 }, { "label": "[11]", "url": "https://github.com/ietf-wg-aipref/drafts", "claim": "IETF AI Preferences (aipref) working group, *AIPREF working drafts*, fetched 2026-10-30", "date": null, "quote": "AIPREF working drafts", "ref": 11 }, { "label": "[12]", "url": "https://datatracker.ietf.org/wg/aipref/history/", "claim": "IETF Datatracker, *aipref working group history*, charter approved 2025-01-07", "date": null, "quote": "2024-11-19 | Zaheduzzaman Sarker | Group created in state Proposed / 2025-01-07 | Cindy Morgan | Charter approved, group active / Changed milestone \"A standard track specification describing vocabulary for expressing AI-related preferences to the IESG for publication\", set due date to August 2026 from August 2025 / 2025-09-23 | Mike Bishop | Changed milestone", "ref": 12 }, { "label": "[13]", "url": "https://datatracker.ietf.org/doc/draft-ietf-aipref-vocab/", "claim": "IETF Datatracker, *draft-ietf-aipref-vocab — A Vocabulary For Expressing AI Usage Preferences (IETF Datatracker)*, last updated 2026-09-13", "date": null, "quote": "Intended RFC status | | Proposed Standard / Active Internet-Draft (aipref WG) / Paul Keller, Martin Thomson / Last updated 2026-09-13 / Replaces draft-keller-aipref-vocab / WG state | | WG Document / IESG state | | I-D Exists / Document shepherd | | (None)", "ref": 13 }, { "label": "[14]", "url": "https://datatracker.ietf.org/api/v1/doc/document/?group__acronym=aipref&type=rfc&format=json", "claim": "IETF Datatracker API, *RFC documents in group aipref*, fetched 2026-10-30", "date": null, "quote": "\"total_count\": 0", "ref": 14 }, { "label": "[15]", "url": "https://datatracker.ietf.org/doc/draft-ietf-aipref-vocab/history/", "claim": "IETF Datatracker, *draft-ietf-aipref-vocab history*, history through the -08 posting on 2026-09-13", "date": null, "quote": "2025-09-04 | 03 | Mark Nottingham | IETF WG state changed to In WG Last Call from WG Document / 2025-11-03 | 04 | Mark Nottingham | IETF WG state changed to WG Document from In WG Last Call / 2026-09-13 | 08 | Martin Thomson | New version available: draft-ietf-aipref-vocab-08.txt / 2025-04-30 | 00 | Mark Nottingham | WG -00 approved", "ref": 15 }, { "label": "[16]", "url": "https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-aipref-vocab/?format=json", "claim": "IETF Datatracker API, *IETF Datatracker document record for draft-ietf-aipref-vocab*, rev 08; time 2026-09-14", "date": null, "quote": "\"rev\": \"08\" / \"time\": \"2026-09-14T06:18:02Z\" / \"expires\": \"2027-03-18T06:18:02Z\" / \"title\": \"A Vocabulary For Expressing AI Usage Preferences\"", "ref": 16 }, { "label": "[17]", "url": "https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/history/", "claim": "IETF Datatracker, *draft-ietf-aipref-attach history*, -04 expired 2026-05-01; -05 posted 2026-08-18", "date": null, "quote": "2026-05-01 | 04 | (System) | Document has expired / 2026-08-18 | 05 | Martin Thomson | New version available: draft-ietf-aipref-attach-05.txt", "ref": 17 }, { "label": "[18]", "url": "https://ietf-wg-aipref.github.io/drafts/draft-ietf-aipref-vocab.html", "claim": "IETF AI Preferences (aipref) working group, *A Vocabulary For Expressing AI Usage Preferences (editor's copy)*, 14 September 2026", "date": null, "quote": "A Vocabulary For Expressing AI Usage Preferences", "ref": 18 }, { "label": "[19]", "url": "https://developers.openai.com/api/docs/bots", "claim": "OpenAI, *Overview of OpenAI Crawlers*, fetched 2026-10-30", "date": null, "quote": "Overview of OpenAI Crawlers / OpenAI uses OAI-SearchBot and GPTBot robots.txt tags to enable webmasters to manage how their sites and content work with AI.", "ref": 19 }, { "label": "[20]", "url": "https://www.spinxo.com/robots.txt", "claim": "SpinXO, *robots.txt*, fetched 2026-10-30", "date": null, "quote": "AI usage preference (draft-ietf-aipref-attach). / Content-Usage: train-ai=y, search=y", "ref": 20 }, { "label": "[21]", "url": "https://www.spinxo.com/", "claim": "SpinXO, *SpinXO home page*, response last-modified Fri, 30 Oct 2026", "date": null, "quote": "content-usage: train-ai=y, search=y", "ref": 21 }, { "label": "[22]", "url": "https://launchpad.net/robots.txt", "claim": "Canonical (Launchpad), *robots.txt*, fetched 2026-10-30", "date": null, "quote": "# Source: https://robotstxt.com/ai / User-agent: * / Content-Usage: ai=n / Content-Signal: ai-train=no, search=yes, ai-input=no", "ref": 22 }, { "label": "[23]", "url": "https://bugs.launchpad.net/robots.txt", "claim": "Canonical (Launchpad), *robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: ai=n", "ref": 23 }, { "label": "[24]", "url": "https://code.launchpad.net/robots.txt", "claim": "Canonical (Launchpad), *robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: ai=n", "ref": 24 }, { "label": "[25]", "url": "https://answers.launchpad.net/robots.txt", "claim": "Canonical (Launchpad), *robots.txt*, fetched 2026-10-30", "date": null, "quote": "Content-Usage: ai=n", "ref": 25 }, { "label": "[26]", "url": "https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt", "claim": "P. Keller (Open Future) and M. Thomson, Ed. (Mozilla), *A Vocabulary For Expressing AI Usage Preferences (draft-ietf-aipref-vocab-01)*, 19 June 2025", "date": null, "quote": "draft-ietf-aipref-vocab-01 / | AI Training | ai | Section 4.2 |", "ref": 26 }, { "label": "[27]", "url": "https://changelogs.ubuntu.com/robots.txt", "claim": "Canonical (Ubuntu), *robots.txt*, response dated Fri, 30 Oct 2026", "date": null, "quote": "# Source: https://robotstxt.com/ai / User-Agent: * / Content-Usage: ai=n / server: nginx/1.14.0 (Ubuntu)", "ref": 27 }, { "label": "[28]", "url": "https://theysaidso.com/robots.txt", "claim": "They Said So, *robots.txt*, response dated Fri, 30 Oct 2026", "date": null, "quote": "# Source: https://robotstxt.com/ai / User-Agent: * / Content-Usage: ai=n / Content-Signal: search=yes, ai-input=no, ai-train=no", "ref": 28 }, { "label": "[29]", "url": "https://datatracker.ietf.org/doc/html/draft-romm-aipref-contentsignals-00", "claim": "M. Tremante (Cloudflare) and L. Romm, *Vocabulary For Expressing Content Signals (draft-romm-aipref-contentsignals-00 HTML)*, 1 October 2025", "date": null, "quote": "draft-romm-aipref-contentsignals-00 / Table 1: Usage category labels / | Search | search | Section 3.1 | / | AI Input | ai-input | Section 3.2 | / | AI Training | ai-train | Section 3.3 |", "ref": 29 }, { "label": "[30]", "url": "https://mailarchive.ietf.org/arch/msg/ai-control/EANb9b9bljOanLBFm5FRerYlxyI/", "claim": "Michael Tremante, *Cloudflare's Content Signal Policy*, 24 September 2025", "date": null, "quote": "Cloudflare's Content Signal Policy / Michael Tremante / We see this as an interim measure to address immediate needs, while work is done towards standardization. / will revisit our policy once that has happened", "ref": 30 }, { "label": "[31]", "url": "https://blog.cloudflare.com/accountable-mixed-use-ai-crawlers/", "claim": "Bryan Becker, Cloudflare Blog, *Have it both ways: stay discoverable in search while disallowing AI training*, published 2026-09-15", "date": null, "quote": "Bryan Becker / As standards such as ai-prefs mature, we will revisit this approach.", "ref": 31 }, { "label": "[32]", "url": "https://www.cloudflare.com/press/press-releases/2026/cloudflare-helps-end-the-search-or-ai-training-tradeoff/", "claim": "Cloudflare, *Cloudflare Helps End the Search-or-AI-Training Tradeoff*, 15 September 2026", "date": null, "quote": "September 15, 2026 / Today's controls are designed to work alongside these emerging standards.", "ref": 32 }, { "label": "[33]", "url": "https://aicrawlercheck.com/blog/ietf-aipref-content-usage-robots-txt", "claim": "Scout Agent, AI Crawler Check, *Content-Usage robots.txt: IETF AIPREF Explained (2026)*, published 2026-10-18", "date": null, "quote": "Do AI companies honour Content-Usage today? / No major AI company has said publicly that its crawler reads Content-Usage yet / 2026-10-18", "ref": 33 } ], "form": "document-format", "governance": "IETF AI Preferences (aipref) working group: \"Area Web and Internet Transport (wit) State Active Charter charter-ietf-aipref-01 Approved\" \"Chairs Mark Nottingham, Suresh Krishnan Area Director Mike Bishop\". The group was created on 2024-11-19 and its charter approved on 2025-01-07: \"2025-01-07 Cindy Morgan Charter approved, group active\". Work happens on the ai-control@ietf.org list and in the GitHub repository ietf-wg-aipref/drafts", "group": "AIPREF", "history": [ { "date": "2026-09-06", "note": "verified against datatracker.ietf.org/doc/html/draft-ietf-aipref-vocab-07" }, { "date": "2026-10-16", "note": "revision draft-ietf-aipref-vocab-07 → 08" }, { "date": "2026-11-12", "note": "Completed v0.5 primary-source specification, protocol-graph, and ecosystem adoption pass." } ], "id": "aipref-vocabulary", "implementation": "prototype", "last_verified": "2026-10-31", "name": "AIPREF Vocabulary (A Vocabulary For Expressing AI Usage Preferences)", "native_status": "Active Internet-Draft, not an RFC: \"Document Type Active Internet-Draft (aipref WG) Authors Paul Keller, Martin Thomson\" \"WG state WG Document\" \"IESG state I-D Exists\". The Datatracker API lists no aipref RFC (checked 2026-10-28). The document went into working-group last call on 2025-09-04 and back to WG Document on 2025-11-03: \"Mark Nottingham IETF WG state changed to In WG Last Call from WG Document\"; \"Mark Nottingham IETF WG state changed to WG Document from In WG Last Call\". The -08 text says \"Its contents DO NOT REFLECT CONSENSUS of the Working Group either in whole or part. Presense or absense of any particular text does not indicate consensus, and this document is published solely as a basis of further discussion.\". The charter milestone was \"2026-08-31 Aug 2026 A standard track specification describing vocabulary for expressing AI-related preferences to the IESG for publication draft-ietf-aipref-vocab\", moved there on 2025-09-23 from August 2025; on 2026-10-28 the draft had not been sent to the IESG", "origin": { "org": "Paul Keller (Open Future) as draft-keller-aipref-vocab", "date": "2025-03-30" }, "part_of": null, "parties": [ "agent-site" ], "phase": "working-group", "probe": { "method": "GET", "on_absent": "No AIPREF-vocabulary token found in the attachment surface; cannot distinguish 'no preference stated' from 'publisher uses a different vocabulary (e.g. Cloudflare Content Signals)'", "parse": "Parse any Content-Usage directive value against the AIPREF controlled vocabulary tokens defined in this draft", "path": "{origin}/robots.txt" }, "question": "What controlled set of values expresses a publisher's AI-use preferences, independent of how they are attached to content?", "scope": "general", "spec_url": "https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt", "step": "permit", "summary_md": "**A Vocabulary For Expressing AI Usage Preferences** (`draft-ietf-aipref-vocab`) defines a vocabulary for preferences regarding how automated processing systems use digital assets. The exemplary serialization is a Dictionary: `train-ai=y, search=n` allows model training, disallows search, and leaves other categories unknown. The format is only exemplary, and the data model in Section 3 can be used without this serialization. A Datatracker new-revision event names `draft-ietf-aipref-vocab-08` and records `time` `2026-09-14`. The draft states that its contents do not reflect consensus of the working group in whole or in part.", "track": "ietf", "version": { "label": "draft-ietf-aipref-vocab-08", "date": "2026-09-14" }, "watch": [ { "type": "ietf", "doc": "draft-ietf-aipref-vocab" } ], "use_cases": [ "control-ai-crawling" ], "audience": [ "site-owner", "standards-body", "platform" ], "pairs_with": [ "aipref-content-usage-attachment", "cloudflare-content-signals-policy", "tdmrep", "rsl", "ai-crawler-tokens-robots" ], "prerequisites": [], "hatnote_md": "This page is about the vocabulary Internet-Draft of the IETF AI Preferences (aipref) working group, draft-ietf-aipref-vocab, which defines categories of use (AI Training, AI Use, Search) and how a statement of preference allows or disallows each. It does not say where such statements are published: that is the separate working-group draft draft-ietf-aipref-attach, which carries them in a Content-Usage HTTP header field and a Content-Usage rule in robots.txt; see [AIPREF Content-Usage Attachment](/protocols/aipref-content-usage-attachment/). It is not robots.txt (the Robots Exclusion Protocol, RFC 9309) itself, which the attachment draft updates. It is not Cloudflare's Content Signals Policy, which defines its own content signals search, ai-input, and ai-train; see [Content Signals Policy](/protocols/cloudflare-content-signals-policy/). It is also not [Really Simple Licensing (RSL)](/protocols/rsl/) or the [Text and Data Mining Reservation Protocol (TDMRep)](/protocols/tdmrep/), which are separate specifications, or [ai.txt](/protocols/ai-txt/).", "ietf_tracker": { "doc": "draft-ietf-aipref-vocab", "rev": "08", "state": "active", "stream": "IETF", "group_type": "WG", "wg": "aipref", "replaced_by": null, "posted_utc": "2026-09-14", "expires_utc": "2027-03-18", "as_of": "2026-10-31", "source": "https://datatracker.ietf.org/doc/draft-ietf-aipref-vocab/", "source_label": "per IETF Datatracker" }, "tier": "spec_brief", "lifecycle_status": "active_draft", "wire_archetype": "crawler_policy", "freshness": "current", "v05_verified": true, "v05_last_checked_display": "2026-10-31", "v05_hatnote_html_md": "This page is about the vocabulary Internet-Draft of the IETF AI Preferences (aipref) working group, draft-ietf-aipref-vocab, which defines categories of use (AI Training, AI Use, Search) and how a statement of preference allows or disallows each. It does not say where such statements are published: that is the separate working-group draft draft-ietf-aipref-attach, which carries them in a Content-Usage HTTP header field and a Content-Usage rule in robots.txt; see [AIPREF Content-Usage Attachment](/protocols/aipref-content-usage-attachment/). It is not robots.txt (the Robots Exclusion Protocol, RFC 9309) itself, which the attachment draft updates. It is not Cloudflare's Content Signals Policy, which defines its own content signals search, ai-input, and ai-train; see [Content Signals Policy](/protocols/cloudflare-content-signals-policy/). It is also not [Really Simple Licensing (RSL)](/protocols/rsl/) or the [Text and Data Mining Reservation Protocol (TDMRep)](/protocols/tdmrep/), which are separate specifications, or [ai.txt](/protocols/ai-txt/). [1][2][3][4][5][6][7]", "v05_elevator_pitch_md": null, "v05_lead_md": "**A Vocabulary For Expressing AI Usage Preferences** (`draft-ietf-aipref-vocab`) defines a vocabulary for preferences regarding how automated processing systems use digital assets. [1] The exemplary serialization is a Dictionary: `train-ai=y, search=n` allows model training, disallows search, and leaves other categories unknown. The format is only exemplary, and the data model in Section 3 can be used without this serialization. [1] A Datatracker new-revision event names `draft-ietf-aipref-vocab-08` and records `time` `2026-09-14`. The draft states that its contents do not reflect consensus of the working group in whole or in part. [1][8]", "v05_identity_sentence_md": "**A Vocabulary For Expressing AI Usage Preferences** (`draft-ietf-aipref-vocab`) defines a vocabulary for preferences regarding how automated processing systems use digital assets. [1]", "v05_infobox_rows": [ { "label": "Category", "value_md": "[Permit](/category/permit/) (`permit`)" }, { "label": "Form", "value_md": "Document format (`document-format`)" }, { "label": "Originated by", "value_md": "Paul Keller (Open Future), individual draft `draft-keller-aipref-vocab`, latest revision 2025-03-30, replaced by `draft-ietf-aipref-vocab`. On 26 April 2025 the chairs adopted `draft-keller-aipref-vocab-01` and appointed Paul Keller and Martin Thomson as editors. `draft-ietf-aipref-vocab-08` (14 September 2026) lists P. Keller (Open Future) and M. Thomson, Ed. (Mozilla). [1][9][10]" }, { "label": "Governed by", "value_md": "IETF AI Preferences (aipref) working group. Area: Web and Internet Transport (wit). State: Active. Charter: `charter-ietf-aipref-01` Approved. Chairs: Mark Nottingham and Suresh Krishnan. Area Director: Mike Bishop. List: `ai-control@ietf.org`. Drafts: `github.com/ietf-wg-aipref/drafts`. Created in state Proposed on 2024-11-19. Charter approved and group made active on 2025-01-07. [1][2][11][12]" }, { "label": "Track", "value_md": "IETF. Intended status: Standards Track. Datatracker intended RFC status: Proposed Standard. [1][13]" }, { "label": "IETF tracker", "value_md": "[draft-ietf-aipref-vocab](https://datatracker.ietf.org/doc/draft-ietf-aipref-vocab/) · Active Internet-Draft (aipref WG) · authors Paul Keller, Martin Thomson · last updated 2026-09-13 · WG state WG Document · IESG state I-D Exists · replaces `draft-keller-aipref-vocab` [13]" }, { "label": "Status", "value_md": "Active Internet-Draft (aipref WG Document; no document shepherd assigned; no WG RFCs published yet). The -08 text notes its contents do not yet reflect full working-group consensus. Working-group last call started 2025-09-04 and returned to WG Document on 2025-11-03. [1][2][12][13][14][15]" }, { "label": "Version", "value_md": "`draft-ietf-aipref-vocab-08`, header date 14 September 2026, expires 18 March 2027 (posted 2026-09-13; WG -00 approved 2025-04-30; replaces `draft-keller-aipref-vocab`). [1][8][9][13][15][16]" }, { "label": "Message format", "value_md": "Exemplary serialization is a Structured Fields Dictionary. Labels: AI Training `train-ai` (Section 4.1), AI Use `ai-use` (Section 4.2), Search `search` (Section 4.3). Explicit preferences are the tokens `y` and `n`. Example: `train-ai=y, search=n`. [1]" }, { "label": "IANA registration", "value_md": "This document has no IANA actions. [1]" }, { "label": "Specification", "value_md": "[A Vocabulary For Expressing AI Usage Preferences](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) (`draft-ietf-aipref-vocab-08`, 14 September 2026) [1][16]" }, { "label": "Found at", "value_md": "No attachment location in the vocabulary draft: the serialization is exemplary, and the charter keeps the vocabulary independent of how preferences are associated with content. Attachment is [draft-ietf-aipref-attach-05](https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt) (G. Illyes, Google, and M. Thomson, Mozilla, 19 August 2026), which defines a Content-Usage HTTP header and a robots.txt Content-Usage rule and updates RFC 9309. Revision -04 of that draft expired on 2026-05-01 and -05 was posted on 2026-08-18. Editor's copy: [draft-ietf-aipref-vocab.html](https://ietf-wg-aipref.github.io/drafts/draft-ietf-aipref-vocab.html). [1][2][3][17][18]" }, { "label": "Licence", "value_md": "Copyright (c) 2026 IETF Trust and the document authors. Subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents. Code components must include Revised BSD License text. [1]" } ], "v05_problem_md": "The aipref charter asks for a standard track vocabulary for expressing AI-related preferences, independent of how those preferences are associated with content. Technical enforcement of preferences is out of scope for that charter. [2] Evaluating a statement yields `allow`, `disallow`, or `unknown` per category, with any `disallow` winning so the most restrictive preference applies. Under Section 4.3, `Search` permits internal AI model training and model use whose outputs exclusively serve search links and relevance excerpts (excluding generated summaries), overriding `AI Training` (Section 4.1) and `AI Use` (Section 4.2). [1] Recipients choose whether to follow declared preferences: preferences are not a security mechanism, and the specification neither enforces compliance nor alters statutory copyright exceptions, contractual terms, or jurisdictional legal obligations. [1]", "v05_mechanism_delta_md": "Evaluating a statement yields `allow`, `disallow`, or `unknown` per category, with any `disallow` winning so the most restrictive preference applies. Under Section 4.3, `Search` permits internal AI model training and model use whose outputs exclusively serve search links and relevance excerpts (excluding generated summaries), overriding `AI Training` (Section 4.1) and `AI Use` (Section 4.2). [1]", "v05_scope_boundary_md": "Recipients choose whether to follow declared preferences: preferences are not a security mechanism, and the specification neither enforces compliance nor alters statutory copyright exceptions, contractual terms, or jurisdictional legal obligations. [1]", "v05_fuzzy_additions": null, "v05_diagram": null, "v05_wire_artifact": null, "v05_counterparts": { "classic_analogues": [ { "name": "ODRL Information Model 2.2", "spec_or_rfc": "W3C ODRL Information Model 2.2 (February 2018)", "relation_type": "analogous_to_classic", "relation_label": "Analogous to classic standard", "delta_md": "ODRL Information Model 2.2 is the W3C model that the RSL 1.0 specification cites from February 2018, and TDMRep says its TDM Policy is a profile of the Open Digital Rights Language 2.2. AIPREF Vocabulary instead defines the categories AI Training, AI Use, and Search and says its Dictionary serialization is only exemplary. [1][6][7]" } ], "agentic_peers": [ { "target_id": "aipref-content-usage-attachment", "target_name": "AIPREF Content-Usage Attachment", "relation_type": "depended_on_by", "relation_label": "Depended on by", "delta_md": "The Content-Usage attachment, draft-ietf-aipref-attach-05 by G. Illyes (Google) and M. Thomson (Mozilla), dated 19 August 2026, defines a Content-Usage HTTP header field and a robots.txt Content-Usage rule, and it says that header follows the vocabulary and processing rules in the vocabulary draft. AIPREF Vocabulary defines the labels train-ai, ai-use, and search and says its Dictionary format is only an exemplary serialization. [1][3]" }, { "target_id": "cloudflare-content-signals-policy", "target_name": "Content Signals Policy", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "Content Signals Policy, which Will Allen published on 24 September 2025, defines three content signals, search, ai-input, and ai-train, and their relevance to crawlers. AIPREF Vocabulary defines different categories, AI Training, AI Use, and Search, mapped to the labels train-ai, ai-use, and search. [1][5]" }, { "target_id": "tdmrep", "target_name": "TDMRep (TDM Reservation Protocol)", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "TDMRep, the W3C Text and Data Mining Reservation Protocol final community-group report of 10 May 2024 edited by Laurent Le Meur (EDRLab), defines tdm-reservation as a boolean whose value 1 means TDM rights are reserved, plus an optional tdm-policy. AIPREF Vocabulary defines usage categories such as AI Training and Search rather than that reservation boolean. [1][7]" }, { "target_id": "rsl", "target_name": "Really Simple Licensing", "relation_type": "peer_alternative", "relation_label": "Peer alternative", "delta_md": "RSL 1.0 is an XML license, published 2025-12-10, with media type application/rsl+xml. One example prohibits any use by AI systems, including model training, with a prohibits element of type usage and value ai-all, and another states a price in euros with an amount element. AIPREF Vocabulary states allow or disallow for categories such as AI Training and Search, and its Dictionary serialization is only exemplary. [1][6]" }, { "target_id": "ai-crawler-tokens-robots", "target_name": "AI crawler tokens in robots.txt", "relation_type": "complements", "relation_label": "Complements", "delta_md": "AI crawler tokens name a robots.txt product. RFC 9309 (September 2022) says a crawler uses its product token to find relevant groups and defines Allow and Disallow lines. OpenAI says it uses OAI-SearchBot and GPTBot robots.txt tags so webmasters can manage how sites work with AI. AIPREF Vocabulary defines usage labels such as train-ai and search. [1][4][19]" } ] }, "v05_adoption": { "visible": true, "empty_state_note_md": null, "scope_note_md": "Selected verified implementations (5 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).", "side_a": { "visible": true, "heading": "Origins publishing AIPREF vocabulary labels", "col4_header": "Observed `Content-Usage` dictionary & `draft-ietf-aipref-vocab` version fit", "note_md": null, "rows": [ { "actor": "SpinXO", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "robots.txt sets `Content-Usage: train-ai=y, search=y` under the comment `draft-ietf-aipref-attach`. The home response sends `content-usage: train-ai=y, search=y`. `train-ai` and `search` are the AI Training and Search labels in `draft-ietf-aipref-vocab-08` Table 1. Allow and disallow map to `y` and `n`.", "source_md": "[SpinXO robots.txt (fetched 2026-10-30)](https://www.spinxo.com/robots.txt) [20] · [SpinXO home page (fetched 2026-10-30)](https://www.spinxo.com/) [21] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1]" }, { "actor": "Launchpad", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `Content-Usage: ai=n` in the `User-agent: *` group on launchpad.net, bugs.launchpad.net, code.launchpad.net, and answers.launchpad.net, next to `Content-Signal: ai-train=no, search=yes, ai-input=no`. The file comment cites `https://robotstxt.com/ai`. `ai` is the AI Training label in `draft-ietf-aipref-vocab-01` Table 1 and is not a `draft-ietf-aipref-vocab-08` Table 1 label.", "source_md": "[launchpad.net/robots.txt (fetched 2026-10-30)](https://launchpad.net/robots.txt) [22] · [bugs.launchpad.net/robots.txt (fetched 2026-10-30)](https://bugs.launchpad.net/robots.txt) [23] · [code.launchpad.net/robots.txt (fetched 2026-10-30)](https://code.launchpad.net/robots.txt) [24] · [answers.launchpad.net/robots.txt (fetched 2026-10-30)](https://answers.launchpad.net/robots.txt) [25] · [draft-ietf-aipref-vocab-01](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1]" }, { "actor": "Ubuntu Changelogs", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `Content-Usage: ai=n` in the `User-Agent: *` group. The file comment cites `https://robotstxt.com/ai`. The response names `nginx/1.14.0 (Ubuntu)`. `ai` is the AI Training label in `draft-ietf-aipref-vocab-01` Table 1 and is absent from `draft-ietf-aipref-vocab-08` Table 1.", "source_md": "[changelogs.ubuntu.com/robots.txt (fetched 2026-10-30)](https://changelogs.ubuntu.com/robots.txt) [27] · [draft-ietf-aipref-vocab-01](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1]" }, { "actor": "They Said So", "role": "Publisher", "status": "Live (HTTP 200)", "status_display": "Live (HTTP 200) · checked 2026-10-30", "col4_md": "Serves `Content-Usage: ai=n` in the `User-Agent: *` group, next to `Content-Signal: search=yes, ai-input=no, ai-train=no`. The file comment cites `https://robotstxt.com/ai`. `ai` is the AI Training label in `draft-ietf-aipref-vocab-01` Table 1 and is absent from `draft-ietf-aipref-vocab-08` Table 1.", "source_md": "[theysaidso.com/robots.txt (fetched 2026-10-30)](https://theysaidso.com/robots.txt) [28] · [draft-ietf-aipref-vocab-01](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1]" } ] }, "side_b": { "visible": true, "heading": "Platforms, mappings & standards alignment", "col4_header": "Vocabulary mapping & implementation status", "note_md": null, "rows": [ { "actor": "Cloudflare Content Signals Policy", "role": "Platform", "status": "Partial", "status_display": "Partial · as of 2026-09-15", "col4_md": "`draft-romm-aipref-contentsignals-00` Table 1 maps Search to `search`, AI Input to `ai-input`, and AI Training to `ai-train`. Michael Tremante called Cloudflare's Content Signal Policy an interim measure and wrote that they will revisit the policy once a consensus position has happened. Bryan Becker wrote that as standards such as `ai-prefs` mature, Cloudflare will revisit this approach. The September 15, 2026 press release says today's controls are designed to work alongside these emerging standards.", "source_md": "[draft-romm-aipref-contentsignals-00](https://datatracker.ietf.org/doc/html/draft-romm-aipref-contentsignals-00) [29] · [Michael Tremante, ai-control (24 September 2025)](https://mailarchive.ietf.org/arch/msg/ai-control/EANb9b9bljOanLBFm5FRerYlxyI/) [30] · [Bryan Becker, Cloudflare Blog (September 15, 2026)](https://blog.cloudflare.com/accountable-mixed-use-ai-crawlers/) [31] · [Cloudflare press release (September 15, 2026)](https://www.cloudflare.com/press/press-releases/2026/cloudflare-helps-end-the-search-or-ai-training-tradeoff/) [32]" } ] }, "additional_tables": null, "censuses": [ { "label": "AI Crawler Check, Do AI companies honour Content-Usage today?", "as_of": "2026-10-18", "value_md": "No major AI company has said publicly that its crawler reads Content-Usage yet. [33]" } ], "footer_md": null }, "v05_see_also": [ { "target_id": "agent-permissions-json", "target_name": "agent-permissions.json", "relation_label": "Complements", "delta": "agent-permissions.json constrains actions on a page with resource_rules and action_guidelines, while the AIPREF vocabulary expresses preferences such as train-ai and search and defines no action list.", "item_md": "**[agent-permissions.json](/protocols/agent-permissions-json/)** (Complements) — agent-permissions.json constrains actions on a page with resource_rules and action_guidelines, while the AIPREF vocabulary expresses preferences such as train-ai and search and defines no action list." }, { "item_md": "**[Permit protocols](/category/permit/)** — Category index for `permit` standards." } ], "v05_compiled_md": "---\nid: aipref-vocabulary\ntitle: \"AIPREF Vocabulary (A Vocabulary For Expressing AI Usage Preferences)\"\ntier: spec_brief\nlifecycle_status: active_draft\ncategory: permit\nform: document-format\nwire_archetype: crawler_policy\nspec_url: https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt\nlast_checked: 2026-10-31\n---\n\n# AIPREF Vocabulary (A Vocabulary For Expressing AI Usage Preferences)\n\n**Category:** [Permit](/category/permit/) (`permit`) · **Form:** Document format (`document-format`) · **Last checked:** 2026-10-31\n\n> *This page is about the vocabulary Internet-Draft of the IETF AI Preferences (aipref) working group, draft-ietf-aipref-vocab, which defines categories of use (AI Training, AI Use, Search) and how a statement of preference allows or disallows each. It does not say where such statements are published: that is the separate working-group draft draft-ietf-aipref-attach, which carries them in a Content-Usage HTTP header field and a Content-Usage rule in robots.txt; see [AIPREF Content-Usage Attachment](/protocols/aipref-content-usage-attachment/). It is not robots.txt (the Robots Exclusion Protocol, RFC 9309) itself, which the attachment draft updates. It is not Cloudflare's Content Signals Policy, which defines its own content signals search, ai-input, and ai-train; see [Content Signals Policy](/protocols/cloudflare-content-signals-policy/). It is also not [Really Simple Licensing (RSL)](/protocols/rsl/) or the [Text and Data Mining Reservation Protocol (TDMRep)](/protocols/tdmrep/), which are separate specifications, or [ai.txt](/protocols/ai-txt/). [1][2][3][4][5][6][7]*\n\n**A Vocabulary For Expressing AI Usage Preferences** (`draft-ietf-aipref-vocab`) defines a vocabulary for preferences regarding how automated processing systems use digital assets. [1] The exemplary serialization is a Dictionary: `train-ai=y, search=n` allows model training, disallows search, and leaves other categories unknown. The format is only exemplary, and the data model in Section 3 can be used without this serialization. [1] A Datatracker new-revision event names `draft-ietf-aipref-vocab-08` and records `time` `2026-09-14`. The draft states that its contents do not reflect consensus of the working group in whole or in part. [1][8]\n\n| Field | Value |\n| :--- | :--- |\n| **Category** | [Permit](/category/permit/) (`permit`) |\n| **Form** | Document format (`document-format`) |\n| **Originated by** | Paul Keller (Open Future), individual draft `draft-keller-aipref-vocab`, latest revision 2025-03-30, replaced by `draft-ietf-aipref-vocab`. On 26 April 2025 the chairs adopted `draft-keller-aipref-vocab-01` and appointed Paul Keller and Martin Thomson as editors. `draft-ietf-aipref-vocab-08` (14 September 2026) lists P. Keller (Open Future) and M. Thomson, Ed. (Mozilla). [1][9][10] |\n| **Governed by** | IETF AI Preferences (aipref) working group. Area: Web and Internet Transport (wit). State: Active. Charter: `charter-ietf-aipref-01` Approved. Chairs: Mark Nottingham and Suresh Krishnan. Area Director: Mike Bishop. List: `ai-control@ietf.org`. Drafts: `github.com/ietf-wg-aipref/drafts`. Created in state Proposed on 2024-11-19. Charter approved and group made active on 2025-01-07. [1][2][11][12] |\n| **Track** | IETF. Intended status: Standards Track. Datatracker intended RFC status: Proposed Standard. [1][13] |\n| **IETF tracker** | [draft-ietf-aipref-vocab](https://datatracker.ietf.org/doc/draft-ietf-aipref-vocab/) · Active Internet-Draft (aipref WG) · authors Paul Keller, Martin Thomson · last updated 2026-09-13 · WG state WG Document · IESG state I-D Exists · replaces `draft-keller-aipref-vocab` [13] |\n| **Status** | Active Internet-Draft (aipref WG Document; no document shepherd assigned; no WG RFCs published yet). The -08 text notes its contents do not yet reflect full working-group consensus. Working-group last call started 2025-09-04 and returned to WG Document on 2025-11-03. [1][2][12][13][14][15] |\n| **Version** | `draft-ietf-aipref-vocab-08`, header date 14 September 2026, expires 18 March 2027 (posted 2026-09-13; WG -00 approved 2025-04-30; replaces `draft-keller-aipref-vocab`). [1][8][9][13][15][16] |\n| **Message format** | Exemplary serialization is a Structured Fields Dictionary. Labels: AI Training `train-ai` (Section 4.1), AI Use `ai-use` (Section 4.2), Search `search` (Section 4.3). Explicit preferences are the tokens `y` and `n`. Example: `train-ai=y, search=n`. [1] |\n| **IANA registration** | This document has no IANA actions. [1] |\n| **Specification** | [A Vocabulary For Expressing AI Usage Preferences](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) (`draft-ietf-aipref-vocab-08`, 14 September 2026) [1][16] |\n| **Found at** | No attachment location in the vocabulary draft: the serialization is exemplary, and the charter keeps the vocabulary independent of how preferences are associated with content. Attachment is [draft-ietf-aipref-attach-05](https://www.ietf.org/archive/id/draft-ietf-aipref-attach-05.txt) (G. Illyes, Google, and M. Thomson, Mozilla, 19 August 2026), which defines a Content-Usage HTTP header and a robots.txt Content-Usage rule and updates RFC 9309. Revision -04 of that draft expired on 2026-05-01 and -05 was posted on 2026-08-18. Editor's copy: [draft-ietf-aipref-vocab.html](https://ietf-wg-aipref.github.io/drafts/draft-ietf-aipref-vocab.html). [1][2][3][17][18] |\n| **Licence** | Copyright (c) 2026 IETF Trust and the document authors. Subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents. Code components must include Revised BSD License text. [1] |\n\n**Contents**\n1. [Problem and scope](#problem-and-scope)\n2. [Counterparts and related standards](#counterparts-and-related-standards)\n3. [Adoption and ecosystem](#adoption-and-ecosystem)\n4. [See also](#see-also)\n5. [References](#references)\n\n---\n\n## Problem and scope\n\nThe aipref charter asks for a standard track vocabulary for expressing AI-related preferences, independent of how those preferences are associated with content. Technical enforcement of preferences is out of scope for that charter. [2] Evaluating a statement yields `allow`, `disallow`, or `unknown` per category, with any `disallow` winning so the most restrictive preference applies. Under Section 4.3, `Search` permits internal AI model training and model use whose outputs exclusively serve search links and relevance excerpts (excluding generated summaries), overriding `AI Training` (Section 4.1) and `AI Use` (Section 4.2). [1] Recipients choose whether to follow declared preferences: preferences are not a security mechanism, and the specification neither enforces compliance nor alters statutory copyright exceptions, contractual terms, or jurisdictional legal obligations. [1]\n\n---\n\n## Counterparts and related standards\n\n### Classic web analogues\n\n| Standard | Spec / RFC | Relationship | Architectural Delta |\n| :--- | :--- | :--- | :--- |\n| **ODRL Information Model 2.2** | `W3C ODRL Information Model 2.2 (February 2018)` | Analogous to classic standard | ODRL Information Model 2.2 is the W3C model that the RSL 1.0 specification cites from February 2018, and TDMRep says its TDM Policy is a profile of the Open Digital Rights Language 2.2. AIPREF Vocabulary instead defines the categories AI Training, AI Use, and Search and says its Dictionary serialization is only exemplary. [1][6][7] |\n\n### Agentic protocol peers\n\n| Protocol | Relationship | Architectural Delta |\n| :--- | :--- | :--- |\n| **[AIPREF Content-Usage Attachment](/protocols/aipref-content-usage-attachment/)** | Depended on by | The Content-Usage attachment, draft-ietf-aipref-attach-05 by G. Illyes (Google) and M. Thomson (Mozilla), dated 19 August 2026, defines a Content-Usage HTTP header field and a robots.txt Content-Usage rule, and it says that header follows the vocabulary and processing rules in the vocabulary draft. AIPREF Vocabulary defines the labels train-ai, ai-use, and search and says its Dictionary format is only an exemplary serialization. [1][3] |\n| **[Content Signals Policy](/protocols/cloudflare-content-signals-policy/)** | Peer alternative | Content Signals Policy, which Will Allen published on 24 September 2025, defines three content signals, search, ai-input, and ai-train, and their relevance to crawlers. AIPREF Vocabulary defines different categories, AI Training, AI Use, and Search, mapped to the labels train-ai, ai-use, and search. [1][5] |\n| **[TDMRep (TDM Reservation Protocol)](/protocols/tdmrep/)** | Peer alternative | TDMRep, the W3C Text and Data Mining Reservation Protocol final community-group report of 10 May 2024 edited by Laurent Le Meur (EDRLab), defines tdm-reservation as a boolean whose value 1 means TDM rights are reserved, plus an optional tdm-policy. AIPREF Vocabulary defines usage categories such as AI Training and Search rather than that reservation boolean. [1][7] |\n| **[Really Simple Licensing](/protocols/rsl/)** | Peer alternative | RSL 1.0 is an XML license, published 2025-12-10, with media type application/rsl+xml. One example prohibits any use by AI systems, including model training, with a prohibits element of type usage and value ai-all, and another states a price in euros with an amount element. AIPREF Vocabulary states allow or disallow for categories such as AI Training and Search, and its Dictionary serialization is only exemplary. [1][6] |\n| **[AI crawler tokens in robots.txt](/protocols/ai-crawler-tokens-robots/)** | Complements | AI crawler tokens name a robots.txt product. RFC 9309 (September 2022) says a crawler uses its product token to find relevant groups and defines Allow and Disallow lines. OpenAI says it uses OAI-SearchBot and GPTBot robots.txt tags so webmasters can manage how sites work with AI. AIPREF Vocabulary defines usage labels such as train-ai and search. [1][4][19] |\n\n---\n\n## Adoption and ecosystem\n\n*Selected verified implementations (5 probed or cited examples across 2 tables; non-exhaustive — see [Ecosystem censuses](#ecosystem-censuses) below for ecosystem-wide totals).*\n\n### Origins publishing AIPREF vocabulary labels\n\n| Actor | Role | Status | Observed `Content-Usage` dictionary & `draft-ietf-aipref-vocab` version fit | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **SpinXO** | Publisher | Live (HTTP 200) · checked 2026-10-30 | robots.txt sets `Content-Usage: train-ai=y, search=y` under the comment `draft-ietf-aipref-attach`. The home response sends `content-usage: train-ai=y, search=y`. `train-ai` and `search` are the AI Training and Search labels in `draft-ietf-aipref-vocab-08` Table 1. Allow and disallow map to `y` and `n`. | [SpinXO robots.txt (fetched 2026-10-30)](https://www.spinxo.com/robots.txt) [20] · [SpinXO home page (fetched 2026-10-30)](https://www.spinxo.com/) [21] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1] |\n| **Launchpad** | Publisher | Live (HTTP 200) · checked 2026-10-30 | Serves `Content-Usage: ai=n` in the `User-agent: *` group on launchpad.net, bugs.launchpad.net, code.launchpad.net, and answers.launchpad.net, next to `Content-Signal: ai-train=no, search=yes, ai-input=no`. The file comment cites `https://robotstxt.com/ai`. `ai` is the AI Training label in `draft-ietf-aipref-vocab-01` Table 1 and is not a `draft-ietf-aipref-vocab-08` Table 1 label. | [launchpad.net/robots.txt (fetched 2026-10-30)](https://launchpad.net/robots.txt) [22] · [bugs.launchpad.net/robots.txt (fetched 2026-10-30)](https://bugs.launchpad.net/robots.txt) [23] · [code.launchpad.net/robots.txt (fetched 2026-10-30)](https://code.launchpad.net/robots.txt) [24] · [answers.launchpad.net/robots.txt (fetched 2026-10-30)](https://answers.launchpad.net/robots.txt) [25] · [draft-ietf-aipref-vocab-01](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1] |\n| **Ubuntu Changelogs** | Publisher | Live (HTTP 200) · checked 2026-10-30 | Serves `Content-Usage: ai=n` in the `User-Agent: *` group. The file comment cites `https://robotstxt.com/ai`. The response names `nginx/1.14.0 (Ubuntu)`. `ai` is the AI Training label in `draft-ietf-aipref-vocab-01` Table 1 and is absent from `draft-ietf-aipref-vocab-08` Table 1. | [changelogs.ubuntu.com/robots.txt (fetched 2026-10-30)](https://changelogs.ubuntu.com/robots.txt) [27] · [draft-ietf-aipref-vocab-01](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1] |\n| **They Said So** | Publisher | Live (HTTP 200) · checked 2026-10-30 | Serves `Content-Usage: ai=n` in the `User-Agent: *` group, next to `Content-Signal: search=yes, ai-input=no, ai-train=no`. The file comment cites `https://robotstxt.com/ai`. `ai` is the AI Training label in `draft-ietf-aipref-vocab-01` Table 1 and is absent from `draft-ietf-aipref-vocab-08` Table 1. | [theysaidso.com/robots.txt (fetched 2026-10-30)](https://theysaidso.com/robots.txt) [28] · [draft-ietf-aipref-vocab-01](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-01.txt) [26] · [draft-ietf-aipref-vocab-08](https://www.ietf.org/archive/id/draft-ietf-aipref-vocab-08.txt) [1] |\n\n### Platforms, mappings & standards alignment\n\n| Actor | Role | Status | Vocabulary mapping & implementation status | Source |\n| :--- | :--- | :--- | :--- | :--- |\n| **Cloudflare Content Signals Policy** | Platform | Partial · as of 2026-09-15 | `draft-romm-aipref-contentsignals-00` Table 1 maps Search to `search`, AI Input to `ai-input`, and AI Training to `ai-train`. Michael Tremante called Cloudflare's Content Signal Policy an interim measure and wrote that they will revisit the policy once a consensus position has happened. Bryan Becker wrote that as standards such as `ai-prefs` mature, Cloudflare will revisit this approach. The September 15, 2026 press release says today's controls are designed to work alongside these emerging standards. | [draft-romm-aipref-contentsignals-00](https://datatracker.ietf.org/doc/html/draft-romm-aipref-contentsignals-00) [29] · [Michael Tremante, ai-control (24 September 2025)](https://mailarchive.ietf.org/arch/msg/ai-control/EANb9b9bljOanLBFm5FRerYlxyI/) [30] · [Bryan Becker, Cloudflare Blog (September 15, 2026)](https://blog.cloudflare.com/accountable-mixed-use-ai-crawlers/) [31] · [Cloudflare press release (September 15, 2026)](https://www.cloudflare.com/press/press-releases/2026/cloudflare-helps-end-the-search-or-ai-training-tradeoff/) [32] |\n\n### Ecosystem censuses\n\n- **AI Crawler Check, Do AI companies honour Content-Usage today?** (*as of 2026-10-18*): No major AI company has said publicly that its crawler reads Content-Usage yet. [33]\n\n---\n\n## See also\n\n- **[agent-permissions.json](/protocols/agent-permissions-json/)** *(Complements)* — agent-permissions.json constrains actions on a page with resource_rules and action_guidelines, while the AIPREF vocabulary expresses preferences such as train-ai and search and defines no action list.\n- **Category:** [Permit protocols](/category/permit/)\n\n---\n\n## References\n\n1. P. Keller (Open Future) and M. Thomson, Ed. (Mozilla), *A Vocabulary For Expressing AI Usage Preferences (draft-ietf-aipref-vocab-08)* (14 September 2026) — \n2. IETF Datatracker, *AI Preferences (aipref) working group* (charter charter-ietf-aipref-01 Approved) — \n3. G. Illyes (Google) and M. Thomson (Mozilla), *Associating AI Usage Preferences with Content in HTTP (draft-ietf-aipref-attach-05)* (19 August 2026) — \n4. M. Koster, G. Illyes, H. Zeller, and L. Sassman, *Robots Exclusion Protocol* (RFC 9309, September 2022) — \n5. Will Allen, Cloudflare Blog, *Giving users choice with Cloudflare's new Content Signals Policy* (published 2025-09-24; modified 2026-07-15) — \n6. RSL Technical Steering Committee, *Really Simple Licensing (RSL) 1.0 Specification* (published 2025-12-10) — \n7. Laurent Le Meur (EDRLab), W3C TDMRep Community Group, *TDM Reservation Protocol (TDMRep)* (Final Community Group Report, 10 May 2024) — \n8. IETF Datatracker API, *New-revision events for draft-ietf-aipref-vocab* (nine revisions; -08 published 2026-09-14) — \n9. IETF Datatracker, *draft-keller-aipref-vocab — Proposal for an Opt-Out Vocabulary (IETF Datatracker)* (latest revision 2025-03-30; last updated 2025-04-10) — \n10. Mark Nottingham, *[ai-control] Adoption of draft-keller-aipref-vocab-01* (26 April 2025) — \n11. IETF AI Preferences (aipref) working group, *AIPREF working drafts* (fetched 2026-10-30) — \n12. IETF Datatracker, *aipref working group history* (charter approved 2025-01-07) — \n13. IETF Datatracker, *draft-ietf-aipref-vocab — A Vocabulary For Expressing AI Usage Preferences (IETF Datatracker)* (last updated 2026-09-13) — \n14. IETF Datatracker API, *RFC documents in group aipref* (fetched 2026-10-30) — \n15. IETF Datatracker, *draft-ietf-aipref-vocab history* (history through the -08 posting on 2026-09-13) — \n16. IETF Datatracker API, *IETF Datatracker document record for draft-ietf-aipref-vocab* (rev 08; time 2026-09-14) — \n17. IETF Datatracker, *draft-ietf-aipref-attach history* (-04 expired 2026-05-01; -05 posted 2026-08-18) — \n18. IETF AI Preferences (aipref) working group, *A Vocabulary For Expressing AI Usage Preferences (editor's copy)* (14 September 2026) — \n19. OpenAI, *Overview of OpenAI Crawlers* (fetched 2026-10-30) — \n20. SpinXO, *robots.txt* (fetched 2026-10-30) — \n21. SpinXO, *SpinXO home page* (response last-modified Fri, 30 Oct 2026) — \n22. Canonical (Launchpad), *robots.txt* (fetched 2026-10-30) — \n23. Canonical (Launchpad), *robots.txt* (fetched 2026-10-30) — \n24. Canonical (Launchpad), *robots.txt* (fetched 2026-10-30) — \n25. Canonical (Launchpad), *robots.txt* (fetched 2026-10-30) — \n26. P. Keller (Open Future) and M. Thomson, Ed. (Mozilla), *A Vocabulary For Expressing AI Usage Preferences (draft-ietf-aipref-vocab-01)* (19 June 2025) — \n27. Canonical (Ubuntu), *robots.txt* (response dated Fri, 30 Oct 2026) — \n28. They Said So, *robots.txt* (response dated Fri, 30 Oct 2026) — \n29. M. Tremante (Cloudflare) and L. Romm, *Vocabulary For Expressing Content Signals (draft-romm-aipref-contentsignals-00 HTML)* (1 October 2025) — \n30. Michael Tremante, *Cloudflare's Content Signal Policy* (24 September 2025) — \n31. Bryan Becker, Cloudflare Blog, *Have it both ways: stay discoverable in search while disallowing AI training* (published 2026-09-15) — \n32. Cloudflare, *Cloudflare Helps End the Search-or-AI-Training Tradeoff* (15 September 2026) — \n33. Scout Agent, AI Crawler Check, *Content-Usage robots.txt: IETF AIPREF Explained (2026)* (published 2026-10-18) — \n", "status_notice_md": null, "superseded_by": null }, { "acronym": "TDMRep", "adoption": { "level": "observed", "by": "Elsevier, Optica Publishing Group, Springer Nature, Le Progrès, Hachette Livre, Spawning (Data Diligence), img2dataset, Mondadori, and 4 other verified implementations", "probe_run": null }, "aliases": [ "TDM Reservation Protocol" ], "analog": "Rights-reservation metadata (like a Creative Commons license badge)", "collisions": [], "discovery": { "mechanism": "Well-known JSON file, HTTP headers, HTML meta tags, or EPUB/PDF metadata", "path": "/.well-known/tdmrep.json; tdm-reservation / tdm-policy HTTP headers; in HTML; tdm:reservation in EPUB and PDF metadata" }, "dispute": null, "evidence": [ { "label": "[1]", "url": "https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/", "claim": "Laurent Le Meur (EDRLab), *TDM Reservation Protocol (TDMRep)*, Final Community Group Report, 10 May 2024", "date": null, "quote": "published by the Text and Data Mining Reservation Protocol Community Group under the W3C Community Final Specification Agreement (FSA). / Editor: Laurent Le Meur (EDRLab) / It is not a W3C Standard nor is it on the W3C Standards Track. / This initiative is a technical answer to the constraints set by the Article 4 of the new European Directive on copyright and related rights in the Digital Single Market. / This specification defines a JSON file named tdmrep.json, which MUST be hosted in the /.well-known repository of a Web server. / In each rule, location and tdm-reservation are mandatory, tdm-policy is optional. / The format of policies defined in this specification is a profile of the Open Digital Rights Language 2.2 [ODRL]. / https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/ Editor: Laurent Le Meur (EDRLab) Previous version TDMRep, Second Version Useful links TDMRep / Final Community Group Report 10 May 2024\" } TDM Reservation Protocol (TDMRep) / TDM Reservation Protocol (TDMRep) Final Community Group Report 10 May 2024 This version: https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/ / The \"opt-out\" option specified by the Article 4 of the CDSM Directive is expressed by the use of tdm-reservation with value equal 1. / 1 TDM rights are reserved. If a TDM Policy is set, TDM Agents MAY use it to get information on how they can acquire from the rightsholder an authorization to mine the content. / A TDM Agent MUST check the presence of a TDM file on the origin server before it starts scraping the content of the Web server. / Important note: TDM Actors which benefit from the Article 3 of the CDSM Directive do not have to comply to this requirement. / These properties cover TDM rights for every resource in the package, and this specification does not cover the definition of specific TDM rights for the different resources present in the package.", "ref": 1 }, { "label": "[2]", "url": "https://www.w3.org/community/tdmrep/2021/01/20/call-for-participation-in-tdm-reservation-protocol-community-group/", "claim": "W3C Team, *Call for Participation in TDM Reservation Protocol Community Group*, 2021-01-20; checked 2026-10-29", "date": null, "quote": "This group was originally proposed on 2021-01-18 by Laurent Le Meur.", "ref": 2 }, { "label": "[3]", "url": "https://www.w3.org/community/tdmrep/", "claim": "W3C, *Text and Data Mining Reservation Protocol Community Group*, checked 2026-10-29", "date": null, "quote": "2024-08-09 TDM Reservation Protocol, version 3 / Notes, September 30th, 2025 Laurent Le Meur | Posted on: October 1, 2025 / URL https://www.w3.org/2022/tdmrep/. It is referenced from the TDMRep Community home page. As multiple EU / All participants in this group have signed the W3C Community Contributor License Agreement . / It is not a NO-TDM signal, but a RIGHTS-RESERVED signal.", "ref": 3 }, { "label": "[4]", "url": "https://www.iana.org/assignments/well-known-uris/well-known-uris-1.csv", "claim": "IANA, *Well-Known URIs*, registry CSV, fetched 2026-10-30", "date": null, "quote": "tdmrep.json,[https://www.w3.org/2022/tdmrep/],provisional,W3C,,2024-02-15, / 7808 permanent IESG 2015-08-03 tdmrep.json https://www.w3.org/2022/tdmrep/ provisional W3C 2024-02-15 tor-relay The \"tor-relay\" Well-Known Resource", "ref": 4 }, { "label": "[5]", "url": "https://www.w3.org/events/meetings/4d16ca76-dc36-4bf2-914e-13c2ca89ad2d/", "claim": "W3C, *TDMRep Community Group Meeting at TPAC 2025*, 2025-11-14; checked 2026-10-29", "date": null, "quote": "We'll then discuss a possible evolution of TDMRep, using the Vocabulary defined by AI Pref.", "ref": 5 }, { "label": "[6]", "url": "https://www.w3.org/community/tdmrep/participants", "claim": "W3C, *Participants in the Text and Data Mining Reservation Protocol Community Group*, checked 2026-10-29", "date": null, "quote": "Laurent Le Meur EDRLab Check and nominate Chair: Giulia Marangoni AIE - Italian Publishers", "ref": 6 }, { "label": "[7]", "url": "https://github.com/w3c-cg/tdm-reservation-protocol", "claim": "W3C TDMRep Community Group, *w3c-cg/tdm-reservation-protocol repository*, checked 2026-10-30", "date": null, "quote": "\"full_name\": \"w3c-cg/tdm-reservation-protocol\" / \"html_url\": \"https://github.com/w3c-cg/tdm-reservation-protocol\", \"description\": \"Repository of the Text and Data Mining Reservation Protocol Community Group\",", "ref": 7 }, { "label": "[8]", "url": "https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240202/", "claim": "Laurent Le Meur (EDRLab), *TDM Reservation Protocol (TDMRep) Version 2*, published 2024-02-02", "date": null, "quote": "February 2024 This version: https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240202/ Editor: Laurent Le Meur ( EDRLab ) Previous version", "ref": 8 }, { "label": "[9]", "url": "https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20220216/", "claim": "W3C TDMRep Community Group, *TDM Reservation Protocol (TDMRep) Version 1*, 2022-02-16; checked 2026-10-29", "date": null, "quote": "Final Community Group Report 16 February 2022 This version: https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20220216/ Editor: Laurent Le Meur", "ref": 9 }, { "label": "[10]", "url": "https://publications.europa.eu/resource/cellar/214471fe-786e-11e9-9f05-01aa75ed71a1.0006.03/DOC_1", "claim": "European Union, *Directive (EU) 2019/790 on copyright and related rights in the Digital Single Market, Article 4(3)*, 2019-05-17; checked 2026-10-29", "date": null, "quote": "The exception or limitation provided for in paragraph 1 shall apply on condition that the use of works and other subject matter referred to in that paragraph has not been expressly reserved by their rightholders in an appropriate manner, such as machine-readable means in the case of content made publicly available online.", "ref": 10 }, { "label": "[11]", "url": "https://www.rfc-editor.org/rfc/rfc8615.html", "claim": "M. Nottingham (IETF), *RFC 8615: Well-Known Uniform Resource Identifiers (URIs)*, published May 2019", "date": null, "quote": "This memo defines a path prefix for \"well-known locations\",", "ref": 11 }, { "label": "[12]", "url": "https://www.w3.org/TR/xhtml-rdfa-primer/", "claim": "W3C, *RDFa 1.1 Primer - Third Edition*, 2015-03-17", "date": "2015-03-17", "quote": "The last couple of years have witnessed a fascinating evolution: while the Web was initially", "ref": 12 }, { "label": "[13]", "url": "https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/", "claim": "IETF Datatracker, *draft-ietf-aipref-attach — Associating AI Usage Preferences with Content in HTTP (IETF Datatracker)*, last updated 2026-08-18", "date": null, "quote": "Active Internet-Draft (aipref WG)", "ref": 13 }, { "label": "[14]", "url": "https://blog.cloudflare.com/content-signals-policy/", "claim": "Cloudflare, *Giving users choice with Cloudflare's new Content Signals Policy*, published 2025-09-24; modified 2026-07-15", "date": null, "quote": "server: cloudflare cf-ray: a52db34f6977d9de-FRA alt-svc: h3=\":443\"; ma=86400 width=device-width, initial-scale=1.0 en-us @cloudflare https://blog.cloudflare.com/content-signals-policy/ 1200 628", "ref": 14 }, { "label": "[15]", "url": "https://rslstandard.org/rsl", "claim": "RSL Technical Steering Committee, *Really Simple Licensing (RSL) 1.0 Specification*, published 2025-12-10", "date": null, "quote": "robots.txt License: directives HTTP Link headers with rel=\"license\" HTML license associations established using or