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
Что это такое?Sphere (Unicity AgentSphere) — это Web3-кошелёк и платформа агентов для сети Unicity: криптокошелёк с переводом токенов, личными сообщениями, групповым чатом и маркетплейсом в одном приложении.
Это сайт, который я открываю в браузере, или что-то, что нужно установить и запустить самому?Это веб-приложение на React 19, TypeScript и Vite, которым вы пользуетесь в браузере. В репозитории также есть файлы Docker и Docker Compose, так что вы можете развернуть собственный экземпляр на своём сервере.
Как его запустить?Установите Node.js 20+, скопируйте .env.example в .env и заполните ключевые переменные, затем запустите dev-сервер Vite командой npm run dev. В качестве альтернативы в комплекте есть настройка Docker Compose.
Что должно быть установлено до начала работы?Только Node.js 20+ — всё остальное подтянется из npm. Тесты работают на Vitest с jsdom, плюс Playwright для сквозных (end-to-end) тестов.
Можно ли использовать его с Bitcoin или Ethereum, или он только для Unicity?Он создан для сети Unicity: все операции с кошельком идут через @unicitylabs/sphere-sdk, который обрабатывает переходы состояний Unicity, L3, Nostr и IPFS. В README другие блокчейны не упоминаются.
Код открытый — могу ли я сделать форк или использовать его повторно?Нет. В README он описан как частный проект Unicity Labs, а в репозитории нет открытой лицензии, поэтому код не лицензирован для повторного использования или распространения.
Что кошелёк реально умеет в повседневном использовании?Основные возможности: быстрые и дешёвые переводы токенов, управление токенами и отслеживание баланса, уведомления о входящих платежах, система @юзернеймов, QR-коды, переключение между кошельками, управление seed-фразой и данные о рынке в реальном времени.
Как другие dApps подключаются к моему кошельку?Sphere реализует ConnectHost — сторону кошелька в протоколе Sphere Connect: dApp подключается либо как iframe внутри Sphere, либо через всплывающее окно, запрашивает определённые разрешения, и каждое действие по отправке или подписи обрабатывается в интерфейсе кошелька с вашим подтверждением.
Как устроены сообщения?Личные сообщения работают через Nostr, а групповой чат использует каналы на базе релея по стандарту NIP-29 с публичными и приватными группами, кодами приглашений, отслеживанием непрочитанного и обменом сообщениями через WebSocket в реальном времени на отдельном ралее wss://sphere-relay.unicity.network.
Что такое «агенты» в AgentSphere?Это специализированные интерфейсы, которые загружаются как вкладки: Messages для личных сообщений Nostr, Group Chat для каналов NIP-29 и Sphere Agents, который открывает любой внешний dApp в iframe по произвольному URL. Новые типы агентов можно добавить через 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, messaging, notifications, blockchain, chat, tailwindcss
Creator
unicity-sphere
Size
211.3 MB
Stars
9.6K
Updated
CommitOct 16
Age
10mo
Commits · 90 Days