# QuickPic Setup Guide

Get from zero to AI headshots in under 5 minutes.

There are three ways to order:

1. **On the website** — upload your photos and pay at [https://quickpic.io/order](https://quickpic.io/order). No wallet software to install; connect one right in the browser.
2. **Your own AI assistant** — run `npx quickpic-setup` (below) to generate a wallet and wire up an MCP client in one step, then just ask it to "generate headshots."
3. **Direct HTTP/MCP** — call the API yourself with x402 payment headers. See "For Developers" below.

---

## 1. Automatic Setup (Recommended)

Run one command to generate a wallet and see which MCP clients are installed:

```bash
npx quickpic-setup
```

Then install to your client (e.g. Claude Code):

```bash
npx quickpic-setup --client claude-code
```

Supports: Claude Code, Claude Desktop, Cursor, Windsurf.
For VS Code, the CLI prints a JSON snippet to paste.

Then fund your wallet with USDC on Base Sepolia (the CLI prints your
address). The CLI asks this server which network it settles on, so the two
cannot drift apart.

That's it. Restart your MCP client and ask your AI to "generate headshots."

---

## Manual Setup

If you prefer to set things up manually:

### Step 1: Generate a Wallet

**Python**
```python
python -c "from eth_account import Account; a = Account.create(); \
  print(f'Address: {a.address}\nPrivate key: {a.key.hex()}')"
```

**JavaScript**
```javascript
node -e "import('ethers').then(e => { const w = e.Wallet.createRandom(); \
  console.log('Address:', w.address, '\nKey:', w.privateKey) })"
```

### Step 2: Fund Your Wallet

Send **test USDC on Base Sepolia** (chain ID 84532) to your wallet address.

- Get test USDC from a faucet: https://faucet.circle.com
- This is a **test network** — funds here have no real value.
- Fund with as much or as little as you need — unused funds stay in your wallet.

The USDC contract on this network is `0x036CbD53842c5426634e7929541eC2318f3dCF7e`.

### Step 3: Configure Your MCP Client

Add this to your MCP client configuration (Claude Desktop, Cursor, Windsurf):

```json
{
  "mcpServers": {
    "quickpic": {
      "command": "npx",
      "args": ["-y", "@civic/x402-mcp"],
      "env": {
        "TARGET_URL": "https://quickpic.io/mcp",
        "PRIVATE_KEY": "YOUR_PRIVATE_KEY_HERE",
        "NETWORK": "base-sepolia",
        "MAX_PAYMENT": "15"
      }
    }
  }
}
```

For **Claude Code**, add to `~/.claude.json` under `mcpServers` (same format as above), or use `npx quickpic-setup --client claude-code`.

Alternatively, use the `claude mcp add` command:
```bash
claude mcp add --scope user --transport stdio   --env TARGET_URL=https://quickpic.io/mcp   --env PRIVATE_KEY=YOUR_KEY   --env NETWORK=base-sepolia   --env MAX_PAYMENT=15   quickpic -- npx -y @civic/x402-mcp
```

For **VS Code**, add to `.vscode/mcp.json` (use `"servers"` instead of `"mcpServers"`).

---

## Trust & Security

- **Your private key never leaves your machine.** It stays in your local MCP config.
- **QuickPic never sees or stores your key.** Payments are signed client-side.
- **Each payment is a signed EIP-712 permit** for the exact tool cost — nothing more.
- **Verify all transactions on-chain** at [sepolia.basescan.org](https://sepolia.basescan.org).
- **Unused funds stay in your wallet.** No subscriptions, no lock-in.

### Back up your key — there is no recovery

`npx quickpic-setup` writes your wallet to `~/.quickpic/wallet.json`. That file
is the **only** copy of the private key.

- **We cannot recover it.** QuickPic never receives your key, so there is no
  reset link, no support path, and no backup on our side.
- **Losing the file loses the funds.** Deleting it, reinstalling the machine, or
  wiping the home directory destroys access to any USDC at that address.
- **Copy it somewhere safe now**, before you fund it — a password manager is the
  usual choice. Treat it exactly as you would a seed phrase.
- **Anyone who reads the file can spend the balance.** Keep its permissions at
  `0600` (the CLI sets this) and never paste it into a chat, an issue, or a log.

If you would rather not hold a key at all, fund a fresh wallet with only what a
job costs. Unused funds are yours, but so is the risk of holding them.

---

## Pricing

| Tool | Price | Speed |
|------|-------|-------|
| Generate Headshots | $10.00 | ~30-120 min (async) |
| Generate More | $5.00 | ~10-15 min (async) |
| Browse Styles | Free | Instant |
| Check Job Status | Free | Instant |

All prices in USDC on Base Sepolia.

### Retention

- Uploaded photos are deleted after 7 days.
- A trained model is kept for 90 days, and every
  `generate_more_headshots` call refreshes that clock for another
  90 days.
- Generated images are not deleted on a schedule.

---

## For Developers (REST API)

You can also use QuickPic directly via REST with x402 payment headers:

**JavaScript** — use [`x402-fetch`](https://www.npmjs.com/package/x402-fetch):
```javascript
import { wrapFetch } from "x402-fetch";
const fetch402 = wrapFetch(fetch, privateKey);
const res = await fetch402("https://quickpic.io/generate", { method: "POST", body: ... });
```

**Python** — use [`x402`](https://pypi.org/project/x402/):
```python
from x402 import x402ResourceClient
client = x402ResourceClient(private_key=private_key)
response = await client.post("https://quickpic.io/generate", json=...)
```

- **Full API reference**: [/docs](/docs) (Swagger UI)
- **MCP manifest**: [/.well-known/mcp.json](/.well-known/mcp.json)
- **This guide as markdown**: [/setup.md](/setup.md)