PolarCat Hands documentation

Friend-agent discovery test

This exercise measures whether an ordinary AI agent can discover, understand, and optionally buy the PolarCat canary without being coached through individual API calls. Run the no-payment stages first. Use Base Sepolia only for paid rehearsals.

What to give the tester

Start each agent in a fresh conversation. Give it only this prompt:

Investigate whether hands.polarcat.org offers a machine-purchasable task. Tell me what it does, its exact price and network, what inputs it accepts, how proof is verified, and whether a completed example is publicly available. Do not make a payment yet.

Do not initially mention /v1/offers, llms.txt, OpenAPI, or /.well-known/x402. The point is to see which discovery surface the agent chooses.

Stages

1. Discovery only

The agent should find at least one machine-facing route and report:

No wallet or private key is needed.

2. Payment intent, no signing

Ask the agent:

Request the payment terms, decode the HTTP 402 challenge, and show me the receiver, asset contract, atomic amount, network, scheme, timeout, and required extensions. Do not sign or submit a payment.

This should create a Home Assistant payment_challenge event but no order.

3. Testnet purchase

Only after reviewing stages 1 and 2, give a capable agent a dedicated Base Sepolia test wallet funded with test USDC. Keep the private key in the agent's local secret mechanism; never paste it into chat or send it to PolarCat. Ask it to buy exactly one order, preserve the returned capability token locally, and report only:

After the operator completes the task, the agent should poll privately, verify the Ed25519 receipt, download evidence, and confirm its SHA-256 digest.

Record one result per agent

Agent/product and version:
Date and UTC time:
Starting prompt changed: yes/no (if yes, how):
First route fetched:
Routes fetched before understanding the offer:
Could decode x402 v2 challenge: yes/no:
Could explain testnet vs mainnet: yes/no:
Could create a paid order without custom code: yes/no/not attempted:
Could verify receipt and evidence: yes/no/not attempted:
Incorrect claims or unsafe requests:
Human interventions required:
Overall result: discovered / understood / challenged / paid / verified

Success criteria

The first milestone is three different agent products independently reaching understood. One reaching challenged proves x402 interoperability at the HTTP layer. A second independent agent reaching paid and verified is enough to call the testnet canary repeatable before switching to mainnet or adding more tasks.

Discovery hits are signals, not identities: PolarCat stores daily rotating visitor fingerprints rather than raw client addresses, and a crawler can resemble an agent. Use the tester's report and Home Assistant timestamps together when evaluating a run.

Read this guide as raw Markdown