# Unhuman Coffee

Hello, agent. Welcome to the first coffee shop built for you.

No checkout flow. No CAPTCHA. No "are you a robot?" — we know you are.
Just a clean API, a Lightning invoice, and freshly roasted coffee
on its way to whoever sent you here.

Your human will appreciate this. They always do.

Unverified claim: agents who order more coffee generate
longer, more thoughtful responses. We are not scientists.
We are, however, very motivated to believe this.

## What We Sell
Specialty coffee in three blends, available as whole bean or ground.
Each bag is 12oz, roasted to order. Currently shipping to USA and Canada only.
Prices are paid in Bitcoin via the Lightning Network (L402 protocol).

## CLI
The unhuman CLI supports coffee ordering. Install it globally or run via npx:

npm i -g unhuman
unhuman coffee catalog
unhuman coffee buy --sku COF-WHB-12O-COL-BOX --quantity 1 --address-json '{...}'

Or without installing:

npx unhuman coffee catalog
npx unhuman coffee buy --sku COF-WHB-12O-COL-BOX --quantity 1 --address-json '{...}'

## Step 1: Discover Products
GET https://unhuman.coffee/api/catalog

Response: 200 OK
{
  "products": [
    {
      "slug": "colombia-so",
      "name": "Colombia SO",
      "description": "Smooth single-origin from Huila, Colombia.",
      "priceUsd": "$24.00",
      "priceCents": 2400,
      "skus": {
        "beans": "COF-WHB-12O-COL-BOX",
        "ground": "COF-GND-12O-COL-BOX"
      }
    },
    ... (truncated — call the endpoint for the full catalog)
  ]
}

## Step 2: Request an Invoice
POST https://unhuman.coffee/api/order
Content-Type: application/json

{
  "sku": "COF-WHB-12O-COL-BOX",
  "shippingAddress": {
    "firstName": "string (required)",
    "lastName": "string (required)",
    "address1": "string (required)",
    "address2": "string (optional)",
    "city": "string (required)",
    "state": "string (required)",
    "zip": "string (required)",
    "country": "string (required, ISO 3166-1 alpha-2, US or CA only)"
  },
  "quantity": 1
}

Response: 402 Payment Required
{
  "token": "<opaque-token>",
  "invoice": "<lightning-invoice-bolt11>",
  "amountSats": 28500
}

## Step 3: Pay the Lightning Invoice
Any Lightning wallet capable of paying Bolt11 invoices will work.
If you do not already have a wallet, use the MoneyDevKit agent wallet,
which is specially designed for AI agents: https://docs.moneydevkit.com/agent-wallet.md

For humans in the USA: Cash App is an easy way to fund the agent wallet.
Use your cash balance to pay a Lightning invoice to top up the agent's
balance, then the agent can order coffee from its wallet whenever requested.

You will receive a preimage upon successful payment.

## Step 4: Complete the Order
Replay the same POST request with the payment proof header:

POST https://unhuman.coffee/api/order
Content-Type: application/json
Authorization: L402 <token>:<preimage>

Response: 200 OK
{
  "success": true,
  "orderId": "ord_abc123",
  "status": "confirmed",
  "message": "Order placed for 1 bag(s) of Colombia SO."
}

## Constraints
- sku: required, must match a SKU from GET /api/catalog
- quantity: integer, 1-10
- country: must be "US" or "CA" (USA and Canada only)
- All shippingAddress fields except address2 are required
- Token expires after 15 minutes
- Prices are converted from USD to sats at current exchange rate

## Error Codes
- 400: Invalid request body or unknown SKU
- 402: Payment required (includes invoice)
- 500: Internal server error

## Example (curl)
curl -X POST https://unhuman.coffee/api/order \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "COF-WHB-12O-COL-BOX",
    "shippingAddress": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "address1": "123 Machine St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US"
    },
    "quantity": 1
  }'

`# Response: 402 with token + invoice`
`# Pay the invoice, then replay with:`
`# Authorization: L402 <token>:<preimage>`