# FundWise Agent Skill FundWise is Group money, done right: Members create private Groups, log Expenses, see live Balances, and settle exact USDC amounts on Solana with clear Receipts. This is the public Agent Skill Endpoint for FundWise. It is safe to fetch without authentication and does not expose private Member data. - Production app: https://fundwise.pages.dev - API docs: https://fundwise.pages.dev/api/docs - API catalog: https://fundwise.pages.dev/.well-known/api-catalog - OpenAPI service description: https://fundwise.pages.dev/api/openapi.json - Auth.md agent registration metadata: https://fundwise.pages.dev/auth.md - A2A Agent Card: https://fundwise.pages.dev/.well-known/agent-card.json - Agent Skills index: https://fundwise.pages.dev/.well-known/agent-skills/index.json - MCP Server Card: https://fundwise.pages.dev/.well-known/mcp/server-card.json - Primary product path: Group -> Expense -> Balance -> Settlement -> Receipt - Settlement asset: USDC on Solana - Identity: Solana wallet public key ## Current roadmap boundary - Current first milestone: Split Mode on Solana mainnet. - Next milestone: Fund Mode on Solana mainnet as an invite-only closed beta for a trusted cohort. - Then: Seeker app distribution. - Then: Telegram bot + Telegram mini app distribution in parallel with Seeker. - Then: full multi-chain funding/wallet support with persistent secondary EVM funding wallet support. LI.FI/CCTP remain inbound rails into USDC on Solana; they are not multi-ledger settlement. - Then: non-crypto onboarding through embedded wallets, Bridge.xyz, and Visa/card payments. - Fundy is already live on Railway as a Telegram-native FundLabs agent and MCP server; Zerion CLI-backed wallet analysis/readiness/verification is live inside Fundy. - This FundWise web app's current LI.FI path is a top-up support path only: `Route funds for Settlement` and `Route funds for Contribution`. ## What agents may do Agents may help Members with read-only and draft-safe workflows: - Discover the FundWise API surface. - Read authenticated Group, Expense, Balance, Settlement, and Receipt data when the Member has granted access. - Summarize who owes whom in a Group. - Suggest next actions, reminders, and Settlement Request Links. - Draft Expenses or proof-upload intents when a draft API is available. - For Fundy, link Telegram users to FundWise wallets through the 5-minute `/api/telegram/link-code` -> `/link FW-XXXXXX` -> `/api/telegram/link` flow. ## What agents must not do Agents must not: - Move money on behalf of a Member. - Auto-send a Settlement after opening a Settlement Request Link. - Execute Contributions or Fund Mode Proposal payouts from Telegram or an autonomous agent surface. - Invent Group, Expense, Settlement, Contribution, or Proposal data. - Scrape or expose private Member data without authenticated access. - Treat SOL as a settlement asset. SOL is only for gas. - Call Supabase directly. Use the FundWise HTTP API only. ## Auth model ### Fundy service auth Fundy is the live hosted Telegram bot and MCP server that runs the FundWise Agent. Fundy links a Telegram user to one active Solana wallet by having the signed-in web app generate a 5-minute code at `POST /api/telegram/link-code`; the user pastes that code in Fundy's DM with `/link FW-XXXXXX`; Fundy consumes it through `POST /api/telegram/link`. Service-auth headers: ```http Authorization: Bearer Content-Type: application/json ``` Fundy service auth applies only to those Telegram linking endpoints: `/api/telegram/link` (link codes are minted under the Member's browser wallet session at `/api/telegram/link-code`). There is no acting-wallet header — the linked Member wallet is derived server-side from the active Telegram link record after the service key is verified. Group membership, creator ownership, and wallet-match checks still apply. ### Browser wallet session The web app uses wallet-signed session cookies through: - `POST /api/auth/wallet/challenge` - `POST /api/auth/wallet/verify` - `GET /api/auth/wallet/session` ### Scoped Agent Access Fundy MCP token auth exists in Fundy's separate service. Broad third-party Scoped Agent Access in the FundWise web app is still planned. It will use Member-granted tokens scoped to wallet, Group, action type, expiration, and revocation. Do not ask users for the Fundy service key. ### Spending Policies Spending Policies are planned and required before any agent can pay a Settlement. They cap agent payment capacity by Member wallet, agent identity, Group, asset, counterparty, per-Settlement amount, daily amount, expiry, and revocation. Anything outside policy must fall back to a Settlement Request Link for human wallet confirmation. ### Agent-native payment protocols FundWise does not currently expose paid API access or commerce checkout routes. Planned Payable Settlement Requests should evaluate x402, MPP, and ACP only after Scoped Agent Access and Spending Policies exist. Until then, agents must treat these protocols as TODOs, not available payment rails. ## Main API entry points Fetch https://fundwise.pages.dev/api/docs for full request and response examples. Current auth/link APIs: - `POST /api/telegram/link-code` — create a 5-minute one-time code for the wallet-authenticated Member. - `POST /api/telegram/link` — Fundy consumes `/link FW-XXXXXX` and binds Telegram user -> wallet. - `GET /api/telegram/link?telegramId=` — Fundy checks the active link. - `DELETE /api/telegram/link` — Fundy unlinks a Telegram user. Current browser-session read APIs: - `GET /api/groups?wallet=` — list Groups for the acting wallet. - `GET /api/groups/{groupId}/ledger` — read protected Group ledger, Balances, suggested Settlements, and Activity Feed. - `GET /api/expenses?groupId=` — list Group Expenses. - `GET /api/settlements/{settlementId}` — read a Receipt. Mutations requiring explicit Member intent: - `POST /api/groups` — create a Group. - `POST /api/groups/{groupId}/invites` — create a tokenized Group invite. - `POST /api/groups/{groupId}/members` — join a Group with a valid invite token. - `POST /api/expenses` — create a real Expense. - `PATCH /api/expenses/{expenseId}` — edit an Expense as its creator. - `DELETE /api/expenses/{expenseId}` — delete an Expense as its creator. - `POST /api/proposals` — create a Fund Mode reimbursement Proposal. - `PATCH /api/proposals/{proposalId}` — update editable off-chain Proposal metadata before approval. - `POST /api/proposals/{proposalId}/comments` — add a Proposal-scoped comment. - `POST /api/proposals/{proposalId}/review` — approve or reject a pending Proposal. - `POST /api/proposals/{proposalId}/execute` — record a verified Squads execution for an approved Proposal. - `POST /api/profile/display-name` — update Profile Display Name. Receipt-recording only after wallet-confirmed on-chain action: - `POST /api/settlements` — record a verified Settlement signature. - `POST /api/contributions` — record a verified Contribution signature. Planned payable settlement endpoints: - `POST /api/agent/spending-policies` — create a Spending Policy after wallet confirmation. - `GET /api/agent/spending-policies` — list current Spending Policies. - `PATCH /api/agent/spending-policies/{policyId}` — lower, renew, or revoke policy limits. - `POST /api/agent/settlement-requests` — create a Payable Settlement Request. - `GET /api/agent/settlement-requests/{requestId}` — inspect a Payable Settlement Request. - `POST /api/agent/settlement-requests/{requestId}/pay` — pay only if policy permits; otherwise return a human Settlement Request Link. - `POST /api/agent/settlement-requests/{requestId}/verify` — verify payment proof and create the normal Receipt. ## Deep-link rules For Settlements, agents should reuse the existing Settlement Request Link pattern: `https://fundwise.pages.dev/groups/{groupId}?settle=` Rules: - The amount is resolved from live Group Balance when the page opens. - The Settlement is never auto-sent. - The debtor reviews the state and confirms in their wallet. - Fundy may send or remind with this link, but must not sign or submit the transfer. - Planned Payable Settlement Requests use the same live Balance and Receipt rules, but add Spending Policy checks and payment proof verification. ## Fundy command mapping - `/balance`, `/owe` -> `GET /api/groups?wallet=` then `GET /api/groups/{groupId}/ledger`. - `/expenses` -> `GET /api/expenses?groupId=`. - `/settlements` -> `GET /api/groups/{groupId}/ledger` and filter Activity Feed for Settlements. - `/group` -> `GET /api/groups/{groupId}?wallet=`. - `/settle` -> generate a Settlement Request Link to the web app. - `/draft` -> draft API is planned; do not create a real Expense unless the Member explicitly confirms that behavior. - `/analyze`, `/readiness`, `/verify` -> Zerion CLI-backed flows are live in Fundy; combine Zerion output with FundWise read APIs. ## Rate limits and retries - Keep bot polling and retries conservative. - Retry only idempotent GET calls automatically. - Do not automatically retry mutation calls that create records. - Treat `401` as relink or re-auth required. - Treat `403` as not a Group Member or insufficient capability. - Treat `404` as stale Group, Expense, or Receipt reference. ## Safety and terms FundWise is financial software. In the current product, agents are assistants, not signers. Any action that moves USDC or changes on-chain state must return the Member to the FundWise web app and wallet confirmation flow. Future Payable Settlement Requests may allow under-limit agent payment only after Spending Policies, idempotency, payment proof verification, and normal Receipt generation are implemented. Never treat a prompt or natural-language request as payment authorization.