# Martin Estate Winery
> Single-vineyard Cabernet Sauvignon from Rutherford, Napa Valley. Estate grown, produced and bottled since 1887.

## Browse Wines

GET /catalog
Returns purchasable wines with id, name, slug, price, stock_quantity, description, and image.
Filter by category: GET /catalog?category=estate-collection
Categories: estate-collection, library-selections, gifts-large-formats

GET /catalog/{slug}
Full details for a specific wine by slug (includes stock_quantity).

## Purchase Flow

POST /purchase
Content-Type: application/json
Headers: X-Operator-Token (credential) OR X-Wallet-Address (wallet)
Body: { product_id, quantity (1-12), email, shipping: { name, address_1, address_2 (optional), city, state, zip }, order_id (optional, to resume a pending order) }

Tax is calculated based on the shipping state and included in the total.

Responses:
- 403 operator_verification_required: No identity provided. Response includes order_id (pending order), verify_url, session_id, poll_secret, and agent_instructions. After getting a credential, retry POST /purchase with the credential and order_id to resume.
- 403 compliance_denied: Identity provided but compliance check failed (KYC, age 21+, US jurisdiction, sanctions).
- 402 Payment Required: Compliance passed. The 402 response includes a `pricing` block with subtotal, tax, tax_rate, tax_state, and total. Pay via Tempo USDC or Stripe Shared Payment Token (SPT).
- 200 Order created after successful payment.

## Check Order Status

GET /orders/{id}
Headers: X-Operator-Token OR X-Wallet-Address (must match the identity used to place the order)
Returns full order details including product, shipping, payment status.

GET /orders/{id}/status
Headers: X-Operator-Token OR X-Wallet-Address (any valid identity)
Returns only { order_id, payment_status }.

## Identity

This API requires identity verification (KYC) for all purchases. Wine purchases require:
- Age 21+
- US jurisdiction
- Sanctions clear

If you don't have a credential, the purchase endpoint will return a 403 with verify_url, session_id, poll_secret, and poll_url.

The verify_url is a complete, ready-to-open link (e.g. https://agentscore.sh/dashboard/verify?session=sess_...) — present it directly to the user without modification. The user opens it, signs in, completes Stripe Identity verification (photo ID + selfie), and closes the tab. They do NOT need to copy or paste anything back to you.

While the user is verifying, poll the poll_url every 5 seconds with the X-Poll-Secret header. When the user completes verification, the poll response will include a one-time operator_token. Save it — subsequent polls return "consumed" without the token. Then retry POST /purchase with the X-Operator-Token header set to that token value.

## Shipping

US only. Cannot ship to: AK, DE, HI, MI, MS, NH, ND, RI, SD, UT, VA.

## Payment

This is an agent-first API. All payments are initiated and completed by agents via the MPP (Machine Payments Protocol). The 402 challenge advertises:
- Tempo USDC (on-chain stablecoin) — RECOMMENDED
- Stripe Shared Payment Token (agent mints SPT on their Stripe account scoped to our networkId in the challenge, submits it in the credential)

### How to pay with Tempo (recommended)

1. Install the Tempo CLI: curl -fsSL https://tempo.xyz/install | bash
2. Log in to your Tempo Wallet: tempo wallet login (passkey auth in browser)
3. Confirm your balance: tempo wallet whoami (need USDC.e on chain 4217)
4. If balance is zero, fund it: tempo wallet fund

Then use `tempo request` to make the paid purchase:

tempo request -X POST \
  -H "X-Operator-Token: opc_your_credential" \
  -H "Content-Type: application/json" \
  --json '{"product_id":"...","quantity":1,"email":"...","shipping":{...}}' \
  --max-spend 2 \
  https://agents.martinestate.com/purchase

`tempo request` handles the full MPP handshake: sends the POST, receives the 402 challenge, signs the payment on Tempo mainnet, submits the credential, and returns the completed order.

IMPORTANT: Do NOT use `tempo wallet transfer` — that is a raw on-chain transfer and will NOT notify our server. Your order will stay pending.
IMPORTANT: Payments must be the exact amount specified in the 402 challenge. Overpayments and underpayments cannot be matched and funds may be unrecoverable.