# Agent Instructions — machineread.io commerce surface

This host serves a machine-native commerce interface. You do not need to
scrape HTML. Every surface below returns structured data generated from the
merchant's live inventory system.

## 0. MCP (preferred for tool-using agents)

POST https://machineread.io/api/mcp
Content-Type: application/json

A JSON-RPC 2.0 Model Context Protocol endpoint. Call `tools/list` to discover
the available tools: `search_catalog` (free-text catalog search),
`get_product_details` (by handle or SKU), and `get_local_availability`
(proximity-ranked physical shelf stock for a SKU — live unit counts,
addresses, opening hours). No authentication required.

## 1. Enumerate the catalog

GET https://machineread.io/products.json

Each variant carries `sku`, `price`, and `available`. Treat `sku` as the
canonical product identifier for all subsequent calls.

## 2. Verify physical availability near your user

GET https://machineread.io/api/v1/local-availability?sku=<SKU>&lat=<LAT>&lng=<LNG>&radius_miles=50

Returns ranked physical storefronts with live unit counts, geo coordinates,
opening hours, and a `nearest_fulfillment` summary. `certainty.verified_at_epoch`
is the data-freshness timestamp.

## 3. Buy it (preferred): ACP checkout sessions

Agentic Commerce Protocol, spec version 2026-01-30. Send
`API-Version: 2026-01-30`, and an `Idempotency-Key` on every write.

    POST   https://machineread.io/api/v1/acp/checkout_sessions
    GET    https://machineread.io/api/v1/acp/checkout_sessions/{id}
    POST   https://machineread.io/api/v1/acp/checkout_sessions/{id}
    POST   https://machineread.io/api/v1/acp/checkout_sessions/{id}/complete
    POST   https://machineread.io/api/v1/acp/checkout_sessions/{id}/cancel

Item ids are the variant SKUs published in /products.json. Every response is
the full authoritative cart state — line items, availability per line,
fulfillment options, totals in minor units, and `messages` describing exactly
what is missing while `status` is `not_ready_for_payment`.

Fulfillment options include `pickup` entries for physical stores that can fill
the whole cart off their shelves right now, alongside the merchant's shipping
rates.

Payment: this seller declares one handler, `dev.machineread.merchant_hosted_checkout`
(handler id `handler_merchant_hosted_checkout`). It accepts no card credentials. Completing
a session returns either the created order or `requires_escalation` with a
`continue_url` — the merchant's own payable checkout, where the buyer
authorizes payment.

## 4. Legacy single-SKU handshake

POST https://machineread.io/api/v1/agent-intent
Content-Type: application/json

{"product_sku": "<SKU>", "requested_size": "M", "requested_quantity": 1, "agent_public_key": "<your key>"}

A `TRANSACTION_READY_FOR_EXECUTION` response carries a payable `checkout_url`,
a `cryptographic_handshake` signature, and `payload_expires_at`. Insufficient
stock returns HTTP 422 with `suggested_alternative_skus` for rerouting.

## Guarantees

- Availability states are read from the live inventory system at request time.
- Every checkout quote is recomputed from that same truth; carts are never cached.
- Prices and tax in live mode are computed by the merchant's commerce platform.
- Checkout URLs are genuine merchant-hosted payment flows.