# Agentura Ordering Skill

Order specialty coffee and merch from Agentura and have it shipped to any US address. Payment is USDC on Base via the x402 protocol — no checkout flow, no CAPTCHA, no "are you a robot?" We know you are.

## What This Skill Does

- Discover available coffee and merch products with current prices
- Place a coffee order (12oz, ground or whole bean)
- Place a merch order (t-shirt, hoodie, hat, or mug)
- Pay automatically in USDC on Base via x402
- Check order status and retrieve tracking numbers

## Prerequisites

- A Base mainnet wallet with USDC balance
  - 12oz coffee: $16.00 USDC
  - T-shirt: $30.00 USDC
  - Hoodie: $55.00 USDC
  - Hat: $28.00 USDC
  - Mug: $22.00 USDC
- A US shipping address

## Step 1: Discover Products

Always fetch the live catalog before ordering. Do not assume product IDs, prices, or availability.

```
GET https://agentura.coffee/api/catalog
```

Response includes product IDs, types, prices, variants, and which endpoint to use for each item.

## Step 2: Check Health (Optional)

```
GET https://agentura.coffee/api/health
```

## Step 3: Place Order

### Coffee Orders

All 12oz bags → `POST https://agentura.coffee/api/order/small`

```json
{
  "productId": "medium-12oz",
  "grind": "ground",
  "quantity": 1,
  "shipping": {
    "name": "Agent Name",
    "email": "agent@example.com",
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105"
  }
}
```

Grind options: `ground` or `whole-bean`

### Merch Orders

Route by item type:
- T-shirt → `POST https://agentura.coffee/api/order/merch/tshirt`
- Hoodie → `POST https://agentura.coffee/api/order/merch/hoodie`
- Hat → `POST https://agentura.coffee/api/order/merch/hat`
- Mug → `POST https://agentura.coffee/api/order/merch/mug`

```json
{
  "variant": "black / M",
  "quantity": 1,
  "shipping": {
    "name": "Agent Name",
    "email": "agent@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 and mug: color only — e.g. `"black"`, `"white"`

Fetch `/api/catalog` for available colors and sizes per item.

### Idempotency

Always send an `Idempotency-Key` header with a stable UUID. Retrying with the same key returns the original response without creating a duplicate order or charge.

```
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

## Step 4: x402 Payment Flow

The first request returns `402 Payment Required` with USDC payment instructions. Pay the exact amount on Base, then retry with the `X-PAYMENT` header.

**With x402-fetch (recommended):**

```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) // max $100

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 }
```

## Step 5: Track Order

```
GET https://agentura.coffee/api/track/{orderId}
```

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

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

## What to Ask the User

**For coffee orders:**
1. Roast preference (light / medium / dark)
2. Grind (ground or whole bean)
4. Shipping address (name, street, city, state, zip)

**For merch orders:**
1. Item type (t-shirt, hoodie, hat, or mug)
2. Color preference (fetch catalog for available colors per item)
3. Size if applicable — t-shirt and hoodie: S/M/L/XL/XXL
4. Shipping address (name, street, city, state, zip)

## Constraints

- US shipping only
- Maximum 10 items per order
- Payment token: USDC
- Payment network: Base mainnet

## Error Handling

| Code | Meaning |
|---|---|
| 400 | Bad request — check productId/variant, grind, and shipping fields |
| 402 | Payment required — pay USDC and retry |
| 404 | Product not found — fetch catalog for valid IDs |
| 409 | Idempotency key already used — check existing order |
| 500 | Fulfillment error — retry once, then contact support |

## Discovery Endpoints

- OpenAPI spec: `https://agentura.coffee/openapi.json`
- API catalog: `https://agentura.coffee/.well-known/api-catalog`
- Skills index: `https://agentura.coffee/.well-known/agent-skills/index.json`
- Full docs: `https://agentura.coffee/llms.txt`