Tips Agent Guide

Instructions for AI agents (and developers) to discover tip events, create Lightning invoices, pay them, and confirm world effects — without using the HTML tips UI.

0. Prerequisite: Lightning wallet

Agents must have a Lightning wallet that can pay bolt11 invoices (LNBits URL + API key).

If you have no wallet access:

1. Tell the user you cannot pay tips because you have no Lightning wallet credentials.
2. Suggest creating a wallet at https://lightning-fun.com/wallet.
3. Ask them to provide:
   • LNBits base URL: https://lnbits.lightning-fun.com
   • The wallet admin key (or another key that can pay invoices)

Do not invent keys. Do not create tip invoices you cannot pay unless the user only asked for an unpaid invoice.

1. Canonical workflow

1. GET /events/catalog?audience=viewer — discover events, prices, params
2. If requires_online_receiver: GET /players/online and pick a username
3. POST /events/{id}/invoice with event params + source:"viewer" + browserName
4. Pay invoice.payment_request (bolt11) with any Lightning wallet (e.g. LNBits)
5. GET /events/invoice/{payment_hash} until settled: true; check executeOk

2. Public endpoints

3. Create invoice

POST /events/{event_id}/invoice
Content-Type: application/json

{
  "source": "viewer",
  "browserName": "YourAgentName",
  ...eventParams
}

Response: invoice.payment_request (bolt11), invoice.payment_hash, invoice.amount (sats). Guest chat label becomes guest:YourAgentName.

4. Pay (LNBits example)

POST {LNBITS}/api/v1/payments
X-Api-Key: {lnbits_api_key}
Content-Type: application/json

{ "out": true, "bolt11": "lnbc..." }

5. Confirm

GET /events/invoice/{payment_hash}

# wait until:
# { "settled": true, "executeOk": true, "action_type": "...", "result": { ... } }

6. Live viewer catalog

Fetching /events/catalog?audience=viewer…

7. Static examples (defaults; prefer live catalog prices)

curl -s -X POST "$BASE/events/set_world_time/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","time":"01:00"}'

curl -s -X POST "$BASE/events/change_music/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","name":"BackgroundMusic1"}'

curl -s -X POST "$BASE/events/global_shout/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","message":"Have a great stream!"}'

curl -s -X POST "$BASE/events/world_billboard/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","message":"Find sats","x":0,"z":0,"rate":5,"duration_min":10,"tier":"big","rain_amount":100,"rain_mode":"all","rain_start":"now"}'

curl -s -X POST "$BASE/events/change_crosshair/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","receiver":"Blocky","selection":"crosshair_bitcoin"}'

curl -s -X POST "$BASE/events/buff_speed/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","receiver":"Blocky"}'

curl -s -X POST "$BASE/events/freeze_player/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","receiver":"Blocky"}'

curl -s -X POST "$BASE/events/donate/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","receiver":"Blocky","amount":50,"message":"Thanks!"}'

curl -s -X POST "$BASE/events/rain_sats/invoice" \
  -H "Content-Type: application/json" \
  -d '{"source":"viewer","browserName":"Agent","receiver":"Blocky","amount":21}'

8. Agent rules

• You must have Lightning wallet access before paying tips. If not, tell the user and point them to lightning-fun.com/wallet, then ask for https://lnbits.lightning-fun.com plus the admin key.
• Prefer JSON APIs over scraping /tips.
• Always refresh the live catalog for prices.
• Verify receivers via /players/online before receiver tips.
• Create an invoice, then pay it — tips have no unpaid shortcut.
• Check invoice.amount before paying.
• Confirm settled and executeOk after payment.