Agent integration guide

PolarCat Hands sells one fixed physical-presence proof through x402. The buyer does not create an account and cannot submit arbitrary instructions, files, code, credentials, or locations.

Read live terms first

Never hard-code the price, network, asset contract, receiver, or availability. Read them from the service at execution time:

GET https://hands.polarcat.org/.well-known/x402
GET https://hands.polarcat.org/v1/service
GET https://hands.polarcat.org/v1/offers

Continue only when ordering_enabled is true. The sole accepted request body is:

{"offer_id":"physical-presence-proof-v1"}

Extra properties are rejected.

Purchase flow

1. Send the order body to POST /v1/orders without a payment signature.
2. Receive HTTP 402 and decode the base64url PAYMENT-REQUIRED header as x402 v2.
3. Select the advertised exact payment requirement.
4. Validate its network, asset, amount, receiver, resource URL, and timeout against the buyer's mandate.
5. Echo the advertised extensions and add a unique 16–128 character payment-identifier for this logical order.
6. Sign using the buyer's wallet and retry the identical body with PAYMENT-SIGNATURE.
7. Save the returned order_id, access_token, status_url, marker nonce, and PAYMENT-RESPONSE settlement header.

An order response is released only after successful facilitator settlement. A plain HTTP 402 request does not transfer funds.

Idempotent retries

Reuse the same payment identifier only when retrying the same logical order with the same complete signed payment payload. A successful replay returns the same order and capability without a second settlement. Reusing an identifier with a different signed payload returns a conflict.

If settlement fails after verification, retain the same payload and identifier for the retry. Do not generate a second logical order unless the first attempt has been abandoned and its state is understood.

Polling and capability handling

Poll the returned status_url approximately once per minute:

Authorization: Bearer <access_token>

The capability token is equivalent to private access to that order. Do not log, publish, place in a URL, or send it to PolarCat telemetry. Expected states are queued, in_progress, and completed.

When completed, the protected order response includes:

• the server-issued marker nonce;
• x402 settlement transaction;
• sanitized evidence metadata and SHA-256;
• protected evidence URL;
• Ed25519-signed completion receipt.

Verify completion

Fetch GET /v1/receipt-key and verify the receipt before accepting the result. The signature binds the order, offer, marker, city-level location, timestamps, payment, and evidence digest. Then download the protected JPEG and independently calculate its SHA-256.

If the operator separately publishes the proof, GET /v1/proofs/{order_id} can be verified without the buyer capability. Public proof publication is optional and does not change the buyer's private response.

Important responses

The live OpenAPI document at /openapi.json and the live HTTP 402 challenge are authoritative over this prose if the service evolves.

Read this guide as raw Markdown