Unicity AgentSphere

A Web3 wallet and agent platform for the Unicity network — dual-layer crypto wallet, DMs, group chat, and marketplace.

Features

Multi-Layer Wallet

Layer 1 (ALPHA blockchain):

• Wallet creation, import, and management
• Transaction history and vesting
• Password protection
• L1-L3 bridge

Layer 3 (Unicity state transitions):

• Fast, low-cost token transfers
• Token management and balance tracking
• Incoming payment notifications
• Nametag system (@username)

Common: QR codes, wallet switching, seed phrase management, real-time market data.

Connect Protocol (dApp ↔ Wallet)

Sphere implements ConnectHost — the wallet side of the Sphere Connect protocol. External dApps can connect to Sphere and request wallet operations:

• Iframe mode — dApp embedded inside Sphere as an iframe connects via PostMessageTransport
• Popup mode — dApp opens Sphere as a popup window, user approves the connection
• Permission-based access — dApp requests specific scopes; user approves or rejects
• Intent handling — dApp triggers send/sign/DM flows in the wallet UI

Key components: ConnectPage (/connect route), ConnectProvider, ConnectionApprovalModal.

Deep Links (unicity-connect://)

Sphere supports a custom URL protocol for inter-app linking within DMs. When a dApp sends a unicity-connect:// URL in a DM, Sphere renders it as an interactive button with two options: Open in Sphere (loads the URL as an iframe agent) or Open in browser (opens in a new tab).

Protocol format:

unicity-connect://host/path?query=params

When opened, the protocol is resolved to https:// (or http:// for localhost/127.0.0.1).

How it works:

1. Sending — a dApp builds a URL and replaces https:// with unicity-connect:// before sending it as a DM message
2. Rendering — Sphere's markdown parser detects unicity-connect:// in plain text, [text](unicity-connect://...), and <a href="unicity-connect://..."> formats, rendering a DeepLinkButton dropdown
3. Opening in Sphere — a global handler (registered by useDeepLinkNavigation in DashboardLayout) navigates to /agents/custom?url=<httpsUrl>, loading the target as an iframe agent
4. Opening in browser — the resolved http(s):// URL is opened in a new tab via window.open

Key files:

• src/utils/deepLinkHandler.ts — protocol conversion (deepLinkToHttps), global click handler registry
• src/utils/markdown.tsx — DeepLinkButton component, deep link detection in all link formats
• src/hooks/useDeepLinkNavigation.ts — registers the Sphere-side navigation handler

Agent System

Agents are specialized interfaces loaded as tabs. Currently active:

• Messages (DM) — private conversations via Nostr
• Group Chat — public group channels via NIP-29
• Sphere Agents — load any external dApp via iframe (custom URL)

Additional agent types can be added in src/config/activities.ts.

Group Chat (NIP-29)

Relay-based group messaging via NIP-29:

• Public and private groups with invite codes
• Real-time messaging via WebSocket
• Group discovery, join/leave, unread tracking
• Dedicated Zooid relay at wss://sphere-relay.unicity.network

Quick Start

Requirements

• Node.js 20+

Setup

npm install
cp .env.example .env    # Configure environment variables
npm run dev              # Start dev server at http://localhost:5173

Commands

npm run dev          # Development server
npm run build        # TypeScript compile + Vite production build
npm run preview      # Preview production build
npm run lint         # ESLint
npm run test         # Vitest watch mode
npm run test:run     # Vitest single run

Environment Variables

Copy .env.example to .env. Key variables:

VITE_WELCOME_AGENT_NAMETAG=kbbot # Welcome DM agent nametag
VITE_WELCOME_DELAY_MS=4000       # Delay before