FundWise

Split expenses. Earn together. Start a private Group, log shared Expenses, see live Balances, and settle up with a clear Receipt.

FundWise is the first product in the broader FundLabs strategy: FundLabs builds the financial layer for groups, human or AI. The product family is FundWise for shared finance, Fundy for Telegram / personal-agent distribution, and Receipt Endpoint for agent-commerce audit trails.

FundWise also has Fund Mode for pooled USDC Treasuries. Split Mode is the shipped wedge and current public proof; Fund Mode is the next mainnet milestone after Split Mode, starting as an invite-only closed beta for shared Treasuries, Contributions, reimbursement Proposals, approvals, proof, and integrations.

Documentation Map

Read these in order:

1. AGENTS.md
2. STATUS.md
3. CONTEXT.md
4. docs/positioning.md
5. ROADMAP.md
6. PRD.md
7. issues.md
8. docs/adr/

Quick links:

• STATUS.md - current repo state, locked decisions, next session
• CONTEXT.md - domain language and product invariants
• docs/positioning.md - canonical tagline, FundLabs positioning, messaging hierarchy, and claims guardrails
• PRD.md - MVP scope, user stories, implementation decisions
• ROADMAP.md - phased delivery plan
• issues.md - active indexed FW-* backlog, pick queue, handoff notes, and branch-audit findings
• docs/README.md - full documentation index by root docs, execution checklists, API/agent docs, security docs, research, ADRs, and topic groups
• docs/split-mode-mainnet-checklist.md - Split Mode production/mainnet launch checklist
• docs/fund-mode-beta-checklist.md - Fund Mode devnet beta checklist and remaining beta work
• docs/ops-runbook.md - Supabase, Cloudflare, RLS, and production operations runbook
• docs/shipped-vs-planned.md - canonical shipped, planned, and out-of-scope product matrix
• docs/lifi-route-rehearsal.md - LI.FI EVM wallet path, Sepolia boundary, and mainnet rehearsal steps
• docs/monetization.md - launch monetization notes; ADR-0032 is authoritative for the current take-rate model
• docs/api.md - static API reference snapshot; live markdown is at /api/docs
• docs/research/ - retained research notes that still support current decisions
• DECISIONS.md - ADR index
• docs/agentic-settlement-endpoint.md - research note for Payable Settlement Requests, x402, MPP, and pay.sh
• docs/agent-payment-policy.md - spending capacity, safety policy, endpoint gaps, and Group ownership notes for payment-aware agents
• audit.md - current security findings and mainnet blockers

Current Product Shape

Split Mode

The current MVP path is:

Group -> Expense -> Balance -> Settlement -> Receipt

• Web app first
• /groups uses a wallet-first entry state so disconnected users can connect immediately and continue into their Group list
• After wallet connect, the app should restore the exact intent the user came for: invite-linked Group, Settlement Request Link, or first Group creation
• Plain /groups with no existing Groups should open Group creation immediately; returning users with existing Groups should stay on the Group list
• Group creation defaults to Split Mode; Fund Mode is visible as an invite-only beta inside the create flow rather than a public default path
• Wallet-native auth (@solana/wallet-adapter-*); optional Phantom Connect may layer on later (see ADR-0014)
• Wallet-signed browser-session verification gates protected Group ledger reads and Receipts
• Invite link or QR join flow with an explicit Join {GroupName} confirmation after connect
• Settlement Request Links open the live settleable state and context, but never auto-send a Settlement
• USDC-only settlement asset
• Source Currency entry is future-only for the current public demo; it must not ship until every Expense stores the original amount, converted USD/USDC ledger value, and Exchange Rate Snapshot end to end
• Expense Proof upload is future-only for the current public demo; it must not ship until storage, preview, size limits, and access rules are implemented
• Split Mode stays free for launch, including normal USDC Settlements
• Activity Feed, not chat
• Current net Group Balance settlement, not per-Expense settlement

Fund Mode

Fund Mode is the hero product direction and the next mainnet milestone after Split Mode. It stays invite-only while the trusted cohort validates the Proposal lifecycle, fee flows, and Squads-backed Treasury execution.

