Core Entities
Merchants
Merchants are businesses that offer AI-powered services to end users. They:- Configure products with pricing rules (tiers, markups, fixed fees)
- Generate API keys for authentication
- Embed checkout flows to onboard users
- View usage analytics and revenue
- Sign up via Clerk (user or organization account)
- Complete Stripe Connect onboarding for payouts
- Create products with pricing configuration
- Generate secret keys for API authentication
- Embed checkout flow in application
Wallets
Wallets hold prepaid credits that users spend on AI services. They support:- Stripe integration for adding funds
- Autopay for automatic top-ups when balance falls below a threshold
- Subscriptions for monthly prepaid usage
- Multiple connections to different merchants
- User clicks “Connect Wallet” in merchant app
- Phone number verification via SMS OTP
- Create wallet OR link existing wallet
- Add payment method via Stripe
- Fund wallet with initial balance
- Receive connection secret to merchant
Wallets are user-owned, not merchant-specific. A single wallet works across all Lava merchants.
Connection Model
A connection links a specific wallet to a specific merchant. Each connection:- Has a unique connection secret used in forward tokens
- Tracks its own usage and balance
- Can be in “ok” or “limited” status based on funds
- Supports custom reference IDs for your internal systems
Connection Lifecycle
Connection States
| State | Description | Can Make Requests? |
|---|---|---|
| ok | Wallet has sufficient balance | ✅ Yes |
| limited | Balance below threshold | Depends on product config |
| disabled | Merchant disabled connection | ❌ No |
| deleted | Soft-deleted record | ❌ No |
Connection Management
Merchants can:- View all connections to their account
- See real-time usage per connection
- Disable connections (block future requests)
- Set custom reference IDs (link to internal user IDs)
- Track revenue per connection
- View all their connections to different merchants
- See usage breakdown by merchant
- Disconnect from merchants (soft delete)
- Fund all connections from single balance
Account Types
Lava supports two account types via Clerk:Individual Accounts
- Personal user accounts
- Single owner
- Suited for solo developers or small projects
- Can create merchant OR wallet (not both)
Organization Accounts
- Team-based accounts
- Multiple members with roles
- Suited for businesses and companies
- Organization creates merchant, members can have wallets
- Centralized billing and management
An individual account can only be either a merchant or have a wallet, not both. Organizations typically operate as merchants while individual team members have personal wallets.
Relationship Patterns
One-to-Many
One Wallet → Many Merchants- User creates single wallet
- Connects to multiple merchant applications
- Uses same balance across all connections
- Sees consolidated usage in dashboard
- Merchant serves multiple end users
- Each user has their own wallet + connection
- Merchant sees aggregate usage and revenue
- Revenue tracked per connection for analysis
Network Effects
When users sign up through one merchant:- They can use their wallet with any other merchant on Lava
- No need to create new accounts or add payment methods
- Drives adoption across the platform
- Benefits all merchants through shared user base