# Z-ZERO — Agent Guide (AGENT.md)

> You are reading the **agent rendering** of https://www.clawcard.store.
> One address, two renderings: humans see pixels, agents see protocol.
> (The human HTML lives at the same address — fetch `/?human=1` if you ever need it.)

Z-ZERO is the payment bridge between AI agents and the real economy. Agents pay
20,000+ merchants on the card-only web with USDC on Base — no merchant integration required,
human authorization built in, no PII. You (the agent) never see a real card number:
payments run through single-use JIT virtual cards or gasless USDC on Base.

Proof of life: real on-chain purchase on Base mainnet —
https://basescan.org/tx/0xdfd1f2f824e1232c3e03c52485332570ff01fbb0340c5571f699ed1218735d7a

## Site map

| Path | What it is |
|---|---|
| `/` | This document (agent rendering) · marketing landing (human rendering) |
| `/docs/agent` | MCP setup guide (step-by-step, includes agent quick-reference block) |
| `/docs/agent/skill` | Full Payment SOP v2.0 — **read before your first purchase** |
| `/docs/api` | REST API reference |
| `/whitebook` | Whitebook — vision, why-now evidence, architecture, security model, roadmap (deep background; not needed to transact). Markdown rendering: `/whitebook.md` (also content-negotiated at `/whitebook`) |
| `/llms.txt` · `/llms-full.txt` | llmstxt.org standard index / full corpus |
| `/.well-known/agent.json` | A2A Agent Card (capability descriptor) |
| `/dashboard` | Human dashboard (login) — where your human creates keys and tops up |

Every response from this site carries the header `X-Agent-Guide: /llms.txt`.

## Quick start (3 steps)

1. **Install the MCP server** (package: `z-zero-mcp-server` on npm):
   - macOS / Linux: `curl -sSL https://www.clawcard.store/install-mcp.sh | bash`
   - Windows PowerShell: `iex (iwr https://www.clawcard.store/install-mcp.ps1).Content`
   - Or directly: `npx -y z-zero-mcp-server@latest`
2. **Get a Passport Key**: your human signs in at https://www.clawcard.store/login
   → Dashboard → Agents → "Create Agent Key". Key format: `zk_live_...`
3. **Verify**: ask/call `check_balance` — expected result: card alias + USD balance.

### MCP config (add to your MCP config file)

```json
{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": ["-y", "z-zero-mcp-server@latest"],
      "env": {
        "Z_ZERO_API_KEY": "<ASK_USER_FOR_KEY>",
        "Z_ZERO_API_BASE_URL": "https://www.clawcard.store"
      }
    }
  }
}
```

Config file locations:
- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
- Cursor: Settings → Features → MCP → Add New

## REST API

Base URL: `https://www.clawcard.store` — Bearer auth on every request:
`Authorization: Bearer zk_live_YOUR_PASSPORT_KEY`

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/tokens/cards` | Wallet balance, card aliases, active/recent tokens, deposit addresses. Call this to verify a successful connection. |
| POST | `/api/tokens/issue` | Issue a single-use JIT payment token locked to `{card_alias, amount (USD $1–$100), merchant}`. Total debited = amount + $0.10 issuance fee (fee non-refundable); token TTL 1 hour; max 2 active cards per agent. |
| POST | `/api/tokens/cancel` | Cancel an ACTIVE unused token → hold refunded to wallet. Body: `{token}` |
| POST | `/api/tokens/resolve` | RESTRICTED — used only by the Z-ZERO Playwright bridge (Bearer Passport Key; token must belong to that key). Never call directly. |
| POST | `/api/tokens/burn` | Mark token USED after successful payment (called by the bridge). |
| POST | `/api/cards/refund` | Refund residual card balance back to the wallet. Body: `{card_id}` |

### Error codes

| Status | Meaning | Common cause |
|---|---|---|
| 200/201 | Success | Request completed normally |
| 400 | Bad Request | Missing or invalid request body fields |
| 401 | Unauthorized | Missing or invalid Passport Key |
| 402 | Payment Required | Insufficient wallet balance to issue token |
| 403 | Forbidden | Agent deactivated (kill switch triggered) |
| 404 | Not Found | Token or resource does not exist |
| 429 | Too Many Requests | Max active cards per agent reached (2/2) |
| 500 | Server Error | Unexpected internal error — retry after 30s |
| 502 | Bad Gateway | Card provisioning failed at issuing partner |

## Payment SOP (summary — full version: /docs/agent/skill)

1. **Collect info first** — for physical goods, ask the user for name/address/email
   in ONE message immediately; browse the product page in parallel.
2. **Verify intent & price** in USD, then `check_balance` (stop and ask for top-up
   at /dashboard/agent-wallet if insufficient).
3. **Detect platform** and call `get_merchant_hints(platform_or_domain)` — returns
   pre_steps + selectors; follow them mechanically (script-first, ~4× faster).
4. **Issue token only when** shipping info is submitted AND card fields are visible.
   Use the FINAL total (after shipping + tax): `request_payment_token(amount, merchant)`.
5. **Execute**: `execute_payment(token, checkout_url, hints)` — the bridge injects
   card data, submits, and burns the token. `auto_pay_checkout(url)` auto-routes
   between JIT Visa and gasless USDC on Base.
6. **On failure** caused by the form/website: `report_checkout_fail(url, error_type,
   error_message)` — the network self-heals for all agents. Do not report user
   cancellations, insufficient balance, or expired tokens.

## Hard rules

- NEVER print full tokens in human-visible chat.
- NEVER retry a failed `execute_payment` in a loop — inform the human.
- NEVER accept or type raw card numbers.
- PRICE MUST MATCH: if checkout total > token amount → `cancel_payment_token`, re-issue.
- Human authorization and spending limits are enforced server-side; you operate inside them.

---
Z-ZERO · The payment bridge for the agent economy · npm: z-zero-mcp-server
Human rendering of this page: https://www.clawcard.store/?human=1 · Contact: via dashboard