• Group-owned Treasury using Squads primitives
• Contributions into Treasury
• Intended use: durable shared pools for friends, households, clubs, and recurring Groups
• Public Group creation keeps Fund Mode invite-only for now; internal testing can be re-enabled with FUNDWISE_FUND_MODE_INVITE_WALLETS
• Proposal / approval / execution flow is the highest-priority Fund Mode mainnet closed-beta path
• LI.FI, Zerion, FundWise Agent / Fundy, and later embedded-wallet, Bridge.xyz, and Visa/card rails should support Treasury Contributions, Proposal readiness, and reimbursement workflows without bypassing wallet-confirmed money movement
• Private Group mini-games and prediction-market-like mechanics are out of scope for FundWise unless they are separately justified later outside the current Split Mode and Fund Mode roadmap

Sponsor layers

• LI.FI is the current top-up support layer. It lets EVM-first users route supported mainnet USDC into their Solana wallet during Settlement through a Route funds for Settlement flow without needing to understand the underlying route details. Sepolia is not a supported FundWise rehearsal path; see docs/lifi-route-rehearsal.md. Full multi-chain wallet support is later in the roadmap, after Seeker and Telegram distribution.
• Zerion is a secondary intelligence layer for wallet analysis, reminders, and FundWise Agent flows. The Zerion CLI path is already live inside Fundy for /analyze, /readiness, and /verify-style wallet context.
• FundWise Agent is the umbrella name for assistant surfaces that read Group state, draft Expenses or Proposals, create reminders, and suggest next actions through scoped wallet-bound permissions. Telegram bot and Telegram mini app are channels for it.
• Fundy is live on Railway as the Telegram-native FundLabs agent and MCP server for external agents. It runs from a separate repository, calls FundWise over public HTTP, exposes token-authenticated MCP tools, links Telegram users to FundWise wallets, reads Group state, drafts Expenses, surfaces Settlement deep-links, and uses Zerion CLI for wallet readiness. Money movement still deep-links back to the web app for wallet confirmation. Later versions add a richer LLM layer, tax guidance, and broader personal-finance workflows. See ADR-0018, ADR-0022, ADR-0023, and ADR-0039.
• Agent Skill Endpoint (/skill.md) is already live as a public discovery document at https://fundwise.fun/skill.md. API reference markdown is available at https://fundwise.fun/api/docs. Scoped Agent Access tokens and agent-paid Settlements are still planned.
• Payable Settlement Requests are a planned research direction for agent-paid settlement through x402 / MPP-style payment flows. They should expose unpaid invoice/request state, payment challenge data, verification status, and the final Receipt only after payment is verified. See docs/agentic-settlement-endpoint.md.
• Spending Policies are required before any agent can pay a Settlement. They set per-Settlement caps, daily limits, Group scope, counterparty scope, expiry, and human fallback behavior. See docs/agent-payment-policy.md.
• Embedded wallets / Bridge.xyz / Visa card payments are future non-crypto onboarding paths, not current MVP functionality. The rollout order is crypto-native Groups first, then Seeker and Telegram distribution, then full multi-chain funding support, then non-crypto users through embedded wallets, bank-transfer rails, and card payments.

Neither sponsor integration should complicate the primary Split Mode settlement path.

Competitive posture

The shared-expense category is crowded, and crypto-native bill-splitting competitors already exist. FundWise should not position itself as "the first crypto Splitwise" or rely on bill-splitting novelty. The wedge is narrower: verified USDC Settlement for real private Groups, live Settlement Request Links that resolve the current Balance, clear Receipts, and a support path for debtors whose funds are not already on Solana.

The company-level story is broader: FundLabs is building the financial layer for Groups, humans, and AI agents. Split Mode is the entry hook because it is familiar; Fund Mode is the product because durable Groups need shared Treasuries, Proposal governance, proof, exits, and eventually productive idle money. Fundy and Receipt Endpoint expand the same stack into Telegram, personal agents, and agentic-commerce receipts.

The long-term moat is trust and distribution first, then data advantage from structured Expenses, Balances, Settlements, Receipts, Expense Proof, wallet-readiness signals, and scoped agent permissions. Fundy creates distribution where Groups already coordinate and turns FundWise data into useful reminders, drafts, readiness checks, and personal-finance workflows; Fund Mode creates durable Group retention through Treasury workflows. Public claims must still follow docs/shipped-vs-planned.md.

