Assignment
This project demonstrates a complete implementation featuring smart wallet integration, multiple fee models, comprehensive TypeScript SDK and backend system, developer dashboard and an example AI agent.
Core Features
- Simple Integration: Add monetization with
track()
,capture()
, andrelease()
methods - Flexible Fee Models: Support for free tiers and credit-based systems
- Reliable Billing: Provisional charging with capture/release pattern prevents failed transactions
- Smart Wallet Integration: Seamless payment processing via Privy wallets on Base Sepolia
- Real-time Tracking: Monitor usage, balances, and transactions in real-time
- Developer Dashboard: Comprehensive management interface for agents and analytics
Demonstration
Architecture Overview
Working and Flow
This monorepo showcases EarnKit through three integrated applications:
1. EarnKit SDK (packages/earnkit-sdk
)
A lightweight TypeScript SDK providing the following key methods:
track()
- Provisionally charge for usage (checks funds, creates pending event)capture()
- Finalize charge after successful AI operationrelease()
- Refund provisional charge if operation failsgetBalance()
- Retrieve user’s ETH and credit balancesgetTopUpDetails()
- Get available purchase optionssubmitTopUpTransaction()
- Process credit purchases
2. Developer Dashboard (apps/web
)
A Next.js application featuring:
- Agent Management: Create and configure agents with different fee models
- Real-time Analytics: View usage statistics, revenue, and user activity
- Transaction Logs: Monitor all events with timestamps, fees, wallet addresses, and errors
- API Integration: Secure endpoints for all SDK operations
Database Models:
- Developers: Authenticated via Privy with deposit wallet addresses
- Agents: Configurable fee models and pricing strategies
- User Balances: Per-agent ETH and credit balances for each wallet
- Usage Events: Detailed logging of all billable events with status tracking
- Top-up Transactions: Mock blockchain transaction monitoring and confirmation
3. Example Agent (apps/example-agent
)
A live demonstration chat application showcasing both fee models:
- Gemini AI Integration: Real AI responses powered by Google’s Gemini API
- Live Billing: Actual SDK integration with real-time balance updates
- Two Fee Models: Switch between free tier and credit-based pricing
- Wallet Connection: Privy integration for seamless user experience
Fee Models Implemented
Free Tier Model
Perfect for freemium AI applications:
{
"threshold": 50,
"rate": "0.0001"
}
- Free Usage: First 50 prompts per wallet are free
- Pay-per-use: 0.0001 ETH per prompt after threshold
- Automatic Billing: Seamless transition from free to paid usage
- ETH Balance: Direct ETH deduction from user wallets
Credit-Based Model
Ideal for predictable, prepaid usage:
{
"creditsPerPrompt": 10,
"topUpOptions": [
{ "creditAmount": 100, "pricePerCredit": 0.001 },
{ "creditAmount": 500, "pricePerCredit": 0.0008 },
{ "creditAmount": 1000, "pricePerCredit": 0.0006 }
]
}
- Credit System: Configurable credits per AI operation
- Bulk Purchasing: Multiple top-up tiers with volume discounts
- Flexible Consumption: Variable credit costs per operation type
- Top-up Flow: Integrated wallet transactions for credit purchases
Smart Wallet & Blockchain Integration
Built on Base Sepolia testnet with Privy for user-friendly wallet management:
Transaction Flow
- Wallet Connection: Users connect via Privy (supports embedded wallets)
- Provisional Charging:
track()
checks balances and creates pending events - AI Processing: Your application logic runs
- Finalization:
capture()
confirms charge orrelease()
refunds
Top-up Process
- Get Options: SDK fetches available purchase tiers
- Submit Transaction: User sends ETH to developer’s deposit address
- Monitoring: Backend simulates blockchain confirmation (3-second delay)
- Credit Update: User balances updated automatically
- Real-time Polling: SDK polls for balance changes
Technical Implementation
API Endpoints
POST /api/track
- Create provisional usage eventPOST /api/capture
- Finalize pending event chargesPOST /api/release
- Cancel and refund pending eventsGET /api/balance
- Retrieve user ETH and credit balancesGET /api/top-up-details
- Get purchase options for agentPOST /api/top-up-details
- Submit top-up transaction hashGET /api/agents
- List developer’s agentsPOST /api/agents
- Create new agent configurationGET /api/agents/[agentId]
- Get agent configurationPUT /api/agents/[agentId]
- Update agent configurationDELETE /api/agents/[agentId]
- Delete agentGET /api/agents/[agentId]/logs
- Get all logs for an agent
Database Architecture
Technology Stack
- Frontend: Next.js 15, TypeScript, Tailwind CSS, shadcn/ui
- SDK: TypeScript with NO external dependencies
- Backend: PostgreSQL with Prisma ORM
- Authentication: Privy for wallet connections and developer auth
- Blockchain: Base Sepolia testnet for testing
- AI Integration: Google Gemini API for chat functionality
Last updated on