Magic Sphere

A Magic Sphere oracle that charges 100 sats per question using Cashu ecash and the L402 payment protocol.

How payments work

User asks question
       ↓
Server creates Cashu mint quote → Lightning invoice (100 sats)
       ↓
User scans QR code & pays
       ↓
Mint marks invoice PAID
       ↓
Server mints ecash proofs → saved to data/proofs.json  ← money claimed here
       ↓
Server returns Magic Sphere answer
       ↓
Operator visits /admin to melt ecash proofs → Lightning withdrawal

L402 protocol flow

Step	Detail
POST /api/ask	Returns 402 + WWW-Authenticate: L402 token="…", invoice="lnbc…"
User pays invoice	Via any Lightning wallet
POST /api/ask + Authorization: L402 <token>	Server verifies payment, mints ecash proofs, returns answer

Setup

cp .env.example .env   # fill in SERVER_SECRET and ADMIN_SECRET at minimum
npm install
npm start

Open http://localhost:3000.

Environment variables

Variable	Default	Description
MINT_URL	https://mint.minibits.cash/Bitcoin	Cashu NUT-04 mint
AMOUNT_SATS	100	Price per question
SERVER_SECRET	random	HMAC key for L402 tokens
ADMIN_SECRET	(unset)	Password for the admin panel
PORT	3000	HTTP port

Withdrawing earnings

Ecash proofs accumulate in data/proofs.json. To withdraw:

1. Open your Lightning wallet and generate a receive invoice.
2. Navigate to http://localhost:3000/admin?secret=<ADMIN_SECRET>.
3. Paste the invoice and click Melt & Withdraw.

The server spends the stored Cashu proofs to pay your invoice through the mint. Any change from proof denominations is saved back as new proofs.

You can also use the API directly:

# Check balance
curl -H "x-admin-secret: <ADMIN_SECRET>" http://localhost:3000/admin/balance

# Withdraw to a Lightning invoice
curl -X POST \
  -H "x-admin-secret: <ADMIN_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"invoice":"lnbc..."}' \
  http://localhost:3000/admin/withdraw

Requirements

• Node.js ≥ 18
• A publicly accessible Cashu mint supporting NUT-04 (/v1/mint/quote/bolt11 and /v1/mint/bolt11)