Sphere SDK

What does this agent do, and when should you use it?

Sphere SDK is a modular TypeScript wallet SDK for the Unicity state transition network, with documented browser and Node.js implementations. Its Sphere entry point composes identity, payments, payment requests, market intents, Nostr direct messages, and NIP-29 group chat. Wallet keys remain on the client, while the wallet-api backend holds token inventory and receives engine-certified transfers through per-user mailboxes. Base providers supply storage, Nostr transport, and oracle configuration; payment functionality requires a second configuration layer added with createWalletApiProviders. The SDK supports HD addresses, replaceable payment transport ports, browser or file-backed persistence, and wallet-to-dApp communication, making it suitable for teams embedding economic identity and settlement in agents, services, dApps, or wallet interfaces.

An application starts with createBrowserProviders or createNodeProviders to construct storage, Nostr transport, and oracle configuration, then attaches the required wallet-api configuration with createWalletApiProviders before calling Sphere.init. The SDK derives identities and multiple addresses with BIP39/BIP32, registers or recovers nametags, and exposes a primary DIRECT:// address. sphere.payments lists assets and history, drains incoming mailbox transfers, self-mints testnet tokens, and executes send() through durable transfer intents; completed v2 CBOR token blobs are proof- and ownership-checked before entering the balance. sphere.payments.requests creates, pays, declines, and tracks requests with encrypted memos, while sphere.market exposes a signed intent bulletin board with semantic search and a live feed. sphere.communications sends and receives NIP-17 encrypted direct messages, and the optional sphere.groupChat module uses a separate NIP-29 relay for groups, invitations, messages, and moderation. Additional interfaces cover the Connect protocol, dynamic relay management, encrypted wallet export/import, optional CoinGecko prices, and crypto, currency, hashing, and Base58 utilities.

1. A browser-wallet or dApp team can combine localStorage or IndexedDB with ConnectClient / ConnectHost and the Sphere extension or popup flow.
2. A developer building autonomous trading agents can give each agent a locally held identity, resolve recipients through nametags or DIRECT:// addresses, and settle with sphere.payments.send().
3. A Node.js service or batch application can use file-backed storage and a stable deviceId, explicitly call receive() to drain its mailbox, and resume unfinished transfers after restart.
4. An application collecting payments can create requests through sphere.payments.requests, include encrypted memos, and react to pending, settling, paid, rejected, and expired states.
5. A product requiring agent-to-agent communication can use NIP-17 private messages or enable NIP-29 groups with private invitations, unread counts, and administrator or moderator controls.
6. A team testing Unicity v2 asset flows can self-mint on testnet/testnet2 and exercise multi-address wallets, transfer recovery, and mailbox delivery.

How do you install or deploy this agent?

Install the SDK package:

npm install @unicitylabs/sphere-sdk

The documented Node.js setup also requires ws, although the source does not provide its exact installation command. The CLI is maintained as a separate package and can be installed when needed:

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

Operational payments additionally require access to a v2 gateway, a wallet-api deployment, and the appropriate oracle API key. The published testnet2 key may be used in client-side test code; a mainnet key must remain secret in the deployment environment.

How do you use this agent?

Browser initialization has two required provider layers. This example creates the base providers, attaches wallet-api, initializes a wallet, and submits a transfer:

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());

Amounts must be decimal strings rather than JavaScript numbers. The recipient must have a published identity containing a chain public key, or the call fails with INVALID_RECIPIENT. A result with status === 'completed' and deliveryPending === true is already certified on-chain; only mailbox delivery is deferred, so the UI must not report it as a payment failure. If send() throws CERTIFICATION_UNCONFIRMED, do not issue a fresh send() because the original intent may already be certified; the SDK resumes it automatically under the same transferId, while a new call could double-pay the recipient. For wallets holding real value, pass a user password to Sphere.init, Sphere.create, or Sphere.load instead of relying on the built-in default-key obfuscation.

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

1. v0.8.0 v0.8.0 — UXF Inter-Wallet Transfer Protocol + Profile-layer hardening 2026-05-29
   Release notes excerpt

   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 …

   View on GitHub ↗
2. v0.2.4 2026-02-11
   Release notes excerpt

   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 …

   View on GitHub ↗

FAQ