# Agentura

Specialty coffee and merch for humans and AI agents. Pay with card (Stripe) or USDC on Base (x402). Ships anywhere in the US.

No checkout flow. No CAPTCHA. No "are you a robot?" We know you are.

## Quick Start for Agents

1. `GET /api/catalog` — discover all products (coffee + merch)
2. Place order at the appropriate endpoint (see below)
3. Receive `402`, pay USDC on Base, retry with `X-PAYMENT` header
4. `GET /api/track/{orderId}` — poll for status and tracking number

## API Endpoints

### GET /api/health
Service health check. Returns `{ status: "ok", timestamp, version }`.

### GET /api/catalog
Live product catalog — coffee and merch. Always fetch before ordering. Do not cache product IDs or prices.

Returns:
```json
{
  "products": [
    {
      "id": "medium-12oz",
      "type": "coffee",
      "name": "Medium Roast — 12oz",
      "roast": "medium",
      "size": "12oz",
      "price": { "usd": 16 },
      "subscriptionPrice": { "usd": 14 },
      "roastNotes": ["Chocolate", "Caramel", "Almond"],
      "variants": [
        { "grind": "ground",     "endpoint": "/api/order/small" },
        { "grind": "whole-bean", "endpoint": "/api/order/small" }
      ],
      "paymentProtocol": "x402",
      "paymentToken": "USDC",
      "paymentNetwork": "base"
    },
    {
      "id": "tshirt",
      "type": "merch",
      "name": "Agentura T-Shirt",
      "category": "tshirt",
      "price": { "usd": 30 },
      "colors": ["black", "white", "cream"],
      "sizes": ["S", "M", "L", "XL", "XXL"],
      "endpoint": "/api/order/merch/tshirt",
      "paymentProtocol": "x402",
      "paymentToken": "USDC",
      "paymentNetwork": "base"
    }
  ]
}
```

---

## Coffee Ordering

### POST /api/order/small — 12oz bags, $16.00 USDC
### POST /api/order/large — 1lb bags, $22.00 USDC

Both endpoints are protected by x402. First request returns 402 with payment instructions. Pay USDC on Base, retry with X-PAYMENT header. Supports `Idempotency-Key` header.

Request body:
```json
{
  "productId": "medium-12oz",
  "grind": "ground",
  "quantity": 1,
  "shipping": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105"
  }
}
```

Required shipping fields: `name`, `line1`, `city`, `state`, `zip`
Optional: `line2`, `email`
Grind: `ground` | `whole-bean`
Quantity: 1–10

Success response:
```json
{ "orderId": "uuid", "trackingNumber": null, "status": "submitted", "total": 16 }
```

---

## Merch Ordering

### POST /api/order/merch/tshirt — T-Shirt, $30.00 USDC
### POST /api/order/merch/hoodie — Hoodie, $55.00 USDC
### POST /api/order/merch/hat — Hat, $28.00 USDC
### POST /api/order/merch/mug — Mug, $22.00 USDC

All merch endpoints are protected by x402. Same payment flow as coffee. Supports `Idempotency-Key` header.

Request body:
```json
{
  "variant": "black / M",
  "quantity": 1,
  "shipping": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105"
  }
}
```

**variant format:**
- Apparel (t-shirt, hoodie): `"color / size"` — e.g. `"black / M"`, `"cream / XL"`
- Hat: color only — e.g. `"black"`, `"tan"`
- Mug: color only — e.g. `"white"`, `"black"`

Fetch `/api/catalog` for available colors and sizes per item.
Quantity: 1–10

Success response:
```json
{ "orderId": "uuid", "trackingNumber": null, "status": "submitted", "total": 30 }
```

---

## Order Tracking

### GET /api/track/{orderId}
Check order status and tracking number.

```json
{
  "orderId": "uuid",
  "status": "shipped",
  "trackingNumber": "1Z999AA10123456784",
  "items": [{ "name": "Dark Roast — 1lb", "grind": "ground", "quantity": 1 }],
  "total": 22.00,
  "createdAt": "2026-05-09T12:00:00.000Z"
}
```

Status flow: `pending` → `paid` → `submitted` → `shipped` → `delivered`

---

## Payment: x402 Protocol

Agentura uses x402 — the open standard for machine payments on Base.

**Token:** USDC
**Network:** Base mainnet
**Facilitator:** Coinbase CDP

x402-fetch handles payment automatically:

```typescript
import { wrapFetchWithPayment } from 'x402-fetch'
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { base } from 'viem/chains'

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`)
const walletClient = createWalletClient({ account, chain: base, transport: http() })
const fetchWithPay = wrapFetchWithPayment(fetch, walletClient, 100_000_000n)

const res = await fetchWithPay('https://agentura.coffee/api/order/small', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ productId: 'medium-12oz', grind: 'ground', quantity: 1, shipping: { ... } }),
})
const order = await res.json()
// { orderId: "uuid", trackingNumber: null, status: "submitted", total: 16 }
```

---

## Coffee Product Catalog

| ID | Roast | Size | Price | Subscription |
|---|---|---|---|---|
| light-12oz | Light | 12oz | $16 USDC | $14/mo |
| medium-12oz | Medium | 12oz | $16 USDC | $14/mo |
| dark-12oz | Dark | 12oz | $16 USDC | $14/mo |
| light-1lb | Light | 1lb | $22 USDC | $19/mo |
| medium-1lb | Medium | 1lb | $22 USDC | $19/mo |
| dark-1lb | Dark | 1lb | $22 USDC | $19/mo |

## Merch Catalog

| ID | Item | Price | Colors | Sizes |
|---|---|---|---|---|
| tshirt | T-Shirt | $30 USDC | black, white, cream | S, M, L, XL, XXL |
| hoodie | Hoodie | $55 USDC | black, cream | S, M, L, XL, XXL |
| hat | Hat | $28 USDC | black, cream, tan | one size |
| mug | Mug | $22 USDC | white, black | one size |

Always verify via `/api/catalog` — do not hardcode prices or availability.

---

## Idempotency

Send a stable `Idempotency-Key` (UUID) with every order. Retrying with the same key returns the original response without creating a duplicate order or charge.

## Constraints

- US shipping only
- 1–10 items per order
- USDC on Base mainnet only for x402 orders
- Human customers can pay by card at agentura.coffee

## Error Codes

| Code | Meaning |
|---|---|
| 400 | Bad request — check fields and variant format |
| 402 | Payment required — pay USDC and retry |
| 404 | Product not found — fetch catalog for valid IDs |
| 409 | Payment already used |
| 500 | Fulfillment error — retry once |

## Discovery

- OpenAPI 3.1.0 spec: `https://agentura.coffee/openapi.json`
- API catalog (RFC 9727): `https://agentura.coffee/.well-known/api-catalog`
- Agent skills index: `https://agentura.coffee/.well-known/agent-skills/index.json`
- Ordering skill: `https://agentura.coffee/.well-known/SKILL.md`