Shipped vs planned

Use docs/shipped-vs-planned.md as the canonical product-state matrix. The short version:

• Shipped/demoable: Split Mode devnet MVP, Fundy live on Railway with Zerion-backed wallet readiness, Zerion readiness script, public Agent Skill Endpoint baseline.
• Support layer: LI.FI as mainnet-only Route funds for Settlement.
• Next: Split Mode mainnet, then Fund Mode mainnet invite-only closed beta.
• Future: Source Currency, Expense Proof, Seeker app, Telegram mini app expansion, full multi-chain wallet support, Scoped Agent Access expansion, Payable Settlement Requests, embedded-wallet onboarding, Bridge.xyz bank rails, Visa/card payments, and tax guidance.
• Out of scope for FundWise: mini-games and prediction-market-like mechanics.

Hosted app and agent discovery

• Production web app: https://fundwise.fun
• Agent Skill: https://fundwise.fun/skill.md
• API docs: https://fundwise.fun/api/docs

Tech Stack

• Frontend: Next.js 15, React 19, Tailwind v4, Radix / shadcn UI
• Wallets: @solana/wallet-adapter-* (primary); optional @phantom/react-sdk when Portal is configured
• Chain: Solana mainnet target for Split Mode; devnet remains the rehearsal environment for Fund Mode until the invite-only mainnet closed beta is ready
• Settlement asset: USDC
• Off-chain state: Supabase / Postgres
• Fund Mode Treasury: Squads (@sqds/multisig)
• Cross-chain support: LI.FI SDK

Repo Structure

/
├── AGENTS.md
├── CONTEXT.md
├── PRD.md
├── ROADMAP.md
├── STATUS.md
├── issues.md
├── DECISIONS.md
├── docs/adr/
├── docs/agentic-settlement-endpoint.md
├── docs/agent-payment-policy.md
├── app/
│   ├── page.tsx
│   ├── story/
│   │   └── page.tsx          ← public product narrative and PLG loop
│   ├── demo/
│   │   └── page.tsx          ← interactive 5-step product walkthrough
│   └── groups/
│       ├── page.tsx
│       └── [id]/
│           ├── page.tsx
│           └── settlements/[settlementId]/page.tsx
├── components/
│   ├── settlement-preview-dialog.tsx  ← settlement preview before wallet sign
│   └── group-dashboard/
│       ├── expense-dialog.tsx
│       ├── fund-mode-dashboard.tsx
│       ├── group-sidebar.tsx
│       ├── profile-name-dialog.tsx
│       └── split-mode-dashboard.tsx
├── hooks/
│   └── use-group-dashboard.ts
├── lib/
│   ├── db.ts
│   ├── expense-engine.ts
│   ├── simple-payment.ts
│   ├── lifi-bridge.ts
│   ├── squads-multisig.ts
│   └── supabase.ts
├── docs/
│   ├── adr/                         ← active architecture decisions
│   └── archive/                      ← deferred ADRs
├── tests/
│   └── *.test.ts                     ← vitest coverage for ledger, API, and audit guards
├── vitest.config.ts
├── supabase/
    ├── migrations/                  ← source of truth for database changes
    └── schema.sql                   ← human-readable snapshot, may lag migrations

Group Dashboard Structure

The main Group route is no longer a single giant page component.

• app/groups/[id]/page.tsx is the route shell and UI wiring layer.
• hooks/use-group-dashboard.ts owns Group loading, membership checks, shareable Settlement Request Links, Settlement execution, Treasury initialization, Contribution persistence, and profile-name persistence.
• components/group-dashboard/ holds the Split Mode dashboard, Fund Mode dashboard, sidebar, Expense dialog, and profile dialog as focused UI modules.

Getting Started

Prerequisites

• Node 20+
• pnpm
• A Solana wallet
• A Solana RPC URL
• A Supabase project with the current schema applied

Install

pnpm install

Environment

Create .env.local manually. The repo does not currently ship an .env.example.

Required keys used by the app:

