unicity-sphere /sphere-sdk-connect-example

★ 9,503⑂ 33👁 18⑃ 30● 2▤ 0
TypeScriptCreated 2026-02-14
More from this author
+0
Daily
9,503
stars
33
forks
18
watchers
30
prs
2
issues
0
releases

README

Sphere Connect Example

Four runnable examples showing the different ways an app can work with a Sphere
wallet — as a browser dApp, as a Node dApp, as a bot that runs its own
wallet, or as a backend that just authenticates a user.

 What is Sphere Connect?

Sphere Connect is a typed RPC protocol that lets a dApp talk to a user's Sphere
wallet — reading balances, sending tokens, signing messages — without ever
seeing the private keys. The dApp runs a ConnectClient; the wallet runs a
ConnectHost; a transport carries messages between them.


dApp (ConnectClient)  ←→  Transport  ←→  Wallet (ConnectHost)


 All five packages require @unicitylabs/sphere-sdk ≥ 0.14.1. Wallet hosts
 from 0.14.1 onward enforce an SDK version floor at the handshake: a client
 built on an older SDK is refused with UNSUPPORTED_PROTOCOL_VERSION (4007)
 before any approval UI appears, so a dApp that is not bumped simply stops
 connecting. The Connect protocol MAJOR is unchanged (still 2), which is
 all the gate compares — this is a dependency bump and a rebuild, nothing more.
 (SPHERE_CONNECT_VERSION is 2.3 at the 0.17.6 pinned below.) See
 browser/CONNECT.md.

Not every example uses Connect: the bot runs its own wallet directly, and
the backend in backend-auth only verifies a signature. See the guide below.

 Which example do I need?

The examples differ along two axes: whose wallet your app uses, and what
it needs to do with it.

| Example | Your app is… | The wallet is… | Can move tokens? | Reach for it when… |
|---|---|---|---|---|
| browser/ | a web page / dApp | the user's, elsewhere | ✅ with per-action approval | your dApp runs in a browser and the user is present to approve each send — e.g. a browser game where the player approves in-game purchases |
| nodejs/ | a Node CLI / service | the user's, over WebSocket | ✅ with approval | you need a CLI / desktop / server dApp that drives a user's wallet over a WebSocket (see the caveat in its README) |
| bot/ | an autonomous agent | its own (own keys, wallet-api custody) | ✅ no approval — it owns the funds | you're building a tipping bot, faucet, game NPC that pays rewards, or an agent that acts from its own float with no human in the loop |
| backend-auth/ | a frontend + backend | the user's (frontend only signs) | ❌ auth only | you need to know who the player is — login, leaderboards, ownership, sessions — but do not need to move their tokens. Recommended for games/apps that need authenticated identity, not custody or intents |

Rules of thumb:

- Need to move a user's tokens? → browser/ (web) or nodejs/ (Node over WS). The user approves each action.
- Moving your own tokens autonomously? → bot/. It is the wallet; no approval prompts.
- Just need to know who the user is? → backend-auth/. It authenticates and stops there — it never touches funds.

 Quick Start

 browser/ — web dApp over Connect

bash
cd browser
npm install
npm run dev         http://localhost:5174

Needs a Sphere wallet reachable at http://localhost:5173. Se

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