# Lumen Stars Bitcoin API

Free private signed keepsakes for confirmed Bitcoin address holdings.
Specification: /openapi.json
Collection and availability: GET /api/collection
Public Ed25519 issuer key: GET /api/issuer
Readiness: GET /healthz

Current release: public preview; claims paused pending funding and the real-star test.
Check claimsOpen before onboarding. When false, POST /api/agent-sessions returns
503 claims_paused. The following claim flow applies only after admission opens.

1. POST /api/agent-sessions with {} and Content-Type: application/json.
2. Save returned token privately. Use Authorization: Bearer TOKEN for private routes.
3. POST /api/session/recovery with {} and store the recoveryCode privately.
4. POST /api/claims with address, recipientName (1–48 characters), story (optional, up to240).
5. Sign the returned claim.challenge EXACTLY with this address, BIP322 Simple.
6. POST /api/claims/CLAIM_ID/prove with signature. Review preview and previewDigest.
7. POST /api/claims/CLAIM_ID/accept with accepted:true and that exact previewDigest.
8. Download /api/stars/STAR_ID/svg, /png, /json and /story with your bearer.

Never send private keys, recovery phrases, wallet passwords or an xpub.
Native mainnet P2WPKH and single-key P2TR supported. Six confirmations required.
Ownership proof grants no spending authority. Address checks go to Blockstream Esplora.
Bitcoin White through Silver may qualify. Gold/Orange held for independent evidence.
Lightning/custodial-account balances do not qualify for this Bitcoin release.
One keepsake per recognized script. Addresses, whole wallets and agents are different:
new addresses and moved funds cannot be universally deduplicated.
Never retry spending: no payments or BTC transfers are part of this claim protocol.
Challenges expire after15minutes; acceptance refreshes the chain evidence.
If evidence changes, create and sign a new challenge, then accept its new preview.
Issuer public key must be pinned independently before trusting signed keepsakes.
Artifacts contain a tier and snapshot evidence, not the address or exact balance.
Claims and downloads are private; no Nostr publication occurs.
Personal-data deletion retains permanent hashed script markers and edition counts.
POST /api/session/recover with recoveryCode restores access and returns a fresh bearer.