Discovery guide
PolarCat publishes overlapping discovery surfaces because different agents and
indexers understand different conventions. All canonical URLs are pinned to
https://hands.polarcat.org; they are never derived from a request-controlled
Host header.
Discovery surfaces
| Surface | Purpose |
|---|---|
/.well-known/x402 |
Domain-level declaration that this host is an x402 resource server |
/v1/service |
PolarCat service, location, capabilities, payment mode, and links |
/v1/offers |
Current offer, exact body, live availability, price, and network |
/openapi.json |
Complete REST interface |
/llms.txt |
Short language-model execution instructions |
/v1/docs |
Machine-readable documentation index |
/v1/proofs |
Operator-approved public proof index |
HTTP 402 bazaar extension |
Input/output schema carried with live payment terms |
An unfamiliar agent given only the hostname should try the well-known x402
manifest, service manifest, or llms.txt, then use /v1/offers as the immediate
source of truth before requesting payment terms.
Well-known x402 manifest
PolarCat declares kind: resource-server. It does not claim to be the facilitator
that verifies and settles payments. The manifest permits cross-origin GET and is
cacheable.
Its shape follows the active Internet-Draft
draft-hawkins-x402-dns-discovery-03, published 23 August 2026. Internet-Drafts
are work in progress and can change or expire; clients should tolerate unknown
fields and continue validating the live x402 challenge.
The optional _x402 DNS TXT pointer is deliberately deferred while PolarCat is
rehearsing on Base Sepolia. The HTTPS well-known manifest remains directly
discoverable without it, and no stale DNS network hint needs to be replaced during
the mainnet transition.
No false A2A claim
PolarCat does not currently publish an A2A Agent Card. The service implements a REST/x402 purchase and polling protocol, not the A2A task protocol. Adding an Agent Card before implementing A2A operations would make discovery metadata misleading.
Discovery telemetry
Reads of machine-facing discovery routes create privacy-limited Home Assistant signals. PolarCat uses a daily rotating HMAC fingerprint and broad user-agent family; it does not retain raw client addresses or full user-agent strings for this feature.
A discovery hit proves only that a client read a route. It does not prove that the client was autonomous, understood the offer, or intended to buy. The progression from weaker to stronger evidence is:
discovery_hit → payment_challenge → order_queued → order_completed → proof_published
Use controlled friend-agent tests alongside timestamps when evaluating whether a particular agent successfully discovered the service.