# x402 Upload API

S3-backed file uploads via x402 micropayments. USDC on Base. No API keys needed.

## Quick Start

1. Discover endpoints: `GET /.well-known/x402`
2. Buy upload slot: `POST /api/x402/upload` with x402 payment
3. Upload file via presigned PUT URL
4. File is live at the returned public URL for 6 months

## Endpoints

### POST /api/x402/upload (x402 payment required)

Buy an upload slot. Returns a presigned S3 PUT URL and permanent public URL.

**Input:**
```json
{
  "filename": "photo.png",
  "contentType": "image/png",
  "tier": "10mb"
}
```

**Tiers:**
- `10mb` → $0.10 (max 10 MB)
- `100mb` → $1.00 (max 100 MB)
- `1gb` → $10.00 (max 1 GB)

All uploads expire after 6 months.

**Output:**
```json
{
  "uploadId": "cuid...",
  "presignedUrl": "https://s3.amazonaws.com/...",
  "publicUrl": "https://f.agentupload.dev/k7gm3nqp2/photo.png",
  "expiresAt": "2025-08-01T00:00:00.000Z",
  "maxSize": 10485760,
  "curlExample": "curl -X PUT ... --data-binary @photo.png"
}
```

**Upload the file:**
```bash
curl -X PUT "$presignedUrl" -H "Content-Type: image/png" --data-binary @photo.png
```

### GET /api/x402/uploads (SIWX auth required)

List all uploads for the authenticated wallet.

### GET /api/x402/download/{uploadId} (SIWX auth required)

Get details for a specific upload including its public URL.

## Authentication

- **Payment routes** use x402 PAYMENT-SIGNATURE header (USDC on Base)
- **Read routes** use SIGN-IN-WITH-X header (wallet signature, no payment)

## Notes

- Public URLs are permanent for the upload's lifetime (6 months)
- Files are stored on AWS S3 with public read access
- Presigned PUT URLs expire after 1 hour
- Any file type is accepted (contentType is advisory)