unicity-sphere /sphere

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

★ 9,629⑂ 56👁 14⑃ 413● 137▤ 0
TypeScriptCreated 2025-11-22unicity.ai
+0
日增长
9,629
stars
56
forks
14
watchers
413
prs
137
issues
0
releases

README

Unicity AgentSphere

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

 Features

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, and  formats, rendering a DeepLinkButton dropdown
3. Opening in Sphere — a global handler (registered by useDeepLinkNavigation in DashboardLayout) navigates to /agents/custom?url=, 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

bash
npm install
cp .env.example .env     Configure environment variables
npm run dev               Start dev serve

Top issues

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON