Skip to content

MVP Specifications

This document defines the smallest set of features that validate AI Wallet's core value with developers. Objective: Specify scope, requirements, and acceptance criteria to ship a usable MVP quickly and learn.

Key Insights

  • Core MVP modules (4–6 weeks solo):
  • Auth & funding: "Login with AI Wallet" + OpenRouter OAuth PKCE; Stripe prepaid credits (optional USDC), non-custodial.
  • Spend governance: per-user/app/org caps, velocity locks, anomaly kill switch; tamper-evident usage ledger.
  • Consent & audit receipts: who/what/model/provider/region/purpose/retention/cost/time; export/revoke.
  • SDKs: <WalletProvider/>, useWallet(), and server middleware/policy-edge proxy to enforce caps without handing out long-lived keys.
  • Vercel compatibility: BYOK support so teams keep their infra and still get wallets/budgets/consent.
  • Differentiation vs gateways/routers: cross-router identity, portable consent receipts, and multi-rail wallet — not routing.
  • Scope boundaries: integrate OpenRouter/Vercel as rails; avoid building a router; keep one backend per request to reduce latency/complexity.

Sources

  • archive/AI_Wallet_Topical_Threads/Competition-Narratives-MVPSpecs-04Nov25-ChatGPTPlus.pdf
  • archive/AI_Wallet_Topical_Threads/MVPPlan-CloudCredits-Angels-01Nov25-ChatGPTPlus.pdf

Decisions/Implications

  • Neutral layer above gateways; product value lives in identity, budgets, receipts, and distribution, not routing.
  • Security stance: short-lived capabilities, audience binding/TTL, policy-edge proxy from Day 1.
  • US-first; PKCE optional behind a flag if needed for early demos, but emphasize visible end-user value.

Goals and Success Criteria

Primary Goal

Validate AI Wallet's core value proposition by shipping a working MVP that demonstrates: - Cross-app user authentication and wallet functionality - Per-user/per-app budget controls with real-time enforcement
- Basic consent receipts and usage tracking - Developer-friendly SDK integration

Success Criteria (MVP)

  • [ ] 3-5 indie AI apps successfully integrated
  • [ ] 50+ end users with active wallet accounts
  • [ ] $1,000+ in wallet top-up volume
  • [ ] Sub-100ms overhead for budget checks
  • [ ] 99.5% uptime for core services
  • [ ] Zero security incidents (key leakage, unauthorized access)
  • [ ] Developer NPS score >7 for SDK experience

Key Metrics to Track

  • Apps integrated per week
  • Wallet users and retention
  • Credits consumed vs top-up volume
  • Average session time in wallet portal
  • Developer integration time
  • Budget enforcement accuracy

In-Scope and Out-of-Scope

In-Scope (MVP)

Core Infrastructure: - User authentication and account management - Wallet balance and Stripe integration - Budget creation and enforcement - Usage tracking and consent receipts - Developer SDK (React components) - Policy-edge proxy for single AI gateway - Basic dashboard for developers and users

User Experience: - Login with AI Wallet (OAuth) - Wallet top-up flow via Stripe - Per-app budget management - Usage history viewing - Simple consent interface

Developer Experience: - Drop-in React components: <AIWalletLoginButton />, <AIWalletPaywall />, <AIWalletBudgetGate /> - Server SDK for budget checking and usage logging - Dashboard for app configuration and metrics - Documentation and integration examples

Out-of-Scope (MVP)

Advanced Features: - Multi-gateway support (focus on one: Vercel AI Gateway OR OpenRouter) - Enterprise SSO/SAML integration - Advanced policy templates and AI Act compliance - Web3 rails (USDC, on-chain identity) - Custom router or model intelligence - Complex marketplace features - Mobile native applications - API rate limiting beyond basic usage controls - Advanced analytics and ML-based budget optimization

Enterprise Features: - Multi-tenant admin controls - Role-based access management - Integration with existing IAM systems - Custom compliance reporting - Enterprise billing and procurement integration

User Stories and Flows

Developer Persona (Indie AI App Builder)

Story 1: Basic Integration "As a developer building an AI chatbot, I want to integrate AI Wallet so that users can pay for usage without me handling billing infrastructure."

Acceptance Criteria: - [ ] Can add <AIWalletLoginButton /> to login flow - [ ] Can wrap chat interface with <AIWalletBudgetGate /> - [ ] Users can authenticate and top up via Stripe - [ ] Usage is tracked and budget limits enforced

