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、一个 Node dApp、一个自带钱包的机器人，以及一个只负责验证用户身份的后端。
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——不用 caret 范围，因为对示例来说，版本固定的清晰性比跟随浮动版本更重要。
我的 dApp 连接时可能出什么问题？钱包主机在握手阶段就会强制检查 SDK 最低版本：使用较旧 SDK 的客户端会在任何授权界面出现之前收到 4007 错误并被拒绝，所以没有升级 SDK 的 dApp 会直接连不上。
这四个示例都使用 Connect 协议吗？不是。只有 browser/ 和 nodejs/ 使用 Connect 通信。bot/ 示例直接运行自己的钱包，完全不涉及 Connect；backend-auth/ 则只是验证签名，不驱动钱包。
这个机器人不需要询问任何人就能转账，是怎么做到的？它本身就是钱包：通过 wallet-api 托管持有自己的密钥，因此不会出现授权弹窗。这适合打赏机器人、水龙头或用自有资金发放奖励、无需人工参与的游戏 NPC。
在 backend-auth 里用 Sphere 钱包登录是怎么工作的？前端代理发起一次 sign_message，后端从中恢复出公钥并签发一个 JWT。它只做身份验证，绝不触碰用户的资金——README 建议将其用于需要身份而非托管的游戏。
我可以在托管的 Sphere 钱包上测试本地 dApp 吗？只能通过 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