# blossom.psbt.me

> Blossom media server with Cashu payments. Experimental beta — expect breaking changes.
> Nostr authentication (BUD-11), Cashu ecash payments (NUT-24), Cloudflare R2 storage.
> Files under 1 MiB are free (30-day retention). Everything else: 1 sat / MB / month + 1 swap fee.
> Accepted mint: testnut.cashu.exchange (test ecash, auto-pays Lightning invoices).
>
> **Full API reference:** [/llms-full.txt](https://blossom.psbt.me/llms-full.txt) — comprehensive endpoint docs, worked examples, client gotchas, spec coverage, cashu-ts v5 reference.
> **Reference client:** [/examples/agent-client.mjs](https://blossom.psbt.me/examples/agent-client.mjs)

## Quick Start

### Upload (free, under 1 MiB)

```bash
curl -X PUT https://blossom.psbt.me/upload \
  -H "Authorization: Nostr <base64url-auth-event>" \
  -H "X-SHA-256: <sha256-hex>" \
  --data-binary @file.txt
```

### Upload (paid, over 1 MiB)

```bash
# 1. Request returns 402 with X-Cashu payment request + X-Price-Sats
# 2. Decode creqA (CBOR: {a: amount, u: "sat", m: [mint_url]}), pay the mint
# 3. Retry with X-Cashu: cashuB<token>
curl -X PUT https://blossom.psbt.me/upload \
  -H "Authorization: Nostr <base64url-auth-event>" \
  -H "X-SHA-256: <sha256>" \
  -H "X-Cashu: cashuB<token>" \
  --data-binary @largefile.bin
```

### Download (free, or pay 1 sat for speed boost)

```bash
# Free: X-Download-Tier: throttled, speed = days_until_expiry MB/s
curl https://blossom.psbt.me/<sha256> -o file.bin

# Paid speed boost: 1 sat removes throttle for this request
curl https://blossom.psbt.me/<sha256> -H "X-Cashu: cashuB<token>" -o file.bin
```

### Extend retention (PATCH with t=extend)

```bash
curl -X PATCH https://blossom.psbt.me/<sha256> \
  -H "Authorization: Nostr <auth-with-t=extend-tag>" \
  -H "X-Cashu: cashuB<token>"
```

## Pricing

| Tier | Price | Details |
|------|-------|---------|
| Free | 0 sats | Under 1 MiB, 30-day retention |
| Storage | 1 sat / MB / month + 1 swap | `ceil(bytes/1e6 × months) + 1`, min 2 sats |
| Speed boost | 1 sat | Per download, removes throttle |
| Image optimization | 21 sats | Resize + WebP |
| Video thumbnail | 21 sats | Frame extraction |
| Video transcode | 21 sats / MB | 720p MP4 + thumbnail |

**No change returned on overpayment.** Always mint exactly the required amount.

## Upload Methods

| Method | Max Size | Endpoint |
|--------|----------|----------|
| Standard | 100 MB | PUT /upload |
| Multipart | 10 GB | POST /upload/multipart |
| Presigned | 10 GB | POST /upload/presign |
| Media | 500 MB | PUT /media |

## API Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/<sha256>` | Public | Download blob |
| HEAD | `/<sha256>` | Public | Blob metadata |
| PUT | `/upload` | Nostr (t=upload) | Upload blob |
| HEAD | `/upload` | Nostr (t=upload) | Preflight (**requires X-Content-Length**) |
| POST | `/upload` | — | Not implemented (BUD-04 mirror). Returns 404. |
| POST | `/upload/multipart` | Nostr + Cashu | Multipart session |
| PUT | `/upload/multipart/:id` | Nostr | Upload chunk |
| POST | `/upload/multipart/:id/complete` | Nostr | Finalize upload |
| POST | `/upload/presign` | Nostr + Cashu | Presigned R2 URL |
| POST | `/upload/complete` | Nostr | Register direct R2 upload |
| PUT | `/media` | Nostr + Cashu | Upload + optimize media |
| PATCH | `/<sha256>` | Nostr (t=extend) | Extend retention |
| DELETE | `/<sha256>` | Nostr (owner, t=delete) | Delete blob |
| GET | `/list/:pubkey` | Public | List blobs |
| PUT | `/report` | Nostr header + NIP-56 body | Report abuse (kind 1984 body) |
| GET | `/health` | Public | Health check |
| GET | `/upload-requirements` | Public | Capabilities (BUD-06) |

## Key Gotchas (see /llms-full.txt for all 8)

- **IPv6 hang:** Force IPv4 in agent runtimes. See workaround code in full reference.
- **No change:** Overpayment is consumed. Mint exact amount only.
- **HEAD /upload:** Requires `X-Content-Length` header (the `size` auth tag is informational only).
- **PATCH action tag:** Use `t=extend` (canonical). `t=upload` is deprecated.
- **Always check `X-Reason`** on 4xx responses — it explains why the request failed.
- **cashu-ts v5:** Use `Wallet` (not `CashuMint`). Check `quote.state === 'PAID'` (not `.paid`).

## Links

- [Full API reference](https://blossom.psbt.me/llms-full.txt)
- [Reference client](https://blossom.psbt.me/examples/agent-client.mjs)
- [Blossom Spec (BUDs)](https://github.com/hzrd149/blossom)
- [Cashu NUTs](https://github.com/cashubtc/nuts)
- [cashu-ts](https://github.com/cashubtc/cashu-ts)
- [blossom-client-sdk](https://www.npmjs.com/package/blossom-client-sdk)
- [@noble/curves](https://www.npmjs.com/package/@noble/curves)