• SOLANA_RPC_URL — server-side RPC for receipt verification in API routes
• NEXT_PUBLIC_SOLANA_RPC_URL
• SOLANA_RPC_FALLBACK_URLS
• NEXT_PUBLIC_SOLANA_RPC_FALLBACK_URLS
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
• SUPABASE_SERVICE_ROLE_KEY
• FUNDWISE_SESSION_SECRET

Optional Fund Mode beta keys:

• FUNDWISE_FUND_MODE_INVITE_WALLETS — comma-separated Solana wallets allowed to create invite-only Fund Mode Groups
• SOLANA_DEVNET_RPC_URL / NEXT_PUBLIC_SOLANA_DEVNET_RPC_URL — devnet RPC used by Fund Mode Treasury, Contribution, and Proposal flows when the public Split Mode app uses mainnet
• SOLANA_DEVNET_RPC_FALLBACK_URLS / NEXT_PUBLIC_SOLANA_DEVNET_RPC_FALLBACK_URLS
• LIFI_API_KEY — optional server-side LI.FI key for scripts and future server routes. Do not expose this in client bundles.
• NEXT_PUBLIC_LIFI_API_KEY — optional LI.FI browser-allowed API key. Do not put a server-secret LI.FI key here; the current LI.FI SDK flow runs in the browser.

For a deployed devnet demo, set SOLANA_RPC_URL to a private devnet RPC. Public Solana devnet RPC endpoints may reject Cloudflare Workers with 403, which lets the wallet transaction land but prevents FundWise from recording the verified Receipt.

Fallback compatibility is present for:

• NEXT_PUBLIC_SUPABASE_ANON_KEY

Run

pnpm dev
pnpm build
pnpm lint
pnpm test          # vitest — expense engine unit tests

Dev server notes:

• pnpm dev should serve the app at http://127.0.0.1:3000.
• If port 3000 is already occupied, run PORT=3001 pnpm dev.
• A GET /availability 404 probe or Node --localstorage-file warning during startup is not a dev-server failure if the app still prints Ready and /api/health returns { "ok": true }.

Deploy on Cloudflare Pages

FundWise is configured for a Cloudflare Pages project, not direct Worker deploys.

Pages build settings:

• Build command: pnpm build:pages
• Build output directory: .vercel/output/static
• Deploy command: leave empty
• Node.js: 22 works on Cloudflare Pages; 20 also works locally

Do not use wrangler deploy for this app. If deploying manually, use:

pnpm deploy:pages

Current verification state:

• pnpm exec tsc --noEmit passes
• pnpm lint passes
• pnpm build passes
• pnpm test — 123 tests passing
• pnpm supabase:verify-rls passes against the configured Supabase project

Database Bootstrap

The base FundWise tables now live in supabase/migrations/, not only in supabase/schema.sql. Treat supabase/migrations/ as the database source of truth; supabase/schema.sql is a readable snapshot and can lag later migration files.

If a remote Supabase project was linked before that bootstrap migration existed, backfill it with:

supabase db push --include-all

The 2026-05-14 Supabase hardening was applied through the SQL Editor and mirrored in migrations: anonymous ledger access is denied by RLS, update_expense_with_splits and record_settlement_locked execute only through service_role, and settlements.tx_sig is unique.

MVP Notes

• Solana devnet is the active execution environment for now.
• Mainnet-beta comes later, after the devnet hardening and rehearsal path is finished.
• Members need SOL for gas even though Settlements use USDC.
• FundWise now preflights stablecoin transfers before the wallet prompt so users see insufficient-USDC, insufficient-SOL, and token-account-creation guidance earlier.
• The current rollout order is: Split Mode mainnet -> Fund Mode mainnet invite-only closed beta -> Seeker app -> Telegram bot + Telegram mini app in parallel with Seeker -> full multi-chain funding/wallet support -> non-crypto onboarding with embedded wallets, Bridge.xyz, and Visa/card payments
• Planned Expense entry expansion: allow Source Currency input, show a current exchange-rate quote, save the Exchange Rate Snapshot, and keep Balances / Settlements in the converted USD/USDC ledger value. This is future-only until the storage and ledger path is complete.
• Planned proof expansion: allow one lightweight receipt photo / PDF upload or proof link on an Expense.
• The current docs source of truth is split across STATUS.md, CONTEXT.md, and PRD.md. If another doc disagrees, those three win.

License

TBD.