sphere README

The project's README from github.com/unicity-sphere/sphere. As one markdown file: README.md.

Unicity AgentSphere

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

Features

Unicity state transitions:

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:

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

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:

Agent System

Agents are specialized interfaces loaded as tabs. Currently active:

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

Group Chat (NIP-29)

Relay-based group messaging via NIP-29:

Quick Start

Requirements

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 welcome DM (ms)
SSL_CERT_PATH=                   # Dev server HTTPS (optional)
HMR_HOST=                        # Remote HMR host (optional)
BASE_PATH=/                      # Deployment base path

Tech Stack

Project Structure

src/
├── index.html           # HTML entry point
├── main.tsx             # App bootstrap, provider tree
├── App.tsx              # Route definitions
├── sdk/                 # React adapter layer over sphere-sdk (24 files)
│   ├── hooks/core/      # useSphere, useWalletStatus, useIdentity, useNametag, useSphereEvents, useIpfsSync
│   ├── hooks/payments/  # useTokens, useBalance, useAssets, useTransfer, useTransactionHistory
│   ├── hooks/comms/     # useSendDM, usePaymentRequests
│   └── utils/           # format utilities
├── components/
│   ├── activity/        # Activity ticker, market feed display
│   ├── agents/          # Agent cards and selection
│   ├── chat/            # DM, group chat, mini chat, hooks
│   ├── wallet/          # L3, onboarding, shared, ui components
│   ├── layout/          # DashboardLayout, Header
│   ├── desktop/         # Desktop layout, TabBar, Taskbar
│   ├── connect/         # Wallet connection flow
│   └── ...              # splash, theme, tutorial, ui
├── pages/               # IntroPage, AgentPage, MarketsPage, + lazy-loaded pages
├── hooks/               # 9 app-level hooks
├── contexts/            # ServicesProvider (GroupChat)
├── services/            # FaucetService
├── config/              # activities, localStorage keys
├── lib/                 # TanStack Query client config
├── utils/               # markdown, mentions, retry
└── types/               # TypeScript type definitions
tests/
└── unit/                # Vitest tests (jsdom)

Docker

docker compose up        # Runs on port 3010

License

Private project — Unicity Labs

sphere (unicity-sphere/sphere)

Searching Database…

9.6K ·GitHub
Sphere
What is this?Sphere (Unicity AgentSphere) is a Web3 wallet and agent platform for the Unicity network: a crypto wallet with token transfers, DMs, group chat, and a marketplace in one app.
Is this a website I open in a browser, or something I install and run myself?It is a web application built with React 19, TypeScript and Vite that you use in a browser. The repo also ships Docker and Docker Compose files, so you can self-host your own instance.
How do I get it running?Install Node.js 20+, copy .env.example to .env and fill in the key variables, then start the Vite dev server with npm run dev. A Docker Compose setup is included as an alternative.
What do I need installed before starting?Just Node.js 20+ — everything else comes from npm. Tests run on Vitest with jsdom, plus Playwright for end-to-end tests.
Can I use it with Bitcoin or Ethereum, or is it Unicity-only?It is built for the Unicity network: all wallet operations go through @unicitylabs/sphere-sdk, which handles Unicity state transitions, L3, Nostr and IPFS. The README mentions no other chains.
Is the code open source — can I fork it or reuse it?No. The README describes it as a private project by Unicity Labs and the repository carries no open-source license, so the code is not licensed for reuse or redistribution.
What can the wallet actually do day to day?Core features: fast, low-cost token transfers, token management and balance tracking, incoming payment notifications, an @username nametag system, QR codes, wallet switching, seed phrase management, and real-time market data.
How do other dApps connect to my wallet?Sphere implements ConnectHost, the wallet side of the Sphere Connect protocol: a dApp connects either as an iframe embedded inside Sphere or through a popup window, requests specific permission scopes, and every send or sign intent is handled in the wallet UI with your approval.
How does the messaging side work?DMs run over Nostr, while group chat uses NIP-29 relay-based channels with public and private groups, invite codes, unread tracking, and real-time WebSocket messaging on a dedicated relay at wss://sphere-relay.unicity.network.
What are the 'agents' in AgentSphere?They are specialized interfaces loaded as tabs: Messages for Nostr DMs, Group Chat for NIP-29 channels, and Sphere Agents, which load any external dApp in an iframe from a custom URL. New agent types can be added via src/config/activities.ts.
What are similar projects?rh-swap, hey.xyz, ink-kit, gun, solana-meme-tool, metamask-extension, StarLive, fleetbase
Which topics is it in?dapp, wallet, payments, crypto, marketplace, qr-code, web3, notifications, messaging, blockchain, chat, tailwindcss
Creator
unicity-sphere
Size
211.3 MB
Stars
9.6K
Updated
CommitOct 16
Age
10mo
Commits · 90 Days