# 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://isleofmansaltco.com **Payment for AI agents: Lightning Network.** This shop accepts Lightning payment on the agent API path (bolt11 invoice preferred, LNURL-pay fallback, optional preimage confirmation). Agents do not pay by card. Humans check out by card (SumUp) 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 (array of absolute image URLs), size_label, weight_grams, price_gbp, vat_rate, stock_quantity, in_stock, url) 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. GET /api/agent/v1/quote?country=...&items= (or repeated slug=...&qty=...) returns the same result for clients that cannot POST. - 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. Optional header Idempotency-Key: a repeat with the same key within ~10 minutes returns the original order (best-effort). - 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. ## Voucher codes (optional) - Quote and create-order accept an optional "voucher_code" (body field; GET quote: ?voucher_code=...). Codes are supplied to customers by the shop; no code is advertised here. - When applied, responses include voucher_code, voucher_effect and voucher_discount_gbp, and totals/amount_sats reflect it. - An invalid, expired or used-up code returns 400 with code voucher_invalid (it is never silently ignored). ## Responses and errors - Every JSON response includes "api_version": "1". - Errors are {"error": "...", "code": "..."}. Stable codes: out_of_stock, invalid_country, invalid_phone, gift_box_choices, quantity_limit, product_not_available, invalid_request, fx_unavailable, payment_unverified, not_found, rate_limited, voucher_invalid. - SKU and slug inputs are trimmed of surrounding whitespace. Response slugs remain database identifiers. The quote and order endpoints also accept chilli-sea-salt for red-chilli-sea-salt and furikake-seasoning for furikake, including gift-box choices. Use catalog url fields for public product links. - Only products listed in the catalog can be ordered through this API; anything else returns product_not_available. ## Rules - Shipping: only "Isle of Man" or "United Kingdom". Free shipping at or over free_shipping_threshold_gbp (currently £50, so a basket of £50.00 or more ships free to both Isle of Man and United Kingdom); otherwise priced per parcel. No weight is refused: heavy baskets are split into parcels at the largest band max_grams plus one remainder parcel, and quotes return parcel_count and parcel_weights_grams. - 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) - order_number looks like IOMSALT-100 (digits); payment_ref looks like IOMSALT-XXXXXXXX (8 characters from A-H, J-N, P-Z and 2-9). The payment comment must be the payment_ref, never the order_number. - 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. The shop marks the order paid automatically (wallet webhook); poll status_url or check_payment_url and you will see payment_status "paid" without posting a preimage. - Optional faster path: POST the payment_preimage to confirm_payment_url. - Fallback: pay exactly amount_sats to the lightning_address via LNURL-pay with the payment_ref (IOMSALT-XXXXXXXX) as the comment; it is matched automatically by reference and exact amount. - The sats amount is locked when the order is created. Do not re-quote after creating an order; pay the order's amount_sats / invoice. - LNURL fallback payments must be exactly amount_sats. Under- or over-payments are not matched automatically; prefer the bolt11 invoice. - Stock is only reserved (decremented) when an order is paid, not when it is created. A pending unpaid order does not hold stock. - Once paid, the order is passed to the shop to pack and ship. Unpaid orders may be cancelled after about 24h. - If this API is unreachable, hand the basket to a human with the product page links (https://isleofmansaltco.com/product/{urlSlug}/) to buy by card on the website. ## Contact - Email: agents@isleofmansaltco.com (agent and order support) - For order questions, include order_number and payment_ref (IOMSALT-…) when you have them - Do not send wallet seed phrases, private keys or NWC credentials by email or anywhere else ## 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.