---
title: "sphere"
type: "tool"
slug: "unicity-sphere-sphere"
canonical_url: "https://www.graphcanon.com/tools/unicity-sphere-sphere"
github_url: "https://github.com/unicity-sphere/sphere"
homepage_url: "https://unicity.ai"
stars: 8565
forks: 41
primary_language: "TypeScript"
license: null
categories: ["developer-tools", "ai-agents"]
tags: ["web3", "agent-platform", "crypto-wallet"]
updated_at: "2026-07-07T18:36:13.859006+00:00"
---

# sphere

> Web3 wallet and agent platform for the Unicity network

Unicity AgentSphere is a dual-layer crypto wallet with features like DMs, group chat, marketplace, and deep link support. It implements the Connect protocol for interactions between decentralized applications (dApps) and wallets.

## Facts

- Repository: https://github.com/unicity-sphere/sphere
- Homepage: https://unicity.ai
- Stars: 8,565 · Forks: 41 · Open issues: 29 · Watchers: 5
- Primary language: TypeScript
- Last pushed: 2026-07-07T13:16:12+00:00

## Categories

- [Developer Tools](/categories/developer-tools.md)
- [AI Agents](/categories/ai-agents.md)

## Tags

web3, agent platform, crypto wallet

## Related tools

- [ECC](/tools/affaan-m-ecc.md) - The agent harness performance optimization system (★ 226,962)
- [hermes-agent](/tools/nousresearch-hermes-agent.md) - The self-improving AI agent built by Nous Research (★ 210,880)
- [AutoGPT](/tools/significant-gravitas-autogpt.md) - AutoGPT: Build, Deploy, and Run AI Agents (★ 185,417)
- [ollama](/tools/ollama-ollama.md) - Get up and running with Kimi-K2.6, GLM-5.1, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models. (★ 175,659)
- [prompts.chat](/tools/f-prompts-chat.md) - The world's largest open-source prompt library for AI (★ 165,019)
- [JavaGuide](/tools/snailclimb-javaguide.md) - Snailclimb/JavaGuide: 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发 (★ 156,863)
- [langflow](/tools/langflow-ai-langflow.md) - Langflow is a powerful platform for building and deploying AI-powered agents and workflows. (★ 151,298)
- [dify](/tools/langgenius-dify.md) - Production-ready platform for agentic workflow development (★ 148,070)

## README (excerpt)

```text
# 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](https://github.com/nostr-protocol/nips/blob/master/29.md):
- 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 server at http://localhost:5173
```

### Commands

```bash
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:

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

---

**Machine-readable endpoints**

- JSON: [`/api/graphcanon/tools/unicity-sphere-sphere`](/api/graphcanon/tools/unicity-sphere-sphere)
- LLM index: [/llms.txt](/llms.txt)
- Full corpus: [/llms-full.txt](/llms-full.txt)

_GraphCanon - The knowledge graph for AI development. https://www.graphcanon.com/_