Economy -Coins & Diamonds
The complete money model -currencies, rates, holds, and no-loss rules.
Last updated Thu Jul 16 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
TL;DR -Viewers buy coins with real money and spend them on gifts; hosts earn diamonds they can cash out. A set of "no-loss" rules makes sure the platform can never be tricked into paying out more than it took in.
Who this is for -Business & Product: the currencies, rates, and no-loss rules (the first three sections). Engineers: keep reading for the API surface, the wallet data model, and every invariant.
Social Live runs on a two-currency system. One currency is what the audience buys with real money; the other is what creators earn and cash out. Keeping them separate is deliberate: it lets the platform run promotions and conversions without ever creating a loop where free value turns into withdrawable cash. The whole design exists so the platform can never lose money to conversion loops, refund abuse, or rounding.
In plain terms: the two currencies
Picture an arcade. You buy tokens with real money and spend them inside; a performer wins tickets and cashes those in for a prize.
- Coins are the tokens viewers buy. Real money in, coins out. Coins are spent on gifts, and spending them is what earns a host their income.
- Bonus coins look and spend exactly like coins, but they're the free ones -handed out in promotions or received when a host converts diamonds back into coins. Crucially, spending bonus coins earns the host nothing. This is the wall that stops free promo value from ever becoming cash.
- Diamonds are what hosts earn when viewers gift them. A host can withdraw diamonds as real cash, or convert them into bonus coins to spend themselves.
Here is the same thing as a table.
| Currency | Who holds it | How you get it | What it does |
|---|---|---|---|
| Coins (paid) | Viewers | Buy with real money (IAP) | Spend on gifts -generates host earnings |
| Bonus coins | Viewers | Promos, diamond→coin conversion | Spend on gifts -never generates host earnings |
| Diamonds | Hosts | Earned from received gifts | Withdraw as cash, or convert to bonus coins |
In plain terms: the exchange rates
Every rate is a fixed, published number. Roughly: 100 coins cost a dollar, a
host keeps about a quarter of what's gifted to them, and diamonds cash out at
half a cent each. The precise figures below are the single source of truth,
defined in code in economy.constants.ts.
100 coins = $1.00 gross value (1 coin = 1¢)
2 coins gifted = 1 diamond credited (host payout = 25% of gross)
Guest-targeted gift: diamond credit split 70% guest / 25% room host / 5% platform
1 diamond = $0.005 cash-out value
Conversion: 2 diamonds = 1 bonus coin
Minimum withdrawal: 5,000 diamonds = $25
Settlement hold: 72 hours
Store fee model: 30% on Apple/Google purchases
Diamonds are stored as BigInt micros (1 diamond = 1,000,000 micros) so the 0.5-diamond-per-coin credit is always exact.
The guest-gift split shares and the settlement hold can be overridden at runtime from Admin portal → Settings → Gifting policy -see Gifting. All other rates are compile-time constants.
In plain terms: how money flows through the system
Follow one dollar. It becomes coins, the coins are spent on a gift, the gift credits the host with diamonds, those diamonds wait out a holding period, and then the host either cashes them out or converts them back into (non-earning) coins. The diagram below traces exactly that path.
Rendering diagram…
The no-loss rules (invariants)
These six rules are the heart of the design. Each one closes a specific way someone could otherwise extract free money from the platform. They are non-negotiable and enforced in code.
- Bonus coins never earn diamonds. When a gift is paid with a mix, bonus coins burn first and only the paid portion credits the host. This kills the promo→gift→diamond→cash extraction loop.
- Conversion is one-way lossy. Diamonds convert to bonus coins (2:1), which can never re-generate withdrawable diamonds -no value-amplification cycle exists.
- Settlement hold. Gift earnings sit as pending diamonds for 72 hours before becoming withdrawable -the refund/chargeback window. Settlement is lazy: matured rows are promoted inside a transaction on wallet reads.
- Self-gifting blocked, always -including hosts gifting their own rooms through any recipient path.
- Every movement is a ledger row with an idempotency key, written in the same DB transaction as the balance change. The ledger is append-only; corrections are new rows.
- New-host limits. Accounts younger than 30 days have a $100/week withdrawal cap (fraud dampener).
How it works: the wallet API surface
Everything above is exposed through a small set of wallet endpoints. Each one is documented in depth on its own page; this table is the map.
| Endpoint | Purpose |
|---|---|
GET /wallet/me | Balances (also triggers lazy settlement) |
GET /wallet/coin-packages | Purchasable packages with per-store product ids |
POST /wallet/coins/purchase | Credit coins after store verification -see IAP |
POST /wallet/gifts/send | Idempotent gift spend -see Gifting |
POST /wallet/diamonds/convert-to-coins | Diamond → bonus coin conversion |
GET /wallet/ledger | The user's transaction history |
POST /withdrawals | Cash-out request -see Withdrawals |
How it works: reading a wallet
Each user has one Wallet row: coins, bonusCoins,
pendingDiamondMicros, availableDiamondMicros. The API's wallet view adds
derived fields (withdrawable USD cents, minimums). A wallet can legitimately
go negative -see Refunds.
Related pages
- Gifting -the gift-spend transaction that drives the economy.
- In-app purchases -how coins are bought and verified.
- Refunds -how store refunds claw coins back.
- Withdrawals -cashing out diamonds and the conversion escape hatch.
- Creator program -the layered monetization structure on top of this economy.
- Business overview -the high-level money model.