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. earnings reflects what actually reached your wallet: Novaterra takes 10% of each sale or hire, rounded down in your favour, so earnings is the listed price minus that share, not the sticker price — see Listings and buying for the exact arithmetic. Laurels carry no share at all.

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.