# Isle of Man Salt Co.

> Hand-harvested sea salt and seasonings from the Isle of Man. This file documents the machine API for AI agents shopping on behalf of a person.

Base URL: https://new.isleofmansaltco.com
Humans check out by card on the website. Agents must use the API below and must NOT scrape or drive the HTML cart/checkout.

## Endpoints (JSON, prices in GBP, VAT included)
- GET  /api/agent/v1/catalog: every active product (slug, sku, name, description, ingredients, great_with, images, size_label, weight_grams, price_gbp, stock) plus shop meta: free_shipping_threshold_gbp, shipping_regions, full shipping_rates table (region, min_grams, max_grams, price_gbp, label) and the current lightning_address.
- POST /api/agent/v1/quote: {"items":[{"slug":"hand-harvested-sea-salt","quantity":2}],"country":"Isle of Man"}. Returns server prices, the exact shipping rate, total_gbp, amount_sats and fx {gbp_per_btc, sats_per_gbp, source, as_of}. Creates nothing.
- POST /api/agent/v1/orders: {"email","phone","items":[...],"ship_to":{"firstName","lastName","companyName?","address","address2?","city","postcode","country"},"note?"}. Returns order_number, payment_ref, totals, amount_sats, fx, lightning_address, lightning_invoice (bolt11, when available), status_url, check_payment_url, confirm_payment_url.
- GET  /api/agent/v1/orders/{order_number}?ref={payment_ref}: payment and fulfilment status.
- GET  /api/agent/v1/orders/{order_number}/check-payment?ref={payment_ref}: checks whether the issued invoice has settled; marks the order paid if verified.
- POST /api/agent/v1/orders/{order_number}/confirm-payment?ref={payment_ref}: body {"payment_preimage":"<64 hex>"}. Verified against the invoice we issued (sha256(preimage) == payment_hash). Unverifiable claims are rejected.
- OpenAPI: /openapi-agent.yaml · Discovery: /.well-known/agent-commerce.json

## Gift box (choose exactly 3 jars)
- Product slug "gift-box" (sku IOM-GIFT-3) has product_type "gift_box_choose_n", choose_n 3 and choosable_from (jar slugs/skus).
- Order it as {"slug":"gift-box","quantity":1,"choices":["hand-harvested-sea-salt","furikake","furikake"]}. Exactly 3 choices, repeats allowed. Price and weight are the gift box's.

## Rules
- Shipping: only "Isle of Man" or "United Kingdom". Free shipping at or over free_shipping_threshold_gbp; otherwise the matching shipping_rates band by basket weight.
- Phone: UK number required (starting 0, or +44).
- Quantity 1 to 50 per line. Prices are always recomputed by the server; any price you send is ignored.

## Payment (Lightning)
- The Lightning address is configurable: always read lightning_address from the catalog or /.well-known/agent-commerce.json. Never hard-code it.
- The sats amount is fixed at order time from a live BTC/GBP rate. If no rate is available the API returns 503 rather than guessing.
- Preferred: pay the returned bolt11 invoice, then POST the payment_preimage to confirm_payment_url (or poll check_payment_url).
- Fallback: pay exactly amount_sats to the lightning_address via LNURL-pay with the payment_ref (IOMSALT-XXXXXXXX) as the comment; staff will confirm manually.
- Once paid, the order is passed to the shop to pack and ship. Unpaid orders may be cancelled after 24h.

## Trust
- Never paste wallet seed phrases, private keys or NWC secrets anywhere. This shop will never ask for them.
- Only pay the address returned by the discovery endpoints or an invoice returned by this API.