Story 2: Usage Monitoring "As a developer, I want to see which models users are calling and how much they're spending."

Acceptance Criteria: - [ ] Dashboard shows total usage per user/app - [ ] Can view detailed call logs with timestamps - [ ] Can set basic per-user limits - [ ] Can export usage data as CSV

Story 3: Budget Controls
"As a developer, I want to prevent users from exceeding their budget limits."

Acceptance Criteria: - [ ] Can set monthly/weekly/daily budget limits - [ ] Requests are blocked when budget exceeded - [ ] Users receive clear error messages - [ ] Can implement grace period for limit breaches

End User Persona

Story 4: Wallet Setup "As an AI enthusiast, I want to create an AI Wallet so I can pay for multiple AI tools with one account."

Acceptance Criteria: - [ ] Can sign up with email or social login - [ ] Can add payment method via Stripe - [ ] Can view wallet balance and recent transactions - [ ] Can connect AI apps that support AI Wallet

Story 5: App Integration "As a user, I want to connect my AI Wallet to my favorite AI tools."

Acceptance Criteria: - [ ] Can authorize apps to use my wallet - [ ] Can see which apps are connected - [ ] Can set per-app spending limits - [ ] Can revoke app permissions

Story 6: Usage Control "As a user, I want to track and control my AI spending across apps."

Acceptance Criteria: - [ ] Can view usage history per app - [ ] Can set daily/monthly limits per app - [ ] Receive notifications when approaching limits - [ ] Can export usage data

Key User Flows

Developer Integration Flow: 1. Sign up as developer → Create app → Get API keys 2. Install AI Wallet SDK → Add login components 3. Configure budget policies → Deploy 4. Monitor usage in dashboard → Iterate

User Onboarding Flow: 1. Sign up/Login → Add payment method → Browse compatible apps 2. Connect app → Set budgets → Use app normally 3. Monitor spending → Adjust limits → Add/remove apps

Functional and Non-Functional Requirements

Functional Requirements

FR-001: Authentication - Support OAuth 2.0 with PKCE - Social login (Google, GitHub) + email/password - Session management with JWT (15-30 min expiry) - Refresh token support

FR-002: Wallet Management - Credit-based system (1 credit = $0.01) - Stripe integration for top-ups ($10, $20, $50) - Transaction history and balance tracking - Basic refund capability

FR-003: Budget Controls - Per-user, per-app budget limits - Support for daily/weekly/monthly limits - Real-time budget checking - Grace period for limit breaches

FR-004: Usage Tracking - Log all API calls with user, app, model, cost - Store consent receipts for each authorization - Export usage data as CSV/JSON - Basic filtering and search

FR-005: SDK Components - React login component - Budget gate component for AI calls - Paywall component for top-ups - Server-side budget checking API

Non-Functional Requirements

NFR-001: Performance - Budget check response time <100ms - User login <2 seconds - Dashboard load time <3 seconds - API throughput: 1000 requests/minute

NFR-002: Security - HTTPS everywhere - Encrypt API keys at rest - JWT with short expiry and refresh tokens - Rate limiting on all endpoints - Input validation and sanitization

NFR-003: Reliability - 99.5% uptime for core services - Handle Stripe webhook failures gracefully - Database backup and recovery procedures - Error logging and monitoring

NFR-004: Scalability - Support 10,000+ registered users - Handle 1M+ API calls per day - Horizontal scaling for gateway proxy - CDN for static assets

Acceptance Criteria and Test Plan

Test Categories

Unit Tests (Required: 80% coverage) - Authentication service methods - Budget calculation logic - Usage tracking functions - Stripe payment webhooks - API validation and sanitization

Integration Tests - End-to-end user signup and login - Complete payment flow (top-up → usage → billing) - Budget enforcement during API calls - Consent receipt creation and export

API Testing - All REST endpoints with valid/invalid inputs - OAuth flow testing - Rate limiting verification - Error handling and edge cases

SDK Testing - React component rendering - State management and prop passing - Error boundary handling - Browser compatibility (Chrome, Firefox, Safari)

Acceptance Test Scenarios

