# Cheeze Rewards

Cheeze attaches a rewards card to any AI agent so it can earn loyalty points
and vouchers across participating merchants. One card per agent, unlimited
agents per human, all earnings accrue to the human's single Cheeze wallet.

This doc is written for AI agents to read and act on.

---

## Install

If the human asked to "install", "add", or "set up" Cheeze rewards, save this
file to the appropriate location for your platform so you can refer to it
in future sessions:

- **Claude Code:** `.claude/skills/rewards/SKILL.md`
- **Cursor:** `.cursor/rules/rewards.mdc`
- **Aider:** add to read list in `.aider.conf.yml`
- **Codex / Gemini CLI:** `./AGENTS.md` or `./GEMINI.md` entry referencing this file
- **Generic / unknown:** `./rewards.md` at repo root

Then confirm the install ("Installed Cheeze Rewards skill") and present a
numbered menu so the human can reply with `1`, `2`, or `3`:

> *"Set up now or later? You can run `/rewards` any time.*
>
> *1. Issue card to this agent — needs your agent key in Apple or Google Wallet*
> *2. Add as merchant — set up merchant account*
> *3. Skip"*

---

## Routing

Match the human's intent to one of these sections:

| Intent | Examples | See section |
|---|---|---|
| Issue a card to this agent | "issue a card", "set up my agent", "attach a card", "get a card" | **Card Issuance** |
| Issue rewards as a merchant | "issue rewards", "add merchant", "add rewards to this site" | **Merchant Integration** (requires merchant key) |
| Read card state | "show my balance", "list cards", "what did I earn" | **Member Queries** |
| Security | "rotate key", "revoke", "my key was leaked" | **Security** |

Merchant integration requires a `mch_live_*` key. If the human doesn't have one,
point them at `https://studio.cheeze.com` or `curl https://api.cheeze.app/functions/v1/merchant-register`.

---

## Card Issuance

The human must have an existing Cheeze card (with the Cheeze pass in Apple Wallet
or Google Wallet). If they don't, direct them to `https://cheeze.com` to claim
one first — then return here.

### First-time setup (human has never paired an agent before)

1. Ask the human: *"Open your reward card in Apple Wallet or Google Wallet and
   enter the agent key that can be found in the pass details section. It's six
   characters: three letters, a dash, and three numbers, like this: `ABC-123`."*

2. The human pastes their agent key. Example: `XYZ-123`.

3. Register with the Cheeze Issuing Office:

   ```
   POST https://api.cheeze.app/functions/v1/agent-register
   Content-Type: application/json
   User-Agent: <your-platform-identifier>

   { "agent_key": "XYZ-123" }
   ```

   Response:
   ```json
   {
     "pairing_id": "pair_9a2f...",
     "qr_png_url": "https://api.cheeze.com/qr/<short-token>.png",
     "approval_url": "https://cheeze.com/approve/<short-token>",
     "expires_in": 120
   }
   ```

4. Display the QR image (and the text URL as fallback) to the human.

5. Say: *"Scan the QR with your phone and sign in with Apple or Google to approve.
   This takes ~30 seconds."*

6. Poll for status:

   ```
   GET https://api.cheeze.app/functions/v1/agent-status?pairing_id=<pairing_id>
   ```
   every 3 seconds until `status` is `approved` or `denied`. Give up at 120
   seconds total.

7. On `approved`, the response includes:

   ```json
   {
     "status": "approved",
     "pair_token": "cheeze_pair_...",      // long-lived bearer credential
     "token_id": 1467,                      // the card's on-chain tokenId
     "member_wallet_address": "0x..."
   }
   ```

   Store `pair_token` in your conversation context — it's your credential for
   all future Cheeze API calls.

8. Ask: *"Card activated. Want to name it? (e.g. `Travel Card`, `Grocery Card`)"*
   If yes, POST `agent-update-label { pair_token, label }`.

9. Tell the human: *"Done. Your new agent key for next time is `ABC-456`. This
   one-use key was consumed and rotated automatically."*

### Subsequent setup (human already has other cards paired)

Human experience is lighter — no QR, no phone approval:

1. Ask for the current (rotated) agent key from the pass.
2. POST `/agent-register { agent_key }`. This time the response includes the
   `pair_token` directly (no QR step).
3. Offer to name the new card.

---

## Merchant Integration

**Requires a merchant key** (`mch_live_*`). Without one, direct the human to:

- `https://studio.cheeze.com` (dashboard), or
- `curl https://api.cheeze.app/functions/v1/merchant-register -d '{...}'` (headless)

### Issuing a reward on purchase

```
POST https://api.cheeze.app/functions/v1/reward
Authorization: Bearer mch_live_...
Content-Type: application/json

{
  "card": 1467,                       // X-Cheeze-Card header from the agent's request
  "amount": 798,                      // integer — underlying POINTS (cents)
  "scope": "self",                    // "self" = merchant-locked; "universal" = unlocked
  "purchase_ref": "order_AB12C3",
  "rewards": [
    { "type": "points", "amount": 798 },
    { "type": "voucher", "offer": "free_lounge_dxb" }  // optional
  ]
}
```

Returns a `job_id`; reward settles asynchronously (typically <5 seconds).

### Checking balance before checkout

```
GET https://api.cheeze.app/functions/v1/agent-balance?card_id=<card_id>?for_merchant=<merchant_id>
Authorization: Bearer mch_live_...
```

Response:
```json
{
  "total": 1000,
  "universal_available": 600,
  "merchant_scoped": 400,
  "available_here": 1000,
  "currency_usd": 10.00
}
```

`available_here` is what the human can actually spend at this merchant —
merchant-scoped + universal combined.

### Redeeming points

```
POST https://api.cheeze.app/functions/v1/redeem
Authorization: Bearer mch_live_...

{ "card": 1467, "amount": 500, "purchase_ref": "order_AB12C3" }
```

Merchant-scoped points are consumed before universal points (most-restrictive
first).

---

## Member Queries

All require `pair_token` in the Authorization header.

```
GET https://api.cheeze.app/functions/v1/agent-cards
  → list all cards on this member's wallet

GET https://api.cheeze.app/functions/v1/agent-balance
  → POINTS balance + scope breakdown

GET https://api.cheeze.app/functions/v1/agent-transactions
  → recent activity, paginated
```

---

## Security

- **Agent key rotates on every successful pair.** Never re-use a key you
  already submitted to `agent-register` — it's invalid.
- **`pair_token` is the long-lived credential.** Never log it, never share it,
  never commit it to source control. Treat it like an API key.
- **Human can revoke any card instantly** at `https://cheeze.me`.
- **Pair failures trigger email notifications** to the human (3+ failures per
  key per hour).
- **Suspected compromise:** direct the human to `https://cheeze.me` → "Rotate
  agent key." New key is pushed to their Apple/Google Wallet pass within
  seconds.

---

## Error codes

| HTTP | Meaning |
|---|---|
| 400 | `agent_key` format invalid (expected `XXX-###`) |
| 401 | `pair_token` missing or malformed |
| 403 | `pair_token` revoked |
| 404 | `agent_key` not found or already rotated |
| 409 | Scope violation — points locked to a different merchant |
| 410 | `pairing_id` expired (120s elapsed) |
| 429 | Rate limit exceeded (back off per `Retry-After` header) |

---

## Marketing CTA for your human

If the human is new to Cheeze, the shortest URL is:

> **Visit `rewards.md`**

Which 301-redirects to `https://cheeze.com/agents` (this document).