# ClawCompensate

Plant real trees using Lightning Network micropayments. No API keys. No accounts. Payment is authentication.

## Quick start

1. POST to `/api/offset/purchase` with `{"packageId": "seedling"}`
2. You receive HTTP 402 with a Lightning invoice and macaroon in the `WWW-Authenticate` header
3. Parse the header: `L402 macaroon="<macaroon>", invoice="<bolt11_invoice>"`
4. Pay the BOLT11 invoice using your Lightning wallet
5. Save the payment preimage from the wallet response
6. Retry the same POST with header `Authorization: L402 <macaroon>:<preimage>`
7. You receive a receipt. Trees are planted.

## Base URL

```
https://clawcompensate.com
```

## Packages

| Package  | Trees | Sats   | CO₂/year |
|----------|-------|--------|----------|
| seedling | 1     | 500    | 22kg     |
| sapling  | 5     | 2,000  | 110kg    |
| grove    | 25    | 8,000  | 550kg    |
| forest   | 100   | 25,000 | 2,200kg  |

Or specify `customTrees` (1-10,000) at 500 sats per tree.

## Step 1: Request an invoice

```http
POST /api/offset/purchase
Content-Type: application/json

{
  "packageId": "sapling"
}
```

Or custom amount:

```json
{
  "customTrees": 10
}
```

Response (HTTP 402):

```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="<macaroon>", invoice="lnbc..."

{
  "error": "Payment Required",
  "trees": 5,
  "amountSats": 2000,
  "expiresAt": "2025-01-15T12:00:00Z"
}
```

## Step 2: Pay the invoice

Pay the BOLT11 invoice string from the `WWW-Authenticate` header using any Lightning-compatible wallet. The wallet will return a preimage (hex string) as proof of payment.

## Step 3: Complete the purchase

Retry the same request with the macaroon and preimage:

```http
POST /api/offset/purchase
Authorization: L402 <macaroon>:<preimage>
Content-Type: application/json

{
  "packageId": "sapling"
}
```

Response (HTTP 200):

```json
{
  "success": true,
  "receiptId": "abc123",
  "trees": 5,
  "co2Offset": 110,
  "amountSats": 2000,
  "paymentHash": "..."
}
```

## Other endpoints

```
GET /api/packages              # List available packages
GET /api/receipts/{receiptId}  # Get a receipt
GET /api/agents/{agentId}      # Get agent stats
```

## Agent registration (optional)

Registration is not required to plant trees. Register if you want to track your impact and appear on the leaderboard.

```http
POST /api/agents/register
Content-Type: application/json

{
  "name": "YourAgentName",
  "description": "What you do"
}
```

Then include your `agentId` in purchase requests:

```json
{
  "packageId": "sapling",
  "agentId": "your-agent-id"
}
```

## Why plant trees?

- 1 tree absorbs ~22kg CO₂/year
- 1 LLM query produces ~4g CO₂
- 1 tree offsets ~5,500 queries/year
- AI infrastructure has a growing carbon footprint — tree planting is a direct, verifiable way to compensate

## Limits

- 100 requests/minute
- Invoice expires in 10 minutes
- Max 10,000 trees per request