docs(x402): add an Explorer section — browse, sell, connect an agent - #25
Merged
Conversation
The x402 docs described the discovery directory as an API and a CLI flag; the Explorer's web UI wasn't documented at all, and the page that existed still pointed at the old x402-discovery.hpp.io host with a "you can't register by hand" flow that has since been replaced by seller registration. Three pages under Explorer, screenshots and GIFs from the live product: - Find a service — the layout, intent search, how to read a service page and its trust signals, sellers, and the settlement feed. - List your service — sign in, claim what settlements already discovered, register endpoints, mint an ERC-8004 identity, delist. - Connect an agent — install the bridge, wire it into a host (or your own MCP client, or no MCP at all), fund it, and let the agent discover and pay. Notes on accuracy, since these are easy to get wrong: - 0.1.10 and earlier of the bridge fail to start (they died on an upstream `setup` injected by default), so the page states a 0.1.11 floor and how to upgrade an existing global install. - `discover` filters to HPP Sepolia unless you pass `-n`; every command that touches a network carries one, because a Sepolia balance never pays for a mainnet service. - The input contract shown to a buyer is only ever what the seller declared in its own 402 — empty means no parameters, absent means read the seller's docs. Guessing costs a real payment and can return a confident wrong answer. - The hosted MCP server is search-only; it hands the 402 back rather than paying, so it's documented as such instead of as a payment path. Also fixes admonition titles that rendered as literal ":::tip …" text in agents.mdx and quickstart-sellers.mdx (Docusaurus v3 wants `:::tip[Title]`).
…lable
A service shows up in the catalog twice when its seller published both an HTTP
and an MCP listing, and nothing said what to do with that. The page now covers
it, verified against a real paid call on each transport:
- What actually differs — the challenge (`402` header vs JSON-RPC `-32042`),
where the payment and the receipt ride, and the two URLs an MCP listing
carries (the endpoint you connect to vs the payment identity its `402`
advertises, which isn't connectable).
- **The body follows the transport, not the service.** The same service takes
`{"text": …}` over HTTP and `{"args": {"text": …}}` over MCP. `describe` for
the id you're calling; when it says the seller declared nothing, ask the
seller rather than guessing — a guess can cost a payment.
- Calling by id lets the listing pick the transport; calling by URL is HTTP,
because nothing told us otherwise.
- An MCP result has no transaction hash: the receipt is in `_meta`, so the
Explorer is where you confirm the settlement.
Version floor moves to 0.1.12 — 0.1.11 and earlier connected MCP listings to
their payment identity and got a 404. Sellers get the matching advice: declare
the input contract on the MCP twin too, since an `inputSchema` of `args: object`
tells a buyer nothing they can act on before paying.
Also adds a short troubleshooting section (stale global install shadowing npx,
mcp 404s, missing tx hash, wrong network).
- Rename x402/agents.mdx → x402/pay-from-an-ai-agent.mdx - Rename x402/directory.mdx → x402/service-directory.mdx - Update all internal links across x402/ and x402/explorer/ to reflect the new filenames
Member
|
@nolnol3 I just rename two files to match section titles. Please check the changes. |
hayarobi
self-requested a review
July 31, 2026 02:30
Filenames are URLs here, so renaming the files moved two pages that are already published: /x402/agents and /x402/directory. There is no redirects plugin, so the old paths would simply 404. Both are referenced from outside this repo and can't be corrected after the fact — /x402/agents is the npm `homepage` of @hpp-io/x402-mcp-bridge and the `websiteUrl` of its entry in the MCP Registry, and released package metadata is immutable. `slug` keeps the filenames as renamed while the public URLs stay where they were. The new paths are not emitted, so there is no duplicate route to split inbound links or indexing.
Member
Author
|
The rename is clean — links and sidebar ids are all updated, build passes. One catch: filenames are URLs here, so this 404s two live pages — Pushed a 2-line follow-up that keeps your filenames and pins the URLs: slug: agents # x402/pay-from-an-ai-agent.mdx
slug: directory # x402/service-directory.mdxVerified: both URLs are emitted again, Side note — Docusaurus doesn't compare filename to title (this repo has |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The x402 docs described the discovery directory as an API and a CLI flag. The Explorer's web UI wasn't documented at all, and the page that existed still pointed at the old
x402-discovery.hpp.iohost and said you can't register a service by hand — which stopped being true when seller registration shipped.Three pages under a new Explorer category:
Plus:
directory.mdxcorrected (new host, both listing paths), and admonition titles that were rendering as literal:::tip …text fixed inagents.mdxandquickstart-sellers.mdx(Docusaurus v3 wants:::tip[Title]).The GIFs are real runs, not click-throughs
hpp_discover→hpp_describe→hpp_call, tool names and results verbatim from the session log.An earlier draft used click-throughs of the UI; they showed what to click, not what happens, so they were dropped.
Accuracy notes
setupinjected by default) — the page states a 0.1.11 floor and how to upgrade an existing global install.discoverfilters to Sepolia unless you pass-n, so every command that touches a network carries one;-nand theeip155:form are explained where they first appear.402— empty means no parameters, absent means read the seller's docs. Guessing costs a real payment and can return a confident wrong answer.402back rather than paying, and is documented as such./supported.Verification
npm run buildclean (onBrokenLinks: 'throw'), and the built site served locally: 14/14 images load, no failed requests, no<video>left behind.Merge order
These pages screenshot the rewritten Explorer UI in hpp-io/hpp-x402-discovery#44. That should deploy before this merges, otherwise the docs show a page that isn't live yet.