Sphere SDK

这个 Agent 能做什么，适合哪些场景？

Sphere SDK 是面向浏览器和 Node.js 的模块化 TypeScript 钱包 SDK，用于 Unicity 状态转换网络。它以 Sphere 为入口，组合身份、支付、付款请求、市场意图、Nostr 私信和 NIP-29 群聊等模块。钱包密钥保留在客户端，但代币库存由 wallet-api 后端托管；支付经 v2 代币引擎认证后投递至接收方的 wallet-api 邮箱。基础提供器负责存储、Nostr 传输和预言机配置，付款功能还必须通过 createWalletApiProviders 单独接入 wallet-api。SDK 支持浏览器存储、Node.js 文件存储、多 HD 地址和可替换的支付传输端口，适合需要把经济身份与结算能力嵌入代理、dApp、服务端应用或钱包界面的团队。

应用首先用 createBrowserProviders 或 createNodeProviders 创建存储、Nostr 传输和预言机基础层，再以 createWalletApiProviders 加入付款所需的 wallet-api 配置，并通过 Sphere.init 创建或载入钱包。SDK 使用 BIP39/BIP32 派生密钥和多个地址，可注册或恢复 nametag，并公开 DIRECT:// 主地址。sphere.payments 查询资产和历史、接收邮箱转账、自铸测试网代币，并通过持久化 transfer intent 执行 send()；完成的 v2 CBOR 代币由引擎验证所有权及证明后才计入余额。sphere.payments.requests 创建、支付、拒绝和跟踪加密备注的付款请求；sphere.market 提供带签名、语义搜索和实时订阅的意图公告板。sphere.communications 通过 NIP-17 收发端到端加密私信，sphere.groupChat 则通过独立的 NIP-29 中继创建群组、管理邀请、发送消息和执行管理操作。SDK 还提供 Connect 协议、动态中继管理、钱包 JSON 导入导出、PBKDF2 密码加密以及金额、密钥、哈希和 Base58 工具。

1. 开发浏览器钱包或 dApp 的团队，可使用 ConnectClient / ConnectHost、IndexedDB 或 localStorage，以及 Sphere 扩展弹窗通信来连接钱包。
2. 构建自主交易代理的开发者，可为每个代理创建本地密钥身份，通过 nametag 或 DIRECT:// 地址寻找收款方，并调用 sphere.payments.send() 完成结算。
3. 运行 Node.js 服务或命令行批处理的团队，可采用文件存储和稳定的 deviceId，显式调用 receive() 排空邮箱并恢复未完成的转账。
4. 需要收款流程的应用，可通过 sphere.payments.requests 发送带加密备注的请求，并监听 pending、settling、paid、rejected 和 expired 状态。
5. 需要代理间通信的产品，可使用 NIP-17 加密私信，或启用 NIP-29 群聊、私有邀请、未读计数和管理员或版主操作。
6. 测试 Unicity v2 资产流程的团队，可在 testnet/testnet2 上自铸代币，验证多地址、转账恢复和收件箱投递逻辑。

如何安装或部署这个 Agent？

安装 SDK：

npm install @unicitylabs/sphere-sdk

Node.js 快速入门还要求安装 ws；README 未给出它的具体安装命令。命令行界面已经迁移到独立包，可按需安装：

npm install -g @unicity-sphere/cli
sphere --help

实际付款还需要可访问的 v2 网关、wallet-api 部署，以及对应网络的预言机 API key。公开的 testnet2 key 可以用于客户端测试；mainnet key 必须作为机密保存在部署环境中。

如何使用这个 Agent？

浏览器初始化必须分两层配置。下面的调用创建基础提供器、附加 wallet-api，并初始化钱包：

import { Sphere } from '@unicitylabs/sphere-sdk';
import { createBrowserProviders } from '@unicitylabs/sphere-sdk/impl/browser';
import { createWalletApiProviders } from '@unicitylabs/sphere-sdk/impl/shared/wallet-api';

const base = createBrowserProviders({
  network: 'testnet',
  oracle: { apiKey: 'sk_ddc3cfcc001e4a28ac3fad7407f99590' },
});

const providers = createWalletApiProviders(base, {
  baseUrl: 'https://wallet-api.unicity.network',
  network: 'testnet2',
  deviceId: 'my-stable-device-id',
});

const { sphere, created, generatedMnemonic } = await Sphere.init({
  ...providers,
  autoGenerate: true,
});

if (created && generatedMnemonic) {
  console.log('SAVE THIS RECOVERY PHRASE:', generatedMnemonic);
}

const result = await sphere.payments.send({
  recipient: '@alice',
  amount: '1000000',
  coinId: 'UCT',
  memo: 'hello',
});

console.log(result.status);
const { transfers } = await sphere.payments.receive();
console.log(transfers);
console.log(await sphere.payments.assets());

金额必须使用十进制字符串，不能使用 JavaScript number。接收者必须已发布含 chain pubkey 的身份，否则发送会以 INVALID_RECIPIENT 失败。若结果为 status === 'completed' 且 deliveryPending === true，链上认证已经完成，只是邮箱投递延后，不应把它显示为付款失败。若抛出 CERTIFICATION_UNCONFIRMED，不得再次调用新的 send()；原 intent 可能已经上链，SDK 会以相同的 transferId 自动恢复，否则可能造成双重付款。生产钱包应向 Sphere.init、Sphere.create 或 Sphere.load 提供用户密码，以免只依赖内置默认密钥进行静态混淆。

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v0.8.0 v0.8.0 — UXF Inter-Wallet Transfer Protocol + Profile-layer hardening 2026-05-29
   发布说明摘录

   178 PRs promoted from integration/all-fixes to main. - Release PR: [#345](https://github.com/unicity-sphere/sphere-sdk/pull/345) - Tag points at: af41bea6fc36 - Period covered: ~4 months of accumulated profile-layer, UXF, recovery, and connectivity work since the previous release lineage (PRs #128–#130 → #303–#342). ⚠️ Breaking: UXF wire-shape default flip …

   在 GitHub 查看 ↗
2. v0.2.4 2026-02-11
   发布说明摘录

   Bug Fixes - CLI process exit: Fix CLI commands hanging ~10s after completion due to lingering Nostr WebSocket handles - Instant split change token: Fix sender losing change token when process.exit() killed background proof collection before completion Changes - InstantSplitExecutor.submitBackgroundV5 now returns a trackable Promise<void> instead of fire-and-forget - PaymentsModule tracks background promises and exposes waitForPendingOperations() for callers to await completion - CLI send command awaits pending background operations before exiting …

   在 GitHub 查看 ↗

常见问题