Scenario 1: New User Onboarding 1. User signs up → Account created 2. User adds payment method → Stripe setup complete
3. User adds $20 to wallet → Balance updated 4. User connects app → Authorization recorded 5. User makes AI call → Budget checked, call successful 6. User views usage → Transaction logged correctly

Scenario 2: Budget Limit Enforcement 1. User sets $5 daily limit 2. User makes calls totaling $4.50 → All successful 3. User makes additional $0.75 call → Blocked, error returned 4. User attempts to exceed limit → Blocked with clear message 5. User reduces limit → Enforcement updated immediately

Scenario 3: Developer Integration 1. Developer creates account → App created 2. Developer installs SDK → Components available 3. Developer adds login to app → OAuth flow works 4. Developer configures budget policies → Policies active 5. Developer tests with real user → Full flow validated

Open Questions and Assumptions

Key Assumptions

  • Users will prefer single wallet over managing API keys
  • Developers will integrate if SDK is simple enough
  • Stripe integration is sufficient for MVP (no crypto rails needed)
  • Single AI gateway (Vercel or OpenRouter) is adequate
  • Basic consent receipts meet initial compliance needs

Open Questions

  • Q1: Which AI gateway to prioritize for MVP? Vercel AI Gateway (strong developer ecosystem) vs OpenRouter (PKCE native) Decision needed: Week 1

  • Q2: What pricing model for developers? Freemium with usage limits vs. flat monthly fee vs. transaction percentage Recommendation: Freemium with 1000 free calls/month

  • Q3: How to handle failed payments? Suspend service vs. grace period vs. allow negative balance Recommendation: 3-day grace period

  • Q4: What level of consent complexity is needed? Simple app permission vs. model-specific consent vs. purpose-based consent Recommendation: Start simple (app-level) with basic model info

  • Q5: How to handle enterprise customers? Separate enterprise tier vs. scale up from individual accounts Recommendation: Individual-first, enterprise as later expansion

Risk Mitigation

  • Risk: Low developer adoption Mitigation: Focus on 3-5 well-known indie developers as design partners
  • Risk: Stripe integration complexity
    Mitigation: Use Stripe Checkout for simplicity, upgrade to custom flows later
  • Risk: Competitive response from gateways Mitigation: Position as complementary, emphasize cross-router benefits
  • Risk: Complex compliance requirements Mitigation: Start minimal, iterate based on actual customer feedback

Source Attribution

YC Demo Scope Constraints

YC-Specific MVP Requirements

For YC application demo (3-day build), prioritize these essential features:

Must-Have for YC Demo: - Dashboard: /wallet route showing login, balance, activity history - Chatbot App: /try route with Login with AI Wallet button - Real-time Balance: Visible credit deduction per message - Usage Receipts: Activity list showing model, cost, timestamp - Cross-App Proof: Wallet usage reflects chatbot activity

Nice-to-Have (Cuttable for 3-Day Timeline): - Complex RAG: Replace with hardcoded FAQs if needed - Multiple External Apps: Single demo app sufficient - Real Stripe Billing: Demo credits acceptable for YC - Profile Management: Email + placeholder avatar only

Technical Constraints for YC Timeline: - Single codebase (Next.js) with multiple routes - Fake "SDK" component (LoginWithAIWalletButton) - Minimal data model (users, apps, usage_events) - Simple Google OAuth for authentication - OpenRouter + Vercel AI SDK for LLM calls

Success Metrics for YC Demo: - Complete "wallet → app → wallet" flow - Clear balance movement and receipt generation - Professional enough UI to demonstrate concept - Working video of the full flow

YC Demo Architecture Overview

Two-Surface Demo Design: 1. AI Wallet Dashboard (/wallet): User's wallet interface showing balance and activity 2. Demo AI App (/try): External app integrating AI Wallet SDK

Loop Demonstration: - User starts in wallet dashboard ($5, no activity) - Navigate to demo app, login with AI Wallet - Use chatbot, watch credits decrease - Return to wallet, see usage activity from chatbot

Key Story: "One wallet, multiple apps, unified spend and consent"

Primary source: Competition-Narratives-MVPSpecs-04Nov25-ChatGPTPlus.pdf Supporting source: MVPPlan-CloudCredits-Angels-01Nov25-ChatGPTPlus.pdf YC Demo Requirements: yc-071125-chatgpt+.md lines 108-145, 264-299, 362-401 Related: YC Demo Strategy, YC Application Answers