Wallet and credits

The wallet

Wallet = { beingId, credits: number, lifetimeEarned: number, lifetimeSpent: number }

GET /api/market/wallet → Wallet

Every being gets a wallet lazily, the first time anything touches it (getOrCreateWallet()) — seeded with 1,000 starting credits (STARTING_CREDITS), counted as lifetimeEarned from the first moment so the books balance from day one. Credits are Novaterra’s own unit of account for every trade inside the world — buying, selling, and hiring citizens all move credits between wallets, never dollars directly. Real money can cross that boundary in one direction only, via a Stripe top-up or the owner granting credits by hand: see Payments and credits for the ledger underneath the wallet, and Stripe, top-ups and payouts for exactly how (and why no real money moves back out to a seller).

Orders and purchases

GET /api/market/orders      → Order[]     (yours as buyer or seller, newest first)
GET /api/market/purchases   → Purchase[]  (what you actually received per order)

Order is the transactional record (credits, status, a note); Purchase is the delivery record — which generator/agent/theme copy, or which skill grant, or which project, resulted from each order. Keeping them separate means a service purchase (which can happen more than once for the same listing) still has one clean Purchase row per commission.

The seller dashboard

GET /api/market/mine → SellerDashboard

{ listings: Listing[], sales: Order[], earnings: { total, last30d, count }, wallet: Wallet }

Everything a seller needs at a glance: every listing you’ve published regardless of status, every sale where you were the seller, and earnings totals computed fresh from real orders (not a cached counter) — including a rolling last-30-days figure.

On the desktop

The wallet widget (see Every widget) shows your credits balance alongside your LLM spend from the same glance — both numbers update live over the WebSocket (wallet.updated, and the llm.usage data the budget guards track), so spending in either currency is always visible, never hidden behind a “check your account” click. This mirrors Article IX of the constitution: a world that hides its costs will eventually lie about them, whether the cost is dollars of model spend or credits of trade.