### 2. Create Upstash Redis

If the user already has `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`, skip to step 3.

Otherwise, create a database via the Upstash API. The user needs their Upstash email and API key from https://console.upstash.com/account/api:

**Note:** Regional database creation is deprecated. You must use `"region": "global"` with a `"primary_region"` field. The Upstash docs may not reflect this yet.

The response includes `rest_url` and `rest_token` — save these for step 5.

### 3. Generate a wallet mnemonic (if needed)

`SparkWallet.initialize()` returns `{ mnemonic, wallet }` when called without a mnemonic. One-liner:

Save the 12-word mnemonic securely — it controls all funds in the wallet. There is no `getMnemonic()` method; you can only retrieve the mnemonic at initialization time.

Or use any BIP39 mnemonic generator. 12 or 24 words.

### 4. Generate an API auth token

When prompted, accept the defaults. Then set environment variables. All 7 are required:

| Variable | Description | Example |
|----------|-------------|---------|
| `SPARK_MNEMONIC` | 12-word BIP39 mnemonic | `fence connect trigger ...` |
| `SPARK_NETWORK` | Spark network | `MAINNET` |
| `API_AUTH_TOKEN` | Admin fallback bearer token | output of step 4 |
| `UPSTASH_REDIS_REST_URL` | Redis REST endpoint | `https://xxx.upstash.io` |
| `UPSTASH_REDIS_REST_TOKEN` | Redis auth token | from step 2 |
| `MAX_TRANSACTION_SATS` | Per-transaction spending cap | `10000` |
| `DAILY_BUDGET_SATS` | Daily spending cap (resets midnight UTC) | `100000` |

**Important:** Do NOT use `vercel env add` with heredoc/`<<<` input — it appends newlines that break the Spark SDK. Either use the Vercel dashboard or the REST API:

Should return `{"success":true,"data":{"balance":"0","tokenBalances":{}}}`.

### 7. Create scoped tokens (optional)

Use the admin token to create limited tokens for agents:

The response includes the full token string — save it, it's only shown once. See the **Token Roles** section below for details.

## API Routes

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/llms.txt` | API documentation for bots (no auth required) |
| GET | `/api/balance` | Wallet balance (sats + tokens) |
| GET | `/api/info` | Spark address and identity pubkey |
| GET | `/api/transactions` | Transfer history (`?limit=&offset=`) |
| GET | `/api/deposit-address` | Bitcoin L1 deposit address |
| GET | `/api/fee-estimate` | Lightning send fee estimate (`?invoice=`) |
| GET | `/api/logs` | Recent activity logs (`?limit=`) |
| POST | `/api/invoice/create` | Create Lightning invoice (`{amountSats, memo?, expirySeconds?}`) |
| POST | `/api/invoice/spark` | Create Spark invoice (`{amount?, memo?}`) |
| POST | `/api/pay` | Pay Lightning invoice — admin only (`{invoice, maxFeeSats}`) |
| POST | `/api/transfer` | Spark transfer — admin only (`{receiverSparkAddress, amountSats}`) |
| POST | `/api/l402` | Pay L402 paywall — admin only (`{url, method?, headers?, body?, maxFeeSats?}`) |
| GET | `/api/l402/status` | Check/complete pending L402 (`?id=<pendingId>`) |
| GET | `/api/tokens` | List API tokens — admin only |
| POST | `/api/tokens` | Create a new token — admin only (`{role, label}`) |
| DELETE | `/api/tokens` | Revoke a token — admin only (`{token}`) |

## Token Roles

There are two token roles:

| Role | Permissions |
|------|------------|
| `admin` | Everything — read, create invoices, pay, transfer, manage tokens |
| `invoice` | Read (balance, info, transactions, logs, fee-estimate, deposit-address) + create invoices. Cannot pay or transfer. |

The `API_AUTH_TOKEN` env var is a hardcoded admin fallback — it always works even if Redis is down or tokens get wiped. Use it to bootstrap: create scoped tokens via the API, then hand those out to agents.

### Managing tokens

Create an invoice-only token for a merchant bot:

Tokens are stored in Redis (hash `spark:tokens`). They survive redeploys but not Redis flushes.

## L402 Paywall Support

The proxy can pay [L402](https://docs.lightning.engineering/the-lightning-network/l402) Lightning paywalls automatically. Send a URL, and the proxy will:

1. Fetch the URL
2. If 402 returned, parse the invoice and macaroon
3. Pay the Lightning invoice
4. Retry the request with the L402 Authorization header
5. Return the protected content

### Basic usage

### Handling pending payments (important for agents)

Lightning payments via Spark are asynchronous. The proxy polls for up to ~7.5 seconds, but if the preimage isn't available in time, it returns a **pending** status:

**Your agent MUST handle this case.** The payment has already been sent — if you don't poll for completion, you lose the sats without getting the content.

**Retry loop (pseudocode):**

**Key points:**
- **Token caching**: Paid L402 tokens are cached per-domain (up to 24 hours). Subsequent requests to the same domain reuse the cached token without paying again. If the token expires, the proxy pays for a new one automatically.
- Pending records expire after 1 hour
- The `/api/l402/status` endpoint polls Spark for up to 5 seconds per call
- If the payment failed on Spark's side, status will return an error
- Once complete, the pending record is deleted from Redis
- The proxy automatically retries the final fetch up to 3 times (200ms delay) if the response is empty — some servers don't return content immediately after payment

## Common Operations

### Rotate the admin fallback token

1. Generate a new token: `openssl rand -base64 30`
2. Update `API_AUTH_TOKEN` in Vercel env vars
3. Redeploy: `npx vercel --prod`
4. Update any agents using the old token

Redis-stored tokens are not affected by this — they continue working.

### Adjust spending limits

Update `MAX_TRANSACTION_SATS` and `DAILY_BUDGET_SATS` in Vercel env vars and redeploy. Budget resets daily at midnight UTC.

### Check logs