sphere-sdk-connect-example README

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

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 itself is unchanged (still 2.1) — this is a dependency bump and a rebuild, nothing more. 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:

Quick Start

browser/ — web dApp over Connect

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

Needs a Sphere wallet reachable at http://localhost:5173 (or the Sphere extension). See browser/README.md.

Testing a local dApp against the real (hosted) wallet? It only works via iframe — load your dApp as a custom agent at https://sphere.unicity.network/agents/custom. The popup path returns 403 against the hosted wallet. (Applies to both browser/ and backend-auth/frontend.)

nodejs/ — Node dApp over WebSocket

cd nodejs
npm install
npm run server     # Terminal 1: mock wallet  (ws://localhost:8765)
npm run client     # Terminal 2: CLI dApp

Drives a wallet over WebSocketTransport. See nodejs/README.md.

bot/ — a bot with its own wallet

cd bot
npm install
cp .env.example .env    # WALLET_API_URL is REQUIRED — token custody lives there
npm start               # boots its own wallet on testnet2, self-mints, DM-echoes

No Connect involved — the bot is the wallet. Since sphere-sdk 0.14 there is no own-storage custody: Sphere.init throws INVALID_CONFIG without a walletApi composition, so WALLET_API_URL must be set. See bot/README.md.

backend-auth/ — sign in with a Sphere wallet

# Terminal 1 — backend  (http://localhost:8787)
cd backend-auth/backend  && npm install && cp .env.example .env && npm start
# Terminal 2 — frontend (http://localhost:5173)
cd backend-auth/frontend && npm install && cp .env.example .env && npm run dev

Frontend brokers a sign_message; backend recovers the pubkey and issues a JWT. See backend-auth/README.md.

Dependencies

All five packages pin the same published SDK version, exactly (no caret — these are examples, and pin clarity matters more than float):

"@unicitylabs/sphere-sdk": "0.14.2"

Documentation

License

MIT

sphere-sdk-connect-example (unicity-sphere/sphere-sdk-connect-example)

Searching Database…

9.5K ·GitHub
Sphere-sdk-connect-example
Что это такое?Четыре готовых примера приложений, показывающих, как программа может работать с кошельком Sphere: браузерное dApp, dApp на Node, бот со собственным кошельком и бэкенд, который только проверяет подлинность пользователя.
Что такое Sphere Connect — этот репозиторий это библиотека или приложения?Sphere Connect — это типизированный RPC-протокол: в вашем dApp работает ConnectClient, в кошельке пользователя — ConnectHost, а транспорт передаёт сообщения между ними, так что dApp никогда не видит приватные ключи. В этом репозитории лежат четыре готовых примера приложений, а не сам SDK.
Тут четыре папки — какая подойдёт для моего приложения?Выбирайте по тому, что делает приложение: browser/ для веб-dApp, nodejs/ для консольной программы или сервиса через WebSocket, bot/ для автономного агента со своими деньгами, а backend-auth/ для входа, который не переводит токены.
Какая версия Sphere SDK нужна этим примерам?Каждый пакет жёстко закрепляет @unicitylabs/sphere-sdk на версии ≥ 0.14.1 — без диапазонов с крышечкой: для примеров ясная фиксация версии важнее плавающих обновлений.
Что может пойти не так, когда мой dApp пытается подключиться?Кошельки проверяют минимальную версию SDK при рукопожатии: клиент на старом SDK получает отказ с ошибкой 4007 ещё до появления окна подтверждения, поэтому dApp с необновлённым SDK просто не сможет подключиться.
Все ли четыре примера используют протокол Connect?Нет. По Connect общаются только browser/ и nodejs/. Пример bot/ работает со своим кошельком напрямую, без Connect, а backend-auth/ просто проверяет подпись вместо управления кошельком.
Как бот переводит деньги, ни у кого не спрашивая?Он сам является кошельком: хранит свои ключи с хранением через wallet-api, поэтому никаких запросов на подтверждение нет. Это подходит ботам для чаевых, кранам или игровым NPC, которые платят награды из собственных запасов без участия человека.
Как работает вход с кошельком Sphere в backend-auth?Фронтенд запрашивает sign_message, бэкенд извлекает из неё публичный ключ и выдаёт JWT. Это только проверка подлинности — к деньгам пользователя она не прикасается; README советует её для игр, которым нужна личность игрока, а не хранение средств.
Могу ли я проверить локальный dApp с размещённым кошельком Sphere?Только через iframe: загрузите свой dApp там как кастомного агента. Вариант с всплывающим окном возвращает 403 с размещённым кошельком, и это касается как browser/, так и фронтенда backend-auth.
What are similar projects?web3.js, fragment-api-dev, solana-meme-tool, robinhood-lp-bot, Trpjan-solana-trading-toolkit, rh-swap, shardeum, Polymarket-Telegram-Bot
Which topics is it in?wallet, rpc, jwt, cryptocurrency, examples, web3, blockchain, websocket, authentication, sdk, backend, free
Creator
unicity-sphere
Size
1 MB
Stars
9.5K
Updated
CommitOct 05
Age
8mo
Commits · 90 Days