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

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

```json
{"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:

```http
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

| Status | Meaning | Buyer action |
|---|---|---|
| `200` | Settled order or readable public resource | Preserve response and settlement header |
| `400` | Required payment identifier missing or malformed | Correct the x402 extension; do not generate a new payment |
| `401` | Missing or invalid order capability | Recover the original capability locally |
| `402` | Payment required or settlement did not complete | Inspect the current challenge or retry the same failed settlement |
| `409` | Identifier conflict, evidence not ready, or invalid state | Stop and inspect; do not blindly retry with new funds |
| `422` | Request body rejected | Use only the published fixed body |
| `503` | Ordering paused or one-order capacity full | Respect `Retry-After` and retry later without signing first |

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