sphere

Unicity AgentSphere is a Web3 wallet and agent platform built for the Unicity network. It combines cryptocurrency wallet functionality with messaging, group chat, and marketplace features into a unified application. Core wallet features include fast, low-cost token transfers, token management and balance tracking, incoming payment notifications, and a nametag system for user identification. The wallet supports QR codes, wallet switching, seed phrase management, and real-time market data. The platform implements the Sphere Connect protocol, which enables external dApps to connect to the wallet and request operations. Two connection modes are supported: iframe mode, where the dApp is embedded inside Sphere and communicates via PostMessageTransport, and popup mode, where the dApp opens Sphere as a popup window for user approval. Access is permission-based, with dApps requesting specific scopes that users can approve or reject. The protocol also supports intent handling, allowing dApps to trigger send, sign, and DM flows within the wallet UI. Sphere supports a custom deep link protocol (unicity-connect://) for inter-app linking within DMs. When a dApp sends a deep link URL in a DM message, Sphere renders it as an interactive button with options to open the link inside Sphere as an iframe agent or in an external browser tab. The protocol is resolved to standard HTTP/HTTPS URLs, with special handling for localhost addresses. The agent system allows specialized interfaces to be loaded as tabs within the application. Currently active agents include Messages (DM) for private conversations via Nostr, Group Chat for public group channels via NIP-29, and Sphere Agents for loading any external dApp via iframe with a custom URL. Additional agent types can be added through configuration. Group chat functionality is built on NIP-29, a Nostr protocol specification for relay-based group messaging. Features include public and private groups with invite codes, real-time messaging via WebSocket, group discovery, join/leave operations, and unread message tracking. A dedicated relay is available at wss://sphere-relay.unicity.network. The application is built with React 19 and TypeScript, using Vite 7 as the build tool. It leverages TanStack Query v5 for server state management, Tailwind CSS 4 for styling, Framer Motion for animations, and React Router DOM v7 for routing. All wallet operations are handled through the @unicitylabs/sphere-sdk package, which covers L3, Nostr, and IPFS functionality. Testing is done with Vitest and jsdom. The project can be run in development mode with npm run dev, built for production with npm run build, and deployed via Docker Compose on port 3010. Environment variables control configuration such as welcome agent nametag, welcome delay, SSL certificates, and deployment base path. The project is licensed as a private project by Unicity Labs.