# 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:

```text
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.